u2ui 1.5.3 → 1.5.7

package/js/rte/src/config/README.md

@@ -0,0 +1,96 @@
+# Configuration
+
+`config.js` resolves inheritable CSS custom properties for one editable host.
+Absent values and `auto` use semantic defaults derived from the host tag.
+
+## Contract
+
+- `enabled(host)` detects the opt-in property `--u2-rte`.
+- `hostDefaults(host)` returns a shared immutable default for block and Enter
+  behavior.
+- `config(host)` returns an immutable snapshot of the current computed settings.
+- CSS is read on demand, so class changes and media/container queries can alter
+  behavior without recreating a surface.
+- Unknown enum values fall back safely instead of becoming implicit modes.
+- A block value is used only when it is a usable lowercase tag name, so a typo,
+  quoted value, or value list cannot reach `createElement()`.
+
+Current properties:
+
+| Property | Values | Default |
+| --- | --- | --- |
+| `--u2-rte` | any truthy token | disabled |
+| `--u2-rte-block` | tag name, `none`, `auto` | host-specific |
+| `--u2-rte-enter` | `break`, `block`, `item`, `row`, `cell`, `auto` | host-specific |
+| `--u2-rte-cleanup` | `none`, `minimal`, `structural`, `canonical` | `structural` |
+| `--u2-rte-clean-on` | space- or comma-separated triggers | `input paste drop command` |
+| `--u2-rte-elements` | tag list, `@basic`, `@article`, `@document`, `all` | `all` |
+| `--u2-rte-import-unstyle` | `none` or an installed Unstyle level | `styles` |
+| `--u2-rte-ui` | `none`, `roaming`, `static` | `roaming` |
+| `--u2-rte-toolbar` | control names separated by spaces or commas | every represented control |
+| `--u2-rte-toolbar-when` | `always`, `selection` | `always` |
+
+`--u2-rte-enter` is consumed by the `enter` command: `break` inserts a line
+break, every other value names the element Enter splits. `--u2-rte-ui: none`
+hides a roaming `Toolbar`; `static` is reserved for the future static binding.
+The convention client in `rte.js` currently represents only `bold`, so additional
+toolbar names stay invisible until an optional module supplies both command and
+control.
+See [`../command/README.md`](../command/README.md) and
+[`../ui/README.md`](../ui/README.md).
+
+Semantic block defaults preserve native container shape: generic block hosts
+such as `div` use `p`, lists use `li`, and table structure uses `tbody`, `tr`,
+and `td`. A directly editable `li`, `caption`, `th`, or `td` keeps phrasing
+content unwrapped and Enter inserts `br`. Any host can override this, including
+opting those containers back into paragraphs with `--u2-rte-block: p` and
+`--u2-rte-enter: block`.
+
+Functions, command implementations, and policy objects are intentionally not
+encoded as CSS strings. They enter through module registration.
+
+`--u2-rte-elements` is a structural output policy shared by cleanup and
+commands. An explicit list is application-specific; the frozen `basic`,
+`article`, and `document` presets are exported as `elementPresets` and selected
+in CSS with an `@` prefix:
+
+```css
+.article-editor {
+    --u2-rte-elements: @article;
+}
+```
+
+An unknown preset or malformed list resolves to an empty allowlist rather than
+silently broadening content. `all` retains the complete supplied content model.
+The list controls elements only; it is deliberately not an attribute or URL
+sanitizer.
+
+`--u2-rte-import-unstyle` controls presentation cleanup for native paste and
+drop. The default removes classes and inline styles only from elements added by
+that input; `none` keeps native presentation. A custom `Unstyle` policy may
+provide other level names.
+
+`--u2-rte-classes` lists the class names the host treats as content. It is one
+declaration with three consumers: the style control offers exactly those names,
+the sanitizer keeps only those from external HTML, and presentation cleanup
+leaves them and their wrappers alone. A host that declares none behaves exactly
+as before.
+
+`--u2-rte-import-elements` is what may *arrive*, a narrower question than
+`--u2-rte-elements`, which is what a host tolerates in content it already owns.
+It defaults to the `@content` preset: headings, text, lists, tables, media, and
+the text-level semantics that carry meaning — no layout, no embeds, no forms.
+The host list still bounds it; neither can widen the sanitize policy.
+
+`--u2-rte-import-sanitize` switches that whole stage off with `none`, leaving
+what the browser inserted. Which attributes and protocols are acceptable stays
+in JavaScript with the policy — that is a security decision, not a presentation
+one, and not something CSS should be carrying.
+
+## TODO
+
+- Add named sanitize-policy references when applications need CSS selection
+  among several registered JavaScript policies.
+- Decide whether typed `@property` declarations improve debugging without
+  restricting inheritance or future values.
+- Test container-query and adopted-style-sheet changes in integration suites.

