u2ui 1.5.3 → 1.5.7

package/js/rte/rte.js

@@ -1,7 +1,58 @@
+import {Editor} from './src/client/editor.js';
+import {Rte} from './src/core/core.js';
 
-import './src/fixes.js';
-import './src/behavior.js';
-import './src/rte.js';
-import './src/ui.js';
-import './src/ui.items.js';
+export {rangeRect} from './src/browser/range-rect.js';
+export {Commands} from './src/command/commands.js';
+export {BlockStyles} from './src/command/block-style.js';
+export {deleteBackward, deleteForward} from './src/command/delete.js';
+export {Edit} from './src/command/edit.js';
+export {elementAttributes, selectedElement} from './src/command/element.js';
+export {enter, lineBreak} from './src/command/enter.js';
+export {blank, blockEdge, emptyBlock, fill} from './src/command/block-boundary.js';
+export {insertFragment} from './src/command/fragment.js';
+export {insertNode} from './src/command/insert.js';
+export {Lists} from './src/command/list.js';
+export {Tables} from './src/command/table.js';
+export {applyMark, removeMark, setMarks, toggleMark, valueMark} from './src/command/mark.js';
+export {PendingMarks} from './src/command/pending-marks.js';
+export {unstyleCommand} from './src/command/unstyle.js';
+export {config, elementPresets, enabled, hostDefaults, inlineUi} from './src/config/config.js';
+export {Rte} from './src/core/core.js';
+export {History} from './src/history/history.js';
+export {ExternalInput} from './src/input/external-input.js';
+export {InputPipeline, inputRange, inputTrigger} from './src/input/input-pipeline.js';
+export {Editor} from './src/client/editor.js';
+export {externalInputs, importLevel} from './src/client/external-input.js';
+export {history} from './src/client/history.js';
+export {marks} from './src/client/marks.js';
+export {structure} from './src/client/structure.js';
+export {classMark} from './src/mark/standard.js';
+export {
+    bold, boldHtml,
+    code, codeHtml,
+    italic, italicHtml,
+    link, linkHtml,
+    strike, strikeHtml,
+    underline, underlineHtml,
+} from './src/mark/standard.js';
+export {MarkAdapter} from './src/mark/dom-adapter.js';
+export {Mark, MarkType, markSet} from './src/mark/mark.js';
+export {ContentModel} from './src/model/content-model.js';
+export {createHtmlModel, htmlModel} from './src/model/html/html-model.js';
+export {RepairPlanner} from './src/normalize/repair/repair-planner.js';
+export {RepairExecutor} from './src/normalize/execute/repair-executor.js';
+export {Normalizer} from './src/normalize/normalizer/normalizer.js';
+export {EditRange} from './src/selection/range/edit-range.js';
+export {PointMap} from './src/selection/map/point-map.js';
+export {SelectionSnapshot} from './src/selection/snapshot.js';
+export {Point} from './src/selection/point/point.js';
+export {NativeSanitizer} from './src/sanitize/native.js';
+export {SanitizePolicy, sanitizeDefaults, sanitizePolicy} from './src/sanitize/policy.js';
+export {Source} from './src/source/source.js';
+export {Surface} from './src/surface/surface.js';
+export {Transaction} from './src/transaction/transaction.js';
+export {Toolbar} from './src/ui/toolbar.js';
+export {Unstyle, defaultUnstyle, defaultUnstyleLevels} from './src/unstyle/unstyle.js';
 
+export const rte = new Rte(document);
+export const editor = new Editor(rte);

package/js/rte/run.out

@@ -0,0 +1,17 @@
+node:internal/modules/cjs/loader:1433
+  throw err;
+  ^
+
+Error: Cannot find module '/var/www/workplace/u2/js/rte/run.mjs'
+    at Function._resolveFilename (node:internal/modules/cjs/loader:1430:15)
+    at defaultResolveImpl (node:internal/modules/cjs/loader:1040:19)
+    at resolveForCJSWithHooks (node:internal/modules/cjs/loader:1045:22)
+    at Function._load (node:internal/modules/cjs/loader:1216:25)
+    at wrapModuleLoad (node:internal/modules/cjs/loader:254:19)
+    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:171:5)
+    at node:internal/main/run_main_module:36:49 {
+  code: 'MODULE_NOT_FOUND',
+  requireStack: []
+}
+
+Node.js v22.23.2

