@olddevs/ui 4.4.0 → 4.5.1

package/docs/glossary.en.md

@@ -1,5 +1,5 @@
 ---
-sourceHash: 88701a1373b4
+sourceHash: 5cc549fe1c76
 ---
 
 # Glossary of `@olddevs/ui`
@@ -136,50 +136,54 @@ Terms of `RichTextEditor` and `RichTextView` (the `@olddevs/ui/editor` entry poi
 especially easy to borrow a word from a neighboring editor (plugin, service, node) — and that
 introduces a second meaning.
 
-| Term                     | Meaning                                                                                                                                                                                                                                                                                                                                                        | Not to be confused with                                                                                                                                                       |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Editor**               | `RichTextEditor` — a rich text input field                                                                                                                                                                                                                                                                                                                     | A code editor: the kit has none, code is displayed with `CodeView`                                                                                                            |
-| **View**                 | `RichTextView` — read-only display of a saved Document                                                                                                                                                                                                                                                                                                         | The Editor's `readOnly` mode: that one carries the engine, the View does not                                                                                                  |
-| **Table of contents**    | `RichTextToc`: the list of a Document's headings next to the View or the Editor. Collapsed, it is a strip of strokes; expanded, a list; a click on an item goes to the heading                                                                                                                                                                                 | The kit's `Heading` and the navigation of the documentation site                                                                                                              |
-| **Document**             | The Editor's value: an HTML string constrained by the Schema                                                                                                                                                                                                                                                                                                   | The ProseMirror JSON tree in the engine — it is internal; it comes out only as a JSON envelope                                                                                |
-| **JSON envelope**        | A Document as JSON for a file and a template: `{ format: "olddevs-rich-text", version, doc }` (`getJSON()`, `setJSON()`, `defaultValue`), lossless and through the Schema                                                                                                                                                                                      | The Editor's value — the value stays HTML; the bare tree `editor.getJSON()` without an envelope                                                                               |
-| **Schema**               | An allowlist of Blocks, Marks and attributes that the Editor accepts and returns                                                                                                                                                                                                                                                                               | Server-side sanitization — the consumer does it (`sanitizeRichText`)                                                                                                          |
-| **Block**                | A structural element of a Document: paragraph, heading, list, table, image…                                                                                                                                                                                                                                                                                    | A Mark                                                                                                                                                                        |
-| **Mark**                 | Inline formatting inside a Block: bold, link, color…                                                                                                                                                                                                                                                                                                           | A Block                                                                                                                                                                       |
-| **Atom**                 | A Block or inline element that is selected, moved and deleted as a whole: an image (the caption inside it is editable), a divider, a soft break, a mention. Always makes the field non-empty                                                                                                                                                                   | An empty Block: a paragraph without text is not an Atom and does not count as content                                                                                         |
-| **Atom text**            | The string that represents an Atom in the Document's text: `getText` and `getSelectedText` return it, its length is the Atom's weight in `maxLength`, and it is how the Atom is exported to Markdown without rules of its own. For an image it is the caption text, for a divider an empty string                                                              | A Block attribute                                                                                                                                                             |
-| **Layout**               | A Block of columns (the `layout` Tool): six variants — from one to four equal columns, 60/40 and 40/60. Top level only, does not nest into itself; a column for its Blocks is the same as a Document                                                                                                                                                           | A table: it has data rows and cells, while the columns of a Layout are the Document's page structure. The kit's `Grid`: a screen grid, not a Block                            |
-| **Wrapper**              | A Block that gathers a group of Blocks (the `wrapper` Tool, a `div` with `data-block="wrapper"`): they are moved, duplicated and deleted as one Block. Without a Wrapper tone it has no look of its own — the dashed outline exists only in the Editor. Neither a Wrapper nor a Layout nests into a Wrapper                                                    | A quote: it has its own look and meaning in the Document, while a Wrapper without a tone is only grouping                                                                     |
-| **Wrapper tone**         | The styling of a Wrapper as a note (`data-tone`): a background and a stripe on the left in one of five tones of the `Tone` vocabulary — "Note", "Tip", "Important", "Warning", "Caution". Chosen in the "Tone ›" item of the Block handle, the same in the Editor and the View, exported to Markdown as a GitHub alert (what GitHub and Notion call a callout) | The tone of a Field notice (`status` or `error`). Meaning: the tone carries no roles or `aria-*`; the meaning of a note is written as a word in the text                      |
-| **Toolbar**              | A set of formatting buttons; its look is set by `toolbar`. **Fixed** (`fixed`, the default) — above the field, sticks on scroll; **floating** (`floating`) — the same buttons above a non-empty selection. With `bubble` there is no Toolbar — the Selection menu takes its place, with `none` there is neither. On a touch screen the Toolbar is always fixed | The kit's `Toolbar` — the primitive that the Toolbar is built from                                                                                                            |
-| **Insert menu**          | The "Insert" and "Turn into" list: opens on `/` in the text and on the "+" button                                                                                                                                                                                                                                                                              | The browser context menu                                                                                                                                                      |
-| **Selection menu**       | A compact pill on an inverse surface above a non-empty selection: "¶", lists, bold, italic, underline, color, "…", link, emoji; its contents are fixed by the kit. Appears in place of the Toolbar with `toolbar="bubble"` and on top of the fixed Toolbar — there `selectionMenu={false}` turns it off. Absent on a touch screen                              | The floating Toolbar: it has the full set of buttons                                                                                                                          |
-| **Block handle**         | The "⋮" on the Block that holds the caret, and its menu of actions on the whole Block: "Add ›", "Format ›", "Move up", "Move down", "Duplicate", "Delete"                                                                                                                                                                                                      | The Toolbar: it works with the selection, not with a Block                                                                                                                    |
-| **Insert item**          | A row of the Insert menu: inserts a Block or turns the current one into another. One item is visible on `/`, on "+" and in the Block handle                                                                                                                                                                                                                    | A Toolbar button                                                                                                                                                              |
-| **Block action**         | An item of the Block handle menu that works with the whole Block, for example "Duplicate"                                                                                                                                                                                                                                                                      | A button: it works with the selection                                                                                                                                         |
-| **Shortcuts reference**  | A read-only "command — shortcut" popover behind the last button of the fixed Toolbar. The rows are the commands of the enabled Tools, including custom ones; on a phone there is no button                                                                                                                                                                     | The kit's `CommandPalette`: the rows of the Shortcuts reference are not clickable. The kit's `ShortcutsHelp`: it lists screen shortcuts, not Editor ones                      |
-| **HTML mode**            | The mode of the `source` Tool: the "HTML" button on the fixed Toolbar replaces the Document with a field holding its HTML. The field text passes through the Schema and becomes the Document in a single edit — on leaving the mode, on `blur`, on form submit and on reading through the Handle                                                               | The HTML convention: that is the form of custom content in a Document, not a mode. `CodeView`: it displays code, while the HTML field is editable                             |
-| **Glass**                | A semi-transparent background that blurs what is behind it on everything the Editor shows above the Document: the floating Toolbar, the Selection menu, menus, popovers, the Text card. The color is the token of its own surface; with `prefers-reduced-transparency`, `prefers-contrast: more` and on iOS the background is solid                            | The kit's `Menu` and `Popover` outside the Editor: they stay solid                                                                                                            |
-| **UI contribution**      | A UI element of a custom Tool, described as data: a button, an Insert item, a Block action or a Text card. The kit renders it in a Slot; a disabled Tool removes its UI contributions as well                                                                                                                                                                  | A React node in the interface: arbitrary React is allowed only inside the content of a button popover and a Text card                                                         |
-| **Slot**                 | One place on a surface where the UI contributions of custom Tools appear, in `tools` order: the Toolbar group before "Undo", the end of an Insert menu section, the Block handle section before "Delete"                                                                                                                                                       | A position relative to a built-in button: the ids of built-ins are not public API                                                                                             |
-| **Preset**               | A ready-made set of built-in Tools: `full` or `basic` (`RICH_TEXT_PRESETS`). Not a frozen list: a new built-in arrives in it in a minor version                                                                                                                                                                                                                | An exact `tools` list: only the screen changes its composition                                                                                                                |
-| **Tool**                 | One capability of the Editor: its Blocks and Marks, their rules in the Schema and their place in the UI, for example `table`. A built-in one is set by name, a custom one by a description                                                                                                                                                                     | A button: disabling a Tool also removes its Block from the Schema. A Redactor plugin: that is a class of behavior over the DOM without a Schema                               |
-| **custom Tool**          | A Tool that the consumer describes (`CustomTool`): Schema rules as data, an Engine part and UI contributions. Passed in `tools` mixed in with the kit's names                                                                                                                                                                                                  | The kit's internal description: that is a superset of the public shape for built-ins and is not exported                                                                      |
-| **Consumer prefix**      | The start of the name of everything custom — a Tool, its Blocks, Marks and attributes — up to the underscore: `acme_mergeTag`, `data-acme_size`. Kit names have no underscore, so custom names and built-in ones never collide, either in a set or in a Document                                                                                               | A Preset: that is a set of built-in Tools, not a namespace                                                                                                                    |
-| **HTML convention**      | The form of custom content in a Document: a Block is a `div` or `span` with `data-block`, a Mark is a `span` with `data-mark`, attributes are `data-<prefix>_<name>`. Frozen: extended only by adding                                                                                                                                                          | The kit's Schema tags (`p`, `table`, `img`): a custom Block cannot take them                                                                                                  |
-| **Block trait**          | A Block property that only the kit understands, not the engine: "container" (children get their own handle), "can be turned into", "Atom without a formatting menu"                                                                                                                                                                                            | A Block attribute: that one is stored in the Document                                                                                                                         |
-| **Engine part**          | The part of a Tool description needed only by the live Editor: Tiptap extensions and the node view. Supplied immediately or through a Loader                                                                                                                                                                                                                   | Schema rules: those are data, read by the server and the View without an engine                                                                                               |
-| **Loader**               | A function with a dynamic import in place of the Engine part: `engine: () => import(…)`. The heavy built-ins outside `basic` load the same way — the code Block and the table                                                                                                                                                                                  | Preloading (`modulepreload`): the kit does not publish it, the consumer sets it up                                                                                            |
-| **Handle**               | Imperative access from screen code to the Editor through `ref`: insert at the caret, read, focus, history                                                                                                                                                                                                                                                      | Redactor services: those are engine internals, not screen API                                                                                                                 |
-| **Readiness**            | The moment when the engine is created and the Loaders of all enabled Tools, custom and built-in, have finished: from then on Handle methods take effect instead of doing nothing. Happens once per mount; `onReady` reports it                                                                                                                                 | Hydration: after it the engine may still be waiting for Loaders                                                                                                               |
-| **Field focus**          | Focus inside the Editor as a whole: the Document, the Toolbar, the kit's popovers, the HTML field. Moving between them does not lose Field focus; `onFocus` and `onBlur` are about it                                                                                                                                                                          | Document focus (the engine's `focus` and `blur`): a click in the Toolbar removes it                                                                                           |
-| **Author edit**          | A change to the Document equal to typing on a keyboard: a history step, `onChange` after a delay, the character limit applies. This also covers insert, undo and redo from the Handle                                                                                                                                                                          | An External replacement                                                                                                                                                       |
-| **External replacement** | Replacing the whole Document (`value`, `clear()`, `setMarkdown()`, `setJSON()`): the character limit does not truncate it; `onChange` fires immediately for `clear()`, `setMarkdown()` and `setJSON()`, but not for a new `value`                                                                                                                              | An Author edit                                                                                                                                                                |
-| **Skeleton**             | The Editor's look before Readiness: the field frame, a placeholder for the Toolbar and a Document: sanitized by the Schema, it is rendered as static HTML with the same class and rhythm as the engine's Document, without input. On the server — the frame without a Document. A Loader failure turns the Skeleton into a field error with "Retry"            | The View: that is a separate read-only component, while the Skeleton is a state of the Editor that the engine replaces. The kit's `Skeleton` component: a loading placeholder |
-| **Status line**          | A line inside the field frame under the Document: on the left the screen's content (`status`: word count, "Saved", co-author), on the right the kit's character counter                                                                                                                                                                                        | A Field notice: the line shows a lasting state of the screen, not an event                                                                                                    |
-| **Field notice**         | One event tied to the field (`showNotice`): tone `status` (only announced) or `error` (a visible line under the field until the next Author edit). A new one replaces the previous one                                                                                                                                                                         | The kit's toast: that one is global and not tied to a field                                                                                                                   |
-| **Text card**            | A non-modal card under a range of the Document, declared by a custom Tool (`textCards`): a comment, a hint from checking the text. Opens when the caret enters it or on click, focus stays in the text                                                                                                                                                         | A button popover: a button opens that one, while a Text card is opened by a place in the Document                                                                             |
-| **Trigger character**    | A character of a custom Tool (`trigger`) that opens a list of items at the caret when typed at the start of a Block or after a space, like `/`: `@` for mentions, `#` for tags. Picking an item replaces the typed `@query` with a custom node                                                                                                                 | The Insert menu on `/`: that one is built in, while a custom character is set by a Tool                                                                                       |
-| **Paper**                | A light area of the Document in any app theme (`surface="paper"`) — for text that leaves the app on a light background: an email, print, PDF. The Toolbar, menus and field frame stay in the app theme; the View with the same `surface` shows the same Paper                                                                                                  | The `light` theme: it changes the whole app, the Paper only the Document                                                                                                      |
-| **Island**               | A client-side piece of the View that, after mounting, brings a Block in already rendered HTML to life: the "Copy" button on a code Block, the `island` of a custom Block                                                                                                                                                                                       | A node view: it lives only in the Editor engine                                                                                                                               |
-| **Mount point**          | A place in already rendered HTML where an Island mounts a live element: the code Block header that receives the "Copy" button                                                                                                                                                                                                                                  | A Slot: that is a place in the Editor UI for the UI contributions of Tools                                                                                                    |
+| Term                     | Meaning                                                                                                                                                                                                                                                                                                                                                        | Not to be confused with                                                                                                                                                                                                                            |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Editor**               | `RichTextEditor` — a rich text input field                                                                                                                                                                                                                                                                                                                     | A code editor: the kit has none, code is displayed with `CodeView`                                                                                                                                                                                 |
+| **View**                 | `RichTextView` — read-only display of a saved Document                                                                                                                                                                                                                                                                                                         | The Editor's `readOnly` mode: that one carries the engine, the View does not                                                                                                                                                                       |
+| **Table of contents**    | `RichTextToc`: the list of a Document's headings next to the View or the Editor. Collapsed, it is a strip of strokes; expanded, a list; a click on an item goes to the heading                                                                                                                                                                                 | The kit's `Heading` and the navigation of the documentation site                                                                                                                                                                                   |
+| **Document**             | The Editor's value: an HTML string constrained by the Schema                                                                                                                                                                                                                                                                                                   | The ProseMirror JSON tree in the engine — it is internal; it comes out only as a JSON envelope                                                                                                                                                     |
+| **JSON envelope**        | A Document as JSON for a file and a template: `{ format: "olddevs-rich-text", version, doc }` (`getJSON()`, `setJSON()`, `defaultValue`), lossless and through the Schema                                                                                                                                                                                      | The Editor's value — the value stays HTML; the bare tree `editor.getJSON()` without an envelope                                                                                                                                                    |
+| **Schema**               | An allowlist of Blocks, Marks and attributes that the Editor accepts and returns                                                                                                                                                                                                                                                                               | Server-side sanitization — the consumer does it (`sanitizeRichText`)                                                                                                                                                                               |
+| **Block**                | A structural element of a Document: paragraph, heading, list, table, image…                                                                                                                                                                                                                                                                                    | A Mark                                                                                                                                                                                                                                             |
+| **Mark**                 | Inline formatting inside a Block: bold, link, color…                                                                                                                                                                                                                                                                                                           | A Block                                                                                                                                                                                                                                            |
+| **Atom**                 | A Block or inline element that is selected, moved and deleted as a whole: an image (the caption inside it is editable), a divider, a soft break, a mention. Always makes the field non-empty                                                                                                                                                                   | An empty Block: a paragraph without text is not an Atom and does not count as content                                                                                                                                                              |
+| **Atom text**            | The string that represents an Atom in the Document's text: `getText` and `getSelectedText` return it, its length is the Atom's weight in `maxLength`, and it is how the Atom is exported to Markdown without rules of its own. For an image it is the caption text, for a divider an empty string                                                              | A Block attribute                                                                                                                                                                                                                                  |
+| **Layout**               | A Block of columns (the `layout` Tool): six variants — from one to four equal columns, 60/40 and 40/60. Top level only, does not nest into itself; a column for its Blocks is the same as a Document                                                                                                                                                           | A table: it has data rows and cells, while the columns of a Layout are the Document's page structure. The kit's `Grid`: a screen grid, not a Block                                                                                                 |
+| **Wrapper**              | A Block that gathers a group of Blocks (the `wrapper` Tool, a `div` with `data-block="wrapper"`): they are moved, duplicated and deleted as one Block. Without a Wrapper tone it has no look of its own — the dashed outline exists only in the Editor. Neither a Wrapper nor a Layout nests into a Wrapper                                                    | A quote: it has its own look and meaning in the Document, while a Wrapper without a tone is only grouping                                                                                                                                          |
+| **Wrapper tone**         | The styling of a Wrapper as a note (`data-tone`): a background and a stripe on the left in one of five tones of the `Tone` vocabulary — "Note", "Tip", "Important", "Warning", "Caution". Chosen in the "Tone ›" item of the Block handle, the same in the Editor and the View, exported to Markdown as a GitHub alert (what GitHub and Notion call a callout) | The tone of a Field notice (`status` or `error`). Meaning: the tone carries no roles or `aria-*`; the meaning of a note is written as a word in the text                                                                                           |
+| **Toolbar**              | A set of formatting buttons; its look is set by `toolbar`. **Fixed** (`fixed`, the default) — above the field, sticks on scroll; **floating** (`floating`) — the same buttons above a non-empty selection. With `bubble` there is no Toolbar — the Selection menu takes its place, with `none` there is neither. On a touch screen the Toolbar is always fixed | The kit's `Toolbar` — the primitive that the Toolbar is built from                                                                                                                                                                                 |
+| **Insert menu**          | The "Insert" and "Turn into" list: opens on `/` in the text and on the "+" button                                                                                                                                                                                                                                                                              | The browser context menu                                                                                                                                                                                                                           |
+| **Selection menu**       | A compact pill on an inverse surface above a non-empty selection: "¶", lists, bold, italic, underline, color, "…", link, emoji; its contents are fixed by the kit. Appears in place of the Toolbar with `toolbar="bubble"` and on top of the fixed Toolbar — there `selectionMenu={false}` turns it off. Absent on a touch screen                              | The floating Toolbar: it has the full set of buttons                                                                                                                                                                                               |
+| **Block handle**         | The "⋮" on the Block that holds the caret, and its menu of actions on the whole Block: "Add ›", "Format ›", "Move up", "Move down", "Duplicate", "Delete"                                                                                                                                                                                                      | The Toolbar: it works with the selection, not with a Block                                                                                                                                                                                         |
+| **Insert item**          | A row of the Insert menu: inserts a Block or turns the current one into another. One item is visible on `/`, on "+" and in the Block handle                                                                                                                                                                                                                    | A Toolbar button                                                                                                                                                                                                                                   |
+| **Block action**         | An item of the Block handle menu that works with the whole Block, for example "Duplicate"                                                                                                                                                                                                                                                                      | A button: it works with the selection                                                                                                                                                                                                              |
+| **Shortcuts reference**  | A read-only "command — shortcut" popover behind the last button of the fixed Toolbar. The rows are the commands of the enabled Tools, including custom ones; on a phone there is no button                                                                                                                                                                     | The kit's `CommandPalette`: the rows of the Shortcuts reference are not clickable. The kit's `ShortcutsHelp`: it lists screen shortcuts, not Editor ones                                                                                           |
+| **HTML mode**            | The mode of the `source` Tool: the "HTML" button on the fixed Toolbar replaces the Document with a field holding its HTML. The field text passes through the Schema and becomes the Document in a single edit — on leaving the mode, on `blur`, on form submit and on reading through the Handle                                                               | The HTML convention: that is the form of custom content in a Document, not a mode. `CodeView`: it displays code, while the HTML field is editable                                                                                                  |
+| **Glass**                | A semi-transparent background that blurs what is behind it on everything the Editor shows above the Document: the floating Toolbar, the Selection menu, menus, popovers, the Text card. The color is the token of its own surface; with `prefers-reduced-transparency`, `prefers-contrast: more` and on iOS the background is solid                            | The kit's `Menu` and `Popover` outside the Editor: they stay solid                                                                                                                                                                                 |
+| **UI contribution**      | A UI element of a custom Tool, described as data: a button, an Insert item, a Block action or a Text card. The kit renders it in a Slot; a disabled Tool removes its UI contributions as well                                                                                                                                                                  | A React node in the interface: arbitrary React is allowed only inside the content of a button popover and a Text card                                                                                                                              |
+| **Slot**                 | One place on a surface where the UI contributions of custom Tools appear, in `tools` order: the Toolbar group before "Undo", the end of an Insert menu section, the Block handle section before "Delete"                                                                                                                                                       | A position relative to a built-in button: the ids of built-ins are not public API                                                                                                                                                                  |
+| **Preset**               | A ready-made set of built-in Tools: `full` or `basic` (`RICH_TEXT_PRESETS`). Not a frozen list: a new built-in arrives in it in a minor version                                                                                                                                                                                                                | An exact `tools` list: only the screen changes its composition                                                                                                                                                                                     |
+| **Tool**                 | One capability of the Editor: its Blocks and Marks, their rules in the Schema and their place in the UI, for example `table`. A built-in one is set by name, a custom one by a description                                                                                                                                                                     | A button: disabling a Tool also removes its Block from the Schema. A Redactor plugin: that is a class of behavior over the DOM without a Schema                                                                                                    |
+| **custom Tool**          | A Tool that the consumer describes (`CustomTool`): Schema rules as data, an Engine part and UI contributions. Passed in `tools` mixed in with the kit's names                                                                                                                                                                                                  | The kit's internal description: that is a superset of the public shape for built-ins and is not exported                                                                                                                                           |
+| **Tool options**         | What the screen sets on a Tool before the engine is created: the starting flags of Find, `offsetVar`, `levels` and `listWidth` of the Table of contents, the `defaults` of a custom Tool (`defineTool`). The screen sets them with a `tool(…)` entry and the kit reads them once, when the engine is created                                                   | `options` of a Tiptap extension: the extension's author sets those and the Engine part reads them, while Tool options are set by the screen and read by the kit. The Editor's props (`preset`, `maxHeight`): those configure the field, not a Tool |
+| **Configured Tool**      | An entry of `tools` returned by `tool(name, options)` or `tool(definition, options)`: a Tool together with its options. It switches a Tool on without the name in `tools` and wins over a bare name from a Preset                                                                                                                                              | A `defineTool` definition: that describes a Tool, while a Configured Tool is its activation with options. The description of a built-in Tool: it is not exported, and the entry only names the Tool and carries the options                        |
+| **Tool state**           | A data snapshot the screen reads with the `useRichTextToolState(ref, name)` hook: for Find, whether the panel is open, the query, the number of matches and the current one; for the Table of contents, the headings and the current section. The screen re-renders only when the snapshot changes                                                             | `storage` of a Tiptap extension: that is a mutable store inside the engine, while Tool state is read-only. `useRichTextEditorState`: that takes a slice of the live Tiptap `editor`, not a Tool's contract                                         |
+| **Tool commands**        | What the screen calls on a Tool through `handle.tool(name)`: `tool("search")?.open()`, `tool("toc")?.jumpTo(2)`. Each returns a `boolean`; `null` instead of the commands object means the Tool is not in the set, has no commands, or the engine has not been created yet                                                                                     | Handle methods (`insertHTML`, `focus`): those are common to any `tools`, while Tool commands exist only while the Tool is enabled. `editor.commands` and `commands` in Tiptap: those are engine commands and follow its major                      |
+| **Consumer prefix**      | The start of the name of everything custom — a Tool, its Blocks, Marks and attributes — up to the underscore: `acme_mergeTag`, `data-acme_size`. Kit names have no underscore, so custom names and built-in ones never collide, either in a set or in a Document                                                                                               | A Preset: that is a set of built-in Tools, not a namespace                                                                                                                                                                                         |
+| **HTML convention**      | The form of custom content in a Document: a Block is a `div` or `span` with `data-block`, a Mark is a `span` with `data-mark`, attributes are `data-<prefix>_<name>`. Frozen: extended only by adding                                                                                                                                                          | The kit's Schema tags (`p`, `table`, `img`): a custom Block cannot take them                                                                                                                                                                       |
+| **Block trait**          | A Block property that only the kit understands, not the engine: "container" (children get their own handle), "can be turned into", "Atom without a formatting menu"                                                                                                                                                                                            | A Block attribute: that one is stored in the Document                                                                                                                                                                                              |
+| **Engine part**          | The part of a Tool description needed only by the live Editor: Tiptap extensions and the node view. Supplied immediately or through a Loader                                                                                                                                                                                                                   | Schema rules: those are data, read by the server and the View without an engine                                                                                                                                                                    |
+| **Loader**               | A function with a dynamic import in place of the Engine part: `engine: () => import(…)`. The heavy built-ins outside `basic` load the same way — the code Block and the table                                                                                                                                                                                  | Preloading (`modulepreload`): the kit does not publish it, the consumer sets it up                                                                                                                                                                 |
+| **Handle**               | Imperative access from screen code to the Editor through `ref`: insert at the caret, read, focus, history, the commands of Tools (`tool(name)`)                                                                                                                                                                                                                | Redactor services: those are engine internals, not screen API                                                                                                                                                                                      |
+| **Readiness**            | The moment when the engine is created and the Loaders of all enabled Tools, custom and built-in, have finished: from then on Handle methods take effect instead of doing nothing. Happens once per mount; `onReady` reports it                                                                                                                                 | Hydration: after it the engine may still be waiting for Loaders                                                                                                                                                                                    |
+| **Field focus**          | Focus inside the Editor as a whole: the Document, the Toolbar, the kit's popovers, the HTML field. Moving between them does not lose Field focus; `onFocus` and `onBlur` are about it                                                                                                                                                                          | Document focus (the engine's `focus` and `blur`): a click in the Toolbar removes it                                                                                                                                                                |
+| **Author edit**          | A change to the Document equal to typing on a keyboard: a history step, `onChange` after a delay, the character limit applies. This also covers insert, undo and redo from the Handle                                                                                                                                                                          | An External replacement                                                                                                                                                                                                                            |
+| **External replacement** | Replacing the whole Document (`value`, `clear()`, `setMarkdown()`, `setJSON()`): the character limit does not truncate it; `onChange` fires immediately for `clear()`, `setMarkdown()` and `setJSON()`, but not for a new `value`                                                                                                                              | An Author edit                                                                                                                                                                                                                                     |
+| **Skeleton**             | The Editor's look before Readiness: the field frame, a placeholder for the Toolbar and a Document: sanitized by the Schema, it is rendered as static HTML with the same class and rhythm as the engine's Document, without input. On the server — the frame without a Document. A Loader failure turns the Skeleton into a field error with "Retry"            | The View: that is a separate read-only component, while the Skeleton is a state of the Editor that the engine replaces. The kit's `Skeleton` component: a loading placeholder                                                                      |
+| **Status line**          | A line inside the field frame under the Document: on the left the screen's content (`status`: word count, "Saved", co-author), on the right the kit's character counter                                                                                                                                                                                        | A Field notice: the line shows a lasting state of the screen, not an event                                                                                                                                                                         |
+| **Field notice**         | One event tied to the field (`showNotice`): tone `status` (only announced) or `error` (a visible line under the field until the next Author edit). A new one replaces the previous one                                                                                                                                                                         | The kit's toast: that one is global and not tied to a field                                                                                                                                                                                        |
+| **Text card**            | A non-modal card under a range of the Document, declared by a custom Tool (`textCards`): a comment, a hint from checking the text. Opens when the caret enters it or on click, focus stays in the text                                                                                                                                                         | A button popover: a button opens that one, while a Text card is opened by a place in the Document                                                                                                                                                  |
+| **Trigger character**    | A character of a custom Tool (`trigger`) that opens a list of items at the caret when typed at the start of a Block or after a space, like `/`: `@` for mentions, `#` for tags. Picking an item replaces the typed `@query` with a custom node                                                                                                                 | The Insert menu on `/`: that one is built in, while a custom character is set by a Tool                                                                                                                                                            |
+| **Paper**                | A light area of the Document in any app theme (`surface="paper"`) — for text that leaves the app on a light background: an email, print, PDF. The Toolbar, menus and field frame stay in the app theme; the View with the same `surface` shows the same Paper                                                                                                  | The `light` theme: it changes the whole app, the Paper only the Document                                                                                                                                                                           |
+| **Island**               | A client-side piece of the View that, after mounting, brings a Block in already rendered HTML to life: the "Copy" button on a code Block, the `island` of a custom Block                                                                                                                                                                                       | A node view: it lives only in the Editor engine                                                                                                                                                                                                    |
+| **Mount point**          | A place in already rendered HTML where an Island mounts a live element: the code Block header that receives the "Copy" button                                                                                                                                                                                                                                  | A Slot: that is a place in the Editor UI for the UI contributions of Tools                                                                                                                                                                         |