package/js/rte/src/config/config.js

@@ -0,0 +1,134 @@
+const INLINE_HOSTS = new Set([
+    'A', 'ABBR', 'B', 'BUTTON', 'CODE', 'EM', 'H1', 'H2', 'H3', 'H4', 'H5',
+    'H6', 'I', 'KBD', 'LABEL', 'P', 'PRE', 'Q', 'SAMP', 'SMALL', 'SPAN',
+    'STRONG', 'SUB', 'SUP', 'TIME', 'U', 'VAR',
+]);
+const UNWRAPPED_HOSTS = new Set(['LI', 'CAPTION', 'TH', 'TD']);
+const CLEANUP = new Set(['none', 'minimal', 'structural', 'canonical']);
+const ENTER = new Set(['break', 'block', 'item', 'row', 'cell']);
+const UI = new Set(['none', 'roaming', 'static']);
+const IMPORT_SANITIZE = new Set(['policy', 'none']);
+const TAG = /^[a-z][a-z\d-]*$/;
+const CLASS = /^-?[_a-zA-Z][\w-]*$/;
+const FALSE = new Set(['0', 'false', 'none', 'off']);
+const DEFAULT_CLEAN_ON = Object.freeze(['input', 'paste', 'drop', 'command']);
+const EMPTY_ELEMENTS = Object.freeze([]);
+export const elementPresets = Object.freeze({
+    basic: elements('p ul ol li a strong b em i code br'),
+    // What a content field is about: headings, text, lists, tables, media and
+    // the text-level semantics that carry meaning. No layout, no embeds, no
+    // forms. This is the import default: what may arrive is a narrower question
+    // than what a host tolerates in content it owns.
+    content: elements(`
+        p h1 h2 h3 h4 h5 h6 blockquote pre ul ol li table caption thead tbody
+        tfoot tr th td hr img a strong em code span br
+    `),
+    article: elements('p h1 h2 h3 h4 h5 h6 blockquote pre ul ol li hr a strong b em i u s del ins code kbd mark q small sub sup span br'),
+    document: elements('p h1 h2 h3 h4 h5 h6 blockquote pre ul ol li dl dt dd hr figure figcaption img table caption thead tbody tfoot tr th td a strong b em i u s del ins code kbd mark q small sub sup span br'),
+});
+const DEFAULTS = Object.freeze({
+    block: Object.freeze({block: 'p', enter: 'block'}),
+    text: Object.freeze({block: null, enter: 'break'}),
+    list: Object.freeze({block: 'li', enter: 'item'}),
+    table: Object.freeze({block: 'tbody', enter: 'row'}),
+    row: Object.freeze({block: 'tr', enter: 'row'}),
+    cell: Object.freeze({block: 'td', enter: 'cell'}),
+});
+
+export function enabled(host) {
+    const value = getComputedStyle(host).getPropertyValue('--u2-rte').trim().toLowerCase();
+    return value !== '' && !FALSE.has(value);
+}
+
+export function hostDefaults(host) {
+    const tag = host.tagName;
+    if (UNWRAPPED_HOSTS.has(tag)) return DEFAULTS.text;
+    if (tag === 'UL' || tag === 'OL') return DEFAULTS.list;
+    if (tag === 'TABLE') return DEFAULTS.table;
+    if (tag === 'THEAD' || tag === 'TBODY' || tag === 'TFOOT') return DEFAULTS.row;
+    if (tag === 'TR') return DEFAULTS.cell;
+    if (INLINE_HOSTS.has(tag)) return DEFAULTS.text;
+    return DEFAULTS.block;
+}
+
+// Only the setting the model narrowing wants. The whole configuration parses
+// eleven properties, and reading a computed style is the expensive part of a
+// path every keystroke and every availability check goes through.
+export function configuredElements(host) {
+    return allowedElements(getComputedStyle(host), 'elements', null);
+}
+
+export function config(host) {
+    const style = getComputedStyle(host);
+    const defaults = hostDefaults(host);
+    const cleanOn = value(style, 'clean-on');
+    return Object.freeze({
+        block: tag(style, 'block', defaults.block),
+        enter: choice(style, 'enter', ENTER, defaults.enter),
+        cleanup: choice(style, 'cleanup', CLEANUP, 'structural'),
+        cleanOn: Object.freeze(cleanOn ? cleanOn.split(/[\s,]+/).filter(Boolean) : [...DEFAULT_CLEAN_ON]),
+        elements: allowedElements(style, 'elements', null),
+        importElements: allowedElements(style, 'import-elements', elementPresets.content),
+        classes: classNames(style),
+        // Foreign presentation through the class rung: pasted markup keeps no
+        // styles, no presentational attributes, and no undeclared classes.
+        importSanitize: choice(style, 'import-sanitize', IMPORT_SANITIZE, 'policy'),
+        importUnstyle: value(style, 'import-unstyle') || 'classes',
+        ui: choice(style, 'ui', UI, 'roaming'),
+        inlineUi: inlineNames(style),
+    });
+}
+
+// Which contextual UIs a field draws at its content — `table image link`. Unset
+// means every one the loaded modules bring, `none` means the field stays plain
+// while keeping the commands. The same modules then serve a body of text and a
+// bare teaser field without a second editor.
+export function inlineUi(config, name) {
+    return !config.inlineUi || config.inlineUi.includes(name);
+}
+
+function inlineNames(style) {
+    const result = value(style, 'inline-ui').toLowerCase();
+    if (!result) return null;
+    if (result === 'none') return EMPTY_ELEMENTS;
+    return Object.freeze([...new Set(result.split(/[\s,]+/).filter(Boolean))]);
+}
+
+function value(style, name) {
+    const value = style.getPropertyValue(`--u2-rte-${name}`).trim();
+    return value === 'auto' ? '' : value;
+}
+
+function tag(style, name, fallback) {
+    const result = value(style, name).toLowerCase();
+    if (result === 'none') return null;
+    return TAG.test(result) ? result : fallback;
+}
+
+function choice(style, name, choices, fallback) {
+    const result = value(style, name);
+    return choices.has(result) ? result : fallback;
+}
+
+// The class names this host treats as content. One declaration serves the style
+// control, the sanitizer, and presentation cleanup, so a class the host knows is
+// never offered without being allowed, or cleaned away as foreign.
+function classNames(style) {
+    const result = value(style, 'classes');
+    if (!result) return EMPTY_ELEMENTS;
+    const names = result.split(/[\s,]+/).filter(Boolean);
+    return names.every(name => CLASS.test(name)) ? Object.freeze([...new Set(names)]) : EMPTY_ELEMENTS;
+}
+
+function allowedElements(style, name, fallback) {
+    const result = value(style, name).toLowerCase();
+    if (!result) return fallback;
+    if (result === 'all') return null;
+    if (result.startsWith('@')) return elementPresets[result.slice(1)] || EMPTY_ELEMENTS;
+    const names = result.split(/[\s,]+/).filter(Boolean);
+    return names.length && names.every(name => TAG.test(name)) ? Object.freeze([...new Set(names)]) : EMPTY_ELEMENTS;
+}
+
+function elements(value) {
+    return Object.freeze(value.trim().split(/\s+/));
+}