package/js/rte/source.js

@@ -0,0 +1,12 @@
+import {editor} from './rte.js';
+import {sourceView} from './src/client/source.js';
+
+export {sourceView} from './src/client/source.js';
+export {Source} from './src/source/source.js';
+
+// Syntax highlighting is an enhancement: the dialog wraps its text area in
+// <u2-code> and works without it. This entry loads that element on first use,
+// so the composable `sourceView()` stays free of any dependency.
+export const source = sourceView({highlight: () => import('../../el/code/code.js')});
+
+editor.add(source);

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

@@ -0,0 +1,40 @@
+# Browser policies
+
+Browser policies compensate for observable differences in native editing,
+selection, and layout primitives. This directory is not a general `fixes.js`:
+each policy has one named responsibility, no hidden global state, and a focused
+regression suite. Semantic editing behavior remains in commands, normalization,
+or UI rather than being mislabeled as a browser fix.
+
+## Range geometry
+
+`range-rect.js` exports `rangeRect(range, {root})`. A native rectangle with a
+rendered size or a non-zero position is returned unchanged. When a collapsed
+range reports an entirely zero rectangle, the
+function derives its caret edge from following content, preceding content, or
+the nearest rendered ancestor inside `root`, in that order.
+
+- The DOM and live selection are never mutated; no temporary marker is inserted.
+- Text is measured with a temporary native range over one adjacent character.
+- Element boundaries use descendant content first and the element box second.
+- Returned fallbacks have zero width at the inferred caret edge and retain the
+  measured line or element height.
+- `root` is optional, but when supplied it both validates ownership and bounds
+  ancestor fallback.
+- The implementation uses observed geometry, not browser names or user-agent
+  branches.
+
+## Placement of future policies
+
+A new file belongs here only when current engines expose different or unusable
+native behavior below editor semantics. Content structure belongs to the model
+and normalizer; key meaning belongs to commands/input; focus visibility belongs
+to UI. Prefer feature detection and a narrow primitive that higher layers can
+replace or omit.
+
+## TODO
+
+- Verify collapsed text, filler, replaced-element, vertical-writing, zoom, and
+  Shadow DOM geometry in current Chromium, Firefox, and WebKit.
+- Add policy composition only after two independent policies need shared
+  installation or teardown; do not introduce a global fix registry in advance.

package/js/rte/src/browser/interactive.js

@@ -0,0 +1,17 @@
+// A link, a button, or a label around an editing host — `<a><span
+// contenteditable>` — is a host shape engines answer with the element instead of
+// 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.
+// All of it belongs to what surrounds the text, not to someone editing it.
+//
+// Only what surrounds the host is asked for: a link the content itself holds is
+// content, and what a press does to that one is the editor's own business.
+export function interactiveAround(host) {
+    return host?.closest('a[href], button, label') || null;
+}
+
+// And a button answers Space and Enter by activating itself, whatever it holds:
+// the text inside never sees those keys, and no `beforeinput` arrives at all.
+export function activatingAround(host) {
+    return host?.closest('button') || null;
+}

package/js/rte/src/browser/range-rect.js

