u2ui 1.5.3 → 1.5.7

package/js/rte/src/selection/range/edit-range.js

@@ -0,0 +1,223 @@
+import {belongsTo, elementOf, isEditingBoundary, selectionOf} from '../ownership/ownership.js';
+import {Point} from '../point/point.js';
+
+export class EditRange {
+    #root;
+    #range;
+
+    constructor(root, range) {
+        if (!root?.hasAttribute?.('contenteditable')) throw new TypeError('An edit range requires an explicit editable root');
+        if (!range?.cloneRange) throw new TypeError('An edit range requires a native Range');
+        if (!belongsTo(range.startContainer, root) || !belongsTo(range.endContainer, root)) {
+            throw new RangeError('Range boundaries must belong to the editable root');
+        }
+        this.#root = root;
+        this.#range = range.cloneRange();
+    }
+
+    static fromSelection(selection, root) {
+        return selection?.rangeCount ? this.fromRange(selection.getRangeAt(0), root) : null;
+    }
+
+    static fromRange(range, root) {
+        try {
+            return new this(root, range);
+        } catch (error) {
+            if (error instanceof RangeError) return null;
+            throw error;
+        }
+    }
+
+    static fromPoints(start, end, root) {
+        if (!(start instanceof Point) || !(end instanceof Point)) throw new TypeError('Edit range boundaries must be points');
+        if (start.compare(end) > 0) throw new RangeError('Edit range start must not follow its end');
+        const range = root.ownerDocument.createRange();
+        range.setStart(start.node, start.offset);
+        range.setEnd(end.node, end.offset);
+        return new this(root, range);
+    }
+
+    get root() { return this.#root; }
+    get collapsed() { return this.#range.collapsed; }
+    get text() { return this.#range.toString(); }
+    get commonAncestor() { return this.#range.commonAncestorContainer; }
+    get start() { return Point.fromRange(this.#range, 'start'); }
+    get end() { return Point.fromRange(this.#range, 'end'); }
+
+    range() {
+        return this.#range.cloneRange();
+    }
+
+    clone() {
+        return new this.constructor(this.#root, this.#range);
+    }
+
+    setStart(point) {
+        this.#assertPoint(point);
+        if (point.compare(this.end) > 0) throw new RangeError('Range start must not follow its end');
+        this.#range.setStart(point.node, point.offset);
+        return this;
+    }
+
+    setEnd(point) {
+        this.#assertPoint(point);
+        if (this.start.compare(point) > 0) throw new RangeError('Range end must not precede its start');
+        this.#range.setEnd(point.node, point.offset);
+        return this;
+    }
+
+    collapse(edge = 'start') {
+        if (edge !== 'start' && edge !== 'end') throw new TypeError('Collapse edge must be start or end');
+        this.#range.collapse(edge === 'start');
+        return this;
+    }
+
+    select(selection = selectionOf(this.#root), backward = false) {
+        if (!selection) return false;
+        const range = this.#range;
+        if (selection.setBaseAndExtent) {
+            selection.setBaseAndExtent(
+                backward ? range.endContainer : range.startContainer,
+                backward ? range.endOffset : range.startOffset,
+                backward ? range.startContainer : range.endContainer,
+                backward ? range.startOffset : range.endOffset,
+            );
+        } else {
+            selection.removeAllRanges();
+            selection.addRange(range.cloneRange());
+        }
+        return true;
+    }
+
+    splitTextBoundaries() {
+        if (this.#range.collapsed) return this;
+        let node = this.#range.endContainer;
+        let offset = this.#range.endOffset;
+        if (node.nodeType === Node.TEXT_NODE && offset > 0 && offset < node.length) {
+            node.splitText(offset);
+            this.#range.setEnd(node, offset);
+        }
+        node = this.#range.startContainer;
+        offset = this.#range.startOffset;
+        if (node.nodeType === Node.TEXT_NODE && offset > 0 && offset < node.length) {
+            const selected = node.splitText(offset);
+            this.#range.setStart(selected, 0);
+        }
+        return this;
+    }
+
+    intersects(node) {
+        if (!belongsTo(node, this.#root)) return false;
+        try {
+            return this.#range.intersectsNode(node);
+        } catch {
+            return false;
+        }
+    }
+
+    contains(node) {
+        if (!this.intersects(node)) return false;
+        if (node.nodeType === Node.TEXT_NODE) {
+            if (node === this.#range.startContainer && this.#range.startOffset !== 0) return false;
+            if (node === this.#range.endContainer && this.#range.endOffset !== node.length) return false;
+            return true;
+        }
+        const range = node.ownerDocument.createRange();
+        range.selectNode(node);
+        return this.#range.compareBoundaryPoints(0, range) <= 0
+            && this.#range.compareBoundaryPoints(2, range) >= 0;
+    }
+
+    textNodes() {
+        if (this.#range.collapsed) return [];
+        const document = this.#root.ownerDocument;
+        const filter = document.defaultView.NodeFilter;
+        const walker = document.createTreeWalker(this.#root, filter.SHOW_ELEMENT | filter.SHOW_TEXT, {
+            acceptNode: node => {
+                if (node !== this.#root && isEditingBoundary(node)) return filter.FILTER_REJECT;
+                if (node.nodeType !== Node.TEXT_NODE) return filter.FILTER_SKIP;
+                return selectedText(this.#range, node) ? filter.FILTER_ACCEPT : filter.FILTER_REJECT;
+            },
+        });
+        const nodes = [];
+        while (walker.nextNode()) nodes.push(walker.currentNode);
+        return nodes;
+    }
+
+    blocks(match) {
+        if (typeof match !== 'function') throw new TypeError('Block matching requires a predicate');
+        if (this.#range.collapsed) {
+            const block = closest(this.#range.startContainer, this.#root, match);
+            return block ? [block] : [];
+        }
+        const document = this.#root.ownerDocument;
+        const filter = document.defaultView.NodeFilter;
+        const start = Point.fromRange(this.#range, 'start');
+        const end = Point.fromRange(this.#range, 'end');
+        const walker = document.createTreeWalker(this.#root, filter.SHOW_ELEMENT | filter.SHOW_TEXT, {
+            acceptNode: node => {
+                if (node !== this.#root && isEditingBoundary(node)) return filter.FILTER_REJECT;
+                if (node.childNodes.length) return filter.FILTER_SKIP;
+                if (node.nodeType === Node.TEXT_NODE) {
+                    return selectedText(this.#range, node) ? filter.FILTER_ACCEPT : filter.FILTER_REJECT;
+                }
+                return overlaps(start, end, node) ? filter.FILTER_ACCEPT : filter.FILTER_REJECT;
+            },
+        });
+        const blocks = new Set();
+        while (walker.nextNode()) {
+            const block = closest(walker.currentNode, this.#root, match);
+            if (block) blocks.add(block);
+        }
+        return [...blocks].sort(treeOrder);
+    }
+
+    roots() {
+        if (this.#range.collapsed) return [];
+        const nodes = [];
+        const visit = parent => {
+            for (const node of parent.childNodes) {
+                if (isEditingBoundary(node)) continue;
+                if (!this.intersects(node)) continue;
+                if (this.contains(node)) nodes.push(node);
+                else if (node.childNodes.length) visit(node);
+            }
+        };
+        const common = this.#range.commonAncestorContainer;
+        visit(common.nodeType === Node.TEXT_NODE ? common.parentNode : common);
+        return nodes;
+    }
+
+    #assertPoint(point) {
+        if (!(point instanceof Point)) throw new TypeError('Range boundaries must be points');
+        if (!belongsTo(point.node, this.#root)) throw new RangeError('Point must belong to the editable root');
+    }
+}
+
+function selectedText(range, node) {
+    if (!node.length || !range.intersectsNode(node)) return false;
+    if (range.startContainer === node && range.endContainer === node) return range.startOffset < range.endOffset;
+    if (range.startContainer === node && range.startOffset === node.length) return false;
+    if (range.endContainer === node && range.endOffset === 0) return false;
+    return true;
+}
+
+function closest(node, root, match) {
+    let element = elementOf(node);
+    while (element && element !== root) {
+        if (match(element)) return element;
+        element = element.parentElement;
+    }
+    return null;
+}
+
+function treeOrder(node, other) {
+    return node.compareDocumentPosition(other) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1;
+}
+
+function overlaps(start, end, node) {
+    const nodeRange = node.ownerDocument.createRange();
+    nodeRange.selectNode(node);
+    return start.compare(Point.fromRange(nodeRange, 'end')) < 0
+        && end.compare(Point.fromRange(nodeRange, 'start')) > 0;
+}

package/js/rte/src/selection/snapshot.js

@@ -0,0 +1,64 @@
+import {belongsTo, selectionOf} from './ownership/ownership.js';
+
+export class SelectionSnapshot {
+    #root;
+    #range;
+    #backward;
+
+    constructor(root, range, backward = false) {
+        this.#root = root;
+        this.#range = range.cloneRange();
+        this.#backward = backward && !range.collapsed;
+    }
+
+    static capture(selection, root) {
+        if (!selection?.rangeCount || !selection.anchorNode || !selection.focusNode) return null;
+        if (!belongsTo(selection.anchorNode, root) || !belongsTo(selection.focusNode, root)) return null;
+        const range = selection.getRangeAt(0);
+        const backward = !range.collapsed
+            && selection.anchorNode === range.endContainer
+            && selection.anchorOffset === range.endOffset;
+        return new this(root, range, backward);
+    }
+
+    get root() { return this.#root; }
+    get collapsed() { return this.#range.collapsed; }
+    get backward() { return this.#backward; }
+    get text() { return this.#range.toString(); }
+
+    range() {
+        return this.#range.cloneRange();
+    }
+
+    equals(snapshot) {
+        if (!(snapshot instanceof SelectionSnapshot)) return false;
+        const range = snapshot.#range;
+        return this.#root === snapshot.#root
+            && this.#backward === snapshot.#backward
+            && this.#range.startContainer === range.startContainer
+            && this.#range.startOffset === range.startOffset
+            && this.#range.endContainer === range.endContainer
+            && this.#range.endOffset === range.endOffset;
+    }
+
+    valid() {
+        return belongsTo(this.#range.startContainer, this.#root)
+            && belongsTo(this.#range.endContainer, this.#root);
+    }
+
+    restore(selection = selectionOf(this.#root)) {
+        if (!selection || !this.valid()) return false;
+        const range = this.#range;
+        if (selection.setBaseAndExtent) {
+            const anchorNode = this.#backward ? range.endContainer : range.startContainer;
+            const anchorOffset = this.#backward ? range.endOffset : range.startOffset;
+            const focusNode = this.#backward ? range.startContainer : range.endContainer;
+            const focusOffset = this.#backward ? range.startOffset : range.endOffset;
+            selection.setBaseAndExtent(anchorNode, anchorOffset, focusNode, focusOffset);
+        } else {
+            selection.removeAllRanges();
+            selection.addRange(range.cloneRange());
+        }
+        return true;
+    }
+}

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

@@ -0,0 +1,64 @@
+# Source
+
+Reads and writes one surface's content as HTML text, so an application can offer
+direct source editing without giving up the engine's guarantees.
+
+`source.js` provides the whole responsibility; the dialog that shows the text is
+UI and belongs to a client module.
+
+## Contract
+
+- `new Source(surface, {sanitizer, indent})` needs nothing but a surface. The
+  default sanitizer is a `NativeSanitizer`; `indent` must be whitespace.
+- `read()` returns `{html, start, end}`. The offsets point into `html` and
+  locate the current selection, or are null when the surface does not own one.
+  Reading never mutates the surface.
+- `write(html)` replaces the whole content and returns the inserted nodes. It
+  runs as one transaction with the `source` command trigger, so it becomes one
+  undo step, and it leaves the caret at the start of the new content.
+- Writing rejects anything but a string.
+- Core-retained UI is omitted from HTML and survives replacement. A direct
+  modal, popover, or fullscreen editing host therefore never exposes its
+  temporarily nested editor chrome as source content.
+
+## Reading
+
+The writer walks the live DOM instead of post-processing a serialized string, so
+it cannot invent markup, and it reports where DOM boundaries land in its output
+as it goes — no marker nodes are inserted into the content being read. Escaping
+is accounted for, so an offset inside `a & b` is exact.
+
+A level is broken into one node per line only when nothing on it can be affected
+by added whitespace: every child is a block element, a comment, or whitespace
+that is already there. Inline content therefore always stays on one line, and
+the whitespace formatting adds is never significant.
+
+## Writing
+
+Source text is external input even when the same user just read it out, so it
+always goes through the configured sanitizer, which parses through
+`Element.setHTML()`. Nothing is ever assigned to `innerHTML`. The surface's
+`--u2-rte-elements` narrows the sanitizer further, so a host cannot be filled
+with elements it does not allow.
+
+The line breaks reading added are removed again before insertion: a whitespace
+node between block siblings is formatting, not content. This is the exact
+inverse of the rule reading used, so reading and writing the same text is a
+round trip.
+
+## Browser considerations
+
+- `Element.setHTML()` is required. `NativeSanitizer.supported()` reports whether
+  it exists; there is deliberately no unsafe fallback parser.
+
+## TODO
+
+- Let non-interactive consumers replace content without changing selection or
+  focus. Initializing a form adapter must not move the caret into its surface;
+  the current `write()` always restores a selection at the start.
+- Map the dialog's own selection back into the DOM after a write, the way
+  reading maps the other direction.
+- Serialize through a canonical serializer once one exists, so attribute order
+  and boolean attributes are stable across engines.
+- Report where a write's sanitizer removed content, so a source view can tell
+  the user what was dropped instead of silently applying less than was typed.

package/js/rte/src/source/source.js

@@ -0,0 +1,193 @@
+import {htmlModel} from '../model/html/html-model.js';
+import {narrow} from '../command/edit.js';
+import {NativeSanitizer} from '../sanitize/native.js';
+import {SelectionSnapshot} from '../selection/snapshot.js';
+import {replaceContent} from '../surface/content.js';
+
+const VOID = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'source', 'track', 'wbr']);
+
+// Reads and writes one surface's content as HTML text.
+//
+// Reading serializes the live DOM and reports where the current selection falls
+// in that text, so a source view can open exactly where the caret is. It walks
+// the DOM instead of post-processing a string, so it cannot invent markup, and
+// it never mutates the surface to place markers.
+//
+// Writing is the only path that turns text back into content, and it always
+// goes through the configured sanitizer: source text is external input even
+// when the same user just read it out.
+export class Source {
+    #surface;
+    #sanitizer;
+    #indent;
+
+    constructor(surface, {sanitizer = new NativeSanitizer(), indent = '    '} = {}) {
+        if (surface?.element?.nodeType !== Node.ELEMENT_NODE || typeof surface?.transact !== 'function') {
+            throw new TypeError('A source view requires an editor surface');
+        }
+        if (typeof sanitizer?.sanitize !== 'function') throw new TypeError('A source view requires a sanitizer');
+        if (typeof indent !== 'string' || indent.trim()) throw new TypeError('Source indentation must be whitespace');
+        this.#surface = surface;
+        this.#sanitizer = sanitizer;
+        this.#indent = indent;
+    }
+
+    get surface() { return this.#surface; }
+    get sanitizer() { return this.#sanitizer; }
+
+    // `{html, start, end}`. The offsets point into `html`, or are null when the
+    // surface does not currently own a selection.
+    read() {
+        const root = this.#surface.element;
+        const snapshot = SelectionSnapshot.capture(this.#surface.core.selection, root) || this.#surface.selection;
+        const range = snapshot?.valid() ? snapshot.range() : null;
+        const marks = range ? [
+            {node: range.startContainer, offset: range.startOffset},
+            {node: range.endContainer, offset: range.endOffset},
+        ] : [];
+        const writer = new Writer(this.#model(), this.#indent, marks, node => this.#surface.core.retains(node));
+        writer.children(root, 0);
+        // The outermost separated level wraps the whole document; that first and
+        // last break are framing, not content.
+        const lead = writer.text.startsWith('\n') ? 1 : 0;
+        const html = writer.text.slice(lead).replace(/\n$/, '');
+        const clamp = value => value === null ? null : Math.min(Math.max(value - lead, 0), html.length);
+        const [start = null, end = null] = writer.offsets;
+        return {html, start: clamp(start), end: clamp(end)};
+    }
+
+    // Replaces the whole content and returns the inserted nodes.
+    write(html) {
+        if (typeof html !== 'string') throw new TypeError('Source must be written as a string');
+        const root = this.#surface.element;
+        const settings = this.#surface.config;
+        const fragment = this.#sanitizer.sanitize(html, {
+            document: root.ownerDocument,
+            elements: settings.elements ?? undefined,
+            classes: settings.classes.length ? settings.classes : null,
+        });
+        // The breaks between blocks are what reading added for legibility; they
+        // are not content and must not return as text nodes.
+        prune(fragment, this.#model());
+        const nodes = [...fragment.childNodes];
+        this.#surface.transact(transaction => {
+            replaceContent(this.#surface, fragment);
+            transaction.touch(root);
+            const range = root.ownerDocument.createRange();
+            range.setStart(root, 0);
+            range.collapse(true);
+            new SelectionSnapshot(root, range).restore(this.#surface.core.selection);
+        }, {trigger: 'command', command: 'source'});
+        return nodes;
+    }
+
+    #model() {
+        return narrow(htmlModel, this.#surface.config.elements);
+    }
+}
+
+// One indented pass over the DOM that also reports where given DOM boundaries
+// land in its output. A level gets one element per line only where every child
+// is a block, so the whitespace this adds is never significant.
+class Writer {
+    #model;
+    #indent;
+    #marks;
+    #skip;
+    text = '';
+    offsets;
+
+    constructor(model, indent, marks, skip) {
+        this.#model = model;
+        this.#indent = indent;
+        this.#marks = marks;
+        this.#skip = skip;
+        this.offsets = marks.map(() => null);
+    }
+
+    children(parent, depth) {
+        const lines = separated(parent, this.#model, this.#skip);
+        const nodes = [...parent.childNodes];
+        for (const [index, child] of nodes.entries()) {
+            this.#at(parent, index);
+            if (this.#skip(child)) continue;
+            if (lines && blank(child)) continue;
+            if (lines) this.#line(depth);
+            this.node(child, depth);
+        }
+        this.#at(parent, nodes.length);
+        if (lines) this.#line(depth - 1);
+    }
+
+    node(node, depth) {
+        if (node.nodeType === Node.TEXT_NODE) return this.#characters(node);
+        if (node.nodeType === Node.COMMENT_NODE) {
+            this.text += `<!--${node.data}-->`;
+            return;
+        }
+        if (node.nodeType !== Node.ELEMENT_NODE) return;
+        const name = node.localName;
+        this.text += `<${name}${attributes(node)}>`;
+        if (VOID.has(name)) return;
+        this.children(node, depth + 1);
+        this.text += `</${name}>`;
+    }
+
+    #characters(node) {
+        for (const [index, mark] of this.#marks.entries()) {
+            if (this.offsets[index] === null && mark.node === node) {
+                this.offsets[index] = this.text.length + escape(node.data.slice(0, mark.offset)).length;
+            }
+        }
+        this.text += escape(node.data);
+    }
+
+    #at(parent, index) {
+        for (const [position, mark] of this.#marks.entries()) {
+            if (this.offsets[position] === null && mark.node === parent && mark.offset === index) {
+                this.offsets[position] = this.text.length;
+            }
+        }
+    }
+
+    #line(depth) {
+        this.text += '\n' + this.#indent.repeat(Math.max(depth, 0));
+    }
+}
+
+// A level is broken into lines only where nothing on it can be affected by
+// added whitespace: block elements, comments, and whitespace already there.
+function separated(parent, model, skip = () => false) {
+    const nodes = [...parent.childNodes].filter(node => !skip(node));
+    return nodes.some(node => standalone(node, model))
+        && nodes.every(node => blank(node) || standalone(node, model));
+}
+
+function standalone(node, model) {
+    return node.nodeType === Node.COMMENT_NODE
+        || node.nodeType === Node.ELEMENT_NODE && model.block(node);
+}
+
+function blank(node) {
+    return node.nodeType === Node.TEXT_NODE && !node.data.trim();
+}
+
+function prune(parent, model) {
+    for (const child of parent.childNodes) {
+        if (child.nodeType === Node.ELEMENT_NODE) prune(child, model);
+    }
+    if (!separated(parent, model)) return;
+    for (const child of [...parent.childNodes]) if (blank(child)) child.remove();
+}
+
+function attributes(element) {
+    let result = '';
+    for (const attribute of element.attributes) {
+        result += ` ${attribute.name}="${escape(attribute.value).replaceAll('"', '&quot;')}"`;
+    }
+    return result;
+}
+
+function escape(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+}

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

@@ -0,0 +1,36 @@
+# Editable surfaces
+
+`surface.js` represents one explicit `contenteditable` host registered with a
+core. It owns host-specific configuration, saved selection, active state, and
+the current transaction while the core owns document-level routing.
+
+## Contract
+
+- CSS configuration is resolved dynamically through `surface.config`.
+- `capture()` accepts only selections belonging to this editable host.
+- Identical captures reuse the current snapshot and do not emit duplicate
+  selection events.
+- `restore()` restores the last valid selection, including its direction.
+- `transact()` creates one atomic transaction; nested calls reuse it.
+- Lifecycle, selection, and change events reach both the `Surface` EventTarget
+  and the DOM host as bubbling, composed `u2-rte-*` events. The DOM host is
+  notified first, so a listener there observes an event before the modules that
+  react to it, and `u2-rte-change` still arrives last as the completed change.
+- `dispose()` unregisters through the owning core; `[Symbol.dispose]()` exposes
+  it to `using`, and `disconnect()` is idempotent.
+- No mutable state is stored globally or shared accidentally between surfaces.
+
+`content.js` supplies the internal content boundary used by whole-document
+consumers. Direct children retained by the core are editor UI, not surface
+content: replacement preserves them and traversal leaves them out. This matters
+only while native modal, popover, or fullscreen isolation temporarily requires
+the shared chrome to be a descendant of the editable host.
+
+The surface gains schema, normalization, pending marks, history, and composition
+state through modules rather than new globals.
+
+## TODO
+
+- Add typed module state slots without central registration boilerplate.
+- Coordinate IME composition and native input with transaction grouping.
+- Decide how disabled/read-only transitions affect saved selections and UIs.

package/js/rte/src/surface/content.js

@@ -0,0 +1,16 @@
+// Editor UI normally lives outside a surface. Native top-layer isolation is
+// the exception: a modal dialog, popover, or fullscreen host can only keep UI
+// interactive when that UI is its flat-tree descendant. Retained nodes are
+// therefore DOM children but never document content.
+export function contentChildren(surface, parent = surface.element) {
+    return [...parent.childNodes].filter(node => !surface.core.retains(node));
+}
+
+export function replaceContent(surface, ...nodes) {
+    const root = surface.element;
+    const retained = [...root.childNodes].filter(node => surface.core.retains(node));
+    for (const node of [...root.childNodes]) if (!surface.core.retains(node)) node.remove();
+    const fragment = root.ownerDocument.createDocumentFragment();
+    fragment.append(...nodes);
+    root.insertBefore(fragment, retained[0] || null);
+}

package/js/rte/src/surface/surface.js

@@ -0,0 +1,87 @@
+import {config} from '../config/config.js';
+import {SelectionSnapshot} from '../selection/snapshot.js';
+import {Transaction} from '../transaction/transaction.js';
+
+export class Surface extends EventTarget {
+    #core;
+    #element;
+    #options;
+    #selection = null;
+    #transaction = null;
+    #active = false;
+    #connected = true;
+
+    constructor(core, element, options = {}) {
+        super();
+        this.#core = core;
+        this.#element = element;
+        this.#options = Object.freeze({...options});
+    }
+
+    get core() { return this.#core; }
+    get element() { return this.#element; }
+    get options() { return this.#options; }
+    get config() { return config(this.#element); }
+    get selection() { return this.#selection; }
+    get transaction() { return this.#transaction; }
+    get active() { return this.#active; }
+    get connected() { return this.#connected; }
+
+    capture(selection = this.#core.selection) {
+        const snapshot = SelectionSnapshot.capture(selection, this.#element);
+        if (!snapshot) return null;
+        if (this.#selection?.equals(snapshot)) return this.#selection;
+        this.#selection = snapshot;
+        this.emit('u2-rte-selectionchange', {selection: snapshot});
+        return snapshot;
+    }
+
+    restore() {
+        return this.#selection?.restore(this.#core.selection) || false;
+    }
+
+    transact(change, options) {
+        if (!this.#connected) throw new DOMException('The surface is disconnected', 'InvalidStateError');
+        if (this.#transaction) return change(this.#transaction);
+        const transaction = new Transaction(this, options);
+        this.#transaction = transaction;
+        try {
+            return transaction.run(change);
+        } finally {
+            this.#transaction = null;
+        }
+    }
+
+    activate(active = true) {
+        if (this.#active === active) return this;
+        this.#active = active;
+        this.emit(active ? 'u2-rte-activate' : 'u2-rte-deactivate');
+        return this;
+    }
+
+    // The DOM host is notified first: modules listening on the surface act on
+    // an event, so observers would otherwise see the consequence before it.
+    emit(type, detail = {}, options = {}) {
+        const init = {detail: {surface: this, ...detail}, cancelable: options.cancelable};
+        const Event = this.#element.ownerDocument.defaultView.CustomEvent;
+        const dom = this.#element.dispatchEvent(new Event(type, {...init, bubbles: true, composed: true}));
+        const local = this.dispatchEvent(new Event(type, init));
+        return local && dom;
+    }
+
+    dispose() {
+        this.#core.delete(this);
+    }
+
+    [Symbol.dispose]() {
+        this.dispose();
+    }
+
+    disconnect() {
+        if (!this.#connected) return;
+        this.activate(false);
+        this.#connected = false;
+        this.#selection = null;
+        this.emit('u2-rte-disconnect');
+    }
+}