package/js/rte/src/core/README.md

@@ -0,0 +1,63 @@
+# Core
+
+The core is the shared coordinator for all editable elements in one document or
+ShadowRoot. It listens for focus and selection changes once, knows which editor
+is active, and routes work to that editor. It does not decide formatting,
+document structure, or UI behavior.
+
+`core.js` implements this coordinator and registers each editable element as a
+`Surface`.
+
+## Contract
+
+- One core may coordinate any number of explicit editable surfaces.
+- `add()` is idempotent and rejects non-editable or foreign-root elements.
+- With `auto` enabled, focusing an element opted in through `--u2-rte` registers
+  it lazily. Explicit registration does not require that CSS property.
+- Capture-phase `focus` and `focusin` share one idempotent route to tolerate
+  browser and document-lifecycle differences without duplicate activation.
+- The nearest explicit nested `contenteditable` is an isolation boundary.
+- `sync()` resolves the current selection to one registered surface and captures
+  it without scanning or mutating unrelated editor contents. A selection is not
+  a session: once focus has left the editor, only focus starts one again.
+  Engines leave a selection inside an editable that nobody focused — clicking
+  beside one does that — and a toolbar over a caret the keyboard cannot reach is
+  worse than no toolbar. The surface still keeps what it captured.
+- At most one surface is active per core; active state may outlive DOM focus so
+  a roaming UI can safely receive focus.
+- `retain(element)` marks editor-owned UI in the same document. Focus inside it
+  keeps the active surface, `retains(node)` identifies its composed subtree,
+  and `release(element)` removes the mark. This also distinguishes UI from
+  content when a native top-layer boundary requires both to share one host.
+- A link, a button, or a label around an editing host is answered by the element,
+  not by the text: the link is dragged rather than giving the text a caret and
+  followed when the press ends, and the label hands the press to the control it
+  names. Both are suppressed for a press that belongs to
+  the text, and the link is left undraggable — nobody drags a link wrapped
+  around editable content on purpose.
+- The right button never moves the selection inside a surface: its menu is about
+  what is selected, and aiming the menu somewhere else is what would make it
+  useless.
+- A press decides which surface a focus belongs to. Engines hand the focus to
+  the nearest editable when a press lands beside one, which an inline host in
+  running text collects a whole line of; a focus whose press did not land in the
+  surface is refused and given back. A press answers for every focus until it is
+  released — one drag can hand the focus back more than once — and a key taking
+  over ends it too, so a keyboard reaching a surface is never mistaken for it.
+- Focus that lands anywhere else — not a surface, not retained UI — ends the
+  session, so everything drawn for it goes at once. So does focus that lands
+  nowhere: clicking a plain paragraph focuses nothing, and no focus event
+  follows to say so, which is what `focusout` is listened to for. Retaining is
+  therefore how a UI that takes focus stays alive; `Toolbar` retains its element
+  itself.
+- `dispose()` removes listeners and disconnects every surface. It is
+  idempotent; `[Symbol.dispose]()` exposes the same teardown to `using`.
+
+Separate cores are supported for iframes, ShadowRoots, tests, and intentionally
+isolated environments. The public entry point creates one default document core.
+
+## TODO
+
+- Observe removed auto-registered hosts without watching their contents.
+- Complete cross-browser ShadowRoot selection routing.
+- Add module lifecycle registration at the core boundary.

