domma-cms 1.8.32 → 1.8.34

package/plugins/docs/admin/lib/editor.js

@@ -0,0 +1,851 @@
+/**
+ * The document editing surface.
+ *
+ * One mode since 2.0: a contenteditable region whose content is stored as
+ * HTML. Markdown is a way of typing here (shortcuts), not a storage format.
+ * Everything above this module - autosave, find and replace, version restore,
+ * the Outline - calls getValue/setValue/onChange/getSurface, so none of it
+ * has to know how the surface works.
+ *
+ * There is deliberately no third-party editor. A plugin is copied to every
+ * site that installs it, and a dependency it cannot vendor breaks on the site
+ * with no network egress. `document.execCommand` is formally deprecated and
+ * still the only way to get rich editing (with a working undo stack) out of a
+ * contenteditable without shipping a framework. Every call is guarded: where
+ * a browser drops one, that button stops working and typing does not.
+ *
+ * Tables and checklists are plain DOM work on top, and tell the listeners.
+ *
+ * @module docs/admin/lib/editor
+ */
+
+import {markdownTrigger} from '/plugins/docs/admin/lib/shortcuts.js';
+import {sanitizeHtml, promptWith} from '/plugins/docs/admin/lib/api.js';
+
+/** Icons Domma does not ship, drawn here (16px, currentColor). */
+const SVG = {
+    'align-left': '<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="M3 6h18M3 12h12M3 18h16"/></svg>',
+    'align-center': '<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="M3 6h18M6 12h12M4 18h16"/></svg>',
+    'align-right': '<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="M3 6h18M9 12h12M5 18h16"/></svg>',
+    table: '<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="4" width="18" height="16" rx="1"/><path d="M3 10h18M3 15h18M9 4v16M15 4v16"/></svg>',
+    highlight: '<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M9 11l-5 5v3h3l5-5M14 6l4 4M9 11l5-5 4 4-5 5z"/><path d="M3 22h18" stroke-width="3" stroke="#f5c518"/></svg>'
+};
+
+/** The toolbar: groups of tools. `cmd` goes to execCommand; `block` wraps in a block tag; `action` is ours. */
+const TOOLS = [
+    [{kind: 'blocks'}],
+    [
+        {icon: 'undo', title: 'Undo (Ctrl+Z)', cmd: 'undo'},
+        {icon: 'redo', title: 'Redo (Ctrl+Y)', cmd: 'redo'}
+    ],
+    [
+        {icon: 'bold', title: 'Bold (Ctrl+B)', cmd: 'bold', state: 'bold'},
+        {icon: 'italic', title: 'Italic (Ctrl+I)', cmd: 'italic', state: 'italic'},
+        {icon: 'underline', title: 'Underline (Ctrl+U)', cmd: 'underline', state: 'underline'},
+        {icon: 'strikethrough', title: 'Strikethrough', cmd: 'strikeThrough', state: 'strikeThrough'},
+        {svg: 'highlight', title: 'Highlight', action: 'highlight'},
+        {icon: 'code', title: 'Inline code', action: 'inlineCode'}
+    ],
+    [
+        {svg: 'align-left', title: 'Align left', cmd: 'justifyLeft', state: 'justifyLeft'},
+        {svg: 'align-center', title: 'Centre', cmd: 'justifyCenter', state: 'justifyCenter'},
+        {svg: 'align-right', title: 'Align right', cmd: 'justifyRight', state: 'justifyRight'}
+    ],
+    [
+        {icon: 'list-bullet', title: 'Bulleted list', cmd: 'insertUnorderedList'},
+        {icon: 'list-numbered', title: 'Numbered list', cmd: 'insertOrderedList'},
+        {icon: 'check-square', title: 'Checklist', action: 'checklist'},
+        {icon: 'quote', title: 'Quote', block: 'blockquote'}
+    ],
+    [
+        {icon: 'link', title: 'Link (Ctrl+K)', action: 'link'},
+        {icon: 'image', title: 'Image', action: 'image'},
+        {svg: 'table', title: 'Table', action: 'table'},
+        {icon: 'minus', title: 'Horizontal line', cmd: 'insertHorizontalRule'},
+        {icon: 'clear-format', title: 'Clear formatting', cmd: 'removeFormat'}
+    ]
+];
+
+const BLOCKS = [['p', 'Normal text'], ['h1', 'Heading 1'], ['h2', 'Heading 2'], ['h3', 'Heading 3'], ['h4', 'Heading 4'], ['pre', 'Code block'], ['blockquote', 'Quote']];
+
+/** The actions applyNamed (2.8) offers add-ons - the same tools the toolbar applies. */
+const NAMED_TOOLS = {
+    bold: {cmd: 'bold'},
+    italic: {cmd: 'italic'},
+    underline: {cmd: 'underline'},
+    strike: {cmd: 'strikeThrough'},
+    highlight: {action: 'highlight'},
+    inlineCode: {action: 'inlineCode'},
+    link: {action: 'link'},
+    clearFormat: {cmd: 'removeFormat'},
+    bulletList: {cmd: 'insertUnorderedList'},
+    numberedList: {cmd: 'insertOrderedList'},
+    checklist: {action: 'checklist'},
+    quote: {block: 'blockquote'}
+};
+
+/** Sanitise HTML on its way into the surface (see api.js sanitizeHtml). */
+const safeHtml = (html) => sanitizeHtml(html);
+
+const BLOCK_SEL = 'p,div,h1,h2,h3,h4,h5,h6,li,pre,blockquote,td,th';
+
+export class DocEditor {
+    /**
+     * @param {HTMLElement} surfaceHost where the page goes
+     * @param {HTMLElement} toolbarHost where the toolbar goes
+     * @param {object}      [options]
+     * @param {Function}    [options.pickImage] async () => url|null (the Media picker)
+     * @param {Function}    [options.uploadImage] async (File) => url|null
+     */
+    constructor(surfaceHost, toolbarHost, options = {}) {
+        this.host = surfaceHost;
+        this.toolbarHost = toolbarHost;
+        this.options = options;
+        this.surface = null;
+        this.toolbar = null;
+        this.readOnly = false;
+        this.suggesting = false;
+        this._listeners = [];
+        this._quiet = false;
+        this._cleanup = [];
+    }
+
+    /** Build the toolbar and the surface. Safe to call once. */
+    init() {
+        if (this.surface) return this;
+        this.toolbar = this._buildToolbar();
+        this.toolbarHost.replaceChildren(this.toolbar);
+        this.surface = this._buildSurface();
+        this.host.replaceChildren(this.surface);
+        try { document.execCommand('defaultParagraphSeparator', false, 'p'); } catch { /* old engine */ }
+        if (typeof Domma !== 'undefined' && Domma.icons) Domma.icons.scan(this.toolbar);
+        const onSel = () => this._syncToolbar();
+        document.addEventListener('selectionchange', onSel);
+        this._cleanup.push(() => document.removeEventListener('selectionchange', onSel));
+        return this;
+    }
+
+    destroy() {
+        this._cleanup.forEach(fn => { try { fn(); } catch { /* gone */ } });
+        this._cleanup = [];
+        this._listeners = [];
+    }
+
+    /** Kept for find and replace, which once had a Markdown surface to handle. */
+    isMarkdown() { return false; }
+
+    getSurface() { return this.surface; }
+
+    getValue() { return this.surface ? this.surface.innerHTML : ''; }
+
+    /** Replace the content without reporting a change. */
+    setValue(value) {
+        if (!this.surface) return this;
+        this._quiet = true;
+        this.surface.innerHTML = safeHtml(value || '');
+        this._quiet = false;
+        return this;
+    }
+
+    /**
+     * Read-only: nothing typed, no toolbar. Viewers, a document someone else
+     * is editing, and a document in Trash all open this way.
+     */
+    setReadOnly(on) {
+        this.readOnly = Boolean(on);
+        if (this.surface) {
+            this.surface.contentEditable = on ? 'false' : 'true';
+            this.surface.setAttribute('aria-readonly', on ? 'true' : 'false');
+        }
+        this._syncTools();
+        return this;
+    }
+
+    /**
+     * Suggesting (2.5, Docs Pro): the text stays editable, but everything that
+     * changes layout or formatting is off - the toolbar, Markdown shortcuts,
+     * Tab, the table menu, Docs' own paste and drop - so an add-on can turn
+     * each change into a suggestion from the browser's beforeinput events.
+     */
+    setSuggesting(on) {
+        this.suggesting = Boolean(on);
+        this.surface?.classList.toggle('is-suggesting', this.suggesting);
+        this._syncTools();
+        return this;
+    }
+
+    _syncTools() {
+        const off = this.readOnly || this.suggesting;
+        this.toolbar?.classList.toggle('is-disabled', off);
+        this.toolbar?.querySelectorAll('button, select').forEach(b => { b.disabled = off; });
+    }
+
+    /** @returns {Function} unsubscribe */
+    onChange(callback) {
+        if (typeof callback !== 'function') return () => {};
+        this._listeners.push(callback);
+        return () => {
+            const i = this._listeners.indexOf(callback);
+            if (i > -1) this._listeners.splice(i, 1);
+        };
+    }
+
+    focus() { this.surface?.focus(); return this; }
+
+    /** Tell the listeners the content moved (find and replace edits the surface directly). */
+    notifyChanged() { this._emitChange(); }
+
+    /** Plain text of the document as shown - for word and character counts. */
+    text() { return this.surface ? this.surface.innerText || '' : ''; }
+
+    /** The heading elements, in order - the Outline scrolls to these. */
+    headings() {
+        return this.surface ? [...this.surface.querySelectorAll('h1,h2,h3,h4')] : [];
+    }
+
+    // ------------------------------------------------------------ internals
+
+    _emitChange() {
+        if (this._quiet) return;
+        this._listeners.forEach(fn => {
+            try { fn(); } catch (err) { console.error('[docs] change listener failed', err); }
+        });
+    }
+
+    _buildToolbar() {
+        const bar = document.createElement('div');
+        bar.className = 'docs-toolbar';
+        bar.setAttribute('role', 'toolbar');
+        bar.setAttribute('aria-label', 'Formatting');
+        TOOLS.forEach((group) => {
+            const g = document.createElement('div');
+            g.className = 'docs-toolbar__group';
+            for (const tool of group) {
+                if (tool.kind === 'blocks') { g.appendChild(this._buildBlockSelect()); continue; }
+                const btn = document.createElement('button');
+                btn.type = 'button';
+                btn.className = 'docs-tool';
+                btn.title = tool.title;
+                btn.setAttribute('aria-label', tool.title);
+                if (tool.state) btn.dataset.state = tool.state;
+                if (tool.svg) btn.innerHTML = SVG[tool.svg];
+                else {
+                    const i = document.createElement('span');
+                    i.dataset.icon = tool.icon;
+                    i.dataset.iconSize = '16';
+                    btn.appendChild(i);
+                }
+                // mousedown, not click: a click blurs the surface first and a
+                // lost selection is a command applied to nothing.
+                btn.addEventListener('mousedown', (e) => {
+                    e.preventDefault();
+                    if (!this.readOnly && !this.suggesting) this._applyTool(tool);
+                });
+                // Keyboard users still get the button.
+                btn.addEventListener('keydown', (e) => {
+                    if ((e.key === 'Enter' || e.key === ' ') && !this.readOnly && !this.suggesting) { e.preventDefault(); this._applyTool(tool); }
+                });
+                g.appendChild(btn);
+            }
+            bar.appendChild(g);
+        });
+        return bar;
+    }
+
+    _buildBlockSelect() {
+        const sel = document.createElement('select');
+        sel.className = 'docs-tool-select';
+        sel.title = 'Text style';
+        sel.setAttribute('aria-label', 'Text style');
+        for (const [tag, label] of BLOCKS) {
+            const o = document.createElement('option');
+            o.value = tag;
+            o.textContent = label;
+            sel.appendChild(o);
+        }
+        // Remember the selection before the dropdown takes focus.
+        let saved = null;
+        sel.addEventListener('mousedown', () => { saved = this._saveRange(); });
+        sel.addEventListener('focus', () => { saved = saved || this._saveRange(); });
+        sel.addEventListener('change', () => {
+            this._restoreRange(saved);
+            saved = null;
+            this._exec('formatBlock', `<${sel.value}>`);
+            this._emitChange();
+        });
+        this.blockSelect = sel;
+        return sel;
+    }
+
+    _buildSurface() {
+        const el = document.createElement('div');
+        el.className = 'docs-surface';
+        el.contentEditable = 'true';
+        el.spellcheck = true;
+        el.setAttribute('role', 'textbox');
+        el.setAttribute('aria-multiline', 'true');
+        el.setAttribute('aria-label', 'Document');
+        el.dataset.placeholder = 'Start writing - type # and a space for a heading, - for a list, [] for a checklist';
+
+        el.addEventListener('input', () => {
+            this._syncEmpty();
+            this._emitChange();
+        });
+        el.addEventListener('keydown', (e) => this._onKeydown(e));
+        el.addEventListener('paste', (e) => this._onPaste(e));
+        el.addEventListener('drop', (e) => this._onDrop(e));
+        // A checklist item ticks when its box (the marker to the left) is clicked.
+        el.addEventListener('mousedown', (e) => {
+            const li = e.target.closest?.('ul[data-type="checklist"] > li');
+            if (!li || !el.contains(li) || this.readOnly || this.suggesting) return;
+            const r = li.getBoundingClientRect();
+            if (e.clientX < r.left + 2 || e.clientX > r.left + 26) return;
+            e.preventDefault();
+            li.dataset.checked = li.dataset.checked === 'true' ? 'false' : 'true';
+            this._emitChange();
+        });
+        // Links in an editable surface do nothing on click; Ctrl+click opens.
+        el.addEventListener('click', (e) => {
+            const a = e.target.closest?.('a[href]');
+            if (a && (e.ctrlKey || e.metaKey || this.readOnly)) {
+                e.preventDefault();
+                window.open(a.href, '_blank', 'noopener');
+            }
+        });
+        return el;
+    }
+
+    _syncEmpty() {
+        const empty = !this.surface.textContent.trim() && !this.surface.querySelector('img,table,hr,li');
+        this.surface.classList.toggle('is-empty', empty);
+    }
+
+    /** Toolbar buttons show what the caret is in. */
+    _syncToolbar() {
+        if (!this.surface || !this.toolbar) return;
+        const sel = document.getSelection();
+        if (!sel?.anchorNode || !this.surface.contains(sel.anchorNode)) return;
+        this.toolbar.querySelectorAll('[data-state]').forEach((b) => {
+            let on = false;
+            try { on = document.queryCommandState(b.dataset.state); } catch { /* unsupported */ }
+            b.classList.toggle('is-on', on);
+            b.setAttribute('aria-pressed', on ? 'true' : 'false');
+        });
+        const block = this._currentBlock();
+        const tag = block?.closest('h1,h2,h3,h4,pre,blockquote')?.tagName.toLowerCase() || 'p';
+        if (this.blockSelect && this.blockSelect.value !== tag && document.activeElement !== this.blockSelect) {
+            this.blockSelect.value = BLOCKS.some(([t]) => t === tag) ? tag : 'p';
+        }
+    }
+
+    _currentBlock() {
+        const sel = document.getSelection();
+        let node = sel?.anchorNode;
+        if (!node || !this.surface.contains(node)) return null;
+        if (node.nodeType === 3) node = node.parentElement;
+        const block = node.closest(BLOCK_SEL);
+        return block && this.surface.contains(block) ? block : null;
+    }
+
+    _saveRange() {
+        const sel = document.getSelection();
+        if (!sel?.rangeCount) return null;
+        const r = sel.getRangeAt(0);
+        return this.surface.contains(r.commonAncestorContainer) ? r.cloneRange() : null;
+    }
+
+    _restoreRange(range) {
+        this.surface.focus();
+        if (!range) return;
+        const sel = document.getSelection();
+        sel.removeAllRanges();
+        sel.addRange(range);
+    }
+
+    /** Text from the start of the caret's block to the caret. */
+    _textBeforeCaret(block) {
+        const sel = document.getSelection();
+        if (!sel?.rangeCount || !sel.isCollapsed) return null;
+        const r = document.createRange();
+        r.setStart(block || this.surface, 0);
+        r.setEnd(sel.anchorNode, sel.anchorOffset);
+        return r.toString();
+    }
+
+    _onKeydown(e) {
+        if (this.readOnly || this.suggesting) return;
+        if ((e.ctrlKey || e.metaKey) && !e.shiftKey && !e.altKey && e.key.toLowerCase() === 'k') {
+            e.preventDefault();
+            this._insertLink();
+            return;
+        }
+        // Tab indents a list item; in a table it moves between cells.
+        if (e.key === 'Tab') {
+            const cell = this._currentBlock()?.closest('td,th');
+            if (cell) { e.preventDefault(); this._moveCell(cell, e.shiftKey ? -1 : 1); return; }
+            if (this._currentBlock()?.closest('li')) {
+                e.preventDefault();
+                this._exec(e.shiftKey ? 'outdent' : 'indent');
+                this._emitChange();
+            }
+            return;
+        }
+        // A new checklist item starts unticked, whatever the one above says.
+        if (e.key === 'Enter' && !e.shiftKey) {
+            const li = this._currentBlock()?.closest('ul[data-type="checklist"] > li');
+            if (li) setTimeout(() => {
+                const now = this._currentBlock()?.closest('ul[data-type="checklist"] > li');
+                if (now && now !== li) now.dataset.checked = 'false';
+            });
+        }
+        if (e.key !== ' ' && e.key !== 'Enter') return;
+        if (e.ctrlKey || e.metaKey || e.altKey || e.shiftKey) return;
+        const block = this._lineBlock();
+        if (!block) return;
+        const before = this._textBeforeCaret(block);
+        if (before === null) return;
+        const hit = markdownTrigger(before, e.key);
+        if (!hit) return;
+        e.preventDefault();
+        this._applyShortcut(block, hit);
+        this._emitChange();
+        this._syncToolbar();
+    }
+
+    /**
+     * The paragraph the caret is on, as a direct child of the surface - made
+     * into a <p> first when the line is bare text (a contenteditable leaves
+     * its first line unwrapped). Null inside lists, tables, code and quotes:
+     * shortcuts only start new blocks from plain paragraphs.
+     */
+    _lineBlock() {
+        const sel = document.getSelection();
+        let node = sel?.anchorNode;
+        if (!node || !sel.isCollapsed || !this.surface.contains(node)) return null;
+        if (node === this.surface) node = this.surface.childNodes[Math.max(0, sel.anchorOffset - 1)] || this.surface.firstChild;
+        if (!node) return null;
+        let top = node;
+        while (top && top.parentNode !== this.surface) top = top.parentNode;
+        if (!top) return null;
+        if (top.nodeType === 1 && /^(P|DIV)$/.test(top.tagName)) return top;
+        if (top.nodeType === 1 && /^(UL|OL|TABLE|PRE|BLOCKQUOTE|H[1-6]|HR|FIGURE)$/.test(top.tagName)) return null;
+        // Bare inline content: wrap the run around the caret in a paragraph.
+        const inline = (n) => n && (n.nodeType === 3 || (n.nodeType === 1 && !/^(P|DIV|UL|OL|TABLE|PRE|BLOCKQUOTE|H[1-6]|HR|FIGURE|BR)$/.test(n.tagName)));
+        const run = [top];
+        let prev = top.previousSibling;
+        while (inline(prev)) { run.unshift(prev); prev = prev.previousSibling; }
+        let next = top.nextSibling;
+        while (inline(next)) { run.push(next); next = next.nextSibling; }
+        const anchor = sel.anchorNode;
+        const offset = sel.anchorOffset;
+        const p = document.createElement('p');
+        run[0].before(p);
+        run.forEach(n => p.appendChild(n));
+        if (p.contains(anchor)) {
+            const r = document.createRange();
+            r.setStart(anchor, offset);
+            r.collapse(true);
+            sel.removeAllRanges();
+            sel.addRange(r);
+        }
+        return p;
+    }
+
+    /** Remove the first `n` characters of a block's text, across its text nodes. */
+    _stripStart(block, n) {
+        const walker = document.createTreeWalker(block, NodeFilter.SHOW_TEXT);
+        let left = n;
+        let t;
+        while (left > 0 && (t = walker.nextNode())) {
+            const take = Math.min(left, t.data.length);
+            t.data = t.data.slice(take);
+            left -= take;
+        }
+    }
+
+    /** Put the caret at the start (or end) of `el`. */
+    _caretIn(el, atEnd = false) {
+        const r = document.createRange();
+        r.selectNodeContents(el);
+        r.collapse(!atEnd);
+        const sel = document.getSelection();
+        sel.removeAllRanges();
+        sel.addRange(r);
+    }
+
+    /**
+     * Turn the paragraph into what the shortcut asked for. Plain DOM work,
+     * not execCommand: a list made by execCommand inside a freshly emptied
+     * paragraph comes out nested in the <p>, which nothing can then edit.
+     */
+    _applyShortcut(block, {length, action}) {
+        this._stripStart(block, length);
+        const empty = !block.textContent.replace(/ /g, ' ').trim() && !block.querySelector('img');
+        const fill = (el) => {
+            if (empty) el.innerHTML = '<br>';
+            else while (block.firstChild) el.appendChild(block.firstChild);
+            return el;
+        };
+        let target;
+        switch (action.type) {
+            case 'block': {
+                target = fill(document.createElement(action.tag));
+                block.replaceWith(target);
+                break;
+            }
+            case 'ul':
+            case 'ol':
+            case 'checklist': {
+                const list = document.createElement(action.type === 'ol' ? 'ol' : 'ul');
+                const li = fill(document.createElement('li'));
+                if (action.type === 'checklist') { list.dataset.type = 'checklist'; li.dataset.checked = 'false'; }
+                list.appendChild(li);
+                block.replaceWith(list);
+                target = li;
+                break;
+            }
+            case 'hr': {
+                const hr = document.createElement('hr');
+                const p = document.createElement('p');
+                p.innerHTML = '<br>';
+                block.replaceWith(hr, p);
+                target = p;
+                break;
+            }
+            default: return;
+        }
+        this._caretIn(target, !empty);
+        this._syncEmpty();
+    }
+
+    _applyTool(tool) {
+        if (tool.action) {
+            switch (tool.action) {
+                case 'link': return this._insertLink();
+                case 'image': return this._insertImage();
+                case 'table': return this._insertTable();
+                case 'checklist': this._checklist(); break;
+                case 'highlight': this._highlight(); break;
+                case 'inlineCode': this._inlineCode(); break;
+                default: break;
+            }
+        } else if (tool.block) {
+            const inside = this._currentBlock()?.closest(tool.block);
+            this._exec('formatBlock', inside ? '<p>' : `<${tool.block}>`);
+        } else if (tool.cmd) {
+            this._exec(tool.cmd);
+        }
+        this._emitChange();
+        this._syncToolbar();
+    }
+
+    /** Toggle a checklist: a bulleted list marked as one, every item unticked. */
+    _checklist() {
+        const inList = this._currentBlock()?.closest('ul');
+        if (inList && inList.dataset.type === 'checklist') {
+            delete inList.dataset.type;
+            inList.querySelectorAll(':scope > li').forEach(li => li.removeAttribute('data-checked'));
+            return;
+        }
+        if (!inList) this._exec('insertUnorderedList');
+        const ul = this._currentBlock()?.closest('ul');
+        if (!ul) return;
+        ul.dataset.type = 'checklist';
+        ul.querySelectorAll(':scope > li').forEach(li => { if (!li.dataset.checked) li.dataset.checked = 'false'; });
+    }
+
+    _highlight() {
+        let on = false;
+        try { on = /rgb\(255, 243, 163\)|#fff3a3/i.test(document.queryCommandValue('hiliteColor') || document.queryCommandValue('backColor')); } catch { /* unsupported */ }
+        this._exec('styleWithCSS', true);
+        if (!this._exec('hiliteColor', on ? 'transparent' : '#fff3a3')) this._exec('backColor', on ? 'transparent' : '#fff3a3');
+        this._exec('styleWithCSS', false);
+    }
+
+    _inlineCode() {
+        const sel = document.getSelection();
+        if (!sel?.rangeCount) return;
+        const inCode = (sel.anchorNode?.nodeType === 3 ? sel.anchorNode.parentElement : sel.anchorNode)?.closest?.('code');
+        if (inCode && this.surface.contains(inCode) && !inCode.closest('pre')) {
+            inCode.replaceWith(document.createTextNode(inCode.textContent));
+            return;
+        }
+        const text = sel.toString();
+        if (!text) return;
+        const esc = text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+        this._exec('insertHTML', `<code>${esc}</code>`);
+    }
+
+    async _insertLink() {
+        const saved = this._saveRange();
+        const current = (saved?.commonAncestorContainer?.nodeType === 3 ? saved.commonAncestorContainer.parentElement : saved?.commonAncestorContainer)?.closest?.('a');
+        const url = await promptWith('Link address', {title: current ? 'Edit link' : 'Insert link', inputPlaceholder: 'https://example.com'}, current?.getAttribute('href') || '');
+        this._restoreRange(saved);
+        if (url === null || url === undefined) return;
+        const href = String(url).trim();
+        if (!href) { this._exec('unlink'); this._emitChange(); return; }
+        if (!/^(https?:|mailto:|tel:|\/|#)/i.test(href)) {
+            E.toast('Links must start with https://, mailto:, tel: or /', {type: 'warning'});
+            return;
+        }
+        if (saved && saved.collapsed && !current) {
+            const esc = href.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/"/g, '&quot;');
+            this._exec('insertHTML', `<a href="${esc}">${esc}</a>`);
+        } else {
+            this._exec('createLink', href);
+        }
+        this._emitChange();
+    }
+
+    async _insertImage() {
+        const saved = this._saveRange();
+        let url = null;
+        if (typeof this.options.pickImage === 'function') {
+            try { url = await this.options.pickImage(); } catch { url = null; }
+        } else {
+            url = await E.prompt('Image address', {title: 'Insert image', inputPlaceholder: 'https://… or /media/…'});
+        }
+        this._restoreRange(saved);
+        if (!url) return;
+        this._insertImageUrl(url);
+    }
+
+    _insertImageUrl(url, alt = '') {
+        const src = String(url).trim();
+        if (!/^(https?:\/\/|\/)/i.test(src)) return;
+        const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/"/g, '&quot;');
+        this._exec('insertHTML', `<img src="${esc(src)}" alt="${esc(alt)}">`);
+        this._emitChange();
+    }
+
+    async _insertTable() {
+        const saved = this._saveRange();
+        const answer = await E.prompt('Columns x rows, e.g. 3x4', {title: 'Insert table', inputValue: '3x3'});
+        this._restoreRange(saved);
+        const m = /^\s*(\d{1,2})\s*[x×*, ]\s*(\d{1,3})\s*$/i.exec(String(answer || ''));
+        if (!m) return;
+        const cols = Math.min(20, Math.max(1, Number(m[1])));
+        const rows = Math.min(200, Math.max(1, Number(m[2])));
+        const head = `<tr>${'<th><br></th>'.repeat(cols)}</tr>`;
+        const body = `<tr>${'<td><br></td>'.repeat(cols)}</tr>`.repeat(Math.max(0, rows - 1));
+        this._exec('insertHTML', `<table><thead>${head}</thead><tbody>${body}</tbody></table><p><br></p>`);
+        this._emitChange();
+    }
+
+    /** Menu items for the table under an element, for the editor's right-click menu; [] when not in a table. */
+    tableMenu(target) {
+        const cell = target?.closest?.('td,th');
+        if (!cell || !this.surface.contains(cell) || this.readOnly || this.suggesting) return [];
+        const row = cell.parentElement;
+        const table = cell.closest('table');
+        const col = [...row.children].indexOf(cell);
+        const done = () => this._emitChange();
+        const newRow = (like) => {
+            const tr = document.createElement('tr');
+            [...like.children].forEach(() => { const td = document.createElement('td'); td.innerHTML = '<br>'; tr.appendChild(td); });
+            return tr;
+        };
+        return [
+            {label: 'Row above', icon: 'chevron-up', action: () => { row.parentElement.insertBefore(newRow(row), row); done(); }},
+            {label: 'Row below', icon: 'chevron-down', action: () => {
+                const tr = newRow(row);
+                if (row.parentElement.tagName === 'THEAD') {
+                    let tb = table.querySelector('tbody');
+                    if (!tb) { tb = document.createElement('tbody'); table.appendChild(tb); }
+                    tb.insertBefore(tr, tb.firstChild);
+                } else row.after(tr);
+                done();
+            }},
+            {label: 'Column left', icon: 'chevron-left', action: () => { this._addColumn(table, col, 0); done(); }},
+            {label: 'Column right', icon: 'chevron-right', action: () => { this._addColumn(table, col, 1); done(); }},
+            {type: 'divider'},
+            {label: 'Delete row', icon: 'minus', action: () => {
+                if (table.querySelectorAll('tr').length <= 1) table.remove(); else row.remove();
+                done();
+            }},
+            {label: 'Delete column', icon: 'minus', action: () => {
+                if (row.children.length <= 1) table.remove();
+                else table.querySelectorAll('tr').forEach(tr => tr.children[col]?.remove());
+                done();
+            }},
+            {label: 'Delete table', icon: 'trash', danger: true, action: () => { table.remove(); done(); }}
+        ];
+    }
+
+    _addColumn(table, col, offset) {
+        table.querySelectorAll('tr').forEach((tr) => {
+            const ref = tr.children[col];
+            const cell = document.createElement(tr.parentElement.tagName === 'THEAD' ? 'th' : 'td');
+            cell.innerHTML = '<br>';
+            if (!ref) tr.appendChild(cell);
+            else if (offset) ref.after(cell);
+            else ref.before(cell);
+        });
+    }
+
+    _moveCell(cell, dir) {
+        const cells = [...cell.closest('table').querySelectorAll('th,td')];
+        const next = cells[cells.indexOf(cell) + dir];
+        if (!next) return;
+        const r = document.createRange();
+        r.selectNodeContents(next);
+        r.collapse(false);
+        const sel = document.getSelection();
+        sel.removeAllRanges();
+        sel.addRange(r);
+    }
+
+    /**
+     * A paste carries the source page's markup - fonts, colours, tracking
+     * spans - so it is sanitised. Pasted image files go to the Media library
+     * when that is possible, rather than into the document as data.
+     */
+    _onPaste(e) {
+        // Suggesting: the browser's own paste goes on, as a beforeinput the add-on turns into a suggestion.
+        if (this.readOnly || this.suggesting) return;
+        const clip = e.clipboardData;
+        if (!clip) return;
+        const files = [...(clip.files || [])].filter(f => /^image\//.test(f.type));
+        if (files.length && typeof this.options.uploadImage === 'function') {
+            e.preventDefault();
+            this._uploadAll(files);
+            return;
+        }
+        e.preventDefault();
+        const html = clip.getData('text/html');
+        if (html && window.DOMPurify?.sanitize) this._exec('insertHTML', cleanPaste(sanitizeHtml(html)));
+        else this._exec('insertText', clip.getData('text/plain'));
+        this._emitChange();
+    }
+
+    _onDrop(e) {
+        if (this.readOnly) return;
+        if (this.suggesting) { e.preventDefault(); return; }
+        const files = [...(e.dataTransfer?.files || [])].filter(f => /^image\//.test(f.type));
+        if (!files.length || typeof this.options.uploadImage !== 'function') return;
+        e.preventDefault();
+        const pos = document.caretRangeFromPoint?.(e.clientX, e.clientY);
+        if (pos) { const sel = document.getSelection(); sel.removeAllRanges(); sel.addRange(pos); }
+        this._uploadAll(files);
+    }
+
+    async _uploadAll(files) {
+        const saved = this._saveRange();
+        for (const f of files) {
+            let url = null;
+            try { url = await this.options.uploadImage(f); } catch (err) { E.toast(err.message || 'Could not upload the image', {type: 'error'}); }
+            if (url) { this._restoreRange(saved); this._insertImageUrl(url, f.name.replace(/\.[^.]+$/, '')); }
+        }
+    }
+
+    // ----------------------------------------------------- for add-ons (2.4)
+
+    /** The selection inside the page, kept so a dialog can put it back. */
+    saveRange() { return this._saveRange(); }
+    restoreRange(range) { this._restoreRange(range); }
+
+    /** The selected text, or '' (only inside the page). */
+    selectedText(range = this._saveRange()) { return range ? range.toString() : ''; }
+
+    /** Insert HTML (already safe) at the caret or over the selection. */
+    insertHtml(html, range = null) {
+        if (this.readOnly) return false;
+        if (range) this._restoreRange(range);
+        const ok = this._exec('insertHTML', html);
+        this._emitChange();
+        return ok;
+    }
+
+    /**
+     * Wrap the selection in a <span> with the given data-* attributes (a
+     * comment's anchor). Returns false when there is no selection in the page
+     * (a selection across elements is marked piece by piece, all with the same attributes).
+     */
+    wrapSelection(attrs = {}, range = this._saveRange()) {
+        if (this.readOnly || !range || range.collapsed || !this.surface?.contains(range.commonAncestorContainer)) return false;
+        const span = document.createElement('span');
+        for (const [k, v] of Object.entries(attrs)) if (/^data-[a-z0-9-]+$/.test(k)) span.setAttribute(k, String(v));
+        try {
+            range.surroundContents(span);
+        } catch {
+            // Across bold, a link or paragraphs: each piece of text in the selection gets its own span
+            // with the same attributes - together they are the one mark.
+            const root = range.commonAncestorContainer;
+            const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
+                acceptNode: (n) => (range.intersectsNode(n) && n.nodeValue.trim() ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_REJECT)
+            });
+            const pieces = [];
+            while (walker.nextNode()) {
+                const n = walker.currentNode;
+                const s = n === range.startContainer ? range.startOffset : 0;
+                const e = n === range.endContainer ? range.endOffset : n.nodeValue.length;
+                if (e > s) pieces.push({n, s, e});
+            }
+            if (!pieces.length) return false;
+            for (const {n, s, e} of pieces) {
+                if (e < n.nodeValue.length) n.splitText(e);
+                const mid = s > 0 ? n.splitText(s) : n;
+                const wrap = span.cloneNode(false);
+                mid.parentNode.insertBefore(wrap, mid);
+                wrap.appendChild(mid);
+            }
+        }
+        this._emitChange();
+        return true;
+    }
+
+    /**
+     * Apply a named editing action at a saved selection - the context-editing
+     * channel for add-ons (2.8). Refused read-only and while suggesting (the
+     * toolbar is off there so every change arrives through beforeinput).
+     * Returns false when the name is unknown or the editor refused.
+     */
+    applyNamed(name, range = null) {
+        const tool = NAMED_TOOLS[name];
+        if (!tool || this.readOnly || this.suggesting) return false;
+        if (range) this._restoreRange(range);
+        this._applyTool(tool);
+        return true;
+    }
+
+    /** Take away a wrapping added by wrapSelection (a comment deleted). */
+    unwrap(selector) {
+        if (this.readOnly) return 0;
+        let n = 0;
+        this.surface.querySelectorAll(selector).forEach((el) => { el.replaceWith(...el.childNodes); n++; });
+        if (n) this._emitChange();
+        return n;
+    }
+
+    _exec(command, value) {
+        if (command !== 'styleWithCSS') this.surface?.focus();
+        try {
+            return document.execCommand(command, false, value);
+        } catch (err) {
+            console.warn(`[docs] editor command "${command}" is unavailable`, err);
+            return false;
+        }
+    }
+}
+
+/**
+ * Pasted HTML keeps its structure and loses the source page's presentation:
+ * classes, ids and inline styles (other than alignment) go.
+ *
+ * @param   {string} html already sanitised
+ * @returns {string}
+ */
+export function cleanPaste(html) {
+    const t = document.createElement('template');
+    t.innerHTML = html;
+    t.content.querySelectorAll('*').forEach((el) => {
+        const align = el.style?.textAlign;
+        for (const a of [...el.attributes]) {
+            const keep = ['href', 'src', 'alt', 'title', 'colspan', 'rowspan', 'start', 'data-type', 'data-checked'];
+            if (!keep.includes(a.name)) el.removeAttribute(a.name);
+        }
+        if (align && /^(left|right|center|justify)$/.test(align)) el.style.textAlign = align;
+        if (/^(SPAN|FONT)$/.test(el.tagName) && !el.attributes.length) el.replaceWith(...el.childNodes);
+    });
+    return t.innerHTML;
+}