@olddevs/ui 4.5.0 → 4.6.0

package/docs/api/editor-extension.en.md

@@ -2,14 +2,14 @@
 category: api
 status: stable
 source: src/editor/index.ts
-sourceHash: 82b5217dd20e
+sourceHash: 808244893ee6
 ---
 
 # Editor extension API
 
 ## Summary for AI
 
-A map of how a product extends `RichTextEditor` from `@olddevs/ui/editor`, and the stability boundary of this API. The unit of extension is a **custom Tool** (`CustomTool`): the description of one Editor capability, passed in `tools` mixed in with the kit's names. It carries Blocks and Marks with Schema rules (as data), an Engine part (Tiptap extensions, supplied directly or through a Loader) and UI contributions: buttons, Insert items, Block actions, Text cards. A custom Trigger character (`trigger`) is also available: `@` for mentions opens the same list as `/`. The screen's code controls the field through the Handle (`ref`) and the `useRichTextEditorState` hook, learns about Readiness and Field focus through the `onReady`, `onFocus` and `onBlur` callbacks, puts its own content into the Status line (`status`) and reports an error with the `showNotice` command. A Tool has three typed parts, like `options`, `storage` and `commands` of a Tiptap extension: **options** (`tool(name, options)` for the built-in `search` and `toc`, `defineTool` for a custom Tool), **state** (the `useRichTextToolState` hook) and **commands** (`handle.tool(name)`); their types are collected in the extensible `RichTextTools` map, where a custom Tool adds itself through `declare module "@olddevs/ui/editor"`. The same `tools` array is understood by server-side sanitizing (`sanitizeRichText`, `richTextSchema`) and by `RichTextView` with Islands. Everything listed follows the kit's semver from the first release, the HTML convention is frozen, and a Tiptap major is a kit major (section "Stability"). The details of each item live on the [RichTextEditor](../components/inputs/rich-text-editor.md) page; this page covers the map, the contract boundary and the recipes.
+A map of how a product extends `RichTextEditor` from `@olddevs/ui/editor`, and the stability boundary of this API. The unit of extension is a **custom Tool** (`CustomTool`): the description of one Editor capability, passed in `tools` mixed in with the kit's names. It carries Blocks and Marks with Schema rules (as data), Extensions (Tiptap extensions, supplied directly or through a Loader) and UI contributions: buttons, Insert items, Block actions, Text cards. A custom Trigger character (`trigger`) is also available: `@` for mentions opens the same list as `/`. The screen's code controls the field through the Handle (`ref`) and the `useRichTextEditorState` hook, learns about Readiness and Field focus through the `onReady`, `onFocus` and `onBlur` callbacks, puts its own content into the Status line (`status`) and reports an error with the `showNotice` command. A Tool has three typed parts, like `options`, `storage` and `commands` of a Tiptap extension: **options** (`tool(name, options)` for the built-in `search` and `toc`, `defineTool` for a custom Tool), **state** (the `useRichTextToolState` hook) and **commands** (`handle.tool(name)`); their types are collected in the extensible `RichTextTools` map, where a custom Tool adds itself through `declare module "@olddevs/ui/editor"`. The same `tools` array is understood by server-side sanitizing (`sanitizeRichText`, `richTextSchema`) and by `RichTextView` with Islands. Everything listed follows the kit's semver from the first release, the HTML convention is frozen, and a Tiptap major is a kit major (section "Stability"). The details of each item live on the [RichTextEditor](../components/inputs/rich-text-editor.md) page; this page covers the map, the contract boundary and the recipes.
 
 ```tsx
 import {
@@ -40,39 +40,39 @@ The decision is ADR-0058, which supplements ADR-0050. Capitalized terms come fro
 
 - What you need is already among the kit's Tools (["Tools and Presets"](../components/inputs/rich-text-editor.md#инструменты-и-пресеты)): pass the name in `tools`, do not write a custom Tool.
 - To hide a built-in button or item, narrow `tools`. A built-in Tool cannot be replaced by name: turn it off and add a custom Tool under your own name.
-- Only `search` and `toc` have options; `tool("bold", …)` does not compile. Options for other built-in Tools will be added one at a time, as consumers ask for them. You cannot change the behavior of a built-in Tool by substitution (there is no `extend()` as in Tiptap): the descriptions of built-in Tools are not exported.
+- Only `search`, `toc` and `details` have options; `tool("bold", …)` does not compile. Options for other built-in Tools will be added one at a time, as consumers ask for them. You cannot change the behavior of a built-in Tool by substitution (there is no `extend()` as in Tiptap): the descriptions of built-in Tools are not exported.
 - You cannot change the options of a mounted field: they are read once, when the engine is created, together with `tools`. Remount the field with a key.
 - You cannot put arbitrary React in the Toolbar row or in a menu: the kit renders the UI contributions itself. React is allowed only in the content of a popover (of a button, Insert item or Block action) and in a Text card.
-- You cannot intercept paste and drop through a prop: the Engine part of a custom Tool handles them (["Paste and drop order"](../components/inputs/rich-text-editor.md#порядок-вставки-и-drop)).
+- You cannot intercept paste and drop through a prop: the Extensions of a custom Tool handle them (["Paste and drop order"](../components/inputs/rich-text-editor.md#порядок-вставки-и-drop)).
 - What is not provided until consumers ask for it (ADR-0058, section 13): `insertImage` and the selection's HTML in the Handle, `onSelectionChange`, `onPaste`, `onDrop`, `onEmpty`, `onDestroy`, history events, a signal about removed images, locked template Blocks, a "menu" UI contribution kind, Text cards and the Status line in `RichTextView`. Until then the screen has `ref.current.editor` and its events.
 - Custom Trigger characters like `@` are no longer on this list: they are supported by the `trigger` field of a Tool (ADR-0064, section "Trigger character" below).
 
 ## API map
 
-| What                                         | Where in the API                                                                                                   | Details                                                                                                                                                                                                                                 |
-| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Custom Tool                                  | `CustomTool` in `tools`; Presets — `RICH_TEXT_PRESETS`                                                             | ["Custom Tool"](../components/inputs/rich-text-editor.md#свой-инструмент)                                                                                                                                                               |
-| Schema rules and the HTML convention         | `blocks` (`CustomBlock`), `marks` (`CustomMark`), `CustomAttribute`, `PrefixedName`                                | ["Custom Tool"](../components/inputs/rich-text-editor.md#свой-инструмент)                                                                                                                                                               |
-| Button                                       | `buttons` (`CustomToolButton`, `CustomToolPopover`, `CustomToolLabel`)                                             | ["Custom Tool's button"](../components/inputs/rich-text-editor.md#кнопка-своего-инструмента)                                                                                                                                            |
-| Insert item, Block action                    | `insertItems` (`CustomInsertItem`), `blockActions` (`CustomBlockAction`)                                           | ["Insert items and Block actions"](../components/inputs/rich-text-editor.md#пункты-вставки-и-действия-над-блоком)                                                                                                                       |
-| Trigger character                            | `trigger` (`CustomTrigger`, `TriggerItem`, `TriggerContext`)                                                       | ["Custom Trigger character"](../components/inputs/rich-text-editor.md#свой-символ-триггер)                                                                                                                                              |
-| Text card                                    | `textCards` (`CustomTextCard`), the `markRange` helper                                                             | ["Text card"](../components/inputs/rich-text-editor.md#карточка-у-текста)                                                                                                                                                               |
-| Handle and your own panel                    | `RichTextEditorHandle`, `useRichTextEditorState(ref, selector)`                                                    | ["Handle (`ref`) and your own toolbar outside the field"](../components/inputs/rich-text-editor.md#хэндл-ref-и-своя-панель-вне-поля)                                                                                                    |
-| Options of a built-in Tool                   | `tool(name, options)` → `ConfiguredTool` for `search` and `toc`; `SearchToolOptions`, `TocToolOptions`, `TocLevel` | ["Options of a built-in Tool: `tool()`"](../components/inputs/rich-text-editor.md#опции-встроенного-инструмента-tool)                                                                                                                   |
-| A custom Tool with options, state, commands  | `defineTool({ name, defaults, create, state, commands })` → `ToolDefinition`, `tool(definition, options)`          | ["Options, state and commands"](editor-extension.md#опции-состояние-и-команды)                                                                                                                                                          |
-| Types of options, state and commands         | the extensible `RichTextTools` interface                                                                           | ["The `RichTextTools` map and declaration merging"](editor-extension.md#карта-richtexttools-и-declaration-merging)                                                                                                                      |
-| Tool state                                   | `useRichTextToolState(ref, name, selector?)`, `SearchToolState`, `TocToolState`, `TocToolHeading`                  | ["Tool state: `useRichTextToolState`"](../components/inputs/rich-text-editor.md#состояние-инструмента-userichtexttoolstate)                                                                                                             |
-| Tool commands                                | `handle.tool(name)`, `SearchToolCommands`, `TocToolCommands`                                                       | ["Tool commands: `handle.tool()`"](../components/inputs/rich-text-editor.md#команды-инструмента-handletool)                                                                                                                             |
-| Events                                       | `onReady`, `onFocus`, `onBlur`; paste and drop — by the Engine part                                                | ["Events"](../components/inputs/rich-text-editor.md#события)                                                                                                                                                                            |
-| Status line and Field notice                 | the `status` prop; the engine command `showNotice`, the `FieldNotice` type                                         | ["Status line and Field notice"](../components/inputs/rich-text-editor.md#строка-статуса-и-сообщение-поля)                                                                                                                              |
-| Loader, Readiness and Skeleton               | `engine: () => import(…)`                                                                                          | ["Engine part Loader"](../components/inputs/rich-text-editor.md#загрузчик-части-для-движка), ["Skeleton"](../components/inputs/rich-text-editor.md#скелет)                                                                              |
-| Atom text: `getText`, `maxLength`, emptiness | `renderText` of the Engine part                                                                                    | ["Atom text"](../components/inputs/rich-text-editor.md#текст-атома)                                                                                                                                                                     |
-| Server, Markdown, View                       | `sanitizeRichText(html, DOMPurify, tools)`, `richTextSchema(tools)`, `RichTextView`                                | ["Outside the Editor"](../components/inputs/rich-text-editor.md#вне-редактора-сервер-markdown-и-просмотр), [RichTextView, "Custom Tools: the third argument"](../components/content/rich-text-view.md#свои-инструменты-третий-аргумент) |
-| Island of a custom Block                     | `CustomBlock.island`, `CustomIslandProps`, the `tools` prop of `RichTextView`                                      | [RichTextView, "Custom Block's Island"](../components/content/rich-text-view.md#остров-своего-блока)                                                                                                                                    |
+| What                                         | Where in the API                                                                                                                                    | Details                                                                                                                                                                                                                                 |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Custom Tool                                  | `CustomTool` in `tools`; Presets — `RICH_TEXT_PRESETS`                                                                                              | ["Custom Tool"](../components/inputs/rich-text-editor.md#свой-инструмент)                                                                                                                                                               |
+| Schema rules and the HTML convention         | `blocks` (`CustomBlock`), `marks` (`CustomMark`), `CustomAttribute`, `PrefixedName`                                                                 | ["Custom Tool"](../components/inputs/rich-text-editor.md#свой-инструмент)                                                                                                                                                               |
+| Button                                       | `buttons` (`CustomToolButton`, `CustomToolPopover`, `CustomToolLabel`)                                                                              | ["Custom Tool's button"](../components/inputs/rich-text-editor.md#кнопка-своего-инструмента)                                                                                                                                            |
+| Insert item, Block action                    | `insertItems` (`CustomInsertItem`), `blockActions` (`CustomBlockAction`)                                                                            | ["Insert items and Block actions"](../components/inputs/rich-text-editor.md#пункты-вставки-и-действия-над-блоком)                                                                                                                       |
+| Trigger character                            | `trigger` (`CustomTrigger`, `TriggerItem`, `TriggerContext`)                                                                                        | ["Custom Trigger character"](../components/inputs/rich-text-editor.md#свой-символ-триггер)                                                                                                                                              |
+| Text card                                    | `textCards` (`CustomTextCard`), the `markRange` helper                                                                                              | ["Text card"](../components/inputs/rich-text-editor.md#карточка-у-текста)                                                                                                                                                               |
+| Handle and your own panel                    | `RichTextEditorHandle`, `useRichTextEditorState(ref, selector)`                                                                                     | ["Handle (`ref`) and your own toolbar outside the field"](../components/inputs/rich-text-editor.md#хэндл-ref-и-своя-панель-вне-поля)                                                                                                    |
+| Options of a built-in Tool                   | `tool(name, options)` → `ConfiguredTool` for `search`, `toc` and `details`; `SearchToolOptions`, `TocToolOptions`, `TocLevel`, `DetailsToolOptions` | ["Options of a built-in Tool: `tool()`"](../components/inputs/rich-text-editor.md#опции-встроенного-инструмента-tool)                                                                                                                   |
+| A custom Tool with options, state, commands  | `defineTool({ name, defaults, create, state, commands })` → `ToolDefinition`, `tool(definition, options)`                                           | ["Options, state and commands"](editor-extension.md#опции-состояние-и-команды)                                                                                                                                                          |
+| Types of options, state and commands         | the extensible `RichTextTools` interface                                                                                                            | ["The `RichTextTools` map and declaration merging"](editor-extension.md#карта-richtexttools-и-declaration-merging)                                                                                                                      |
+| Tool state                                   | `useRichTextToolState(ref, name, selector?)`, `SearchToolState`, `TocToolState`, `TocToolHeading`                                                   | ["Tool state: `useRichTextToolState`"](../components/inputs/rich-text-editor.md#состояние-инструмента-userichtexttoolstate)                                                                                                             |
+| Tool commands                                | `handle.tool(name)`, `SearchToolCommands`, `TocToolCommands`                                                                                        | ["Tool commands: `handle.tool()`"](../components/inputs/rich-text-editor.md#команды-инструмента-handletool)                                                                                                                             |
+| Events                                       | `onReady`, `onFocus`, `onBlur`; paste and drop — by the Extensions                                                                                  | ["Events"](../components/inputs/rich-text-editor.md#события)                                                                                                                                                                            |
+| Status line and Field notice                 | the `status` prop; the engine command `showNotice`, the `FieldNotice` type                                                                          | ["Status line and Field notice"](../components/inputs/rich-text-editor.md#строка-статуса-и-сообщение-поля)                                                                                                                              |
+| Loader, Readiness and Skeleton               | `engine: () => import(…)`                                                                                                                           | ["Extensions Loader"](../components/inputs/rich-text-editor.md#загрузчик-extensions), ["Skeleton"](../components/inputs/rich-text-editor.md#скелет)                                                                                     |
+| Atom text: `getText`, `maxLength`, emptiness | `renderText` of the Extensions                                                                                                                      | ["Atom text"](../components/inputs/rich-text-editor.md#текст-атома)                                                                                                                                                                     |
+| Server, Markdown, View                       | `sanitizeRichText(html, DOMPurify, tools)`, `richTextSchema(tools)`, `RichTextView`                                                                 | ["Outside the Editor"](../components/inputs/rich-text-editor.md#вне-редактора-сервер-markdown-и-просмотр), [RichTextView, "Custom Tools: the third argument"](../components/content/rich-text-view.md#свои-инструменты-третий-аргумент) |
+| Island of a custom Block                     | `CustomBlock.island`, `CustomIslandProps`, the `tools` prop of `RichTextView`                                                                       | [RichTextView, "Custom Block's Island"](../components/content/rich-text-view.md#остров-своего-блока)                                                                                                                                    |
 
 ## Custom Tool and the HTML convention
 
-There is one description, with two parts inside. The **Schema rules** are plain data with no Tiptap: the Editor, server-side sanitizing and the View read them. The **Engine part** consists entirely of Tiptap extensions (Node, Mark, Extension, ProseMirror plugins, a React node view): behavior only, while the kit sets up HTML parsing and output. The name, the Engine part and a Schema rule for each of its Nodes and Marks are required; everything else has defaults: a plain Block with no traits, exported to Markdown as its content, paragraph rhythm in the View, no UI contributions. A Tool may carry no Block at all — for example, only a paste filter.
+There is one description, with two parts inside. The **Schema rules** are plain data with no Tiptap: the Editor, server-side sanitizing and the View read them. The **Extensions** are made up entirely of Tiptap extensions (Node, Mark, Extension, ProseMirror plugins, a React node view): behavior only, while the kit sets up HTML parsing and output. The name, the Extensions and a Schema rule for each of their Nodes and Marks are required; everything else has defaults: a plain Block with no traits, exported to Markdown as its content, paragraph rhythm in the View, no UI contributions. A Tool may carry no Block at all — for example, only a paste filter.
 
 Every custom name starts with a Consumer prefix followed by an underscore: the Tool `acme_mergeTag`, the attribute `acme_size`. The kit's names have no underscores, so custom and built-in names do not collide, either in the `tools` array or in a saved Document. The kit writes and reads custom HTML:
 
@@ -83,7 +83,7 @@ Every custom name starts with a Consumer prefix followed by an underscore: the T
 | Mark              | `<span data-mark="acme_comment">…</span>`                               |
 | Attribute         | `data-acme_size="m"` — the value follows the rule: list, pattern or URL |
 
-The `tools` array is checked once, when the engine is created (with Loaders, after they have run). A name without a prefix, a name clash, an Engine part with a Node or Mark that has no Schema rule (or the reverse), or a UI contribution without a required field produces an "Editor failed to start" field error, not a silent loss of Blocks on the first save. An unknown **string** in `tools` is still dropped silently.
+The `tools` array is checked once, when the engine is created (with Loaders, after they have run). A name without a prefix, a name clash, Extensions with a Node or Mark that has no Schema rule (or the reverse), or a UI contribution without a required field produces an "Editor failed to start" field error, not a silent loss of Blocks on the first save. An unknown **string** in `tools` is still dropped silently.
 
 ## UI contributions
 
@@ -99,7 +99,7 @@ The kit renders, the Tool describes. So the ARIA roles, the Toolbar's single Tab
 - **The label** is a string or a function that receives `{ locale }` (the `UiProvider` locale); the `UiProvider` message catalog is not extended for third-party Tools, and overriding is through the Tool factory's options (recipe below).
 - **The icon** is required for a button, item and action: a component with the `IconProps` contract from `@olddevs/ui/icons`, or your own.
 - **The popover** — a button, Insert item and Block action have exactly one of `run` and `popover`. The content is a function that receives `{ editor, close }` (for an action, also the Block's `pos`), and the kit provides the frame: the overlay layer, the Editor's popover Glass, the Escape stack, the name (the UI contribution's label), and returning focus and selection to the Document. A Text card sits on the same Glass, so your content does not need a solid background: it would cover the Glass backing. When the system transparency or contrast setting is on, the backing becomes solid on its own anyway. The popover opens at the button (click), at the caret (the button's shortcut, an item from "/", "+", "Add ›", "Format ›" and its shortcut) or at the Block (an action from the Block handle menu and its shortcut).
-- **The shortcut** (`shortcut`) is the single source: the kit binds the keyboard shortcut and writes it into the tooltip, `aria-keyshortcuts` and the Shortcuts reference. Keyboard shortcuts of the Engine part do not reach the reference.
+- **The shortcut** (`shortcut`) is the single source: the kit binds the keyboard shortcut and writes it into the tooltip, `aria-keyshortcuts` and the Shortcuts reference. Keyboard shortcuts bound by the Extensions do not reach the reference.
 - **A disabled Tool** removes its UI contributions from every surface.
 
 ## Trigger character
@@ -125,11 +125,11 @@ A Tool has three typed parts. They carry Tiptap's `options`, `storage` and `comm
 | State    | A snapshot the screen reads                   | The kit for built-ins; the `state` field of `defineTool`                                          | `useRichTextToolState(ref, name, selector?)` |
 | Commands | What the screen calls                         | The kit for built-ins; the `commands` field of `defineTool`                                       | `ref.current?.tool(name)?.command()`         |
 