package/js/rte/src/core/core.js

@@ -0,0 +1,247 @@
+import {enabled} from '../config/config.js';
+import {interactiveAround} from '../browser/interactive.js';
+import {editingHost, isEditableHost, isEditingBoundary} from '../selection/ownership/ownership.js';
+import {Surface} from '../surface/surface.js';
+
+export class Rte extends EventTarget {
+    #root;
+    #document;
+    #options;
+    #surfaces = new Set();
+    #elements = new WeakMap();
+    #retained = new Set();
+    #active = null;
+    #unfocused = false;
+    #pointer = null;
+    #handed = false;
+    #controller;
+
+    constructor(root = document, options = {}) {
+        super();
+        const isDocument = root?.nodeType === Node.DOCUMENT_NODE;
+        const isShadow = root?.nodeType === Node.DOCUMENT_FRAGMENT_NODE && root.host;
+        if (!isDocument && !isShadow) throw new TypeError('RTE root must be a Document or ShadowRoot');
+        this.#root = root;
+        this.#document = isDocument ? root : root.ownerDocument;
+        this.#options = Object.freeze({auto: options.auto !== false});
+        this.#controller = new this.#document.defaultView.AbortController();
+        const listen = {capture: true, signal: this.#controller.signal};
+        root.addEventListener('focus', this.#focus, listen);
+        root.addEventListener('focusin', this.#focus, listen);
+        root.addEventListener('focusout', this.#focusOut, listen);
+        // A press answers for every focus until it is over: one drag can hand the
+        // focus back more than once. A key taking over ends it too, so what is
+        // left of a release that never arrived cannot answer for the keyboard.
+        root.addEventListener('pointerdown', this.#pointerDown, listen);
+        for (const type of ['pointerup', 'pointercancel', 'keydown']) {
+            root.addEventListener(type, this.#pointerDone, listen);
+        }
+        root.addEventListener('click', this.#click, listen);
+        this.#document.addEventListener('selectionchange', this.#selectionChange, {signal: this.#controller.signal});
+    }
+
+    get root() { return this.#root; }
+    get options() { return this.#options; }
+    get active() { return this.#active; }
+    get surfaces() { return [...this.#surfaces]; }
+    get selection() { return this.#root.getSelection?.() || this.#document.getSelection(); }
+
+    // Retained UI may receive focus without deactivating the current surface.
+    // When it temporarily has to live inside a top-layer editing host, content
+    // readers also use this boundary to leave it out of the document.
+    retain(element) {
+        if (element?.nodeType !== Node.ELEMENT_NODE) throw new TypeError('Retained UI must be an element');
+        if (element.ownerDocument !== this.#document) throw new RangeError('Retained UI must belong to the core document');
+        this.#retained.add(element);
+        return element;
+    }
+
+    release(element) {
+        return this.#retained.delete(element);
+    }
+
+    retains(node) {
+        for (let current = node; current;) {
+            if (this.#retained.has(current)) return true;
+            const root = current.getRootNode?.();
+            current = current.parentNode || root?.host || null;
+        }
+        return false;
+    }
+
+    add(element, options) {
+        if (!isEditableHost(element)) {
+            throw new TypeError('RTE surfaces must be explicit contenteditable elements');
+        }
+        if (element.getRootNode() !== this.#root) throw new RangeError('RTE surface must belong to the core root');
+        const current = this.#elements.get(element);
+        if (current) return current;
+        const surface = new Surface(this, element, options);
+        this.#elements.set(element, surface);
+        this.#surfaces.add(surface);
+        this.#emit('u2-rte-add', {surface});
+        return surface;
+    }
+
+    get(element) {
+        return this.#elements.get(element) || null;
+    }
+
+    delete(target) {
+        const surface = target instanceof Surface ? target : this.#elements.get(target);
+        if (!surface || !this.#surfaces.has(surface)) return false;
+        if (this.#active === surface) this.activate(null);
+        this.#surfaces.delete(surface);
+        this.#elements.delete(surface.element);
+        surface.disconnect();
+        this.#emit('u2-rte-delete', {surface});
+        return true;
+    }
+
+    activate(surface) {
+        if (surface && !this.#surfaces.has(surface)) throw new RangeError('Active surface must belong to this core');
+        if (surface === this.#active) return surface;
+        this.#active?.activate(false);
+        this.#active = surface;
+        surface?.activate();
+        this.#emit('u2-rte-activechange', {surface});
+        return surface;
+    }
+
+    sync() {
+        const selection = this.selection;
+        const editable = editingHost(selection?.anchorNode);
+        if (!editable) return null;
+        const surface = this.#elements.get(editable);
+        if (!surface || !selection.focusNode || !surface.element.contains(selection.focusNode)) {
+            this.activate(null);
+            return null;
+        }
+        if (!surface.capture(selection)) {
+            this.activate(null);
+            return null;
+        }
+        // A selection is not a session: once the focus has left the editor, only
+        // focus brings it back. Engines leave a selection inside an editable that
+        // nobody focused — clicking beside one does that — and a toolbar over a
+        // caret the keyboard cannot reach is worse than no toolbar. What the
+        // surface captured, it keeps either way.
+        if (this.#unfocused && this.#active !== surface) return null;
+        this.activate(surface);
+        return surface;
+    }
+
+    dispose() {
+        if (this.#controller.signal.aborted) return;
+        this.#controller.abort();
+        for (const surface of [...this.#surfaces]) this.delete(surface);
+        this.#retained.clear();
+        this.#emit('u2-rte-dispose');
+    }
+
+    [Symbol.dispose]() {
+        this.dispose();
+    }
+
+    #focus = event => {
+        const path = event.composedPath();
+        if (path.some(node => this.#retained.has(node))) {
+            this.#unfocused = false;
+            return;
+        }
+        const editable = path.find(node =>
+            node?.nodeType === Node.ELEMENT_NODE && isEditingBoundary(node)
+        );
+        // Focus that went somewhere else entirely ends the session: retained UI
+        // is already excluded above, so what is left is not the editor's, and
+        // everything drawn for it has to go with it.
+        if (!editable || !isEditableHost(editable)) {
+            this.#unfocused = true;
+            this.activate(null);
+            return;
+        }
+        let surface = this.#elements.get(editable);
+        if (!surface && this.#options.auto && enabled(editable)) surface = this.add(editable);
+        // An engine gives the focus to the nearest editable when a press lands
+        // beside one: an inline host collects its whole line. A press that did
+        // not land in this surface is nobody starting to edit it, and the caret
+        // it would leave behind is one no one asked for.
+        //
+        // Taking it back is the one thing here that reaches into the document:
+        // the element really is focused for a moment, so the page sees a
+        // focus/blur pair it did not ask for, and anything listening for either
+        // on that element — a host's own handler, a css `:focus` rule — sees it
+        // too. Leaving it focused instead is worse: a caret that types into a
+        // surface with no session behind it.
+        if (surface && this.#pointer && !this.#pointer.includes(surface.element)) {
+            this.#unfocused = true;
+            this.activate(null);
+            // Handing the focus back once per press. An engine that answers a
+            // blur by focusing again — the selection is still in there, after
+            // all — would otherwise trade focus with the editor for as long as
+            // the button is down, and the session stays refused either way.
+            if (!this.#handed) {
+                this.#handed = true;
+                editable.blur();
+            }
+            return;
+        }
+        this.#unfocused = !surface;
+        this.activate(surface || null);
+    };
+
+    // Focus falling back to the document is the one way a session ends without
+    // a focus event to end it: nothing is focused, so nothing announces it.
+    // A related target inside a surface or in retained UI is `#focus`'s to
+    // decide — deactivating here would end a session that is only moving.
+    #focusOut = event => {
+        if (this.#owns(event.relatedTarget)) return;
+        this.#unfocused = true;
+        this.activate(null);
+    };
+
+    // The editor's world: one of its surfaces, or UI it retains.
+    #owns(node) {
+        return !!node && (this.retains(node) || this.#elements.has(editingHost(node)));
+    }
+
+    #pointerDown = event => {
+        const path = event.composedPath();
+        this.#pointer = path;
+        this.#handed = false;
+        const editing = this.#editing(path[0]);
+        // The right button opens a menu about what is selected; moving the
+        // selection to what it was aimed at is what makes the menu useless.
+        if (event.button === 2 && editing) event.preventDefault();
+        // The drag has to be off before this very press is acted on, which is
+        // what a capturing listener is early enough for. It stays off: a link
+        // wrapping editable content is not one anybody drags on purpose.
+        const around = interactiveAround(editing);
+        if (around) around.draggable = false;
+    };
+
+    // The press belonged to the text, and so does its release.
+    #click = event => {
+        if (interactiveAround(this.#editing(event.composedPath()[0]))) event.preventDefault();
+    };
+
+    // The editing host a node sits in, if this core is the editor of it.
+    #editing(node) {
+        const host = editingHost(node);
+        if (!host) return null;
+        return this.#elements.has(host) || this.#options.auto && enabled(host) ? host : null;
+    }
+
+    #pointerDone = () => {
+        this.#pointer = null;
+    };
+
+    #selectionChange = () => {
+        this.sync();
+    };
+
+    #emit(type, detail = {}) {
+        const Event = this.#document.defaultView.CustomEvent;
+        return this.dispatchEvent(new Event(type, {detail: {core: this, ...detail}}));
+    }
+}

package/js/rte/src/history/README.md

@@ -0,0 +1,83 @@
+# History
+
+Undo and redo for one surface.
+
+RTE deliberately leaves ordinary typing and deletion to the browser, so history
+cannot be an operation log: it would only ever see the edits the engine itself
+performs. `history.js` therefore records *states*. A `MutationObserver` reports
+every change regardless of its origin — native input, a command, paste, drop, or
+an unrelated application script — and an entry stores the resulting content as a
+cloned `DocumentFragment` with a path-addressed selection.
+
+Because entries are complete states, undo never has to reverse a mutation it did
+not understand. That is what makes a mixed native/engine editing model undoable
+at all.
+
+## Contract
+
+- `new History(surface, {limit = 100, coalesce = 400})` starts with the current
+  content as its baseline entry and observes the surface from that moment.
+- `record()` commits the current content as one entry and reports whether it
+  added one. Unchanged content adds nothing, so any boundary may flush safely.
+- `undo()` and `redo()` move one entry and report whether they moved. Both
+  commit uncommitted input first, so undo leaves the state the user sees.
+- `canUndo` and `canRedo` account for uncommitted input: pending input is
+  undoable, and it invalidates a redo branch before it is recorded.
+- `commands` is the frozen `{undo, redo}` pair for a `Commands` registry. They
+  claim the `historyUndo` and `historyRedo` input types and run without a
+  transaction, because an entry replaces the content and restores the selection
+  itself. Like every other command they require the surface to own the edit's
+  range, so a shortcut never reaches an editor the user has left; a toolbar
+  that still holds a saved selection passes it and keeps working.
+- The methods are unconditional: `undo()` and `redo()` are the programmatic API
+  and do not consult the selection.
+- `clear()` discards every entry and restarts from the current content.
+- Recording a new state drops the redo branch. Exceeding `limit` drops the
+  oldest entry.
+- `u2-rte-history` reports every entry and every move on the surface.
+- `dispose()` stops observing and releases every entry. A disconnected surface
+  disposes its history.
+- Core-retained UI mutations are not edits. Snapshots omit those subtrees and
+  undo/redo preserves them, including when shared chrome is temporarily mounted
+  directly in a top-layer editing host.
+
+## Grouping
+
+Transactions supply the boundaries, so grouping needs no separate timer policy:
+
+- A transaction with the `input` trigger is ordinary typing and coalesces.
+- Every other transaction — `command`, `paste`, `drop` — records one entry
+  before and one after itself, so a command is always its own undo step.
+- Native input that never reaches a transaction coalesces through the observer.
+- Deactivating the surface flushes.
+
+Coalescing keeps one open interval instead of restarting it on every keystroke,
+so continuous typing still becomes several undo steps rather than one.
+
+## Selection
+
+`SelectionSnapshot` holds live nodes and cannot survive replaced content. An
+entry therefore stores each boundary as a child-index path from the surface
+element plus an offset, and rebuilds a `SelectionSnapshot` on restore so
+backward selections keep their direction. An entry captured before the surface
+had a selection adopts the first one it sees, so undoing back to the baseline
+restores a caret too.
+
+## Browser considerations
+
+- Ctrl/Command+Z and +Y are routed from `keydown` by the input pipeline, not
+  from `beforeinput`. A browser stops reporting `historyUndo` once its own undo
+  stack no longer matches content the engine replaced. The `inputTypes` claim
+  remains so that a menu- or gesture-triggered undo is captured as well.
+- Restoring content takes the observer's own records so an applied entry can
+  never record itself.
+
+## TODO
+
+- Expose the coalescing interval and an off switch as `--u2-rte-history`.
+- Store diffs instead of whole fragments once the transaction layer records
+  reversible operations, and keep this state model as the fallback for
+  mutations the engine does not own.
+- Group composition deliberately instead of relying on its mutations alone.
+- Verify entry cost on large documents and decide whether `limit` should be
+  measured in bytes rather than entries.