package/docs/glossary.md

@@ -131,50 +131,54 @@
 Термины `RichTextEditor` и `RichTextView` (вход `@olddevs/ui/editor`). Здесь особенно легко
 взять слово из соседнего редактора (плагин, сервис, нода) — оно заводит второй смысл.
 
-| Термин                   | Значение                                                                                                                                                                                                                                                                                                                                           | Не путать с                                                                                                                                                          |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Редактор**             | `RichTextEditor` — поле ввода форматированного текста                                                                                                                                                                                                                                                                                              | Редактором кода: его в ките нет, показ кода — `CodeView`                                                                                                             |
-| **Просмотр**             | `RichTextView` — только чтение сохранённого Документа                                                                                                                                                                                                                                                                                              | `readOnly`-режимом Редактора: тот держит движок, Просмотр — нет                                                                                                      |
-| **Оглавление**           | `RichTextToc`: список заголовков Документа рядом с Просмотром или Редактором. Свёрнуто — полоса штрихов, раскрыто — список, клик по пункту ведёт к заголовку                                                                                                                                                                                       | `Heading` кита и навигацией сайта документации                                                                                                                       |
-| **Документ**             | Значение Редактора: HTML-строка, ограниченная Схемой                                                                                                                                                                                                                                                                                               | JSON-деревом ProseMirror в движке — оно внутреннее; наружу оно выходит только JSON-конвертом                                                                         |
-| **JSON-конверт**         | Документ как JSON для файла и шаблона: `{ format: "olddevs-rich-text", version, doc }` (`getJSON()`, `setJSON()`, `defaultValue`), без потерь и через Схему                                                                                                                                                                                        | Значением Редактора — значение остаётся HTML; голым деревом `editor.getJSON()` без конверта                                                                          |
-| **Схема**                | Белый список Блоков, Меток и атрибутов, которые Редактор принимает и отдаёт                                                                                                                                                                                                                                                                        | Санитизацией на сервере — её делает потребитель (`sanitizeRichText`)                                                                                                 |
-| **Блок**                 | Структурный элемент Документа: абзац, заголовок, список, таблица, картинка…                                                                                                                                                                                                                                                                        | Меткой                                                                                                                                                               |
-| **Метка**                | Строчное форматирование внутри Блока: жирный, ссылка, цвет…                                                                                                                                                                                                                                                                                        | Блоком                                                                                                                                                               |
-| **Атом**                 | Блок или строчный элемент, который выделяется, переносится и удаляется целиком: картинка (подпись внутри неё правится), разделитель, мягкий перенос, упоминание. Всегда делает поле непустым                                                                                                                                                       | Пустым Блоком: абзац без текста — не Атом и содержимым не считается                                                                                                  |
-| **Текст атома**          | Строка, которой Атом представлен в тексте Документа: её отдают `getText` и `getSelectedText`, её длина — вес Атома в `maxLength`, ею Атом выгружается в Markdown без своих правил. У картинки — текст подписи, у разделителя — пустая строка                                                                                                       | Атрибутом Блока                                                                                                                                                      |
-| **Раскладка**            | Блок из колонок (Инструмент `layout`): шесть вариантов — от одной до четырёх равных колонок, 60/40 и 40/60. Только верхнего уровня, в себя не вкладывается; колонка для своих Блоков — то же, что Документ                                                                                                                                         | Таблицей: у той строки и ячейки данных, а колонки Раскладки — вёрстка Документа. `Grid` кита — сеткой экрана, а не Блоком                                            |
-| **Обёртка**              | Блок, который собирает группу Блоков (Инструмент `wrapper`, `div` с `data-block="wrapper"`): их двигают, дублируют и удаляют одним Блоком. Без Тона Обёртки своего вида нет — пунктир только в Редакторе. Обёртка и Раскладка в Обёртку не вкладываются                                                                                            | Цитатой: у той свой вид и смысл в Документе, а Обёртка без тона — только группировка                                                                                 |
-| **Тон Обёртки**          | Оформление Обёртки заметкой (`data-tone`): фон и полоса слева одного из пяти тонов словаря `Tone` — «Заметка», «Совет», «Важно», «Внимание», «Осторожно». Выбирается в «Тон ›» Ручки Блока, одинаков в Редакторе и Просмотре, в Markdown выгружается GitHub alert (то, что GitHub и Notion называют callout)                                       | Тоном Сообщения поля (`status` или `error`). Смыслом: ролей и `aria-*` тон не несёт, смысл заметки пишется словом в тексте                                           |
-| **Панель**               | Набор кнопок форматирования; вид задаёт `toolbar`. **Фиксированная** (`fixed`, по умолчанию) — над полем, липнет при прокрутке; **плавающая** (`floating`) — те же кнопки над непустым выделением. При `bubble` Панели нет — её место занимает Меню выделения, при `none` нет ни того, ни другого. На сенсорном экране Панель всегда фиксированная | `Toolbar` кита — Примитивом, из которого Панель собрана                                                                                                              |
-| **Меню вставки**         | Список «Добавить» и «Превратить в»: открывается по `/` в тексте и по кнопке «+»                                                                                                                                                                                                                                                                    | Контекстным меню браузера                                                                                                                                            |
-| **Меню выделения**       | Компактная плашка на инверсной поверхности над непустым выделением: «¶», списки, жирный, курсив, подчёркнутый, цвет, «…», ссылка, эмодзи; состав задан китом. Стоит вместо Панели при `toolbar="bubble"` и поверх фиксированной Панели — там её выключает `selectionMenu={false}`. На сенсорном экране её нет                                      | Плавающей Панелью: у той полный набор кнопок                                                                                                                         |
-| **Ручка Блока**          | «⋮» у Блока с кареткой и её меню действий над Блоком целиком: «Добавить ›», «Формат ›», «Вверх», «Вниз», «Дублировать», «Удалить»                                                                                                                                                                                                                  | Панелью: та работает с выделением, а не с Блоком                                                                                                                     |
-| **Пункт вставки**        | Строка Меню вставки: вставляет Блок или превращает текущий. Один пункт виден и по `/`, и по «+», и в Ручке Блока                                                                                                                                                                                                                                   | Кнопкой Панели                                                                                                                                                       |
-| **Действие над Блоком**  | Пункт меню Ручки Блока, который работает с Блоком целиком, например «Дублировать»                                                                                                                                                                                                                                                                  | Кнопкой: та работает с выделением                                                                                                                                    |
-| **Справочник сочетаний** | Поповер «команда — сочетание» только для чтения за последней кнопкой фиксированной Панели. Строки — команды включённых Инструментов, своих тоже; на телефоне кнопки нет                                                                                                                                                                            | `CommandPalette` кита: строки Справочника сочетаний не нажимаются. `ShortcutsHelp` кита: тот — сочетания экрана, а не Редактора                                      |
-| **HTML-режим**           | Режим Инструмента `source`: кнопка «HTML» на фиксированной Панели заменяет Документ полем с его HTML. Текст поля проходит Схему и становится Документом одной правкой — при выходе из режима, `blur`, отправке формы и чтении через Хэндл                                                                                                          | HTML-соглашением: то — форма своего в Документе, а не режим. `CodeView`: тот показывает код, а поле HTML правится                                                    |
-| **Стекло**               | Полупрозрачная заливка с размытием фона у всего, что Редактор показывает поверх Документа: плавающая Панель, Меню выделения, меню, поповеры, Карточка у текста. Цвет — токен своей поверхности; при `prefers-reduced-transparency`, `prefers-contrast: more` и на iOS заливка сплошная                                                             | `Menu` и `Popover` кита вне Редактора: те остаются сплошными                                                                                                         |
-| **UI-запись**            | Элемент интерфейса своего Инструмента, описанный данными: кнопка, Пункт вставки, Действие над Блоком или Карточка у текста. Рисует её кит в Отведённом месте; выключенный Инструмент убирает и свои записи                                                                                                                                         | React-узлом в интерфейсе: произвольный React допускается только в содержимом поповера кнопки и Карточки у текста                                                     |
-| **Отведённое место**     | Одно место на поверхности, где стоят записи своих Инструментов, в порядке `tools`: группа Панели перед «Отменить», конец раздела Меню вставки, секция Ручки Блока перед «Удалить»                                                                                                                                                                  | Позицией относительно встроенной кнопки: id встроенных публичным API не являются                                                                                     |
-| **Пресет**               | Готовый набор встроенных Инструментов: `full` или `basic` (`RICH_TEXT_PRESETS`). Не замороженный список: новый встроенный приходит в него minor-версией                                                                                                                                                                                            | Точным списком `tools`: его состав меняет только экран                                                                                                               |
-| **Инструмент**           | Одна возможность Редактора: её Блоки и Метки, их правила в Схеме и место в интерфейсе, например `table`. Встроенный задаётся именем, свой — описанием                                                                                                                                                                                              | Кнопкой: выключенный Инструмент убирает и Блок из Схемы. Плагином Redactor: тот — класс поведения над DOM без Схемы                                                  |
-| **Свой Инструмент**      | Инструмент, который описывает потребитель (`CustomTool`): правила Схемы данными, Часть для движка и UI-записи. Передаётся в `tools` вперемешку с именами кита                                                                                                                                                                                      | Внутренним описанием кита: то — надмножество публичной формы для встроенных, наружу не экспортируется                                                                |
-| **Префикс потребителя**  | Начало имени всего своего — Инструмента, его Блоков, Меток и атрибутов — до подчёркивания: `acme_mergeTag`, `data-acme_size`. В именах кита подчёркивания нет, поэтому своё и встроенное не совпадают ни в наборе, ни в Документе                                                                                                                  | Пресетом: тот — набор встроенных Инструментов, а не пространство имён                                                                                                |
-| **HTML-соглашение**      | Форма своего в Документе: Блок — `div` или `span` с `data-block`, Метка — `span` с `data-mark`, атрибуты — `data-<префикс>_<имя>`. Заморожено: расширяется только добавлением                                                                                                                                                                      | Тегами Схемы кита (`p`, `table`, `img`): свой Блок их занять не может                                                                                                |
-| **Признак Блока**        | Свойство Блока, которое понимает только кит, а не движок: «контейнер» (детям своя Ручка), «можно превратить в», «Атом без меню форматирования»                                                                                                                                                                                                     | Атрибутом Блока: тот хранится в Документе                                                                                                                            |
-| **Часть для движка**     | То в описании Инструмента, что нужно только живому Редактору: расширения Tiptap и вид узла. Подаётся сразу или Загрузчиком                                                                                                                                                                                                                         | Правилами Схемы: те — данные, их читают сервер и Просмотр без движка                                                                                                 |
-| **Загрузчик**            | Функция с динамическим импортом вместо Части для движка: `engine: () => import(…)`. Так же грузятся тяжёлые встроенные вне `basic` — Блок кода и таблица                                                                                                                                                                                           | Предзагрузкой (`modulepreload`): её кит не публикует, ставит потребитель                                                                                             |
-| **Хэндл**                | Императивный доступ кода экрана к Редактору через `ref`: вставка у каретки, чтение, фокус, история                                                                                                                                                                                                                                                 | Сервисами Redactor: те — внутренности движка, а не API экрана                                                                                                        |
-| **Готовность**           | Момент, когда движок создан и Загрузчики всех включённых Инструментов, своих и встроенных, отработали: с него методы Хэндла действуют, а не молчат. Наступает один раз за монтаж, о нём сообщает `onReady`                                                                                                                                         | Гидратацией: после неё движок может ещё ждать Загрузчики                                                                                                             |
-| **Фокус поля**           | Фокус внутри Редактора целиком: Документ, Панель, поповеры кита, поле HTML. Переход между ними Фокус поля не теряет; `onFocus` и `onBlur` — о нём                                                                                                                                                                                                  | Фокусом Документа (`focus` и `blur` движка): клик в Панель его снимает                                                                                               |
-| **Правка автора**        | Изменение Документа, равное набору с клавиатуры: шаг истории, `onChange` после задержки, предел символов действует. Сюда же вставка, отмена и повтор из Хэндла                                                                                                                                                                                     | Заменой снаружи                                                                                                                                                      |
-| **Замена снаружи**       | Подмена Документа целиком (`value`, `clear()`, `setMarkdown()`, `setJSON()`): предел символов не режет; `onChange` сразу у `clear()`, `setMarkdown()` и `setJSON()`, на новый `value` не вызывается                                                                                                                                                | Правкой автора                                                                                                                                                       |
-| **Скелет**               | Вид Редактора до Готовности: рамка поля, место Панели и Документ: очищенный Схемой, он выведен статичным HTML с тем же классом и ритмом, что Документ движка, без ввода. На сервере — рамка без Документа. Сбой Загрузчика превращает Скелет в ошибку поля с «Повторить»                                                                           | Просмотром: тот — отдельный компонент только для чтения, а Скелет — состояние Редактора, которое сменяется движком. Компонентом `Skeleton` кита — заглушкой загрузки |
-| **Строка статуса**       | Строка внутри рамки поля под Документом: слева содержимое экрана (`status`: число слов, «Сохранено», соавтор), справа счётчик символов кита                                                                                                                                                                                                        | Сообщением поля: строка показывает длительное состояние экрана, а не событие                                                                                         |
-| **Сообщение поля**       | Одно событие, привязанное к полю (`showNotice`): тон `status` (только озвучивается) или `error` (видимая строка под полем до следующей Правки автора). Новое заменяет прежнее                                                                                                                                                                      | Тостом кита: тот глобален и к полю не привязан                                                                                                                       |
-| **Карточка у текста**    | Немодальная карточка под диапазоном Документа, который объявил свой Инструмент (`textCards`): комментарий, подсказка по результатам проверки текста. Открывается кареткой или щелчком, фокус остаётся в тексте                                                                                                                                     | Поповером кнопки: его открывает кнопка, а Карточку — место Документа                                                                                                 |
-| **Символ-триггер**       | Свой символ Инструмента (`trigger`), набор которого в начале Блока или после пробела открывает список пунктов у каретки, как `/`: `@` для упоминаний, `#` для тегов. Выбор заменяет набранное `@запрос` своим узлом                                                                                                                                | Меню вставки по `/`: то — встроенное, а свой символ задаёт Инструмент                                                                                                |
-| **Лист**                 | Светлая область Документа в любой теме приложения (`surface="paper"`) — для текста, который уйдёт из приложения светлым: письмо, печать, PDF. Панель, меню и рамка поля остаются в теме приложения; Просмотр с тем же `surface` показывает тот же Лист                                                                                             | Темой `light`: та меняет всё приложение, Лист — только Документ                                                                                                      |
-| **Остров**               | Клиентский кусок Просмотра, который после монтирования оживляет Блок в уже показанном HTML: кнопка «Копировать» у Блока кода, `island` своего Блока                                                                                                                                                                                                | Видом узла: тот живёт только в движке Редактора                                                                                                                      |
-| **Гнездо**               | Место в показанном HTML, куда Остров монтирует живой элемент: шапка Блока кода, в которую встаёт кнопка «Копировать»                                                                                                                                                                                                                               | Отведённым местом: то — место в интерфейсе Редактора для записей Инструментов                                                                                        |
+| Термин                     | Значение                                                                                                                                                                                                                                                                                                                                           | Не путать с                                                                                                                                                                                                 |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Редактор**               | `RichTextEditor` — поле ввода форматированного текста                                                                                                                                                                                                                                                                                              | Редактором кода: его в ките нет, показ кода — `CodeView`                                                                                                                                                    |
+| **Просмотр**               | `RichTextView` — только чтение сохранённого Документа                                                                                                                                                                                                                                                                                              | `readOnly`-режимом Редактора: тот держит движок, Просмотр — нет                                                                                                                                             |
+| **Оглавление**             | `RichTextToc`: список заголовков Документа рядом с Просмотром или Редактором. Свёрнуто — полоса штрихов, раскрыто — список, клик по пункту ведёт к заголовку                                                                                                                                                                                       | `Heading` кита и навигацией сайта документации                                                                                                                                                              |
+| **Документ**               | Значение Редактора: HTML-строка, ограниченная Схемой                                                                                                                                                                                                                                                                                               | JSON-деревом ProseMirror в движке — оно внутреннее; наружу оно выходит только JSON-конвертом                                                                                                                |
+| **JSON-конверт**           | Документ как JSON для файла и шаблона: `{ format: "olddevs-rich-text", version, doc }` (`getJSON()`, `setJSON()`, `defaultValue`), без потерь и через Схему                                                                                                                                                                                        | Значением Редактора — значение остаётся HTML; голым деревом `editor.getJSON()` без конверта                                                                                                                 |
+| **Схема**                  | Белый список Блоков, Меток и атрибутов, которые Редактор принимает и отдаёт                                                                                                                                                                                                                                                                        | Санитизацией на сервере — её делает потребитель (`sanitizeRichText`)                                                                                                                                        |
+| **Блок**                   | Структурный элемент Документа: абзац, заголовок, список, таблица, картинка…                                                                                                                                                                                                                                                                        | Меткой                                                                                                                                                                                                      |
+| **Метка**                  | Строчное форматирование внутри Блока: жирный, ссылка, цвет…                                                                                                                                                                                                                                                                                        | Блоком                                                                                                                                                                                                      |
+| **Атом**                   | Блок или строчный элемент, который выделяется, переносится и удаляется целиком: картинка (подпись внутри неё правится), разделитель, мягкий перенос, упоминание. Всегда делает поле непустым                                                                                                                                                       | Пустым Блоком: абзац без текста — не Атом и содержимым не считается                                                                                                                                         |
+| **Текст атома**            | Строка, которой Атом представлен в тексте Документа: её отдают `getText` и `getSelectedText`, её длина — вес Атома в `maxLength`, ею Атом выгружается в Markdown без своих правил. У картинки — текст подписи, у разделителя — пустая строка                                                                                                       | Атрибутом Блока                                                                                                                                                                                             |
+| **Раскладка**              | Блок из колонок (Инструмент `layout`): шесть вариантов — от одной до четырёх равных колонок, 60/40 и 40/60. Только верхнего уровня, в себя не вкладывается; колонка для своих Блоков — то же, что Документ                                                                                                                                         | Таблицей: у той строки и ячейки данных, а колонки Раскладки — вёрстка Документа. `Grid` кита — сеткой экрана, а не Блоком                                                                                   |
+| **Обёртка**                | Блок, который собирает группу Блоков (Инструмент `wrapper`, `div` с `data-block="wrapper"`): их двигают, дублируют и удаляют одним Блоком. Без Тона Обёртки своего вида нет — пунктир только в Редакторе. Обёртка и Раскладка в Обёртку не вкладываются                                                                                            | Цитатой: у той свой вид и смысл в Документе, а Обёртка без тона — только группировка                                                                                                                        |
+| **Тон Обёртки**            | Оформление Обёртки заметкой (`data-tone`): фон и полоса слева одного из пяти тонов словаря `Tone` — «Заметка», «Совет», «Важно», «Внимание», «Осторожно». Выбирается в «Тон ›» Ручки Блока, одинаков в Редакторе и Просмотре, в Markdown выгружается GitHub alert (то, что GitHub и Notion называют callout)                                       | Тоном Сообщения поля (`status` или `error`). Смыслом: ролей и `aria-*` тон не несёт, смысл заметки пишется словом в тексте                                                                                  |
+| **Панель**                 | Набор кнопок форматирования; вид задаёт `toolbar`. **Фиксированная** (`fixed`, по умолчанию) — над полем, липнет при прокрутке; **плавающая** (`floating`) — те же кнопки над непустым выделением. При `bubble` Панели нет — её место занимает Меню выделения, при `none` нет ни того, ни другого. На сенсорном экране Панель всегда фиксированная | `Toolbar` кита — Примитивом, из которого Панель собрана                                                                                                                                                     |
+| **Меню вставки**           | Список «Добавить» и «Превратить в»: открывается по `/` в тексте и по кнопке «+»                                                                                                                                                                                                                                                                    | Контекстным меню браузера                                                                                                                                                                                   |
+| **Меню выделения**         | Компактная плашка на инверсной поверхности над непустым выделением: «¶», списки, жирный, курсив, подчёркнутый, цвет, «…», ссылка, эмодзи; состав задан китом. Стоит вместо Панели при `toolbar="bubble"` и поверх фиксированной Панели — там её выключает `selectionMenu={false}`. На сенсорном экране её нет                                      | Плавающей Панелью: у той полный набор кнопок                                                                                                                                                                |
+| **Ручка Блока**            | «⋮» у Блока с кареткой и её меню действий над Блоком целиком: «Добавить ›», «Формат ›», «Вверх», «Вниз», «Дублировать», «Удалить»                                                                                                                                                                                                                  | Панелью: та работает с выделением, а не с Блоком                                                                                                                                                            |
+| **Пункт вставки**          | Строка Меню вставки: вставляет Блок или превращает текущий. Один пункт виден и по `/`, и по «+», и в Ручке Блока                                                                                                                                                                                                                                   | Кнопкой Панели                                                                                                                                                                                              |
+| **Действие над Блоком**    | Пункт меню Ручки Блока, который работает с Блоком целиком, например «Дублировать»                                                                                                                                                                                                                                                                  | Кнопкой: та работает с выделением                                                                                                                                                                           |
+| **Справочник сочетаний**   | Поповер «команда — сочетание» только для чтения за последней кнопкой фиксированной Панели. Строки — команды включённых Инструментов, своих тоже; на телефоне кнопки нет                                                                                                                                                                            | `CommandPalette` кита: строки Справочника сочетаний не нажимаются. `ShortcutsHelp` кита: тот — сочетания экрана, а не Редактора                                                                             |
+| **HTML-режим**             | Режим Инструмента `source`: кнопка «HTML» на фиксированной Панели заменяет Документ полем с его HTML. Текст поля проходит Схему и становится Документом одной правкой — при выходе из режима, `blur`, отправке формы и чтении через Хэндл                                                                                                          | HTML-соглашением: то — форма своего в Документе, а не режим. `CodeView`: тот показывает код, а поле HTML правится                                                                                           |
+| **Стекло**                 | Полупрозрачная заливка с размытием фона у всего, что Редактор показывает поверх Документа: плавающая Панель, Меню выделения, меню, поповеры, Карточка у текста. Цвет — токен своей поверхности; при `prefers-reduced-transparency`, `prefers-contrast: more` и на iOS заливка сплошная                                                             | `Menu` и `Popover` кита вне Редактора: те остаются сплошными                                                                                                                                                |
+| **UI-запись**              | Элемент интерфейса своего Инструмента, описанный данными: кнопка, Пункт вставки, Действие над Блоком или Карточка у текста. Рисует её кит в Отведённом месте; выключенный Инструмент убирает и свои записи                                                                                                                                         | React-узлом в интерфейсе: произвольный React допускается только в содержимом поповера кнопки и Карточки у текста                                                                                            |
+| **Отведённое место**       | Одно место на поверхности, где стоят записи своих Инструментов, в порядке `tools`: группа Панели перед «Отменить», конец раздела Меню вставки, секция Ручки Блока перед «Удалить»                                                                                                                                                                  | Позицией относительно встроенной кнопки: id встроенных публичным API не являются                                                                                                                            |
+| **Пресет**                 | Готовый набор встроенных Инструментов: `full` или `basic` (`RICH_TEXT_PRESETS`). Не замороженный список: новый встроенный приходит в него minor-версией                                                                                                                                                                                            | Точным списком `tools`: его состав меняет только экран                                                                                                                                                      |
+| **Инструмент**             | Одна возможность Редактора: её Блоки и Метки, их правила в Схеме и место в интерфейсе, например `table`. Встроенный задаётся именем, свой — описанием                                                                                                                                                                                              | Кнопкой: выключенный Инструмент убирает и Блок из Схемы. Плагином Redactor: тот — класс поведения над DOM без Схемы                                                                                         |
+| **Свой Инструмент**        | Инструмент, который описывает потребитель (`CustomTool`): правила Схемы данными, Часть для движка и UI-записи. Передаётся в `tools` вперемешку с именами кита                                                                                                                                                                                      | Внутренним описанием кита: то — надмножество публичной формы для встроенных, наружу не экспортируется                                                                                                       |
+| **Опции Инструмента**      | Что экран задаёт Инструменту до создания движка: стартовые флажки Поиска, `offsetVar`, `levels` и `listWidth` Оглавления, `defaults` своего Инструмента (`defineTool`). Экран задаёт их записью `tool(…)`, кит читает один раз, при создании движка                                                                                                | `options` у расширения Tiptap: те задаёт сам автор расширения и читает Часть для движка, а Опции задаёт экран и читает кит. Пропами Редактора (`preset`, `maxHeight`): те настраивают поле, а не Инструмент |
+| **Настроенный Инструмент** | Запись `tools`, которую возвращает `tool(name, options)` или `tool(definition, options)`: Инструмент вместе с его Опциями. Включает Инструмент без имени в `tools` и побеждает голое имя из Пресета                                                                                                                                                | Определением `defineTool`: то описывает Инструмент, а Настроенный Инструмент — его включение с Опциями. Описанием встроенного: оно наружу не выходит, запись лишь называет Инструмент и несёт Опции         |
+| **Состояние Инструмента**  | Снимок данных, который экран читает хуком `useRichTextToolState(ref, name)`: у Поиска — открыта ли панель, запрос, число совпадений и текущее, у Оглавления — заголовки и текущий раздел. Перерисовка только при смене снимка                                                                                                                      | `storage` у расширения Tiptap: то — изменяемое хранилище внутри движка, а Состояние только читается. `useRichTextEditorState`: тот берёт срез живого `editor` Tiptap, а не контракт Инструмента             |
+| **Команды Инструмента**    | Что экран вызывает у Инструмента через `handle.tool(name)`: `tool("search")?.open()`, `tool("toc")?.jumpTo(2)`. Каждая возвращает `boolean`; `null` вместо объекта Команд — Инструмента нет в наборе, у него нет Команд или движок ещё не создан                                                                                                   | Методами Хэндла (`insertHTML`, `focus`): те общие для любого `tools`, а Команды есть, только пока Инструмент включён. `editor.commands` и `commands` у Tiptap: те — команды движка, они следуют его мажору  |
+| **Префикс потребителя**    | Начало имени всего своего — Инструмента, его Блоков, Меток и атрибутов — до подчёркивания: `acme_mergeTag`, `data-acme_size`. В именах кита подчёркивания нет, поэтому своё и встроенное не совпадают ни в наборе, ни в Документе                                                                                                                  | Пресетом: тот — набор встроенных Инструментов, а не пространство имён                                                                                                                                       |
+| **HTML-соглашение**        | Форма своего в Документе: Блок — `div` или `span` с `data-block`, Метка — `span` с `data-mark`, атрибуты — `data-<префикс>_<имя>`. Заморожено: расширяется только добавлением                                                                                                                                                                      | Тегами Схемы кита (`p`, `table`, `img`): свой Блок их занять не может                                                                                                                                       |
+| **Признак Блока**          | Свойство Блока, которое понимает только кит, а не движок: «контейнер» (детям своя Ручка), «можно превратить в», «Атом без меню форматирования»                                                                                                                                                                                                     | Атрибутом Блока: тот хранится в Документе                                                                                                                                                                   |
+| **Часть для движка**       | То в описании Инструмента, что нужно только живому Редактору: расширения Tiptap и вид узла. Подаётся сразу или Загрузчиком                                                                                                                                                                                                                         | Правилами Схемы: те — данные, их читают сервер и Просмотр без движка                                                                                                                                        |
+| **Загрузчик**              | Функция с динамическим импортом вместо Части для движка: `engine: () => import(…)`. Так же грузятся тяжёлые встроенные вне `basic` — Блок кода и таблица                                                                                                                                                                                           | Предзагрузкой (`modulepreload`): её кит не публикует, ставит потребитель                                                                                                                                    |
+| **Хэндл**                  | Императивный доступ кода экрана к Редактору через `ref`: вставка у каретки, чтение, фокус, история, Команды Инструментов (`tool(name)`)                                                                                                                                                                                                            | Сервисами Redactor: те — внутренности движка, а не API экрана                                                                                                                                               |
+| **Готовность**             | Момент, когда движок создан и Загрузчики всех включённых Инструментов, своих и встроенных, отработали: с него методы Хэндла действуют, а не молчат. Наступает один раз за монтаж, о нём сообщает `onReady`                                                                                                                                         | Гидратацией: после неё движок может ещё ждать Загрузчики                                                                                                                                                    |
+| **Фокус поля**             | Фокус внутри Редактора целиком: Документ, Панель, поповеры кита, поле HTML. Переход между ними Фокус поля не теряет; `onFocus` и `onBlur` — о нём                                                                                                                                                                                                  | Фокусом Документа (`focus` и `blur` движка): клик в Панель его снимает                                                                                                                                      |
+| **Правка автора**          | Изменение Документа, равное набору с клавиатуры: шаг истории, `onChange` после задержки, предел символов действует. Сюда же вставка, отмена и повтор из Хэндла                                                                                                                                                                                     | Заменой снаружи                                                                                                                                                                                             |
+| **Замена снаружи**         | Подмена Документа целиком (`value`, `clear()`, `setMarkdown()`, `setJSON()`): предел символов не режет; `onChange` сразу у `clear()`, `setMarkdown()` и `setJSON()`, на новый `value` не вызывается                                                                                                                                                | Правкой автора                                                                                                                                                                                              |
+| **Скелет**                 | Вид Редактора до Готовности: рамка поля, место Панели и Документ: очищенный Схемой, он выведен статичным HTML с тем же классом и ритмом, что Документ движка, без ввода. На сервере — рамка без Документа. Сбой Загрузчика превращает Скелет в ошибку поля с «Повторить»                                                                           | Просмотром: тот — отдельный компонент только для чтения, а Скелет — состояние Редактора, которое сменяется движком. Компонентом `Skeleton` кита — заглушкой загрузки                                        |
+| **Строка статуса**         | Строка внутри рамки поля под Документом: слева содержимое экрана (`status`: число слов, «Сохранено», соавтор), справа счётчик символов кита                                                                                                                                                                                                        | Сообщением поля: строка показывает длительное состояние экрана, а не событие                                                                                                                                |
+| **Сообщение поля**         | Одно событие, привязанное к полю (`showNotice`): тон `status` (только озвучивается) или `error` (видимая строка под полем до следующей Правки автора). Новое заменяет прежнее                                                                                                                                                                      | Тостом кита: тот глобален и к полю не привязан                                                                                                                                                              |
+| **Карточка у текста**      | Немодальная карточка под диапазоном Документа, который объявил свой Инструмент (`textCards`): комментарий, подсказка по результатам проверки текста. Открывается кареткой или щелчком, фокус остаётся в тексте                                                                                                                                     | Поповером кнопки: его открывает кнопка, а Карточку — место Документа                                                                                                                                        |
+| **Символ-триггер**         | Свой символ Инструмента (`trigger`), набор которого в начале Блока или после пробела открывает список пунктов у каретки, как `/`: `@` для упоминаний, `#` для тегов. Выбор заменяет набранное `@запрос` своим узлом                                                                                                                                | Меню вставки по `/`: то — встроенное, а свой символ задаёт Инструмент                                                                                                                                       |
+| **Лист**                   | Светлая область Документа в любой теме приложения (`surface="paper"`) — для текста, который уйдёт из приложения светлым: письмо, печать, PDF. Панель, меню и рамка поля остаются в теме приложения; Просмотр с тем же `surface` показывает тот же Лист                                                                                             | Темой `light`: та меняет всё приложение, Лист — только Документ                                                                                                                                             |
+| **Остров**                 | Клиентский кусок Просмотра, который после монтирования оживляет Блок в уже показанном HTML: кнопка «Копировать» у Блока кода, `island` своего Блока                                                                                                                                                                                                | Видом узла: тот живёт только в движке Редактора                                                                                                                                                             |
+| **Гнездо**                 | Место в показанном HTML, куда Остров монтирует живой элемент: шапка Блока кода, в которую встаёт кнопка «Копировать»                                                                                                                                                                                                                               | Отведённым местом: то — место в интерфейсе Редактора для записей Инструментов                                                                                                                               |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olddevs/ui",
-  "version": "4.4.0",
+  "version": "4.5.1",
   "description": "Olddevs UI — design system: tokens, themes and accessible UI primitives",
   "license": "MIT",
   "private": false,