@@ -0,0 +1,82 @@
+// Native collapsed ranges may report an empty rectangle. Derive the same caret
+// boundary from adjacent rendered content without mutating DOM or selection.
+export function rangeRect(range, {root = null} = {}) {
+    if (!range?.getBoundingClientRect || !range?.cloneRange) throw new TypeError('Range geometry requires a native Range');
+    if (root !== null && (typeof root?.contains !== 'function'
+        || !contains(root, range.startContainer) || !contains(root, range.endContainer))) {
+        throw new RangeError('Range geometry root must contain the range');
+    }
+    const native = range.getBoundingClientRect();
+    if (!range.collapsed || located(native)) return native;
+    return after(range.startContainer, range.startOffset)
+        || before(range.startContainer, range.startOffset)
+        || ancestor(range.startContainer, root)
+        || native;
+}
+
+function after(container, offset) {
+    if (container.nodeType === Node.TEXT_NODE) {
+        return offset < container.length ? textEdge(container, offset, false) : null;
+    }
+    const child = container.childNodes[offset];
+    return child ? nodeEdge(child, false) : null;
+}
+
+function before(container, offset) {
+    if (container.nodeType === Node.TEXT_NODE) {
+        return offset > 0 ? textEdge(container, offset - 1, true) : null;
+    }
+    const child = container.childNodes[offset - 1];
+    return child ? nodeEdge(child, true) : null;
+}
+
+function nodeEdge(node, end) {
+    if (node.nodeType === Node.TEXT_NODE) {
+        if (!node.length) return null;
+        return textEdge(node, end ? node.length - 1 : 0, end);
+    }
+    if (node.nodeType !== Node.ELEMENT_NODE) return null;
+    const child = node.childNodes[end ? node.childNodes.length - 1 : 0];
+    const nested = child && nodeEdge(child, end);
+    if (nested) return nested;
+    const rect = node.getBoundingClientRect();
+    return located(rect) ? edge(rect, end) : null;
+}
+
+function textEdge(node, offset, end) {
+    const range = node.ownerDocument.createRange();
+    range.setStart(node, offset);
+    range.setEnd(node, offset + 1);
+    const rect = range.getBoundingClientRect();
+    return located(rect) ? edge(rect, end) : null;
+}
+
+function ancestor(node, root) {
+    let element = node.nodeType === Node.ELEMENT_NODE ? node : node.parentElement;
+    while (element) {
+        const rect = element.getBoundingClientRect();
+        if (located(rect)) return edge(rect, false);
+        if (element === root) break;
+        element = element.parentElement;
+    }
+    return null;
+}
+
+function edge(rect, end) {
+    const left = end ? rect.right : rect.left;
+    const DOMRect = rect.constructor;
+    if (typeof DOMRect?.fromRect === 'function') {
+        return DOMRect.fromRect({x: left, y: rect.top, width: 0, height: rect.height});
+    }
+    return Object.freeze({x: left, y: rect.top, top: rect.top, right: left,
+        bottom: rect.bottom, left, width: 0, height: rect.height});
+}
+
+function located(rect) {
+    return !!rect && (rect.left !== 0 || rect.top !== 0 || rect.right !== 0 || rect.bottom !== 0
+        || rect.width !== 0 || rect.height !== 0);
+}
+
+function contains(root, node) {
+    return node === root || root.contains(node);
+}

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

