commspliant-html-editor 0.0.3 → 0.0.5

package/README.md

@@ -2,6 +2,8 @@
 
 **Try it out here:** [https://htmleditor.commspliant.com/](https://htmleditor.commspliant.com/)
 
+[![WYSIWYG editor screenshot](screenshot.png)](https://htmleditor.commspliant.com/)
+
 Reusable React + TypeScript editor with two base modes: **Visual** (`contenteditable`) and **HTML** (plain-text source). Downstream apps import the package; they do not copy source.
 
 ## Install
@@ -44,7 +46,9 @@ Give the editor a parent with a definite height (`height: 100%` on a sized ances
 | `value` | `string` | — | Controlled HTML document |
 | `defaultValue` | `string` | `''` | Initial HTML when uncontrolled |
 | `onChange` | `(html: string) => void` | — | Fires when either surface edits the document |
-| `onAutoSave` | `(html: string) => void` | — | Polls every 1s; calls only when the document HTML changed. See [Auto save](#auto-save) |
+| `onAutoSave` | `(html: string \| string[]) => void` | — | Polls every 1s; calls only when the document HTML changed. See [Auto save](#auto-save) |
+| `onSave` | `(html: string \| string[]) => void` | — | File → Save host callback. See [Save and open](#save-and-open) |
+| `onOpen` | `() => string \| string[] \| null` | — | File → Open host callback. See [Save and open](#save-and-open) |
 | `mode` | `'visual' \| 'html'` | — | Controlled mode |
 | `defaultMode` | `'visual' \| 'html'` | `'visual'` | Initial mode when uncontrolled |
 | `onModeChange` | `(mode: EditorMode) => void` | — | Fires when the built-in Visual / HTML toggle is used |
@@ -53,7 +57,7 @@ Give the editor a parent with a definite height (`height: 100%` on a sized ances
 | `onFullscreenChange` | `(fullscreen: boolean) => void` | — | Fires when full screen is entered or exited |
 | `placeholder` | `string` | — | Empty-state hint |
 | `disabled` | `boolean` | `false` | Same lock as `readOnly`. Either prop being true locks the editor |
-| `readOnly` | `boolean` | `false` | When true, neither surface can be edited and both are grayed out; menus and toolbar are grayed out and not clickable |
+| `readOnly` | `boolean` | `false` | Locks document editing. When `enableComments` is also true, comment chrome stays available and `onCommentsChange` still fires; anchor writes do not call `onChange`. See [Comments](#comments) |
 | `className` | `string` | — | Extra class on the editor root |
 | `locale` | `'en' \| 'es'` | `'en'` | Library chrome language. Document content is not translated |
 | `toolbarBackground` | `string` | `#f0f0f0` | CSS color for the icon toolbar row. Omit to use the default light gray |
@@ -75,22 +79,71 @@ Give the editor a parent with a definite height (`height: 100%` on a sized ances
 | `transformHtml` | `(html: string) => string` | — | Optional map over document HTML before it is stored and passed to `onChange`. See [Transform HTML](#transform-html) |
 | `customImagePicker` | `CustomImagePicker` | — | Optional third Insert image source. See [Custom image picker](#custom-image-picker) |
 | `disableBuiltinImageInsert` | `boolean` | `false` | Skip the Insert image dialog and call `customImagePicker.onPick` from the toolbar or Insert menu |
+| `customAudioPicker` | `CustomAudioPicker` | — | Optional third Insert audio source. See [Custom audio picker](#custom-audio-picker) |
+| `disableBuiltinAudioInsert` | `boolean` | `false` | Skip the Insert audio dialog and call `customAudioPicker.onPick` from the Insert menu |
+| `customVideoPicker` | `CustomVideoPicker` | — | Optional third Insert YouTube video source. See [Custom video picker](#custom-video-picker) |
+| `disableBuiltinVideoInsert` | `boolean` | `false` | Skip the Insert YouTube video dialog and call `customVideoPicker.onPick` from the Insert menu |
 | `disableHtmlFileDrop` | `boolean` | `false` | When true, dropping an HTML file on the editor does not replace the document. File → Open is unchanged |
+| `enableMultiPages` | `boolean` | `false` | When true, edit multiple independent HTML pages in visual mode. See [Multi-page editing](#multi-page-editing) |
+| `pages` | `string[]` | — | Controlled page HTML strings when `enableMultiPages` is true |
+| `defaultPages` | `string[]` | — | Initial pages when uncontrolled and `enableMultiPages` is true |
+| `onPagesChange` | `(pages: string[], activePageIndex: number) => void` | — | Fires when any page changes while multi-page mode is enabled |
+| `enableComments` | `boolean` | `false` | When true, comment chrome and thread state are enabled. See [Comments](#comments) |
+| `commentAuthor` | `CommentAuthor` | — | `{ userId, userName }` identity for posting messages in the comment panel |
+| `comments` | `CommentThread[]` | — | Controlled comment thread array (metadata separate from document HTML) |
+| `defaultComments` | `CommentThread[]` | `[]` | Initial threads when uncontrolled |
+| `onCommentsChange` | `(threads: CommentThread[]) => void` | — | Fires when comment threads change |
 | `toolbarCustomization` | `ToolbarCustomizationPersistence` | — | Host load/save for icon-toolbar layout. Omit to persist in `localStorage`. See [Customize toolbar](#customize-toolbar) |
 | `darkMode` | `boolean` | `false` | Initial chrome theme when nothing is persisted (`true` = dark). See [Dark mode](#dark-mode) |
 | `darkModePersistence` | `DarkModePersistence` | — | Host load/save for the chrome theme. Omit to persist in `localStorage`. See [Dark mode](#dark-mode) |
 
-`mode`, `value`, and `fullscreen` are optional. Omit them for internal state; pass them to control from the parent. Chrome includes a File menu (Save, Load, and Print), an Edit menu (Undo and Redo), an Insert menu (Link, Bookmark, Image, Table, Horizontal line, and table row/column items), a View menu (Visual, HTML, Toolbar customize and position, Light/Dark mode, Preview, and Full screen), and a Format menu (paragraph styles, font, clear formatting, paragraph, page, image properties, and table/cell/row properties), unless `menuVisible` is `false`. The icon toolbar has File (Save and Load), Print, Edit (Undo and Redo), Insert (Link, Bookmark, Image, Table, and Horizontal line), Font, Align, Paragraph, and View (Visual | HTML | Preview) groups, with Full screen pinned last, unless `toolbarVisible` is `false`. Hide both to drop the chrome slot entirely. View → Toolbar → Position docks the icon toolbar (the menu bar stays at the top). Top and bottom wrap onto multiple rows when they cannot fit on one line; Full screen stays last, pinned to the right of the first row. Left and right stay a single column and grow the editor instead of wrapping into extra columns. Full screen covers the host page with a fixed overlay; an X control (and Escape) returns to the in-page layout. Visual and HTML mode stay independent of the overlay. Save writes the current document to an HTML file; Load replaces it from an HTML file. Dropping an `.html` / `.htm` file onto the document surface does the same as Load, unless `disableHtmlFileDrop` is set. Print opens the browser print dialog for the document HTML only (not the editor chrome). Preview (View menu and View icon group) opens a large dialog with a scrollable rendering of the current document HTML. Undo and Redo walk document HTML history; they are grayed out when there is nothing to undo or redo. The File, Edit, and Insert menu items use the same icons as the toolbar buttons. Link wraps the selection (or inserts the URL as the visible text at the caret) in an `<a href>` tag; an optional title becomes the native hover tooltip, and opening in a new tab sets `target="_blank"`. Bookmark inserts a named destination (`id`) at the caret or around the selection. Horizontal line inserts an `<hr>` at the caret.
+`mode`, `value`, and `fullscreen` are optional. Omit them for internal state; pass them to control from the parent. Chrome includes a File menu (Save, Load, and Print), an Edit menu (Undo, Redo, and Page properties), an Insert menu (Link, Bookmark, Image, Audio, YouTube video, Table, Horizontal line, and Page break), a Table menu (Insert table, row and column items, Merge cells, Unmerge cells, and table/cell/row properties), a View menu (Visual, HTML, Toolbar customize and position, Zoom, Light/Dark mode, Preview, Read aloud, and Full screen), and a Format menu (paragraph styles, font, clear formatting, paragraph, and image properties), unless `menuVisible` is `false`. The icon toolbar has File (Save and Load), Print, Edit (Undo and Redo), Insert (Link, Bookmark, Image, Table, and Horizontal line), Table (Merge cells and Unmerge cells), Font, Align, Paragraph, and View (Visual | HTML | Preview | Read aloud) groups, with Full screen pinned last, unless `toolbarVisible` is `false`. Hide both to drop the chrome slot entirely. View → Toolbar → Position docks the icon toolbar (the menu bar stays at the top). Top and bottom wrap onto multiple rows when they cannot fit on one line; Full screen stays last, pinned to the right of the first row. Left and right stay a single column and grow the editor instead of wrapping into extra columns. Full screen covers the host page with a fixed overlay; an X control (and Escape) returns to the in-page layout. Visual and HTML mode stay independent of the overlay. By default, Save writes the current document to an HTML file and Load replaces it from an HTML file; pass `onSave` and/or `onOpen` to delegate to host callbacks instead (see [Save and open](#save-and-open)). Dropping an `.html` / `.htm` file onto the document surface does the same as Load, unless `disableHtmlFileDrop` is set. Print opens the browser print dialog for the document HTML only (not the editor chrome). Preview (View menu and View icon group) opens a large dialog with a scrollable rendering of the current document HTML. Read aloud (View menu and View icon group) uses the browser’s built-in speech synthesis to read the current selection, or the full document when nothing is selected; click again to stop. Undo and Redo walk document HTML history; they are grayed out when there is nothing to undo or redo. The File, Edit, and Insert menu items use the same icons as the toolbar buttons where both exist. Link wraps the selection (or inserts the URL as the visible text at the caret) in an `<a href>` tag; an optional title becomes the native hover tooltip, and opening in a new tab sets `target="_blank"`. Bookmark inserts a named destination (`id`) at the caret or around the selection. Audio and YouTube video are available from the Insert menu only (no toolbar buttons). Horizontal line inserts an `<hr>` at the caret. Page break inserts a hard print break at the caret (Insert → Page break, or Ctrl/Cmd+Enter in visual mode). Content after the break starts on a new printed page. Serialized HTML uses inline `break-after: page` / `page-break-after: always` on a `<div>` — distinct from **Insert → Page**, which adds a new editor page when `enableMultiPages` is on.
 
 `menuColor`, `menuBackground`, `menuFontSize`, and `menuFontFamily` restyle the dropdown menu bar and panels only — not the icon toolbar. `border` is the outer editor box and is ignored in fullscreen. Custom menu fonts must already be available on the page.
 
 The toolbar Font dropdown lists web-safe faces (Arial, Georgia, Times New Roman, and the rest of the usual stacks). Choose **Default** to clear an authored `font-family` so the text inherits. Applied faces are written as inline `style="font-family: …"` on the selection (or the page shell from Page properties).
 
+### Custom CSS
+
+Format → Font → **Custom CSS** (and the Custom CSS icon in the Font toolbar group) opens a dialog with a multi-line textarea. With text selected or the caret inside styled text, existing inline CSS is pre-filled — one declaration per line, split at each `;`. On **OK**, declarations are merged onto the current inline styles (matching property names are overridden; others are kept). Use an empty value (e.g. `color:`) to remove a property. The result is stored as compressed one-line inline CSS on a `<span>`. With only a caret (no selection), the CSS applies to the next characters you type. An empty textarea is a no-op. Visual mode only.
+
+```tsx
+import { Editor } from 'commspliant-html-editor'
+
+<Editor />
+// Format → Font → Custom CSS, or the Custom CSS toolbar button
+```
+
+### Page properties
+
+Edit → Page → **Page properties** opens a dialog with **Font**, **Paragraph**, and **Print** tabs. Paragraph sub-tabs include **Spacing**, **Border**, **Background** (fill color and page opacity), and **Background Image**. The **Print** tab edits `@page` size, orientation, and margins. In visual mode, the white editing surface previews that page size and print margins on screen (display-only; serialized HTML is unchanged). Use **View → Zoom** for screen-only fit and percentage zoom; zoom is not stored in the document.
+
+The first time page properties are applied, content is wrapped in a single `<div data-page>` shell with `width: 100%` and `height: 100%`. Background **color** is written on that shell. Background **image** uses the same file, URL, or custom picker as Insert → Image, plus independent width and height (default width `100%`, height unset), and opacity, fit, and position controls (the same options as Image properties → Advanced). Rotation is not supported for page backgrounds. Width and height write `background-size`; keyword fit values (`cover`, `contain`) replace those dimensions.
+
+When a background image is set, a single managed first child `<div id="commspliant-background" data-page-bg contenteditable="false">` holds the image layer so image opacity does not fade page text. If that id already exists in the editor, it is reused and extras are removed. The layer sits behind content (`z-index: -1`) so the document stays editable:
+
+```html
+<div data-page style="width:100%;height:100%;position:relative;isolation:isolate;background-color:#fff">
+  <div id="commspliant-background" data-page-bg contenteditable="false"
+       style="position:absolute;inset:0;z-index:-1;pointer-events:none;user-select:none;background-image:url(&quot;https://example.com/bg.png&quot;);background-size:cover;background-position:center;background-repeat:no-repeat;opacity:0.9"></div>
+  <p>Hello</p>
+</div>
+```
+
+The visual editor holder mirrors the shell fill and background image for display only; serialized `value` HTML is unchanged by that paint step.
+
+```tsx
+import { Editor } from 'commspliant-html-editor'
+
+<Editor />
+// Edit → Page → Page properties → Paragraph → Background Image
+```
+
 ### Editor chrome
 
 Show or hide the menu bar and icon toolbar, and control the full-screen overlay from the host. View → Toolbar → Position docks the icon toolbar; the menu bar stays at the top. Top and bottom wrap onto multiple rows when they cannot fit on one line; Full screen stays last, pinned to the right of the first row. Left and right stay a single column.
 
-On the visual surface, a mouse right-click opens the editor context menu (cut, copy, font and paragraph properties, and table items when the caret is in a table). A touch or pen long-press does not; phones keep the native selection handles and OS Copy / Paste callout so text can be selected.
+On the visual surface, a mouse right-click opens the editor context menu (cut, copy, font and paragraph properties, and table items — including merge and unmerge — when the caret is in a table). A touch or pen long-press does not; phones keep the native selection handles and OS Copy / Paste callout so text can be selected.
 
 ```tsx
 import { useState } from 'react'
@@ -120,14 +173,18 @@ import { Editor } from 'commspliant-html-editor'
 
 Pass `allowedChrome` to show only the menus and icon-toolbar buttons the host allows. Omit the prop (or either field) to leave that surface unfiltered.
 
-The two lists are independent: hiding the File menu does not hide Save on the toolbar, and hiding the Print button does not hide File → Print. `menus` is top-level menu ids only: `file`, `edit`, `insert`, `view`, and `format` (plus any custom menu id from `customActions`). `toolbar` is icon-toolbar item ids:
+The two lists are independent: hiding the File menu does not hide Save on the toolbar, and hiding the Print button does not hide File → Print. `menus` is top-level menu ids only: `file`, `edit`, `insert`, `table`, `view`, and `format` (plus any custom menu id from `customActions`). `toolbar` is icon-toolbar item ids:
+
+`save`, `open`, `print`, `undo`, `redo`, `link`, `bookmark`, `image`, `table`, `horizontalRule`, `mergeCells`, `unmergeCells`, `fontFamily`, `paragraphStyle`, `fontSize`, `fontColor`, `highlightColor`, `customCss`, `formatBrush`, `bold`, `italic`, `underline`, `strikethrough`, `clearFormatting`, `alignLeft`, `alignCenter`, `alignRight`, `alignJustify`, `indent`, `outdent`, `bulletList`, `numberedList`, `visual`, `html`, `preview`, `readAloud`, `fullscreen`
 
-`save`, `open`, `print`, `undo`, `redo`, `link`, `bookmark`, `image`, `table`, `horizontalRule`, `fontFamily`, `paragraphStyle`, `fontSize`, `fontColor`, `highlightColor`, `bold`, `italic`, `underline`, `strikethrough`, `clearFormatting`, `alignLeft`, `alignCenter`, `alignRight`, `alignJustify`, `indent`, `outdent`, `bulletList`, `numberedList`, `visual`, `html`, `preview`, `fullscreen`
+The **Format brush** icon (`formatBrush`) is toolbar-only. Select source text, click the brush to copy inline character formatting (bold, italic, underline, strikethrough, font, size, color, highlight, custom CSS), then select target text to apply. Click the brush again or click it without a selection to cancel.
 
 If `toolbar` is set, custom action ids must be listed to appear on the icon bar.
 
 Empty arrays hide that surface (`menus: []` shows no dropdowns; `toolbar: []` shows no icons). The right-click context menu is not filtered. Commands stay registered; this only hides chrome.
 
+Page properties (including the Print / `@page` tab) live under **Edit → Page**. Hosts that allow only `format` in `allowedChrome` will not show Page properties unless `edit` is included too.
+
 View → Toolbar → Customize toolbar and its persistence still work as they do today, on the allowed toolbar subset. The dialog lists only allowed icon-toolbar items.
 
 ```tsx
@@ -295,7 +352,7 @@ let stored: CustomParagraphStyle[] = []
 | `id` | `string` | Stable id. The dialog assigns one on create |
 | `name` | `string` | Visible name. Always trimmed and non-empty on save |
 | `font` | `CustomParagraphStyleFont` | Size, unit, marks, family, and colors captured by the dialog |
-| `paragraph` | `CustomParagraphStyleParagraph` | Optional paragraph box: align, list, margin, padding, line-height, border, radius, shadow, background, opacity |
+| `paragraph` | `CustomParagraphStyleParagraph` | Optional paragraph box: align, list, margin, padding, line-height, border, radius, shadow, background, opacity, and page-break (`breakInside`, `breakAfter`, `breakBefore`) |
 
 Omit all three props to keep only the built-in styles.
 
@@ -329,6 +386,123 @@ import { Editor } from 'commspliant-html-editor'
 />
 ```
 
+### Save and open
+
+By default, File → Save and the Save toolbar button write the document to a local HTML file (browser save picker or download). File → Open and the Open toolbar button load from a local HTML file. Omit both callbacks to keep that behavior.
+
+Pass `onSave` to persist through the host instead of the built-in file picker. It receives the current document HTML (same as `onChange`, after `transformHtml`) and is awaited.
+
+Pass `onOpen` to load through the host instead of the built-in file picker. Return document HTML to replace the editor, or `null` to cancel. The callback is awaited. HTML file drag-drop is unchanged — it still reads a local file and does not call `onOpen`.
+
+The two props are independent: set only `onSave` to keep Open on the local picker, or only `onOpen` to keep Save on the local picker.
+
+```tsx
+import { Editor } from 'commspliant-html-editor'
+
+<Editor
+  defaultValue="<p>Hello</p>"
+  onSave={async (html) => {
+    await fetch('/api/documents/current', { method: 'PUT', body: html })
+  }}
+  onOpen={async () => {
+    const response = await fetch('/api/documents/current')
+    if (!response.ok) return null
+    return response.text()
+  }}
+/>
+```
+
+### Multi-page editing
+
+Set `enableMultiPages` to edit several independent HTML pages in visual mode. Pages appear stacked with toolbar-colored gaps between them. Use Insert → Page to add a page after the focused one. Edit → Page → Page properties includes a Print tab for `@page` size, orientation, and margins; Reset removes the print rule from the active page.
+
+When multi-page mode is off (default), behavior is unchanged.
+
+**HTML source mode** shows all pages in one textarea, separated by:
+
+```html
+<!-- wysiwyg-page-separator -->
+```
+
+**Persistence:**
+
+- Built-in File → Save / Open operate on the **focused page only** (single `.html` file).
+- Host `onSave`, `onOpen`, and `onAutoSave` receive **all pages** as a `string[]` when `enableMultiPages` is true.
+- Use `onPagesChange` for controlled multi-page state. Export helpers: `splitPagesFromHtml`, `joinPagesToHtml`, and `PAGE_SEPARATOR` from the package.
+
+```tsx
+import { useState } from 'react'
+import { Editor } from 'commspliant-html-editor'
+
+export function MultiPageEditor() {
+  const [pages, setPages] = useState(['<p>Page one</p>', '<p>Page two</p>'])
+
+  return (
+    <Editor
+      enableMultiPages
+      pages={pages}
+      onPagesChange={(nextPages) => setPages(nextPages)}
+      onSave={async (payload) => {
+        if (Array.isArray(payload)) {
+          await fetch('/api/documents/pages', {
+            method: 'PUT',
+            body: JSON.stringify(payload),
+          })
+        }
+      }}
+    />
+  )
+}
+```
+
+### Page break
+
+In visual mode, use **Insert → Page break** or **Ctrl/Cmd+Enter** to insert a hard print break at the caret. The editor shows a dashed line; serialized HTML is a `<div>` with inline `break-after: page` and `page-break-after: always`. Content after the break starts on a new page when printing.
+
+This is not the same as **Insert → Page** (multi-page mode), which adds a separate editor page surface.
+
+### Comments
+
+Set `enableComments` to add lightweight comment threads anchored in the document with `data-comment-thread` markers. Thread metadata (`CommentThread[]`) is separate from document HTML — use `comments` / `onCommentsChange` to persist it.
+
+- **Add comment** (toolbar Insert group and Insert → Comment) wraps the selection or marks the selected image, then opens the comment panel.
+- **Show/Hide comments** (View menu and View icon group) toggles highlight styling only; thread data and anchors remain.
+- **`commentAuthor`** (`{ userId, userName }`) is required to enable Post in the panel.
+
+**Sanitized HTML:** export `stripCommentAnchors` from the package to remove comment-only spans and attributes for published document HTML:
+
+```tsx
+import { Editor, stripCommentAnchors } from 'commspliant-html-editor'
+
+// Editor HTML may include anchors:
+// <p>Price was <span data-comment-thread="cmt_…">£150</span> last week.</p>
+
+const clean = stripCommentAnchors(html)
+// <p>Price was £150 last week.</p>
+```
+
+**Read-only documents:** with `readOnly` and `enableComments`, users can still add and reply to comments. Anchor DOM updates fire `onCommentsChange` only — not `onChange`. Supply `value` and `comments` on load; the editor re-applies anchors for highlights.
+
+```tsx
+import { useState } from 'react'
+import { Editor, type CommentThread } from 'commspliant-html-editor'
+
+export function ReviewEditor() {
+  const [comments, setComments] = useState<CommentThread[]>([])
+
+  return (
+    <Editor
+      value="<p>Immutable version</p>"
+      readOnly
+      enableComments
+      commentAuthor={{ userId: 'u1', userName: 'Reviewer' }}
+      comments={comments}
+      onCommentsChange={setComments}
+    />
+  )
+}
+```
+
 ### Custom actions
 
 Pass a `customActions` array to add host buttons, menu items, or both. Labels and tooltips are your copy — the library does not translate them.
@@ -426,6 +600,88 @@ Omit `customImagePicker` to keep File and URL only. Set `disableBuiltinImageInse
 
 `insertImage` uses the same insert path as File and URL: an `<img>` with inline `max-width: 100%; height: auto`, then any host `css`. `src` must be `http(s)`, a relative path, or a raster `data:` URL.
 
+`onPick` from Page properties (Edit → Page → Page properties → Background Image) leaves the editor dialog open so the picked URL can fill the draft. If your picker is a modal overlay, give it a `z-index` above editor dialogs (`1200`).
+
+### Custom audio picker
+
+Pass `customAudioPicker` to add a third Insert audio source. Labels are your copy — the library does not translate them. When the host finishes picking, call the `insertAudio` function received by `onPick`.
+
+```tsx
+import { Editor, type CustomAudioPicker } from 'commspliant-html-editor'
+
+const library: CustomAudioPicker = {
+  text: 'Library',
+  description: 'Choose from your audio library.',
+  buttonCaption: 'Open library',
+  onPick: (insertAudio) => {
+    openHostLibrary().then((picked) => {
+      insertAudio({
+        src: picked.url,
+        title: picked.title,
+        css: 'width: 100%',
+      })
+    })
+  },
+}
+
+<Editor customAudioPicker={library} />
+```
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `text` | `string` | Third source / navigation button label |
+| `description` | `string` | Shown on the custom source panel |
+| `buttonCaption` | `string` | Caption of the button that starts the host picker |
+| `onPick` | `(insertAudio) => void` | Called when that button is clicked. Call `insertAudio` with a URL or audio `data:` URL, plus optional `title` and inline `css` |
+
+Omit `customAudioPicker` to keep File and URL only. Set `disableBuiltinAudioInsert` to skip the dialog: Insert → Audio calls `onPick` immediately.
+
+```tsx
+<Editor customAudioPicker={library} disableBuiltinAudioInsert />
+```
+
+`insertAudio` uses the same insert path as File and URL: an `<audio controls>` with inline `max-width: 100%`, then any host `css`. `src` must be `http(s)`, a relative path, or an audio `data:` URL.
+
+### Custom video picker
+
+Pass `customVideoPicker` to add a third Insert YouTube video source. Labels are your copy — the library does not translate them. When the host finishes picking, call the `insertVideo` function received by `onPick`.
+
+```tsx
+import { Editor, type CustomVideoPicker } from 'commspliant-html-editor'
+
+const library: CustomVideoPicker = {
+  text: 'Library',
+  description: 'Choose from your video library.',
+  buttonCaption: 'Open library',
+  onPick: (insertVideo) => {
+    openHostLibrary().then((picked) => {
+      insertVideo({
+        src: picked.url,
+        title: picked.title,
+        css: 'max-width: 100%',
+      })
+    })
+  },
+}
+
+<Editor customVideoPicker={library} />
+```
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `text` | `string` | Third source / navigation button label |
+| `description` | `string` | Shown on the custom source panel |
+| `buttonCaption` | `string` | Caption of the button that starts the host picker |
+| `onPick` | `(insertVideo) => void` | Called when that button is clicked. Call `insertVideo` when the host picker finishes |
+
+Omit `customVideoPicker` to keep URL only. Set `disableBuiltinVideoInsert` to skip the dialog: Insert → YouTube video calls `onPick` immediately.
+
+```tsx
+<Editor customVideoPicker={library} disableBuiltinVideoInsert />
+```
+
+The built-in dialog accepts YouTube watch, embed, shorts, and `youtu.be` URLs and inserts an `<iframe>` embed with inline sizing. From the host picker, a YouTube URL inserts the same iframe; other `http(s)` video URLs insert a `<video controls>` element. Both use inline styles in the serialized HTML.
+
 ### Customize toolbar
 
 View → Toolbar → Customize toolbar shows every icon-toolbar group (or only the items in `allowedChrome.toolbar` when that list is set). Uncheck an item to hide it on the icon toolbar (menus stay the same). Drag groups — not individual buttons — to reorder them. Full screen stays pinned last. Reset restores the library default.

package/dist/404.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>HTML editor Playground</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Source+Serif+4:ital,opsz,wght@0,8..60,400;0,8..60,500;0,8..60,600;0,8..60,700;1,8..60,400&family=Inter:ital,wght@0,400;0,500;0,600;0,700;1,400&display=swap"
+      rel="stylesheet"
+    />
+    <script type="module" crossorigin src="/assets/index-8mpvnzOy.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-Cu8klpl0.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>