u2ui 1.5.3 → 1.5.4

package/js/rte/src/normalize/repair/repair-planner.js

@@ -0,0 +1,208 @@
+import {htmlModel} from '../../model/html/html-model.js';
+import {isEditingBoundary} from '../../selection/ownership/ownership.js';
+
+const LEVELS = new Set(['none', 'minimal', 'structural', 'canonical']);
+const KEEP = Object.freeze({type: 'keep'});
+const BOUNDARY = Object.freeze({type: 'boundary'});
+const REMOVE = Object.freeze({type: 'remove'});
+const REJECT = Object.freeze({type: 'reject'});
+
+export class RepairPlanner {
+    #root;
+    #model;
+    #block;
+    #level;
+    #generic;
+    #elements = new Map();
+    #rootWrapper;
+
+    constructor(root, {model = htmlModel, block = null, level = 'structural', generic = ['div', 'span']} = {}) {
+        if (root?.nodeType !== Node.ELEMENT_NODE) throw new TypeError('A repair planner requires an element root');
+        if (typeof model?.allows !== 'function' || typeof model?.allowed !== 'function'
+            || typeof model?.rule !== 'function' || typeof model?.block !== 'function') {
+            throw new TypeError('A repair planner requires a content model');
+        }
+        if (block !== null && (typeof block !== 'string' || !block.trim())) {
+            throw new TypeError('Default block must be a tag name or null');
+        }
+        if (!LEVELS.has(level)) throw new TypeError('Unknown normalization level');
+        if (!Array.isArray(generic) || generic.some(name => typeof name !== 'string' || !name.trim())) {
+            throw new TypeError('Generic blocks must be tag names');
+        }
+        this.#root = root;
+        this.#model = model;
+        this.#block = block?.toLowerCase() || null;
+        this.#level = level;
+        this.#generic = new Set(generic.map(name => name.toLowerCase()));
+    }
+
+    get root() { return this.#root; }
+    get model() { return this.#model; }
+    get block() { return this.#block; }
+    get level() { return this.#level; }
+
+    plan(parent, child) {
+        if (child?.parentNode !== parent) throw new RangeError('Repair planning requires a direct child');
+        if (parent !== this.#root && !this.#root.contains(parent)) throw new RangeError('Repair parent must belong to the planner root');
+        if (this.#level === 'none') return KEEP;
+        if (isEditingBoundary(child)) return BOUNDARY;
+
+        if (this.#level !== 'minimal') {
+            const plan = parent === this.#root
+                ? this.#rootPlan(child)
+                : this.#genericPlan(parent, child) || this.#loosePlan(parent, child);
+            if (plan) return plan;
+        }
+        if (this.#level !== 'minimal' && this.#hollow(child)) return REMOVE;
+        if (this.#level === 'canonical') {
+            const plan = this.#canonicalPlan(parent, child);
+            if (plan) return plan;
+        }
+        if (this.#model.allows(parent, child)) return KEEP;
+        if (ignorable(child)) return REMOVE;
+        if (child.nodeType === Node.ELEMENT_NODE && !this.#model.allowed(child)) {
+            return this.#model.atomic(child) ? REMOVE : action('unwrap', {breaks: this.#model.block(child)});
+        }
+
+        const wrapper = this.#wrapper(parent);
+        if (wrapper && this.#model.allows(parent, wrapper) && this.#model.allows(wrapper, child)) {
+            return action('wrap', {tag: wrapper.localName});
+        }
+        if (child.nodeType === Node.ELEMENT_NODE && neutral(child)) {
+            const children = [...child.childNodes];
+            if (children.length && children.every(node => this.#model.allows(parent, node))) {
+                const content = children.filter(node => !ignorable(node));
+                const breaks = this.#model.block(child) && content.some(node => !this.#model.block(node));
+                return action('unwrap', {breaks});
+            }
+            if (!children.length && !this.#model.atomic(child)) return REMOVE;
+        }
+        for (let target = parent.parentElement; target && this.#root.contains(target); target = target.parentElement) {
+            if (this.#model.allows(target, child)) return action('lift', {target});
+            if (target === this.#root) break;
+        }
+        return REJECT;
+    }
+
+    #rootPlan(child) {
+        // Whether the root accepts its default block does not depend on the
+        // child, so it is decided once instead of for every one of them.
+        this.#rootWrapper ??= this.#usableRootWrapper();
+        const wrapper = this.#rootWrapper;
+        if (!wrapper) return null;
+        if (ignorable(child)) {
+            const previous = child.previousSibling;
+            return child.nodeType === Node.TEXT_NODE
+                && previous
+                && !ignorable(previous)
+                && !this.#model.block(previous)
+                && this.#model.allows(wrapper, child)
+                    ? action('wrap', {tag: wrapper.localName})
+                    : REMOVE;
+        }
+        if (child.nodeType === Node.ELEMENT_NODE && !this.#model.allowed(child) && this.#model.block(child)) {
+            const children = [...child.childNodes];
+            if (children.every(node => this.#model.allows(wrapper, node))) {
+                return action('convert', {tag: wrapper.localName});
+            }
+        }
+        const plan = this.#genericPlan(this.#root, child);
+        if (plan) return plan;
+        if (!this.#model.block(child) && this.#model.allows(wrapper, child)) {
+            return action('wrap', {tag: wrapper.localName});
+        }
+        return null;
+    }
+
+    // A neutral generic block adds nothing to the document: it becomes the block
+    // its context expects, or dissolves into it. Depth is not a reason to keep
+    // one — a bare wrapper is as redundant four levels down as it is at the top,
+    // and valid nesting is exactly why the model alone never removes it. A
+    // generic inline element is not structure and is left to `canonical`.
+    #genericPlan(parent, child) {
+        if (child.nodeType !== Node.ELEMENT_NODE) return null;
+        if (!this.#generic.has(child.localName) || !neutral(child)) return null;
+        if (!this.#model.block(child)) return null;
+        const children = [...child.childNodes];
+        const wrapper = this.#element(this.#model.rule(parent).defaultChild || this.#block);
+        if (wrapper && wrapper.localName !== child.localName
+            && this.#model.allows(parent, wrapper)
+            && children.every(node => this.#model.allows(wrapper, node))) {
+            return action('convert', {tag: wrapper.localName});
+        }
+        const content = children.filter(node => !ignorable(node));
+        if (content.some(node => this.#model.block(node))
+            && content.every(node => this.#model.allows(parent, node))) {
+            return action('unwrap', {breaks: false});
+        }
+        return null;
+    }
+
+    // Loose inline content standing beside blocks in a generic container is the
+    // same asymmetry as a bare wrapper: the root already gives it a block, and
+    // depth is not a reason to leave it homeless. Containers that carry their
+    // own meaning — list items, cells, quotes — keep loose text as it is.
+    #loosePlan(parent, child) {
+        if (!this.#generic.has(parent.localName) || !this.#model.block(parent)) return null;
+        if (ignorable(child) || this.#model.block(child)) return null;
+        const wrapper = this.#element(this.#model.rule(parent).defaultChild || this.#block);
+        if (!wrapper || !this.#model.allows(parent, wrapper) || !this.#model.allows(wrapper, child)) return null;
+        if (![...parent.children].some(node => this.#model.block(node))) return null;
+        return action('wrap', {tag: wrapper.localName});
+    }
+
+    // Canonical goes one step further than valid: a generic wrapper carrying
+    // neither attributes nor meaning of its own is noise even where the model
+    // allows it. A semantic element is never noise, however bare it is.
+    // An inline element with neither attributes nor content says nothing at all,
+    // whatever its name, so it never has to survive being valid.
+    #hollow(child) {
+        return child.nodeType === Node.ELEMENT_NODE
+            && neutral(child)
+            && !child.childNodes.length
+            && !this.#model.block(child)
+            && !this.#model.atomic(child);
+    }
+
+    #canonicalPlan(parent, child) {
+        if (child.nodeType !== Node.ELEMENT_NODE || !neutral(child)) return null;
+        if (this.#model.block(child) || this.#model.atomic(child)) return null;
+        if (!this.#generic.has(child.localName)) return null;
+        return [...child.childNodes].every(node => this.#model.allows(parent, node))
+            ? action('unwrap', {breaks: false})
+            : null;
+    }
+
+    #usableRootWrapper() {
+        const wrapper = this.#element(this.#block);
+        return wrapper && this.#model.allows(this.#root, wrapper) ? wrapper : null;
+    }
+
+    #wrapper(parent) {
+        const name = parent === this.#root && this.#block || this.#model.rule(parent).defaultChild;
+        return this.#element(name);
+    }
+
+    #element(name) {
+        if (!name) return null;
+        let element = this.#elements.get(name);
+        if (!element) {
+            element = this.#root.ownerDocument.createElement(name);
+            this.#elements.set(name, element);
+        }
+        return element;
+    }
+}
+
+function action(type, detail) {
+    return Object.freeze({type, ...detail});
+}
+
+function neutral(node) {
+    return node.attributes.length === 0;
+}
+
+function ignorable(node) {
+    return node.nodeType === Node.COMMENT_NODE
+        || node.nodeType === Node.TEXT_NODE && !node.data.trim();
+}

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

@@ -0,0 +1,105 @@
+# HTML sanitizing
+
+Sanitizing is the security boundary for HTML that comes from outside the
+editor, such as paste, drop, or an HTML source dialog. It decides which
+elements, attributes, and URL protocols may enter a detached fragment.
+Structural normalization runs only afterwards and has a different job: it
+repairs editable document shape.
+
+## Policy
+
+`SanitizePolicy` is an immutable allowlist. Its options are:
+
+- `elements`: element names the security policy can accept;
+- `attributes`: global (`*`) and per-element attribute names;
+- `protocols`: per-element rules for URL attributes;
+- `comments` and `dataAttributes`: explicit booleans, both false by default.
+
+The supplied `sanitizePolicy` accepts the `document` element preset, ordinary
+editor metadata, and conservative web URLs. Inline styles, event attributes,
+`data:` URLs, comments, and data attributes are not enabled by default.
+Relative URLs use the explicit `relative` protocol token. Known URL attributes
+without a matching protocol rule are removed rather than accepted implicitly.
+
+```js
+const policy = new SanitizePolicy({
+    elements: ['p', 'a', 'strong'],
+    attributes: {'*': ['class'], a: ['href', 'rel']},
+    protocols: {a: {href: ['https', 'relative']}},
+});
+```
+
+`clean(root)` enforces attribute and URL rules on an already safely parsed DOM
+tree. It is public for adapters, but it is not an HTML parser or a standalone
+security sanitizer: it must never be paired with `innerHTML`, `DOMParser`, or
+another unsafe sink for untrusted input.
+
+## Native adapter
+
+`NativeSanitizer` passes input directly to `Element.setHTML()` on a detached
+template and returns its `DocumentFragment`. It never inserts the result into
+an editor. `sanitize(html, {elements})` intersects the security elements with a
+surface's structural element list. Security-safe wrappers excluded by that
+surface are unwrapped; the sanitizer policy can never be broadened.
+
+The native HTML Sanitizer API is not available in every target engine yet.
+`NativeSanitizer.supported(document)` exposes that capability. `sanitize()`
+throws `NotSupportedError` when the safe sink is absent; it deliberately has no
+`innerHTML` fallback. RTE's normal paste/drop path therefore remains native in
+those engines and performs presentation plus structural cleanup afterwards; it
+does not need to parse the clipboard HTML string.
+
+The returned fragment remains untrusted if it is serialized back to a string.
+Consumers should insert the fragment through the editor transaction path, not
+round-trip it through an HTML string. `ExternalInput` composes that path for
+rich paste/drop events and direct HTML imports.
+
+## Invariants
+
+- External HTML reaches no unsafe DOM sink.
+- Surface element configuration narrows security policy and never broadens it.
+- Attribute and URL policy remains separate from structural normalization.
+- Sanitizing creates no editor state, listeners, or markers.
+- Policies do not mutate after construction.
+
+## Where the policy is applied
+
+Three paths bring external HTML in, and all three now meet the same policy:
+
+- `Source.write()` and `ExternalInput.insert()` parse an HTML string, so they go
+  through the sanitizer's safe sink first and then `clean()`.
+- An ordinary paste or drop is inserted by the browser itself. Nothing is parsed
+  there and no fallback parser is needed, but the result still has to obey the
+  same attribute policy — so the input pipeline applies `clean()` to the nodes
+  that arrived. Until it did, the most common import was the only one without an
+  allowlist, and layout ids, tracking `data-` attributes and inline styles came
+  straight through.
+
+`clean(root, {preserve})` spares elements that were already there, so a paste
+never re-cleans the document it landed in.
+
+`narrow(root, {elements, preserve, map, skip})` reduces a subtree to the elements
+the policy allows, keeping the content of the rest. Parsed input gets this from
+the safe sink; markup the browser inserted itself has to be narrowed afterwards.
+`elements` may narrow further but never past the policy, and `skip` leaves an
+element to a later stage.
+
+`alias` names an equivalent for an element the list does not carry. Dropping
+`<b>` would lose the emphasis it holds — nothing rewrites it later, because the
+bold mark recognizes `<b>` but only a mark command ever makes an element
+canonical — so a strict list keeps the meaning by taking `<strong>` instead. An
+alias can only ever name an element the list already allows.
+
+## Declared content classes
+
+`clean(root, {classes})` narrows the class attribute to the given names without
+touching the security policy. An application declares its content classes once
+through `--u2-rte-classes`; external HTML then cannot smuggle in classes the
+host does not know, and the same list drives the style control and presentation
+cleanup.
+
+## TODO
+
+- Add contextual parsing for table and list insertion sites.
+- Add optional class, inline-style, and richer image URL policies.
+- Cover mutation-XSS and pasted office markup with shared adapter fixtures.

package/js/rte/src/sanitize/native.js

@@ -0,0 +1,43 @@
+import {sanitizePolicy} from './policy.js';
+
+export class NativeSanitizer {
+    constructor(policy = sanitizePolicy) {
+        if (!policy || !Array.isArray(policy.elements)
+            || !Array.isArray(policy.attributeNames) || typeof policy.clean !== 'function') {
+            throw new TypeError('A sanitize policy is required');
+        }
+        this.policy = policy;
+        Object.freeze(this);
+    }
+
+    static supported(document = globalThis.document) {
+        return typeof document?.createElement?.('template').setHTML === 'function';
+    }
+
+    sanitize(html, options = {}) {
+        const document = options.document ?? globalThis.document;
+        const template = document?.createElement?.('template');
+        if (typeof template?.setHTML !== 'function') {
+            throw new DOMException('Element.setHTML() is not available', 'NotSupportedError');
+        }
+        template.setHTML(html, {sanitizer: config(this.policy, options.elements)});
+        return this.policy.clean(template.content, {
+            base: options.base ?? document.baseURI,
+            classes: options.classes ?? null,
+        });
+    }
+}
+
+function config(policy, elements) {
+    const selected = elements == null ? null : new Set(elements.map(name => name.toLowerCase()));
+    const allowed = selected ? policy.elements.filter(name => selected.has(name)) : policy.elements;
+    const replaced = selected ? policy.elements.filter(name => !selected.has(name)) : [];
+    const result = {
+        elements: allowed,
+        attributes: policy.attributeNames,
+        comments: policy.comments,
+        dataAttributes: policy.dataAttributes,
+    };
+    if (replaced.length) result.replaceWithChildrenElements = replaced;
+    return result;
+}

package/js/rte/src/sanitize/policy.js

@@ -0,0 +1,202 @@
+import {elementPresets} from '../config/config.js';
+
+const NAME = /^[a-z][a-z\d-]*$/;
+const ATTRIBUTE = /^[a-z][a-z\d_.:-]*$/;
+const PROTOCOL = /^[a-z][a-z\d+.-]*$/;
+const URL_ATTRIBUTES = new Set(['action', 'cite', 'formaction', 'href', 'poster', 'src', 'xlink:href']);
+const DEFAULT_ATTRIBUTES = Object.freeze({
+    '*': Object.freeze(['class', 'dir', 'lang', 'title']),
+    a: Object.freeze(['href', 'rel', 'target']),
+    blockquote: Object.freeze(['cite']),
+    img: Object.freeze(['alt', 'height', 'loading', 'src', 'width']),
+    li: Object.freeze(['value']),
+    ol: Object.freeze(['reversed', 'start', 'type']),
+    q: Object.freeze(['cite']),
+    td: Object.freeze(['colspan', 'headers', 'rowspan']),
+    th: Object.freeze(['abbr', 'colspan', 'headers', 'rowspan', 'scope']),
+    time: Object.freeze(['datetime']),
+});
+const DEFAULT_PROTOCOLS = Object.freeze({
+    a: Object.freeze({href: Object.freeze(['http', 'https', 'mailto', 'relative', 'tel'])}),
+    blockquote: Object.freeze({cite: Object.freeze(['http', 'https', 'relative'])}),
+    img: Object.freeze({src: Object.freeze(['http', 'https', 'relative'])}),
+    q: Object.freeze({cite: Object.freeze(['http', 'https', 'relative'])}),
+});
+
+export const sanitizeDefaults = Object.freeze({
+    elements: elementPresets.document,
+    attributes: DEFAULT_ATTRIBUTES,
+    protocols: DEFAULT_PROTOCOLS,
+    comments: false,
+    dataAttributes: false,
+});
+
+export class SanitizePolicy {
+    #attributes;
+    #protocols;
+
+    constructor(options = {}) {
+        this.elements = names(options.elements ?? sanitizeDefaults.elements, NAME, 'element');
+        this.#attributes = groups(options.attributes ?? sanitizeDefaults.attributes, ATTRIBUTE, 'attribute');
+        this.#protocols = protocolGroups(options.protocols ?? sanitizeDefaults.protocols);
+        this.attributeNames = Object.freeze(unique(Object.values(this.#attributes).flat()));
+        this.comments = boolean(options.comments ?? sanitizeDefaults.comments, 'comments');
+        this.dataAttributes = boolean(options.dataAttributes ?? sanitizeDefaults.dataAttributes, 'dataAttributes');
+        Object.freeze(this);
+    }
+
+    allowsAttribute(element, attribute) {
+        const name = element.localName.toLowerCase();
+        const attributeName = attribute.toLowerCase();
+        if (this.dataAttributes && attributeName.startsWith('data-')) return true;
+        return this.#attributes['*']?.includes(attributeName)
+            || this.#attributes[name]?.includes(attributeName)
+            || false;
+    }
+
+    allowsUrl(element, attribute, value, base = element.ownerDocument?.baseURI) {
+        const attributeName = attribute.toLowerCase();
+        if (!URL_ATTRIBUTES.has(attributeName)) return true;
+        const protocols = this.#protocols[element.localName.toLowerCase()]?.[attributeName]
+            || this.#protocols['*']?.[attributeName];
+        if (!protocols) return false;
+        const protocol = urlProtocol(value, base);
+        return protocol !== null && protocols.includes(protocol);
+    }
+
+    // Reduces a subtree to the elements this policy allows, keeping the content
+    // of the rest. Parsed input gets this from the safe sink; markup the browser
+    // inserted itself has to be narrowed afterwards.
+    //
+    // `skip` leaves an element to a later stage. Structural repair already
+    // removes what the content model rejects, and it does so knowing that
+    // dissolving a block into inline content needs a line break to survive.
+    //
+    // `alias` names an equivalent for an element that is not allowed. Dropping
+    // `<b>` would lose the emphasis it carries, so a strict list can still keep
+    // the meaning by taking the canonical element instead.
+    narrow(root, {elements = null, preserve = null, map = null, skip = null, alias = null} = {}) {
+        // A caller may narrow further but never past the policy itself.
+        const allowed = elements === null
+            ? this.elements
+            : this.elements.filter(name => elements.includes(name));
+        const changed = [];
+        for (const element of descendants(root).reverse()) {
+            if (preserve?.has(element) || allowed.includes(element.localName)) continue;
+            if (!element.parentNode || skip?.(element)) continue;
+            const equivalent = alias?.[element.localName];
+            if (equivalent && allowed.includes(equivalent)) {
+                const replacement = element.ownerDocument.createElement(equivalent);
+                for (const attribute of element.attributes) replacement.setAttribute(attribute.name, attribute.value);
+                if (map) map.replaceWrapper(element, replacement);
+                else {
+                    replacement.append(...element.childNodes);
+                    element.replaceWith(replacement);
+                }
+                changed.push(replacement);
+                continue;
+            }
+            if (map) map.unwrap(element);
+            else element.replaceWith(...element.childNodes);
+            changed.push(element);
+        }
+        return changed;
+    }
+
+    // `classes` narrows the class attribute to known names without touching the
+    // security policy: an application declares its content classes once and
+    // foreign ones do not survive external input.
+    clean(root, {base, classes = null, preserve = null} = {}) {
+        const known = classes === null ? null : new Set(classes);
+        for (const element of descendants(root)) {
+            if (preserve?.has(element)) continue;
+            for (const attribute of [...element.attributes]) {
+                if (!this.allowsAttribute(element, attribute.name)
+                    || !this.allowsUrl(element, attribute.name, attribute.value, base)) {
+                    element.removeAttributeNode(attribute);
+                } else if (known && attribute.name.toLowerCase() === 'class') {
+                    keepClasses(element, known);
+                }
+            }
+        }
+        return root;
+    }
+}
+
+export const sanitizePolicy = new SanitizePolicy();
+
+function names(values, pattern, label) {
+    if (!values || typeof values[Symbol.iterator] !== 'function' || typeof values === 'string') {
+        throw new TypeError(`${label} names must be an iterable`);
+    }
+    const result = [];
+    for (const value of values) {
+        const name = String(value).toLowerCase();
+        if (!pattern.test(name)) throw new TypeError(`Invalid ${label} name: ${value}`);
+        if (!result.includes(name)) result.push(name);
+    }
+    return Object.freeze(result);
+}
+
+function groups(value, pattern, label) {
+    if (!plainObject(value)) throw new TypeError(`${label} groups must be an object`);
+    const result = {};
+    for (const [name, values] of Object.entries(value)) {
+        const key = name === '*' ? name : names([name], NAME, 'element')[0];
+        result[key] = names(values, pattern, label);
+    }
+    return Object.freeze(result);
+}
+
+function protocolGroups(value) {
+    if (!plainObject(value)) throw new TypeError('protocol groups must be an object');
+    const result = {};
+    for (const [element, attributes] of Object.entries(value)) {
+        const name = element === '*' ? element : names([element], NAME, 'element')[0];
+        if (!plainObject(attributes)) throw new TypeError('protocol attributes must be an object');
+        const rules = {};
+        for (const [attribute, protocols] of Object.entries(attributes)) {
+            const attributeName = names([attribute], ATTRIBUTE, 'attribute')[0];
+            const values = names(protocols, PROTOCOL, 'protocol');
+            rules[attributeName] = values;
+        }
+        result[name] = Object.freeze(rules);
+    }
+    return Object.freeze(result);
+}
+
+function urlProtocol(value, base) {
+    const input = String(value).trim();
+    const compact = input.replace(/[\u0000-\u0020]/g, '');
+    if (!/^[a-z][a-z\d+.-]*:/i.test(compact)) return 'relative';
+    try {
+        return new URL(input, base).protocol.slice(0, -1).toLowerCase();
+    } catch {
+        return null;
+    }
+}
+
+function keepClasses(element, known) {
+    const kept = [...element.classList].filter(name => known.has(name));
+    if (kept.length === element.classList.length) return;
+    if (kept.length) element.setAttribute('class', kept.join(' '));
+    else element.removeAttribute('class');
+}
+
+function descendants(root) {
+    const result = root.nodeType === Node.ELEMENT_NODE ? [root] : [];
+    return result.concat([...root.querySelectorAll('*')]);
+}
+
+function unique(values) {
+    return [...new Set(values)];
+}
+
+function boolean(value, name) {
+    if (typeof value !== 'boolean') throw new TypeError(`${name} must be a boolean`);
+    return value;
+}
+
+function plainObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value);
+}

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

@@ -0,0 +1,39 @@
+# Selection snapshots
+
+A selection snapshot remembers the current caret or selected text so the editor
+can restore it after focus moves to a toolbar or the DOM changes. It also keeps
+the selection direction, which matters when the user selected backward.
+
+`snapshot.js` stores a live cloned browser `Range` plus that direction. Native
+ranges follow many DOM mutations automatically, so no temporary marker elements
+are inserted into the document.
+
+## Contract
+
+- `SelectionSnapshot.capture(selection, root)` returns `null` unless both
+  endpoints belong to the same explicit editable host.
+- The snapshot retains collapsed, forward, and backward selections.
+- `range()` always returns a clone; callers cannot mutate stored boundaries.
+- `equals()` compares exact boundaries, root, and direction without serializing
+  DOM paths.
+- `restore()` uses `Selection.setBaseAndExtent()` where available so direction
+  is not lost.
+- `valid()` rejects boundaries moved outside the original editable host.
+- Nested `contenteditable` elements are independent selection boundaries.
+
+Live ranges are the first preservation strategy. Editor-owned transformations
+that replace endpoints use `map/point-map.js` to map logical points explicitly
+rather than inserting temporary DOM markers.
+
+`elementOf(node)` and `isEditingBoundary(element)` are the single definitions of
+"the element context of a node" and "this element starts a new editing host".
+Every traversal in the engine uses them, so an invalid `contenteditable` value is
+a boundary nowhere rather than in some traversals only. `indexOf(node)` names a
+child boundary and lives beside `Point`.
+
+## TODO
+
+- Integrate point mapping with canonical normalization transactions.
+- Define affinity at ambiguous inline and atomic-element boundaries.
+- Cover composed ranges and browser-specific Shadow DOM selection behavior.
+- Preserve multi-range selections if browsers expose an interoperable model.

package/js/rte/src/selection/map/README.md

@@ -0,0 +1,53 @@
+# Explicit point mapping
+
+A point is a place where a caret or one edge of a selection can sit. When an
+editor command splits text, wraps nodes, or moves content, that place must move
+with the intended content. Point mapping performs the DOM change and calculates
+the new place together.
+
+`point-map.js` tracks `Point` objects through these editor-owned operations. At
+an ambiguous boundary it uses the point's affinity to decide whether the point
+follows the content before or after the change. It needs no marker nodes.
+
+## Contract
+
+- A map snapshots each point when it is added and returns a fresh mapped point
+  through `get()`; it never mutates the caller's point.
+- `backward` affinity follows preceding content and `forward` affinity follows
+  following content at insertion, split, wrap, and move boundaries.
+- Operations mutate the DOM and its mapped boundaries as one synchronous step.
+- `insert`, `insertFragment`, `insertText`, `splitText`, `wrap`, `unwrap`,
+  `split`, `replace`, `replaceWrapper`, `move`, `mergeText`, and `remove`
+  reject ambiguous or structurally invalid inputs.
+- `insertFragment` consumes a detached fragment as one multi-node insertion.
+  Parent boundaries shift by the inserted child count; boundaries expressed on
+  the fragment become equivalent parent boundaries among the inserted nodes.
+  Native insertion adopts nodes from a template or another document while
+  preserving their identity and mapped descendant points.
+- `insertText` uses DOM UTF-16 offsets and affinity at the insertion point:
+  backward stays before the inserted text, forward follows it.
+- `split` raises one boundary to a child boundary of an ancestor container by
+  splitting every element between them, and returns the resulting child offset.
+  Both halves together replace one element: no point ends up between them, and
+  every point from the boundary onward moves into the trailing half. Trailing
+  clones keep their attributes except duplicate-prone `id`. Whether the
+  container may be split at all is the caller's policy, not the map's.
+- `replace` discards a subtree and collapses its points around the replacement.
+  `replaceWrapper` changes only an element's wrapper and preserves children
+  and points inside them.
+- `move` preserves affinity-bound positions adjacent to the moved node, even
+  across parents.
+- Wrapping accepts only a non-empty, contiguous, ordered sibling sequence and
+  an empty detached wrapper.
+
+The class deliberately performs only mechanical DOM operations. HTML validity,
+editable boundaries, atomic elements, cleanup policy, and dirty-scope selection
+belong to the content model and transaction layers.
+
+## TODO
+
+- Map ranges directly without introducing a dependency from this layer to
+  `EditRange`.
+- Extend the generated cases to `remove`, `replace`, and `move`, whose result
+  cannot be checked against the surrounding text.
+- Compare longer operation sequences with a marker-based oracle.