@@ -0,0 +1,385 @@
+# Convention editor client
+
+This is the deliberately small batteries-included layer above the RTE engine.
+It proves the desired one-import setup without making its provisional module and
+default-UI decisions part of the core.
+
+The public root `rte.js` creates one `Editor` for the default document core:
+
+```js
+import './rte.js';
+```
+
+```css
+[contenteditable] {
+    --u2-rte: true;
+    --u2-rte-toolbar: bold;
+}
+```
+
+No surface is discovered by observation. The core registers an opted-in host
+when focus reaches it; the client then installs its standard command registry
+and input pipeline. A default roaming toolbar is allocated only when the first
+rich-text surface becomes active. `plaintext-only` hosts stay completely native.
+
+The optional `classes.js` entry adds a content-class control. Its choices come
+from the host's `--u2-rte-classes`, so its toolbar select is filled per surface
+rather than at registration: a module control may declare `options` as a
+function of the surface, and the client refills that select before the toolbar
+is shown. The same declaration is what the sanitizer keeps and what
+presentation cleanup leaves alone.
+
+The optional `images.js` entry frames a selected image, with handles on its
+trailing edges and its alt text in a field below it. Both come and go with the
+selection and neither takes the focus by appearing, so naming an image is one
+click away and nothing has to be opened. The name is written as it is typed, so
+Enter has nothing to confirm: it hands the caret back to the text, after the
+image.
+
+The optional `link.js` entry adds a contextual link editor. Its `link` command
+is an ordinary `valueMark`, so any other UI can drive the same create, change,
+and remove path; the module supplies one form.
+
+That form is where the caret is: it appears on its own when the caret enters a
+link, anchored on the link rather than on the selection, and goes when the caret
+leaves — the same rule the table and image handles follow. Appearing therefore
+never takes the focus, because someone is typing. What is left for the toolbar
+control is the one thing that is a decision: turning a selection into a link, and
+at an existing link handing it the keyboard.
+
+The form has no Apply and no Remove: what its fields say is what the link is, as
+it is typed, and an emptied address says there is no link — the form stays on the
+text, so the same words can be linked again.
+Each edit runs the command marked as ongoing input, so history keeps a whole
+address as one step rather than one per keystroke. Marking the link moves the
+document selection into it and an engine follows that with focus, so the field
+being typed into gets focus back with its caret intact — otherwise the second
+character would land in the editor. What it edits is one link, decided when it
+appeared — not wherever the caret has moved on to, or a pending edit would land
+somewhere else the moment the caret did. Enter and Escape hand the caret back to
+the text — after the link, not inside it, because whoever just made one wants to
+keep writing without it. Neither dismisses the form: it goes because the caret
+has left the link, and with every edit already applied one key has nothing left
+to confirm and the other nothing to undo.
+
+Beside the address sits a way to open it in a new tab, shown only while the
+address is one the browser can follow: an application scheme — a page id, a
+record reference — is a link the editor understands and the browser does not. The address is a plain text field on
+purpose: native url validation rejects relative paths, fragments, and
+application schemes and would silently block the form, while which protocols are
+acceptable is the sanitizer's decision.
+
+What an address means is the application's decision, and `linkEditor()` takes
+two hooks for it. `normalize(value, surface)` receives the finished value
+once, when the form is done, and may complete a bare domain, map an address into
+a scheme of its own, or derive `rel` and `target` from it; what it returns is
+what gets written and shown. Not per keystroke, which would rewrite a half-typed
+address under the caret — and not when the field is left either: marking the link
+takes the focus away and hands it back on every keystroke, so leaving a field is
+not an event this form can wait for. `suggest(text, surface)` is asked, possibly
+asynchronously, what a *new* link should point at, given the text it is being put
+on; its answer is used only while the form is still open on the same link and
+the address is still empty. It is offered rather than applied — it stands in the
+field, selected so one keystroke replaces it, and becomes the link when the form
+is done. Applying it at once would mark the link, and marking moves the selection
+into it and the focus after that, throwing whoever asked for a link back into the
+text before they had seen the answer.
+
+`complete(text, surface)` is asked what addresses go with what is being typed and
+answers with entries `{value, label}` — or `{value, html}` for a row with markup,
+which the form writes through `setHTML()`, so the platform sanitizes it; where an
+engine does not ship that yet, the entry shows its address instead. The form
+renders its own list rather than a native datalist, which cannot show markup: the
+arrow keys move through it, Enter takes the current entry, Escape closes the list
+before it closes the form, and a pointer does the same. One question is in flight
+at a time, and a late answer to a word that has since changed is dropped.
+
+Contextual UI goes with the editing session and comes back with it: a module
+draws on `u2-rte-activate` as well as on selection and content changes, because
+returning to the field a caret was already in is no selection change and would
+otherwise leave its handles or its form behind.
+
+Everything this client draws goes into one `Chrome`: its toolbar, the contextual
+handles, the link form, the source dialog. A module receives it as `chrome` in
+its setup context and puts its UI in `chrome.root`, so no module owns a layer, a
+top-layer element, or a place in the application's DOM. The chrome is made on
+first use, so an editor that never shows anything adds nothing to the document,
+and disposing the client takes all of it away at once.
+When the active surface sits in a modal dialog, open popover, or fullscreen
+element, the same chrome follows it into that native top-layer boundary and
+returns afterward. The client registers the chrome as retained core UI, so its
+controls keep activation and direct top-layer hosts keep it out of Source and
+History content.
+
+The optional `images.js` entry frames a selected image with three handles on its
+trailing edges: the bottom-right corner keeps the proportion, the right edge
+changes only the width and the bottom edge only the height. An image sits in a
+text flow with its top and start edges held in place, so dragging the other side
+is the only direction that grows it where the eye expects — a handle on a
+leading edge would move the picture rather than resize it. A drag moves the
+frame only and the size is written once when it is released, so a resize is one
+undo step rather than a trail of them. Selecting the image that was clicked is
+not its job: the input pipeline selects any atomic element a click lands on.
+What is resizable is a selector, so any atomic element can be made sizeable.
+
+The optional `tables.js` entry puts its actions on the table itself. Row handles
+run down the table's left edge and column handles along its top, each lined up
+with the cell the caret is in: add before, delete, add after. A handle whose
+command cannot run is disabled rather than hidden, so the row of three keeps its
+shape. Only `insertTable` is a toolbar control, because it applies where no
+table is.
+
+The layer is one per editor, lives in the browser top layer, and is repositioned
+from selection, change, input, scroll, and resize — never from a timer.
+
+The optional `source.js` entry adds a modal HTML source view. Its dialog wraps
+its text area in `<u2-code>`: where that element is defined it takes the area
+over and highlights it, and where it is not the area renders on its own.
+Highlighting is therefore an enhancement, never a dependency — `sourceView()`
+alone imports nothing, and the root entry passes a `highlight` loader that pulls
+`u2/el/code` before the first open. Closing without applying restores the caret
+the view was opened on.
+
+## Prototype contract
+
+`new Editor(core)` currently installs these defaults per rich-text surface:
+
+- `enter` and `lineBreak` structural commands;
+- `deleteBackward` and `deleteForward` for content-model-approved block joins
+  while ordinary character deletion stays native;
+- one `PendingMarks` instance;
+- `insertText` routing and post-composition formatting while a pending mark exists;
+- one `History` instance with `undo` and `redo`, including Ctrl/Command+Z,
+  Ctrl/Command+Shift+Z, and Ctrl/Command+Y;
+- the ready-made inline marks `bold`, `italic`, `underline`, `strike`, and
+  `code`, with Ctrl/Command+B, +I, and +U;
+- the block structure commands `bullets`, `numbers`, `indent`, `outdent`, and
+  `rule`;
+- one `InputPipeline` using the normal host configuration.
+
+`commands(surface)` and `history(surface)` expose the per-surface registry and
+history to an application; `controls` lists what the registered modules offer by
+name, so a host can build its own list of what `--u2-rte-toolbar` may choose
+from without guessing.
+
+Those defaults arrive as three ordinary modules — `history`, `marks`, and
+`structure`, one file each — registered before any surface exists. They use exactly the module
+contract below and can be removed with `editor.delete('structure')`, so nothing
+about them is privileged. Every control they contribute is gated by
+`--u2-rte-toolbar`, so a host that lists only `bold` shows only Bold while the
+commands and their keyboard shortcuts stay available.
+
+`add(module)` installs an optional extension into already registered and future
+rich-text surfaces. A module has one client-wide name and may provide a command
+factory, lifecycle hooks, and declarative toolbar controls:
+
+```js
+const highlight = {
+    name: 'highlight',
+    commands({pending}) {
+        return {highlight: pending.toggle(highlightHtml)};
+    },
+    toolbar: [{
+        command: 'highlight',
+        label: 'Highlight',
+        text: 'H',
+        state: true,
+    }],
+};
+
+editor.add(highlight);
+```
+
+The factory returns a plain object whose keys are command names and whose values
+follow the normal `Commands` contract. `surface` is the target surface,
+`pending` is its shared `PendingMarks` instance, so formatting modules compose
+with the one `insertText` route rather than installing competing pipelines, and
+`history` is its `History`.
+`toolbar` is optional; its controls require non-empty `command`, `label`, and
+`text`, with optional `state` and `shortcut`.
+
+A module may instead contribute a value-bound select. Its `name` is the CSS
+toolbar token, `command` is one normal command, and every option maps a label to
+an `edit.value`:
+
+```js
+toolbar: [{
+    type: 'select',
+    name: 'block',
+    command: 'blockStyle',
+    label: 'Block style',
+    options: [
+        {value: 'paragraph', label: 'Paragraph'},
+        {value: 'h1', label: 'Heading 1'},
+    ],
+}]
+```
+
+The optional root `blocks.js` entry uses this contract for Paragraph, H1, H2,
+and H3. `blockStyles(styles, options)` creates a replacement module from custom
+definitions, including class-based styles such as `p.lead`. Importing
+`blocks.js` also imports the convention editor and registers the default module.
+
+Module names, command names, and routed `inputType` ownership are exclusive.
+Adding the same module object twice is idempotent; a different module with the
+same name or a command/input route already owned by the client throws. The
+declaration and controls are snapshotted at registration, so later caller
+mutation cannot change future surfaces. Installation into existing surfaces is
+atomic. `delete()` accepts the registered module object or its name, removes its
+commands and controls everywhere, and returns whether it existed. Changing
+module topology clears transient pending caret marks so a removed formatter
+cannot affect later input. A disposed client rejects new modules.
+
+`setup({editor, core, root})` runs once when an extension is added.
+`attach({editor, surface, pending, commands})` runs once for every current and
+future rich-text surface, after that extension's commands are registered. Each
+hook may return nothing or one object with `dispose()`. Surface disposal,
+`delete()`, failed atomic installation, and editor disposal release those
+objects in the reverse scope. There is deliberately no second `destroy()` or
+cleanup-function convention.
+
+This remains a narrow extension contract rather than a general plugin
+framework: setup and attachment are synchronous, command/input ownership stays
+exclusive, and an extension cannot reach private client state.
+`commands(surface)` exposes that surface's registry or `null` for direct
+inspection. `refresh()` re-reads the active surface's CSS and toolbar state.
+
+The first active roaming surface creates one application-owned default toolbar
+element and one small style element in the core root. `--u2-rte-toolbar` filters
+its available controls through the normal `Toolbar` contract. Only `bold` is
+shipped here yet; an unknown name such as `code` remains invisible rather than
+pretending that its command exists. `--u2-rte-ui: none` prevents allocation
+until another roaming surface becomes active. Leaving both the active surface
+and toolbar hides it. Default placement uses the isolated `rangeRect()` browser
+policy, so an empty native caret rectangle is derived from adjacent rendered
+content without inserting a marker into the editor.
+`--u2-rte-toolbar-when: selection` additionally keeps the toolbar hidden at a
+caret and opens it only for a non-collapsed saved selection.
+When Popover is available, the convention toolbar is a manual popover in the
+browser top layer; its fixed range placement and focus-preserving behavior stay
+the same inside a Document or ShadowRoot.
+
+### Visible line breaks
+
+The optional root `breaks.js` entry is the first lifecycle extension:
+
+```js
+import './breaks.js';
+```
+
+```css
+[contenteditable] {
+    --u2-rte-show-breaks: true;
+    --u2-rte-toolbar: bold breaks;
+}
+```
+
+The CSS property chooses the initial view state when a surface connects.
+Leaving `breaks` out of the toolbar list gives an always-on display with no
+toggle. The `showBreaks` command runs outside an editing transaction, so it
+emits a command event but no content-change event and never enters history.
+
+The extension does not insert markers beside `<br>` nodes. One extension-owned
+top-layer overlay contains presentation-only marks and is allocated only while
+at least one surface shows them. A single root scroll listener, resize listener,
+and `ResizeObserver` schedule all visible surfaces together; input and editor
+changes schedule their own surface. Removing the extension restores its host
+attributes, overlay, styles, observers, and listeners. Document and ShadowRoot
+cores keep all of those resources in their own root. Nested editable surfaces
+own their own `<br>` markers, so an outer surface never duplicates them.
+
+### Optional Unstyle
+
+The optional root `unstyle.js` entry adds a selection-only `unstyle` action:
+
+```js
+import './unstyle.js';
+```
+
+```css
+[contenteditable] { --u2-rte-toolbar: bold unstyle; }
+```
+
+Each click applies the first remaining presentation level. The button disables
+when the selection has nothing covered by the policy. `unstyles(levels,
+options)` creates a replacement module with application levels, command/control
+names, label, and text. The underlying policy also cleans safely parsed
+external fragments; the toolbar contains no paste-specific logic.
+
+### Optional rich external input
+
+`externalInputs(options)` adapts the low-level `ExternalInput` boundary to the
+convention client's normal extension lifecycle. It is needed only when an
+application chooses to read and replace rich HTML before native insertion. A
+sanitizer is mandatory and is never selected implicitly:
+
+```js
+import {editor, externalInputs, NativeSanitizer} from '../../rte.js';
+
+editor.add(externalInputs({sanitizer: new NativeSanitizer()}));
+```
+
+The module registers mapped `insertFragment` and attaches one input boundary to
+every current and future rich surface. Removing it disposes the listeners and
+command everywhere. It contributes no toolbar control.
+
+With the default Unstyle policy, an inherited CSS property chooses cumulative
+presentation cleanup for each import:
+
+```css
+[contenteditable] { --u2-rte-import-unstyle: styles; }
+```
+
+The value may be `none`, `classes`, `styles`, `attributes`, or `formatting`.
+Custom `Unstyle` policies may use their own level names. Pass `unstyle: null`
+to disable this stage, or pass `through` as a fixed name or resolver function
+to replace CSS resolution. The security sanitizer still always runs.
+
+`rte.js` exports the factory but does not install it by default. Its ordinary
+input pipeline leaves paste/drop insertion to the browser, removes classes and
+inline styles from only the added elements, and then normalizes their structure.
+That path needs no HTML parser. Applications importing arbitrary HTML strings
+may still provide any safe adapter through the same `sanitize()` contract.
+
+`dispose()` removes every installed input pipeline, listener, toolbar node, and
+style node without disposing the supplied core. It is idempotent and is also
+available through `[Symbol.dispose]()`; core disposal disposes the client. One
+core accepts only one convention client at a time, preventing duplicate input
+pipelines. Disposal releases that ownership so a new client can take over.
+
+## Invariants
+
+- Importing the convention client adds only core listeners. It scans no DOM,
+  installs no observer, and creates no UI before a qualifying surface is active.
+- Every mutable registry and pipeline belongs to one `Editor` instance and one
+  surface; different cores cannot share state.
+- A module is installed once per rich surface, owns all command names and
+  controls it contributes, and is removed from all of them as one operation.
+- Module installation either succeeds for every existing surface or leaves
+  every registry and input route unchanged.
+- All editing still runs through public commands, transactions, point mapping,
+  normalization, and `Toolbar`. The client contains no second editor algorithm.
+- The engine entry `rte.js` remains usable without importing this layer.
+
+## Browser considerations
+
+Lazy registration uses the core's existing capture-phase focus route. The UI
+uses a manual top-layer popover with fixed positioning around the saved range,
+with non-mutating
+collapsed-range geometry fallback, and intentionally does not claim final
+viewport, zoom, touch, writing-mode, or virtual-keyboard policy.
+The real-browser suite covers lazy focus setup, Enter routing, toolbar commands,
+late module installation, future surfaces, rollback, removal, plain-text
+exclusion, rich external-input composition, and complete teardown.
+
+## TODO exposed by the prototype
+
+- Exercise lifecycle failure and coexistence further before adding dependency,
+  ordering, or asynchronous setup concepts.
+- Decide whether the default UI becomes application DOM, a custom element, or
+  an optional UI module before stabilizing its styling hooks.
+- Generalize placement for viewport edges, writing modes, zoom, touch handles,
+  and virtual keyboards.
+- Decide separately whether `code` means inline `<code>` formatting or the old
+  editor's HTML-source UI; block styles now provide the first substantial
+  optional capability.