-The Engine part still follows the Tiptap major (ADR-0058, item 12.4). The three new parts do not depend on Tiptap: their types and behavior follow the kit's semver.
+The Extensions still follow the Tiptap major (ADR-0058, item 12.4). The three new parts do not depend on Tiptap: their types and behavior follow the kit's semver.
 
 ### `tool()`: a built-in Tool with options
 
-`tool(name, options)` returns a Configured Tool: an opaque entry for `tools` (only the kit reads its fields). `search` has options (the starting flags) and so does `toc` (`offsetVar`, `levels`, `listWidth`); their values and an example are on the [RichTextEditor](../components/inputs/rich-text-editor.md#опции-встроенного-инструмента-tool) page. An entry switches the Tool on even without the name in `tools`, and a name from a Preset gives way to it. Two `tool()` entries with the same name are a set error.
+`tool(name, options)` returns a Configured Tool: an opaque entry for `tools` (only the kit reads its fields). `search` has options (the starting flags), and so do `toc` (`offsetVar`, `levels`, `listWidth`) and `details` (`persist`: whether the open state of a collapsible Block is written into the Document); their values and an example are on the [RichTextEditor](../components/inputs/rich-text-editor.md#опции-встроенного-инструмента-tool) page. An entry switches the Tool on even without the name in `tools`, and a name from a Preset gives way to it. Two `tool()` entries with the same name are a set error.
 
 `tool(definition, options)` configures a `defineTool` definition the same way; the options come from its `defaults`.
 
@@ -138,17 +138,17 @@ The Engine part still follows the Tiptap major (ADR-0058, item 12.4). The three
 `defineTool({ name, defaults, create, state?, commands? })` returns a definition: an element of `tools` that works both without `tool()` (with the defaults from `defaults`) and with it.
 
 - **`defaults`** is the full set of options. The options type is inferred from it, so you do not declare it a second time. A literal widens to its base type (`tone: "info"` becomes `string`): for a union, give the value a type, `tone: "info" as "info" | "warning"`.
-- **`create(options)`** returns the body of the description: the same shape as `CustomTool`, without the name (`CustomToolBody`): the Engine part, Schema rules, UI contributions. It is called once per `tools` entry (the definition itself, or the object that `tool(definition, options)` returned): the kit remembers the result for the pair of the definition and the entry's options object. Anything closed over in the `create` body (a counter, a cache) is therefore shared by every Editor that uses that entry. A `tool(…)` entry created in a component body is new on every render, and the Island in `RichTextView` remounts on every render: take the `tools` set out of the render, into a module constant or `useMemo`. Keep the Engine part Loader a module constant: the Loader's cache lives on the function itself, and a new function on every `create` call would load the part again for every entry.
+- **`create(options)`** returns the body of the description: the same shape as `CustomTool`, without the name (`CustomToolBody`): the Extensions, Schema rules, UI contributions. It is called once per `tools` entry (the definition itself, or the object that `tool(definition, options)` returned): the kit remembers the result for the pair of the definition and the entry's options object. Anything closed over in the `create` body (a counter, a cache) is therefore shared by every Editor that uses that entry. A `tool(…)` entry created in a component body is new on every render, and the Island in `RichTextView` remounts on every render: take the `tools` set out of the render, into a module constant or `useMemo`. Keep the Extensions Loader a module constant: the Loader's cache lives on the function itself, and a new function on every `create` call would load the Extensions again for every entry.
 - **`state({ editor, options })`** is the state for `useRichTextToolState`. It is called on every transaction and on every hook read, so it must be fast and free of side effects, and it must return data without DOM nodes. Primitives, arrays and plain objects are compared by value, so the screen re-renders only when the snapshot has changed. `Date`, `Map`, `Set` and class instances are compared by reference: a `state` that creates them anew on every call re-renders the screen on every transaction. Return plain data (`date.toISOString()`) or the same reference while the data has not changed. With no `state`, the Tool has no state and the hook returns `null`.
 - **`commands({ editor, options })`** returns the commands for `handle.tool(name)`. It is called on every access through the Handle: thin wrappers over the engine, no subscriptions. A command returns a `boolean`, like the built-in ones. With no `commands`, `handle.tool(name)` returns `null`.
 - **Merging options.** Nested plain objects are merged with the defaults, and arrays and functions are replaced whole, like `configure` in Tiptap v3. An `undefined` value is ignored: the existing value stays. The `defaults` object is not changed; the options object is shared by `create`, `state` and `commands`: read it, do not mutate it.
 - **Options are read once**, when the engine is created, together with the set. To change them, remount the Editor with a key (`key`). The kit does not validate the values of a custom Tool's options; that is up to its author.
-- **All the rules of a custom Tool apply** (ADR-0058): the Consumer prefix in the name, a unique name in `tools` (the same definition twice, with `tool()` and without, is also a set error), the set checks, the Engine part Loader. `defineTool` is sugar over the same `CustomTool` shape: it has no build path of its own. A plain `CustomTool` object in `tools` works as before, without options, state and commands.
+- **All the rules of a custom Tool apply** (ADR-0058): the Consumer prefix in the name, a unique name in `tools` (the same definition twice, with `tool()` and without, is also a set error), the set checks, the Extensions Loader. `defineTool` is sugar over the same `CustomTool` shape: it has no build path of its own. A plain `CustomTool` object in `tools` works as before, without options, state and commands.
 - **Server.** `defineTool` and `tool()` live in a module with no Tiptap or React at run time (Tiptap appears there only as types), so the `tools` set can be built in a server module next to the rest of the screen's configuration. A definition holds functions, like `CustomTool`, so it reaches a client component together with its module (an import), not as a prop across the RSC boundary. A configured built-in Tool is made of data: with data in its options, it can be passed as a prop too.
 
 ### The `RichTextTools` map and declaration merging
 
-The types of all three parts are collected in the `RichTextTools` interface, like `Storage` and `Commands` in Tiptap: the key is the Tool's name, the value is `{ options; state; commands }`. The kit declares `search` and `toc` in it, and the consumer adds a custom Tool:
+The types of all three parts are collected in the `RichTextTools` interface, like `Storage` and `Commands` in Tiptap: the key is the Tool's name, the value is `{ options; state; commands }`. The kit declares `search`, `toc` and `details` in it (the last has only `options`), and the consumer adds a custom Tool:
 
 ```ts
 declare module "@olddevs/ui/editor" {
@@ -165,7 +165,7 @@ declare module "@olddevs/ui/editor" {
 - The map gives the snapshot type to `useRichTextToolState`, the commands type to `handle.tool()` and the options to `tool()` for a built-in Tool. For a custom Tool, `tool()` takes the options from the `defaults` of its definition, so the `options` field in the map describes the options for readers of the map (`RichTextTools["acme_note"]["options"]`), and `tool()` does not use it.
 - **Typing is optional.** A Tool not added to the map works: its state and commands have the type `unknown`.
 - The file with `declare module` must be a module (it has an `import` or an `export`); otherwise the declaration does not augment the map but declares a module of its own. Put it next to the Tool's definition.
-- Do not confuse the map with typing the engine. If you already type an Engine part through `declare module "@tiptap/core"` (`Commands`, `Storage`), keep doing so: that is the engine layer and follows its major, while `RichTextTools` is the kit layer.
+- Do not confuse the map with typing the engine. If you already type Extensions through `declare module "@tiptap/core"` (`Commands`, `Storage`), keep doing so: that is the engine layer and follows its major, while `RichTextTools` is the kit layer.
 
 ### An end-to-end example
 
@@ -299,12 +299,12 @@ What to note here. The `tool("toc", …)` entry switches the Table of contents o
 
 ## Loaders, Readiness and Skeleton
 
-The Engine part can be supplied by a Loader — `engine: () => import("./engine.js").then((m) => m.engine)`: the server then imports the module with the description, and Tiptap goes into a separate chunk. Loading starts on the first render in the browser, and the promise is cached on the Loader function (so a Loader is one function per module). **Readiness** is when the engine is created and the Loaders of all enabled Tools — custom and the heavy built-in ones (`codeBlock`, `table`) — have run. Before it, the field is a **Skeleton**: the frame, the place of the Toolbar and the Document cleaned by the Schema, with no input and no height jump; on the server, the frame without the Document. A Loader failure is a field error with "Retry", and the Document stays visible. For details, see ["Engine part Loader"](../components/inputs/rich-text-editor.md#загрузчик-части-для-движка) and ["Skeleton"](../components/inputs/rich-text-editor.md#скелет).
+The Extensions can be supplied by a Loader — `engine: () => import("./engine.js").then((m) => m.engine)`: the server then imports the module with the description, and Tiptap goes into a separate chunk. Loading starts on the first render in the browser, and the promise is cached on the Loader function (so a Loader is one function per module). **Readiness** is when the engine is created and the Loaders of all enabled Tools — custom and the heavy built-in ones (`codeBlock`, `table`) — have run. Before it, the field is a **Skeleton**: the frame, the place of the Toolbar and the Document cleaned by the Schema, with no input and no height jump; on the server, the frame without the Document. A Loader failure is a field error with "Retry", and the Document stays visible. For details, see ["Extensions Loader"](../components/inputs/rich-text-editor.md#загрузчик-extensions) and ["Skeleton"](../components/inputs/rich-text-editor.md#скелет).
 
 ## Server, Markdown, View and Island
 
 - **The server** sanitizes the Document with the same `tools` array: `sanitizeRichText(html, DOMPurify, tools)`, the rules as data — `richTextSchema(tools)`. Both are also in the lightweight `@olddevs/ui/editor/schema` without Tiptap and React — together with `markRange`: the description of a custom Tool with a Text card can be built in a server module too. The names of the kit's Tools in `tools` do not narrow the allowlist: sanitizing accepts everything the kit accepts. Without the third argument sanitizing works as before, and custom Blocks are stripped.
-- **Markdown** — rules in the Engine part (`renderMarkdown`, `markdownTokenizer`, `parseMarkdown`). Without them a Block is exported as its content, an Atom as Atom text, and the text is not lost.
+- **Markdown** — rules in the Extensions (`renderMarkdown`, `markdownTokenizer`, `parseMarkdown`). Without them a Block is exported as its content, an Atom as Atom text, and the text is not lost.
 - **`RichTextView`** shows a custom Block as sanitized HTML with paragraph rhythm; styling is your CSS, keyed on `data-block`. An **Island** is a client component in the Block's `island` field: it comes to life after mounting and only if such a Block is in the Document; for this, `RichTextView` receives the same `tools`.
 
 ## Stability
@@ -316,34 +316,34 @@ The contract boundary per ADR-0058, item 12. The reviewer checks the changeset t
 - the description of a custom Tool (`CustomTool` and its fields, `trigger` included), UI contributions and their Slots, Schema rules (`CustomBlock`, `CustomMark`, `CustomAttribute`), Block traits;
 - the HTML convention (`data-block`, `data-mark`, `data-<prefix>_<name>`);
 - the Handle's methods, `useRichTextEditorState`, the `onReady`, `onFocus`, `onBlur` callbacks, the `status` prop, the `showNotice` command and the `FieldNotice` type;
-- options, state and commands (ADR-0069): the `RichTextTools` map, `tool()`, `defineTool()` and its types (`ToolDefinition`, `ConfiguredTool`), `useRichTextToolState`, `handle.tool()`, and the options, state and command fields of `search` and `toc`;
+- options, state and commands (ADR-0069): the `RichTextTools` map, `tool()`, `defineTool()` and its types (`ToolDefinition`, `ConfiguredTool`), `useRichTextToolState`, `handle.tool()`, and the options, state and command fields of `search` and `toc` and the options of `details`;
 - the third argument of `sanitizeRichText` and `richTextSchema`, the `tools` prop and the Island of `RichTextView`, `markRange`;
 - the names of built-in Tools (`ToolName`) and the existence of the Preset arrays `RICH_TEXT_PRESETS` — but not their composition (below).
 
-**Not included:** the kit's DOM and classes around a Slot; the ids of built-in buttons and items; the internal description of built-in Tools (a superset of the public shape) — it is not exported; the exact place of a UI contribution inside a surface; the look of the Skeleton; the shape of a Configured Tool from the inside (the entry is opaque, only the kit reads its fields); the timing of the scroll after the Find commands (it happens a moment after the call); file and chunk names in `dist`, like any path inside the package (["Public contract"](../conventions.md#публичный-контракт)). The API of the raw `editor` and of the Engine part is Tiptap's API, and it follows the engine's major.
+**Not included:** the kit's DOM and classes around a Slot; the ids of built-in buttons and items; the internal description of built-in Tools (a superset of the public shape) — it is not exported; the exact place of a UI contribution inside a surface; the look of the Skeleton; the shape of a Configured Tool from the inside (the entry is opaque, only the kit reads its fields); the timing of the scroll after the Find commands (it happens a moment after the call); file and chunk names in `dist`, like any path inside the package (["Public contract"](../conventions.md#публичный-контракт)). The API of the raw `editor` and of the Extensions is Tiptap's API, and it follows the engine's major.
 
 **Neither a minor nor a patch breaks a saved Document.** The HTML convention is frozen: `data-block` and `data-mark` are extended only by addition. If the form has to change, that is a major, and until the next major the kit reads both forms — both in engine parsing and in the sanitizer.
 
 **What counts as breaking is a violation of the contract, not a pixel shift:**
 
-| Change                                                                                         | Version                                             |
-| ---------------------------------------------------------------------------------------------- | --------------------------------------------------- |
-| A new required field of the description                                                        | major                                               |
-| A new Block trait or a default that changes the behavior of already described Blocks           | major                                               |
-| Abandoning "one Slot per surface" or "custom UI contributions in the order of `tools`"         | major                                               |
-| Moving a UI contribution kind to another surface                                               | major                                               |
-| Changing the form of the HTML convention                                                       | major, and both forms are read until the next major |
-| A new Tiptap major — even with no changes in the kit's code: the consumer's Engine parts break | major                                               |
-| Removing a Tool from a Preset, renaming a Tool                                                 | major                                               |
-| Removing a public name                                                                         | major, after `@deprecated` in a minor (below)       |
-| A new optional field, a new UI contribution kind, a Handle method or a callback                | minor                                               |
-| A new option or state field, a new command, an option on another built-in Tool                 | minor                                               |
-| Removing an option, state or command field, changing its meaning                               | major                                               |
-| A new built-in Tool in a Preset                                                                | minor, the changeset line is in bold                |
-| A shift of a Slot inside a surface                                                             | minor with a changeset line                         |
-| Raising Tiptap's lower bound within a major                                                    | minor                                               |
-| Tightening sanitizing for security                                                             | patch or minor with a note in migration-notes       |
-| The look of the Skeleton, DOM and classes around a Slot                                        | outside the contract                                |
+| Change                                                                                       | Version                                             |
+| -------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| A new required field of the description                                                      | major                                               |
+| A new Block trait or a default that changes the behavior of already described Blocks         | major                                               |
+| Abandoning "one Slot per surface" or "custom UI contributions in the order of `tools`"       | major                                               |
+| Moving a UI contribution kind to another surface                                             | major                                               |
+| Changing the form of the HTML convention                                                     | major, and both forms are read until the next major |
+| A new Tiptap major — even with no changes in the kit's code: the consumer's Extensions break | major                                               |
+| Removing a Tool from a Preset, renaming a Tool                                               | major                                               |
+| Removing a public name                                                                       | major, after `@deprecated` in a minor (below)       |
+| A new optional field, a new UI contribution kind, a Handle method or a callback              | minor                                               |
+| A new option or state field, a new command, an option on another built-in Tool               | minor                                               |
+| Removing an option, state or command field, changing its meaning                             | major                                               |
+| A new built-in Tool in a Preset                                                              | minor, the changeset line is in bold                |
+| A shift of a Slot inside a surface                                                           | minor with a changeset line                         |
+| Raising Tiptap's lower bound within a major                                                  | minor                                               |
+| Tightening sanitizing for security                                                           | patch or minor with a note in migration-notes       |
+| The look of the Skeleton, DOM and classes around a Slot                                      | outside the contract                                |
 
 - **A Tiptap major is a kit major.** The kit supports one Tiptap major at a time; the engine is not in the kit manifest, and the consumer maintains the version range (`^3.31.4`) given on the [RichTextEditor](../components/inputs/rich-text-editor.md#установка) page.
 - **A Preset** is "what the kit considers a full set", not a frozen list. If you need a stable composition, pass an exact list of names.
@@ -499,7 +499,7 @@ An empty label does not crash the field: in development there is a `console.erro
 
 ### `modulepreload` for lazy chunks
 
-The kit does not publish preloads. The chunks of Engine parts (of custom Loaders and of the built-in `codeBlock` and `table` in `full`) start loading on the Editor's first render, and the Skeleton is shown in the meantime. To have a chunk arrive with the page, add a `<link rel="modulepreload">` for it (in React 19, `preloadModule(url)` from `react-dom`); take the hashed URL from your bundler's manifest: the kit's chunk names are not part of the contract. For an example, see [RichTextEditor, "Engine part Loader"](../components/inputs/rich-text-editor.md#загрузчик-части-для-движка); the cost of the "start" and "full" scenarios is in ["Import size"](../getting-started.md#размер-импорта).
+The kit does not publish preloads. The chunks of Extensions (of custom Loaders and of the built-in `codeBlock` and `table` in `full`) start loading on the Editor's first render, and the Skeleton is shown in the meantime. To have a chunk arrive with the page, add a `<link rel="modulepreload">` for it (in React 19, `preloadModule(url)` from `react-dom`); take the hashed URL from your bundler's manifest: the kit's chunk names are not part of the contract. For an example, see [RichTextEditor, "Extensions Loader"](../components/inputs/rich-text-editor.md#загрузчик-extensions); the cost of the "start" and "full" scenarios is in ["Import size"](../getting-started.md#размер-импорта).
 
 ## Links