package/js/rte/src/client/blocks.js

@@ -0,0 +1,38 @@
+import {BlockStyles} from '../command/block-style.js';
+
+export const defaultBlockStyles = Object.freeze([
+    Object.freeze({name: 'paragraph', label: 'Paragraph', selector: 'p', tag: 'p'}),
+    Object.freeze({name: 'h1', label: 'Heading 1', selector: 'h1', tag: 'h1'}),
+    Object.freeze({name: 'h2', label: 'Heading 2', selector: 'h2', tag: 'h2'}),
+    Object.freeze({name: 'h3', label: 'Heading 3', selector: 'h3', tag: 'h3'}),
+]);
+
+export function blockStyles(styles = defaultBlockStyles, {
+    name = 'blocks',
+    control = 'block',
+    command = 'blockStyle',
+    label = 'Block style',
+} = {}) {
+    for (const [property, value] of Object.entries({name, control, command, label})) {
+        if (typeof value !== 'string' || !value.trim()) throw new TypeError(`Block module ${property} must be a non-empty string`);
+    }
+    const policy = new BlockStyles(styles);
+    const commands = Object.freeze({[command]: policy.command()});
+    const options = Object.freeze(policy.styles.map(style => Object.freeze({
+        value: style.name,
+        label: style.label,
+    })));
+    return Object.freeze({
+        name: name.trim(),
+        commands: () => commands,
+        toolbar: Object.freeze([Object.freeze({
+            type: 'select',
+            name: control.trim(),
+            command: command.trim(),
+            label,
+            options,
+        })]),
+    });
+}
+
+export const blocks = blockStyles();