@olddevs/ui 4.5.1 → 4.6.1

package/docs/api/editor-extension.md

@@ -8,7 +8,7 @@ source: src/editor/index.ts
 
 ## Кратко для AI
 
-Карта того, чем продукт расширяет `RichTextEditor` из `@olddevs/ui/editor`, и граница стабильности этого API. Единица расширения — **свой Инструмент** (`CustomTool`): описание одной возможности Редактора, которое передаётся в `tools` вперемешку с именами кита. Он несёт Блоки и Метки с правилами Схемы (это данные), Часть для движка (расширения Tiptap, сразу или Загрузчиком) и UI-записи: кнопки, Пункты вставки, Действия над Блоком, Карточки у текста. Есть и свой Символ-триггер (`trigger`): `@` для упоминаний открывает тот же список, что `/`. Код экрана управляет полем через Хэндл (`ref`) и хук `useRichTextEditorState`, узнаёт о Готовности и Фокусе поля колбэками `onReady`, `onFocus` и `onBlur`, кладёт своё в Строку статуса (`status`) и сообщает об ошибке командой `showNotice`. У Инструмента три типизированные части, как `options`, `storage` и `commands` у расширения Tiptap: **Опции** (`tool(name, options)` у встроенных `search` и `toc`, `defineTool` у своего), **Состояние** (хук `useRichTextToolState`) и **Команды** (`handle.tool(name)`); их типы собраны в расширяемой карте `RichTextTools`, куда свой Инструмент дописывается через `declare module "@olddevs/ui/editor"`. Тот же массив `tools` понимают серверная очистка (`sanitizeRichText`, `richTextSchema`) и `RichTextView` с Островами. Всё перечисленное подчиняется semver кита с первого выпуска, HTML-соглашение заморожено, мажор Tiptap — мажор кита (раздел «Стабильность»). Подробности каждого пункта живут на странице [RichTextEditor](../components/inputs/rich-text-editor.md); здесь — карта, граница контракта и рецепты.
+Карта того, чем продукт расширяет `RichTextEditor` из `@olddevs/ui/editor`, и граница стабильности этого API. Единица расширения — **свой Инструмент** (`CustomTool`): описание одной возможности Редактора, которое передаётся в `tools` вперемешку с именами кита. Он несёт Блоки и Метки с правилами Схемы (это данные), Extensions (расширения Tiptap, сразу или Загрузчиком) и UI-записи: кнопки, Пункты вставки, Действия над Блоком, Карточки у текста. Есть и свой Символ-триггер (`trigger`): `@` для упоминаний открывает тот же список, что `/`. Код экрана управляет полем через Хэндл (`ref`) и хук `useRichTextEditorState`, узнаёт о Готовности и Фокусе поля колбэками `onReady`, `onFocus` и `onBlur`, кладёт своё в Строку статуса (`status`) и сообщает об ошибке командой `showNotice`. У Инструмента три типизированные части, как `options`, `storage` и `commands` у расширения Tiptap: **Опции** (`tool(name, options)` у встроенных `search` и `toc`, `defineTool` у своего), **Состояние** (хук `useRichTextToolState`) и **Команды** (`handle.tool(name)`); их типы собраны в расширяемой карте `RichTextTools`, куда свой Инструмент дописывается через `declare module "@olddevs/ui/editor"`. Тот же массив `tools` понимают серверная очистка (`sanitizeRichText`, `richTextSchema`) и `RichTextView` с Островами. Всё перечисленное подчиняется semver кита с первого выпуска, HTML-соглашение заморожено, мажор Tiptap — мажор кита (раздел «Стабильность»). Подробности каждого пункта живут на странице [RichTextEditor](../components/inputs/rich-text-editor.md); здесь — карта, граница контракта и рецепты.
 
 ```tsx
 import {
@@ -39,39 +39,39 @@ import { sanitizeRichText } from "@olddevs/ui/editor/schema";
 
 - Нужное уже есть среди Инструментов кита ([«Инструменты и Пресеты»](../components/inputs/rich-text-editor.md#инструменты-и-пресеты)): передайте имя в `tools`, своё не пишите.
 - Чтобы спрятать встроенную кнопку или пункт, сузьте `tools`. Подменить встроенный Инструмент по имени нельзя: выключите его и поставьте свой под своим именем.
-- Опции есть только у `search` и `toc`; `tool("bold", …)` не компилируется. Опции остальных встроенных добавляются по одному, когда о них попросят. Поменять поведение встроенного Инструмента подменой нельзя (`extend()` как у Tiptap нет): описания встроенных наружу не выходят.
+- Опции есть только у `search`, `toc` и `details`; `tool("bold", …)` не компилируется. Опции остальных встроенных добавляются по одному, когда о них попросят. Поменять поведение встроенного Инструмента подменой нельзя (`extend()` как у Tiptap нет): описания встроенных наружу не выходят.
 - Сменить Опции у смонтированного поля нельзя: они читаются один раз, при создании движка, вместе с `tools`. Перемонтируйте поле ключом.
 - Произвольный React в строке Панели и в меню нельзя: кит рисует записи сам, React допускается только в содержимом поповера (кнопки, Пункта вставки, Действия над Блоком) и в Карточке у текста.
-- Во вставку и drop пропом вмешаться нельзя: это делает Часть для движка своего Инструмента ([«Порядок вставки и drop»](../components/inputs/rich-text-editor.md#порядок-вставки-и-drop)).
+- Во вставку и drop пропом вмешаться нельзя: это делают Extensions своего Инструмента ([«Порядок вставки и drop»](../components/inputs/rich-text-editor.md#порядок-вставки-и-drop)).
 - Чего нет, пока потребители об этом не попросили (ADR-0058, раздел 13): `insertImage` и HTML выделения в Хэндле, `onSelectionChange`, `onPaste`, `onDrop`, `onEmpty`, `onDestroy`, события истории, сигнал об удалённых картинках, запертые Блоки шаблона, вид записи «меню», Карточки и Строка статуса в `RichTextView`. До тех пор у экрана есть `ref.current.editor` и его события.
 - Свои символы-триггеры вроде `@` в этот перечень больше не входят: они поддержаны полем `trigger` Инструмента (ADR-0064, раздел «Символ-триггер» ниже).
 
 ## Карта API
 
-| Что                                              | Где в API                                                                                                        | Подробно                                                                                                                                                                                                                            |
-| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Свой Инструмент                                  | `CustomTool` в `tools`; Пресеты — `RICH_TEXT_PRESETS`                                                            | [«Свой Инструмент»](../components/inputs/rich-text-editor.md#свой-инструмент)                                                                                                                                                       |
-| Правила Схемы и HTML-соглашение                  | `blocks` (`CustomBlock`), `marks` (`CustomMark`), `CustomAttribute`, `PrefixedName`                              | [«Свой Инструмент»](../components/inputs/rich-text-editor.md#свой-инструмент)                                                                                                                                                       |
-| Кнопка                                           | `buttons` (`CustomToolButton`, `CustomToolPopover`, `CustomToolLabel`)                                           | [«Кнопка своего Инструмента»](../components/inputs/rich-text-editor.md#кнопка-своего-инструмента)                                                                                                                                   |
-| Пункт вставки, Действие над Блоком               | `insertItems` (`CustomInsertItem`), `blockActions` (`CustomBlockAction`)                                         | [«Пункты вставки и Действия над Блоком»](../components/inputs/rich-text-editor.md#пункты-вставки-и-действия-над-блоком)                                                                                                             |
-| Символ-триггер                                   | `trigger` (`CustomTrigger`, `TriggerItem`, `TriggerContext`)                                                     | [«Свой символ-триггер»](../components/inputs/rich-text-editor.md#свой-символ-триггер)                                                                                                                                               |
-| Карточка у текста                                | `textCards` (`CustomTextCard`), помощник `markRange`                                                             | [«Карточка у текста»](../components/inputs/rich-text-editor.md#карточка-у-текста)                                                                                                                                                   |
-| Хэндл и своя панель                              | `RichTextEditorHandle`, `useRichTextEditorState(ref, selector)`                                                  | [«Хэндл (`ref`) и своя панель вне поля»](../components/inputs/rich-text-editor.md#хэндл-ref-и-своя-панель-вне-поля)                                                                                                                 |
-| Опции встроенного Инструмента                    | `tool(name, options)` → `ConfiguredTool` для `search` и `toc`; `SearchToolOptions`, `TocToolOptions`, `TocLevel` | [«Опции встроенного Инструмента: `tool()`»](../components/inputs/rich-text-editor.md#опции-встроенного-инструмента-tool)                                                                                                            |
-| Свой Инструмент с Опциями, Состоянием, Командами | `defineTool({ name, defaults, create, state, commands })` → `ToolDefinition`, `tool(definition, options)`        | [«Опции, Состояние и Команды»](editor-extension.md#опции-состояние-и-команды)                                                                                                                                                       |
-| Типы Опций, Состояния и Команд                   | расширяемый интерфейс `RichTextTools`                                                                            | [«Карта `RichTextTools` и declaration merging»](editor-extension.md#карта-richtexttools-и-declaration-merging)                                                                                                                      |
-| Состояние Инструмента                            | `useRichTextToolState(ref, name, selector?)`, `SearchToolState`, `TocToolState`, `TocToolHeading`                | [«Состояние Инструмента: `useRichTextToolState`»](../components/inputs/rich-text-editor.md#состояние-инструмента-userichtexttoolstate)                                                                                              |
-| Команды Инструмента                              | `handle.tool(name)`, `SearchToolCommands`, `TocToolCommands`                                                     | [«Команды Инструмента: `handle.tool()`»](../components/inputs/rich-text-editor.md#команды-инструмента-handletool)                                                                                                                   |
-| События                                          | `onReady`, `onFocus`, `onBlur`; вставка и drop — Частью для движка                                               | [«События»](../components/inputs/rich-text-editor.md#события)                                                                                                                                                                       |
-| Строка статуса и Сообщение поля                  | проп `status`; команда движка `showNotice`, тип `FieldNotice`                                                    | [«Строка статуса и Сообщение поля»](../components/inputs/rich-text-editor.md#строка-статуса-и-сообщение-поля)                                                                                                                       |
-| Загрузчик, Готовность и Скелет                   | `engine: () => import(…)`                                                                                        | [«Загрузчик Части для движка»](../components/inputs/rich-text-editor.md#загрузчик-части-для-движка), [«Скелет»](../components/inputs/rich-text-editor.md#скелет)                                                                    |
-| Текст атома: `getText`, `maxLength`, пустота     | `renderText` Части для движка                                                                                    | [«Текст атома»](../components/inputs/rich-text-editor.md#текст-атома)                                                                                                                                                               |
-| Сервер, Markdown, Просмотр                       | `sanitizeRichText(html, DOMPurify, tools)`, `richTextSchema(tools)`, `RichTextView`                              | [«Вне Редактора»](../components/inputs/rich-text-editor.md#вне-редактора-сервер-markdown-и-просмотр), [RichTextView, «Свои Инструменты: третий аргумент»](../components/content/rich-text-view.md#свои-инструменты-третий-аргумент) |
-| Остров своего Блока                              | `CustomBlock.island`, `CustomIslandProps`, проп `tools` у `RichTextView`                                         | [RichTextView, «Остров своего Блока»](../components/content/rich-text-view.md#остров-своего-блока)                                                                                                                                  |
+| Что                                              | Где в API                                                                                                                                         | Подробно                                                                                                                                                                                                                            |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Свой Инструмент                                  | `CustomTool` в `tools`; Пресеты — `RICH_TEXT_PRESETS`                                                                                             | [«Свой Инструмент»](../components/inputs/rich-text-editor.md#свой-инструмент)                                                                                                                                                       |
+| Правила Схемы и HTML-соглашение                  | `blocks` (`CustomBlock`), `marks` (`CustomMark`), `CustomAttribute`, `PrefixedName`                                                               | [«Свой Инструмент»](../components/inputs/rich-text-editor.md#свой-инструмент)                                                                                                                                                       |
+| Кнопка                                           | `buttons` (`CustomToolButton`, `CustomToolPopover`, `CustomToolLabel`)                                                                            | [«Кнопка своего Инструмента»](../components/inputs/rich-text-editor.md#кнопка-своего-инструмента)                                                                                                                                   |
+| Пункт вставки, Действие над Блоком               | `insertItems` (`CustomInsertItem`), `blockActions` (`CustomBlockAction`)                                                                          | [«Пункты вставки и Действия над Блоком»](../components/inputs/rich-text-editor.md#пункты-вставки-и-действия-над-блоком)                                                                                                             |
+| Символ-триггер                                   | `trigger` (`CustomTrigger`, `TriggerItem`, `TriggerContext`)                                                                                      | [«Свой символ-триггер»](../components/inputs/rich-text-editor.md#свой-символ-триггер)                                                                                                                                               |
+| Карточка у текста                                | `textCards` (`CustomTextCard`), помощник `markRange`                                                                                              | [«Карточка у текста»](../components/inputs/rich-text-editor.md#карточка-у-текста)                                                                                                                                                   |
+| Хэндл и своя панель                              | `RichTextEditorHandle`, `useRichTextEditorState(ref, selector)`                                                                                   | [«Хэндл (`ref`) и своя панель вне поля»](../components/inputs/rich-text-editor.md#хэндл-ref-и-своя-панель-вне-поля)                                                                                                                 |
+| Опции встроенного Инструмента                    | `tool(name, options)` → `ConfiguredTool` для `search`, `toc` и `details`; `SearchToolOptions`, `TocToolOptions`, `TocLevel`, `DetailsToolOptions` | [«Опции встроенного Инструмента: `tool()`»](../components/inputs/rich-text-editor.md#опции-встроенного-инструмента-tool)                                                                                                            |
+| Свой Инструмент с Опциями, Состоянием, Командами | `defineTool({ name, defaults, create, state, commands })` → `ToolDefinition`, `tool(definition, options)`                                         | [«Опции, Состояние и Команды»](editor-extension.md#опции-состояние-и-команды)                                                                                                                                                       |
+| Типы Опций, Состояния и Команд                   | расширяемый интерфейс `RichTextTools`                                                                                                             | [«Карта `RichTextTools` и declaration merging»](editor-extension.md#карта-richtexttools-и-declaration-merging)                                                                                                                      |
+| Состояние Инструмента                            | `useRichTextToolState(ref, name, selector?)`, `SearchToolState`, `TocToolState`, `TocToolHeading`                                                 | [«Состояние Инструмента: `useRichTextToolState`»](../components/inputs/rich-text-editor.md#состояние-инструмента-userichtexttoolstate)                                                                                              |
+| Команды Инструмента                              | `handle.tool(name)`, `SearchToolCommands`, `TocToolCommands`                                                                                      | [«Команды Инструмента: `handle.tool()`»](../components/inputs/rich-text-editor.md#команды-инструмента-handletool)                                                                                                                   |
+| События                                          | `onReady`, `onFocus`, `onBlur`; вставка и drop — через Extensions                                                                                 | [«События»](../components/inputs/rich-text-editor.md#события)                                                                                                                                                                       |
+| Строка статуса и Сообщение поля                  | проп `status`; команда движка `showNotice`, тип `FieldNotice`                                                                                     | [«Строка статуса и Сообщение поля»](../components/inputs/rich-text-editor.md#строка-статуса-и-сообщение-поля)                                                                                                                       |
+| Загрузчик, Готовность и Скелет                   | `engine: () => import(…)`                                                                                                                         | [«Загрузчик Extensions»](../components/inputs/rich-text-editor.md#загрузчик-extensions), [«Скелет»](../components/inputs/rich-text-editor.md#скелет)                                                                                |
+| Текст атома: `getText`, `maxLength`, пустота     | `renderText` из Extensions                                                                                                                        | [«Текст атома»](../components/inputs/rich-text-editor.md#текст-атома)                                                                                                                                                               |
+| Сервер, Markdown, Просмотр                       | `sanitizeRichText(html, DOMPurify, tools)`, `richTextSchema(tools)`, `RichTextView`                                                               | [«Вне Редактора»](../components/inputs/rich-text-editor.md#вне-редактора-сервер-markdown-и-просмотр), [RichTextView, «Свои Инструменты: третий аргумент»](../components/content/rich-text-view.md#свои-инструменты-третий-аргумент) |
+| Остров своего Блока                              | `CustomBlock.island`, `CustomIslandProps`, проп `tools` у `RichTextView`                                                                          | [RichTextView, «Остров своего Блока»](../components/content/rich-text-view.md#остров-своего-блока)                                                                                                                                  |
 
 ## Свой Инструмент и HTML-соглашение
 
-Описание одно, внутри две части. **Правила Схемы** — обычные данные без Tiptap: их читают Редактор, серверная очистка и Просмотр. **Часть для движка** — расширения Tiptap целиком (Node, Mark, Extension, плагины ProseMirror, React-вид узла): только поведение, а разбор и вывод HTML ставит кит. Обязательны имя, Часть для движка и правило Схемы для каждого её Node и Mark; остальное — по умолчанию: обычный Блок без Признаков, выгрузка в Markdown его содержимым, ритм абзаца в Просмотре, без UI-записей. Инструмент может не нести Блока вовсе — например, только фильтр вставки.
+Описание одно, внутри две части. **Правила Схемы** — обычные данные без Tiptap: их читают Редактор, серверная очистка и Просмотр. **Extensions** — расширения Tiptap целиком (Node, Mark, Extension, плагины ProseMirror, React-вид узла): только поведение, а разбор и вывод HTML ставит кит. Обязательны имя, Extensions и правило Схемы для каждого их Node и Mark; остальное — по умолчанию: обычный Блок без Признаков, выгрузка в Markdown его содержимым, ритм абзаца в Просмотре, без UI-записей. Инструмент может не нести Блока вовсе — например, только фильтр вставки.
 
 Всё своё называется с Префиксом потребителя через подчёркивание: Инструмент `acme_mergeTag`, атрибут `acme_size`. В именах кита подчёркивания нет, поэтому своё и встроенное не пересекаются ни в массиве `tools`, ни в сохранённом Документе. HTML своего пишет и читает кит:
 
@@ -82,7 +82,7 @@ import { sanitizeRichText } from "@olddevs/ui/editor/schema";
 | Метка         | `<span data-mark="acme_comment">…</span>`                          |
 | Атрибут       | `data-acme_size="m"` — значение по правилу: список, шаблон или URL |
 
-Массив `tools` проверяется один раз, при создании движка (с Загрузчиками — когда они отработали). Имя без префикса, совпадение имён, Node или Mark в Части для движка без правила Схемы (и наоборот), запись без обязательного поля дают ошибку поля «Редактор не запустился», а не тихая потеря Блоков при первом сохранении. Неизвестная **строка** в `tools` по-прежнему отбрасывается молча.
+Массив `tools` проверяется один раз, при создании движка (с Загрузчиками — когда они отработали). Имя без префикса, совпадение имён, Node или Mark в Extensions без правила Схемы (и наоборот), запись без обязательного поля дают ошибку поля «Редактор не запустился», а не тихая потеря Блоков при первом сохранении. Неизвестная **строка** в `tools` по-прежнему отбрасывается молча.
 
 ## UI-записи
 
@@ -98,7 +98,7 @@ import { sanitizeRichText } from "@olddevs/ui/editor/schema";
 - **Подпись** — строка или функция, получающая `{ locale }` (локаль `UiProvider`); каталог сообщений `UiProvider` для сторонних Инструментов не расширяется, переопределение — опциями фабрики Инструмента (рецепт ниже).
 - **Иконка** обязательна у кнопки, пункта и Действия: компонент с контрактом `IconProps` из `@olddevs/ui/icons` или свой.
 - **Поповер** — у кнопки, Пункта вставки и Действия над Блоком ровно одно из `run` и `popover`. Содержимое — функция, получающая `{ editor, close }` (у Действия — ещё `pos` Блока), рамку держит кит: слой оверлея, Стекло всплывающих поверхностей Редактора, стек Escape, имя (подпись записи), возврат фокуса и выделения в Документ. Карточка у текста лежит на том же Стекле, поэтому сплошной фон содержимому не нужен: он закроет подложку. При включённой в системе настройке прозрачности или контраста подложка и так станет сплошной. Поповер встаёт у кнопки (щелчок), у каретки (сочетание кнопки, пункт из «/», «+», «Добавить ›», «Формат ›» и его сочетание) или у Блока (Действие из меню Ручки и его сочетание).
-- **Сочетание** (`shortcut`) — единственный источник: кит вешает клавишу и пишет её в подсказку, `aria-keyshortcuts` и Справочник сочетаний. Клавиши Части для движка в справочник не попадают.
+- **Сочетание** (`shortcut`) — единственный источник: кит вешает клавишу и пишет её в подсказку, `aria-keyshortcuts` и Справочник сочетаний. Клавиши, которые вешают Extensions, в справочник не попадают.
 - **Выключенный Инструмент** уносит свои записи отовсюду.
 
 ## Символ-триггер
@@ -124,11 +124,11 @@ import { sanitizeRichText } from "@olddevs/ui/editor/schema";
 | Состояние | Снимок, который экран читает        | Кит у встроенных; поле `state` у `defineTool`                                         | `useRichTextToolState(ref, name, selector?)` |
 | Команды   | То, что экран вызывает              | Кит у встроенных; поле `commands` у `defineTool`                                      | `ref.current?.tool(name)?.команда()`         |
 
-Часть для движка по-прежнему следует мажору Tiptap (ADR-0058, п. 12.4). Три новые части от Tiptap не зависят: их типы и поведение подчиняются semver кита.
+Extensions по-прежнему следуют мажору Tiptap (ADR-0058, п. 12.4). Три новые части от Tiptap не зависят: их типы и поведение подчиняются semver кита.
 
 ### `tool()`: встроенный Инструмент с Опциями
 
-`tool(name, options)` возвращает Настроенный Инструмент — непрозрачную запись для `tools` (её поля читает только кит). Опции есть у `search` (стартовые флажки) и `toc` (`offsetVar`, `levels`, `listWidth`); их значения и пример — на странице [RichTextEditor](../components/inputs/rich-text-editor.md#опции-встроенного-инструмента-tool). Запись включает Инструмент и без имени в `tools`, а имя из Пресета ей уступает. Две записи `tool()` с одним именем — ошибка набора.
+`tool(name, options)` возвращает Настроенный Инструмент — непрозрачную запись для `tools` (её поля читает только кит). Опции есть у `search` (стартовые флажки), `toc` (`offsetVar`, `levels`, `listWidth`) и `details` (`persist`: пишется ли открытость сворачиваемого Блока в Документ); их значения и пример — на странице [RichTextEditor](../components/inputs/rich-text-editor.md#опции-встроенного-инструмента-tool). Запись включает Инструмент и без имени в `tools`, а имя из Пресета ей уступает. Две записи `tool()` с одним именем — ошибка набора.
 
 `tool(definition, options)` настраивает тем же способом определение `defineTool`; Опции берутся из его `defaults`.
 
@@ -137,17 +137,17 @@ import { sanitizeRichText } from "@olddevs/ui/editor/schema";
 `defineTool({ name, defaults, create, state?, commands? })` возвращает определение — элемент `tools`, который работает и без `tool()` (с умолчаниями из `defaults`), и с ним.
 
 - **`defaults`** — полный набор Опций. Тип Опций выводится из него, второй раз его объявлять не нужно. Литерал расширяется до своего типа (`tone: "info"` станет `string`): нужен union-тип — укажите тип значения, `tone: "info" as "info" | "warning"`.
-- **`create(options)`** отдаёт тело описания — ту же форму, что `CustomTool`, без имени (`CustomToolBody`): Часть для движка, правила Схемы, UI-записи. Зовётся один раз на запись `tools` (определение само или объект, который вернул `tool(definition, options)`): кит запоминает результат по паре «определение и объект Опций записи». Всё, что замкнуто в теле `create` (счётчик, кэш), поэтому общее у всех Редакторов с этой записью. Запись `tool(…)`, созданная в теле компонента, на каждом рендере новая, и Остров в `RichTextView` на каждом рендере перемонтируется: выносите набор `tools` из рендера, в константу модуля или в `useMemo`. Загрузчик Части для движка держите константой модуля: кэш загрузчика живёт на самой функции, и новая функция на каждый вызов `create` загружала бы Часть заново для каждой записи.
+- **`create(options)`** отдаёт тело описания — ту же форму, что `CustomTool`, без имени (`CustomToolBody`): Extensions, правила Схемы, UI-записи. Зовётся один раз на запись `tools` (определение само или объект, который вернул `tool(definition, options)`): кит запоминает результат по паре «определение и объект Опций записи». Всё, что замкнуто в теле `create` (счётчик, кэш), поэтому общее у всех Редакторов с этой записью. Запись `tool(…)`, созданная в теле компонента, на каждом рендере новая, и Остров в `RichTextView` на каждом рендере перемонтируется: выносите набор `tools` из рендера, в константу модуля или в `useMemo`. Загрузчик Extensions держите константой модуля: кэш загрузчика живёт на самой функции, и новая функция на каждый вызов `create` загружала бы Extensions заново для каждой записи.
 - **`state({ editor, options })`** — Состояние для `useRichTextToolState`. Её зовут при каждой транзакции и при каждом чтении хука, поэтому она должна быть быстрой и без побочных эффектов, а результат — данные без DOM-узлов. Примитивы, массивы и простые объекты сравниваются по значению, поэтому экран перерисовывается, только когда снимок изменился. `Date`, `Map`, `Set` и экземпляры классов сравниваются по ссылке: `state`, который создаёт их заново на каждый вызов, перерисует экран на каждой транзакции. Отдавайте простые данные (`date.toISOString()`) или ту же ссылку, пока данные не изменились. Нет `state` — у Инструмента нет Состояния, и хук отдаёт `null`.
 - **`commands({ editor, options })`** — Команды для `handle.tool(name)`. Их зовут при каждом обращении к Хэндлу: только обёртки над движком, без подписок. Команда возвращает `boolean`, как у встроенных. Нет `commands` — `handle.tool(name)` отдаёт `null`.
 - **Слияние Опций.** Вложенные простые объекты сливаются с умолчаниями, массивы и функции заменяются целиком — как `configure` у Tiptap v3. Значение `undefined` не в счёт: остаётся то, что было. Объект `defaults` не меняется, объект Опций общий для `create`, `state` и `commands`: читайте его, но не меняйте.
 - **Опции читаются один раз**, при создании движка, вместе с набором. Чтобы сменить их, перемонтируйте Редактор ключом (`key`). Значения Опций своего Инструмента проверяет его автор: кит этого не делает.
-- **Все правила своего Инструмента действуют** (ADR-0058): Префикс потребителя в имени, уникальность имени в `tools` (определение дважды, с `tool()` и без, — тоже ошибка набора), проверки набора, Загрузчик Части для движка. `defineTool` — сахар над той же формой `CustomTool`: отдельного пути сборки у него нет. Обычный объект `CustomTool` в `tools` работает как раньше, без Опций, Состояния и Команд.
+- **Все правила своего Инструмента действуют** (ADR-0058): Префикс потребителя в имени, уникальность имени в `tools` (определение дважды, с `tool()` и без, — тоже ошибка набора), проверки набора, Загрузчик Extensions. `defineTool` — сахар над той же формой `CustomTool`: отдельного пути сборки у него нет. Обычный объект `CustomTool` в `tools` работает как раньше, без Опций, Состояния и Команд.
 - **Сервер.** `defineTool` и `tool()` живут в модуле без Tiptap и React в рантайме (Tiptap там — только типы), поэтому набор `tools` собирается в серверном модуле, рядом с остальной конфигурацией экрана. Определение содержит функции, как и `CustomTool`, поэтому клиентскому компоненту оно отдаётся вместе с модулем (импортом), а не пропом через границу RSC. Настроенный встроенный Инструмент состоит из данных: при данных в опциях его можно передать и пропом.
 
 ### Карта `RichTextTools` и declaration merging
 
-Типы всех трёх частей собраны в интерфейсе `RichTextTools`, как `Storage` и `Commands` у Tiptap: ключ — имя Инструмента, значение — `{ options; state; commands }`. Кит объявляет в нём `search` и `toc`, свой Инструмент потребитель дописывает сам:
+Типы всех трёх частей собраны в интерфейсе `RichTextTools`, как `Storage` и `Commands` у Tiptap: ключ — имя Инструмента, значение — `{ options; state; commands }`. Кит объявляет в нём `search`, `toc` и `details` (у последнего только `options`), свой Инструмент потребитель дописывает сам:
 
 ```ts
 declare module "@olddevs/ui/editor" {
@@ -164,7 +164,7 @@ declare module "@olddevs/ui/editor" {
 - Из карты выводятся тип снимка в `useRichTextToolState`, тип Команд в `handle.tool()` и Опции `tool()` встроенного. Опции своего Инструмента `tool()` берёт из `defaults` его определения, поэтому поле `options` в карте описывает Опции для читателей карты (`RichTextTools["acme_note"]["options"]`), а `tool()` его не использует.
 - **Типизация добровольна.** Инструмент, не дописанный в карту, работает: его Состояние и Команды имеют тип `unknown`.
 - Файл с `declare module` должен быть модулем (в нём есть `import` или `export`); иначе объявление не дополняет карту, а заводит свой модуль. Положите его рядом с определением Инструмента.
-- Карту не стоит путать с типизацией движка. Кто типизирует Часть для движка через `declare module "@tiptap/core"` (`Commands`, `Storage`), продолжает так делать: это слой движка и его мажор, а `RichTextTools` — слой кита.
+- Карту не стоит путать с типизацией движка. Кто типизирует Extensions через `declare module "@tiptap/core"` (`Commands`, `Storage`), продолжает так делать: это слой движка и его мажор, а `RichTextTools` — слой кита.
 
 ### Сквозной пример
 
@@ -300,12 +300,12 @@ export function ArticleBody({ html }: { html: string }) {
 
 ## Загрузчики, Готовность и Скелет
 
-Часть для движка можно отдать Загрузчиком — `engine: () => import("./engine.js").then((m) => m.engine)`: модуль с описанием тогда импортирует и сервер, а Tiptap уходит в отдельный чанк. Загрузка стартует с первого рендера в браузере, промис кэшируется на функции Загрузчика (поэтому Загрузчик — одна функция на модуль). **Готовность** — движок создан и Загрузчики всех включённых Инструментов, своих и тяжёлых встроенных (`codeBlock`, `table`), отработали. До неё поле — **Скелет**: рамка, место Панели и Документ, очищенный Схемой, без ввода и без прыжка высоты; на сервере — рамка без Документа. Сбой Загрузчика — ошибка поля с «Повторить», Документ остаётся виден. Подробно — [«Загрузчик Части для движка»](../components/inputs/rich-text-editor.md#загрузчик-части-для-движка) и [«Скелет»](../components/inputs/rich-text-editor.md#скелет).
+Extensions можно отдать Загрузчиком — `engine: () => import("./engine.js").then((m) => m.engine)`: модуль с описанием тогда импортирует и сервер, а Tiptap уходит в отдельный чанк. Загрузка стартует с первого рендера в браузере, промис кэшируется на функции Загрузчика (поэтому Загрузчик — одна функция на модуль). **Готовность** — движок создан и Загрузчики всех включённых Инструментов, своих и тяжёлых встроенных (`codeBlock`, `table`), отработали. До неё поле — **Скелет**: рамка, место Панели и Документ, очищенный Схемой, без ввода и без прыжка высоты; на сервере — рамка без Документа. Сбой Загрузчика — ошибка поля с «Повторить», Документ остаётся виден. Подробно — [«Загрузчик Extensions»](../components/inputs/rich-text-editor.md#загрузчик-extensions) и [«Скелет»](../components/inputs/rich-text-editor.md#скелет).
 
 ## Сервер, Markdown, Просмотр и Остров
 
 - **Сервер** чистит Документ тем же массивом `tools`: `sanitizeRichText(html, DOMPurify, tools)`, правила данными — `richTextSchema(tools)`. Оба есть и в лёгком `@olddevs/ui/editor/schema` без Tiptap и React — вместе с `markRange`: описание своего Инструмента с Карточкой у текста собирается и в модуле сервера. Имена Инструментов кита в `tools` белый список не сужают: очистка пропускает всё, что пропускает кит. Без третьего аргумента очистка прежняя, и свои Блоки срезаются.
-- **Markdown** — правила в Части для движка (`renderMarkdown`, `markdownTokenizer`, `parseMarkdown`). Без них Блок выгружается содержимым, Атом — Текстом атома, и текст не теряется.
+- **Markdown** — правила в Extensions (`renderMarkdown`, `markdownTokenizer`, `parseMarkdown`). Без них Блок выгружается содержимым, Атом — Текстом атома, и текст не теряется.
 - **`RichTextView`** показывает свой Блок очищенным HTML с ритмом абзаца; вид — ваш CSS по `data-block`. **Остров** — клиентский компонент в поле `island` Блока: оживает после монтирования и только если такой Блок есть в Документе; `RichTextView` для этого получает тот же `tools`.
 
 ## Стабильность
@@ -317,34 +317,34 @@ export function ArticleBody({ html }: { html: string }) {
 - описание своего Инструмента (`CustomTool` и его поля, в том числе `trigger`), UI-записи и их Отведённые места, правила Схемы (`CustomBlock`, `CustomMark`, `CustomAttribute`), Признаки Блока;
 - HTML-соглашение (`data-block`, `data-mark`, `data-<префикс>_<имя>`);
 - методы Хэндла, `useRichTextEditorState`, колбэки `onReady`, `onFocus`, `onBlur`, проп `status`, команда `showNotice` и тип `FieldNotice`;
-- Опции, Состояние и Команды (ADR-0069): карта `RichTextTools`, `tool()`, `defineTool()` и его типы (`ToolDefinition`, `ConfiguredTool`), `useRichTextToolState`, `handle.tool()`, а также поля Опций, Состояния и Команд `search` и `toc`;
+- Опции, Состояние и Команды (ADR-0069): карта `RichTextTools`, `tool()`, `defineTool()` и его типы (`ToolDefinition`, `ConfiguredTool`), `useRichTextToolState`, `handle.tool()`, а также поля Опций, Состояния и Команд `search` и `toc` и Опции `details`;
 - третий аргумент `sanitizeRichText` и `richTextSchema`, проп `tools` и Остров у `RichTextView`, `markRange`;
 - имена встроенных Инструментов (`ToolName`) и сам факт Пресетов-массивов `RICH_TEXT_PRESETS` — но не их состав (ниже).
 
-**Не входят:** DOM и классы кита вокруг Отведённого места; id встроенных кнопок и пунктов; внутреннее описание встроенных Инструментов (надмножество публичной формы) — наружу оно не экспортируется; точное место записи внутри поверхности; вид Скелета; форма Настроенного Инструмента изнутри (запись непрозрачна, её поля читает кит); момент прокрутки после Команд Поиска (она происходит чуть позже вызова); имена файлов и чанков в `dist`, как любой путь внутри пакета ([«Публичный контракт»](../conventions.md#публичный-контракт)). API сырого `editor` и Части для движка — это API Tiptap, он следует мажору движка.
+**Не входят:** DOM и классы кита вокруг Отведённого места; id встроенных кнопок и пунктов; внутреннее описание встроенных Инструментов (надмножество публичной формы) — наружу оно не экспортируется; точное место записи внутри поверхности; вид Скелета; форма Настроенного Инструмента изнутри (запись непрозрачна, её поля читает кит); момент прокрутки после Команд Поиска (она происходит чуть позже вызова); имена файлов и чанков в `dist`, как любой путь внутри пакета ([«Публичный контракт»](../conventions.md#публичный-контракт)). API сырого `editor` и Extensions — это API Tiptap, он следует мажору движка.
 
 **Сохранённый Документ не ломают ни minor, ни patch.** HTML-соглашение заморожено: `data-block` и `data-mark` расширяются только добавлением. Если форму придётся сменить, это мажор, и до следующего мажора кит читает обе формы — и разбором движка, и санитайзером.
 
 **Ломающим считается нарушение контракта, а не сдвиг пикселей:**
 
-| Изменение                                                                                 | Версия                                       |
-| ----------------------------------------------------------------------------------------- | -------------------------------------------- |
-| Новое обязательное поле описания                                                          | major                                        |
-| Новый Признак Блока или значение по умолчанию, меняющее поведение уже описанных Блоков    | major                                        |
-| Отказ от «одно Отведённое место на поверхность» или «свои записи в порядке `tools`»       | major                                        |
-| Перенос вида записи на другую поверхность                                                 | major                                        |
-| Смена формы HTML-соглашения                                                               | major, и до следующего мажора читаются обе   |
-| Новый мажор Tiptap — даже без правок в коде кита: ломаются Части для движка у потребителя | major                                        |
-| Удаление Инструмента из Пресета, переименование Инструмента                               | major                                        |
-| Удаление публичного имени                                                                 | major, после `@deprecated` в minor (ниже)    |
-| Новое необязательное поле, новый вид записи, метод Хэндла или колбэк                      | minor                                        |
-| Новое поле Опций или Состояния, новая Команда, опция у другого встроенного Инструмента    | minor                                        |
-| Удаление поля Опций, Состояния или Команды, смена его смысла                              | major                                        |
-| Новый встроенный Инструмент в Пресете                                                     | minor, строка changeset выделена жирным      |
-| Сдвиг Отведённого места внутри поверхности                                                | minor со строкой changeset                   |
-| Подъём нижней границы Tiptap внутри мажора                                                | minor                                        |
-| Ужесточение очистки ради безопасности                                                     | patch или minor с заметкой в migration-notes |
-| Вид Скелета, DOM и классы вокруг Отведённого места                                        | вне контракта                                |
+| Изменение                                                                              | Версия                                       |
+| -------------------------------------------------------------------------------------- | -------------------------------------------- |
+| Новое обязательное поле описания                                                       | major                                        |
+| Новый Признак Блока или значение по умолчанию, меняющее поведение уже описанных Блоков | major                                        |
+| Отказ от «одно Отведённое место на поверхность» или «свои записи в порядке `tools`»    | major                                        |
+| Перенос вида записи на другую поверхность                                              | major                                        |
+| Смена формы HTML-соглашения                                                            | major, и до следующего мажора читаются обе   |
+| Новый мажор Tiptap — даже без правок в коде кита: ломаются Extensions у потребителя    | major                                        |
+| Удаление Инструмента из Пресета, переименование Инструмента                            | major                                        |
+| Удаление публичного имени                                                              | major, после `@deprecated` в minor (ниже)    |
+| Новое необязательное поле, новый вид записи, метод Хэндла или колбэк                   | minor                                        |
+| Новое поле Опций или Состояния, новая Команда, опция у другого встроенного Инструмента | minor                                        |
+| Удаление поля Опций, Состояния или Команды, смена его смысла                           | major                                        |
+| Новый встроенный Инструмент в Пресете                                                  | minor, строка changeset выделена жирным      |
+| Сдвиг Отведённого места внутри поверхности                                             | minor со строкой changeset                   |
+| Подъём нижней границы Tiptap внутри мажора                                             | minor                                        |
+| Ужесточение очистки ради безопасности                                                  | patch или minor с заметкой в migration-notes |
+| Вид Скелета, DOM и классы вокруг Отведённого места                                     | вне контракта                                |
 
 - **Мажор Tiptap — мажор кита.** Кит поддерживает один мажор Tiptap за раз; движка нет в манифесте кита, и диапазон версий (`^3.31.4`) держит потребитель по странице [RichTextEditor](../components/inputs/rich-text-editor.md#установка).
 - **Пресет** — «то, что кит считает полным набором», а не замороженный список. Кому нужен стабильный состав, передаёт точный список имён.
@@ -500,7 +500,7 @@ export const EDITOR_TOOLS = [
 
 ### `modulepreload` для ленивых чанков
 
-Предзагрузки кит не публикует. Чанки Частей для движка (своих Загрузчиков и встроенных `codeBlock` и `table` в `full`) начинают грузиться с первого рендера Редактора, и это время закрывает Скелет. Чтобы чанк пришёл вместе со страницей, поставьте на него `<link rel="modulepreload">` (в React 19 — `preloadModule(url)` из `react-dom`); URL с хешем берите из манифеста своего сборщика: имена чанков кита в контракт не входят. Пример — [RichTextEditor, «Загрузчик Части для движка»](../components/inputs/rich-text-editor.md#загрузчик-части-для-движка); цена сценариев «старт» и «полный» — [«Размер импорта»](../getting-started.md#размер-импорта).
+Предзагрузки кит не публикует. Чанки Extensions (своих Загрузчиков и встроенных `codeBlock` и `table` в `full`) начинают грузиться с первого рендера Редактора, и это время закрывает Скелет. Чтобы чанк пришёл вместе со страницей, поставьте на него `<link rel="modulepreload">` (в React 19 — `preloadModule(url)` из `react-dom`); URL с хешем берите из манифеста своего сборщика: имена чанков кита в контракт не входят. Пример — [RichTextEditor, «Загрузчик Extensions»](../components/inputs/rich-text-editor.md#загрузчик-extensions); цена сценариев «старт» и «полный» — [«Размер импорта»](../getting-started.md#размер-импорта).
 
 ## Ссылки
 

package/docs/api/messages.en.md

@@ -1,5 +1,5 @@
 ---
-sourceHash: 24a78e5196fa
+sourceHash: 9e3157586a55
 ---
 
 # Message catalog `UiMessages`
@@ -276,6 +276,9 @@ The Editor's strings ([rich-text-editor.md](../components/inputs/rich-text-edito
 | `wrapperToneName.neutral`             | string   | Important                                                                        | Важно                                                                              |
 | `wrapperToneName.warning`             | string   | Warning                                                                          | Внимание                                                                           |
 | `wrapperToneName.danger`              | string   | Caution                                                                          | Осторожно                                                                          |
+| `details`                             | string   | Collapsible block                                                                | Сворачиваемый блок                                                                 |
+| `unwrapDetails`                       | string   | Remove collapsing                                                                | Снять сворачивание                                                                 |
+| `detailsToggle`                       | function | —                                                                                | —                                                                                  |
 | `emoji`                               | string   | Emoji                                                                            | Эмодзи                                                                             |
 | `emojiGrid`                           | string   | Choose an emoji                                                                  | Выберите эмодзи                                                                    |
 | `emojiCategory.favorites`             | string   | Favorites                                                                        | Избранное                                                                          |

package/docs/api/messages.md

@@ -278,6 +278,9 @@
 | `wrapperToneName.neutral`             | строка  | Important                                                                        | Важно                                                                              |
 | `wrapperToneName.warning`             | строка  | Warning                                                                          | Внимание                                                                           |
 | `wrapperToneName.danger`              | строка  | Caution                                                                          | Осторожно                                                                          |
+| `details`                             | строка  | Collapsible block                                                                | Сворачиваемый блок                                                                 |
+| `unwrapDetails`                       | строка  | Remove collapsing                                                                | Снять сворачивание                                                                 |
+| `detailsToggle`                       | функция | —                                                                                | —                                                                                  |
 | `emoji`                               | строка  | Emoji                                                                            | Эмодзи                                                                             |
 | `emojiGrid`                           | строка  | Choose an emoji                                                                  | Выберите эмодзи                                                                    |
 | `emojiCategory.favorites`             | строка  | Favorites                                                                        | Избранное                                                                          |

package/docs/api/migration-notes.en.md

@@ -2,7 +2,7 @@
 category: api
 status: stable
 source: src/index.ts
-sourceHash: 902814b6f802
+sourceHash: 19d3eaf4181f
 ---
 
 # Compatibility and migration notes
@@ -22,7 +22,7 @@ became relevant.
 - When changing a default, accessibility, keyboard behavior or the shape of a
   controlled value: TypeScript may not detect such a migration.
 - When replacing one component with another, for example, when the old API goes away in favor of
-  an existing family.
+  an existing component family.
 
 ## When not to use
 
@@ -110,7 +110,7 @@ ref.current?.tool("search")?.open({ replace: true });
 
 Unchanged: the same panel, the same focus, the same shortcuts. The differences are small: `tool("search")` is `null`
 without the `search` Tool in `tools` and before the engine exists, so a call through `?.` does nothing, just as
-`openSearch` did; `open` returns a `boolean` (`false` in HTML mode) instead of `void`.
+`openSearch` did; `open` returns a `boolean` (`false` in Source mode) instead of `void`.
 
 ### Action before updating
 
@@ -282,12 +282,12 @@ the same page.
 `onChange`, `onUploadImage` and `focus()` do not change, and the previous code builds.
 The note is needed because five changes are visible to current consumers
 of `@olddevs/ui/editor`, and one requires installing packages with pnpm. The new API
-(a custom Tool, the Handle, events, the Status line) requires no action — it is on the
+(a custom Tool, the Handle, events, the Status bar) requires no action — it is on the
 [extension API page](editor-extension.md).
 
 ### 1. Two new peer packages
 
-The blockquote and the divider take their Engine part from `@tiptap/extension-blockquote` and
+The blockquote and the divider take their Extensions from `@tiptap/extension-blockquote` and
 `@tiptap/extension-horizontal-rule` — optional peer dependencies of the
 `@olddevs/ui/editor` entry point with the same `^3.31.4` range (since 3.46.0 the engine
 packages are no longer in the kit manifest; see the entry above).
@@ -329,7 +329,7 @@ did not fit goes away whole, together with everything after it.
 
 **Action before updating.** Check the server-side length validation against the kit's rule:
 the Document's text without markup and Block separators, an Atom by the length of its text.
-The kit has no server-side counter: the weight of a custom Atom depends on its Engine part.
+The kit has no server-side counter: the weight of a custom Atom depends on its Extensions.
 
 ### 3. Skeleton before Readiness
 
@@ -381,7 +381,7 @@ arrive with the page, add `modulepreload` for them
 **What changed.** "Uploading…", "uploaded", an upload refusal, "not an image" and
 "files are not accepted" go through the same channel as the new engine command
 `showNotice`: one place under the field, a new message replaces the previous one, and an error
-(`role="alert"`) stays until the next Author edit. The texts and roles are the same, but the
+(`role="alert"`) stays until the next User edit. The texts and roles are the same, but the
 live region `role="status"` is now present in **every** Editor, not only with the
 `image` Tool.
 
@@ -578,7 +578,7 @@ is parameterized by your state (`SavedView<T>`) and is not tied to
 `TableState`; storage, sharing and the URL stay entirely with you. For details, see the
 [component page](../components/table/saved-views.md).
 
-**The `FormField` hint and error reach the react-aria families.** For
+**The `FormField` hint and error reach the react-aria component families.** For
 `Select`, `Combobox`, `DatePicker` and `TagInput`, the description from `FormField` is now tied to
 the field through `aria-describedby`. **This is an accessibility fix, and it changes
 what is announced:** where a hint was visible on screen but did not reach a screen reader, a
@@ -646,7 +646,7 @@ above came from: `npm run check:dist`, `npm run check:consumer`,
 with changesets.
 
 **Deliberately postponed:** Figma Code Connect (priority P2 in the specification, only after
-the names and axes stabilize); binding the description for the react-aria families (`Select`,
+the names and axes stabilize); binding the description for the react-aria component families (`Select`,
 `Combobox`, `DatePicker`, `TagInput`) — they have their own description slots; merging
 `UploadState` and `TimelineStatus` — it breaks a public type and waits for a major;
 widening the peer to React 18 — it doubles the consumer's CI build.
@@ -735,7 +735,7 @@ the description is **supplemented, not replaced**: the attribute holds a list.
 
 `TextControl` and everything built on it (`MaskedInput`,
 `PhoneInput`, `PasswordInput`, `SearchControl`), plus `NumberInput`, pick up the description. The react-aria
-families (`Select`, `Combobox`, `DatePicker`, `TagInput`) carry their own description slots
+component families (`Select`, `Combobox`, `DatePicker`, `TagInput`) carry their own description slots
 and do not pick up the `FormField` hint yet.
 
 **3. A character that does not fit the mask is announced.** A character that did not fit the mask token
@@ -817,7 +817,7 @@ something read it; `DataTable` became that reader.
 `tableStateToParams`, `tableStateFromParams`, `DEFAULT_TABLE_STATE`.
 
 **5. Selection is within a page.** "Select all" marks the `items` that arrived;
-the kit does not support selecting the whole result set, and the labels about it do not lie.
+the kit does not support selecting all the filtered rows, and the labels about it do not lie.
 If you need selection beyond the page, that is your code, not the kit's.
 
 **6. State is carried into the URL without selection and expansion.** The list of keys

package/docs/api/migration-notes.md

@@ -287,7 +287,7 @@ Shift+F10 — меню ячейки. Новое: кнопки внутри яч
 
 ### 1. Два новых peer-пакета
 
-Цитата и разделитель берут Часть для движка из `@tiptap/extension-blockquote` и
+Цитата и разделитель берут Extensions из `@tiptap/extension-blockquote` и
 `@tiptap/extension-horizontal-rule` — опциональных peer-зависимостей входа
 `@olddevs/ui/editor` с тем же диапазоном `^3.31.4` (с 3.46.0 пакеты движка из
 манифеста кита убраны, см. запись выше).
@@ -329,7 +329,7 @@ pnpm add @tiptap/extension-blockquote @tiptap/extension-horizontal-rule
 
 **Действие до обновления.** Серверную проверку длины сверьте с правилом кита:
 текст Документа без разметки и разделителей Блоков, Атом — длиной своего текста.
-Серверного счётчика у кита нет: вес своего Атома зависит от его Части для движка.
+Серверного счётчика у кита нет: вес своего Атома зависит от его Extensions.
 
 ### 3. Скелет до Готовности
 

package/docs/api/utilities.en.md

@@ -156,10 +156,10 @@ nothing outside React** and subscribes to nothing. The kit provides the shape, a
 ### Invariants the hook exists to keep
 
 - changing **filters, sorting or the page size resets the page** to the first one. Otherwise the user looks at
-  page four of a result set of ten rows, and reads the empty space as "nothing found";
+  page four of ten filtered rows, and reads the empty space as "nothing found";
 - **selection is not reset.** The reverse looks tidier, but it breaks a bulk action exactly when that action is
   needed most;
-- density and column visibility do **not** touch the page. A filter narrows the result set, not the look;
+- density and column visibility do **not** touch the page. A filter narrows the rows, not the look;
 - an explicit `page` in the same call cancels the reset. This is how the state is restored from the address,
   in full and in one go.
 
@@ -190,7 +190,7 @@ router.replace(`?${tableStateToParams(state)}`);
 state. There are two reasons. The list of keys has no length limit. And a link with a selection, opened the next
 day, marks records that no longer exist. Selection is session state, not URL state.
 
-The restored state is passed to the hook as a whole, in one `set` call. The invariant "narrowing the result set
+The restored state is passed to the hook as a whole, in one `set` call. The invariant "narrowing the filtered rows
 resets the page" is cancelled by an explicit page in the same call. Otherwise a link would always open the first
 page.
 
@@ -207,7 +207,7 @@ For how to build a range in the UI, see [FilterBar](../components/table/filter-b
 
 ## Constants, classes and public types: where they are documented
 
-These are public exports, but not standalone components. The page of the family they belong to describes them,
+These are public exports, but not standalone components. The page of the component family they belong to describes them,
 so that AI does not treat a class as a general-purpose API:
 
 | Exports                                                                                                                                       | Documentation                                                 |
@@ -221,8 +221,8 @@ so that AI does not treat a class as a general-purpose API:
 
 Each `*Props` type and each component-specific type exported with a component (for example `TableProps`,
 `CommandItem`, `SelectItem`, `KeyboardSelection` or `DrawerSide`) stays part of that component's public API. It
-is described on the page of its family. The [component catalog](../components/index.md) links the public exports
-to the family pages. `src/index.ts` is the final source for all exports.
+is described on the page of its component family. The [component catalog](../components/index.md) links the public exports
+to the component family pages. `src/index.ts` is the final source for all exports.
 
 ## Related sources and checks
 

package/docs/components/actions/split-button.en.md

@@ -12,7 +12,7 @@ sourceHash: 982b0da00a2f
 
 ## Summary for AI
 
-`SplitButton` is a primary action with a menu trigger for its variants next to it, as **two separate buttons**. The accessible name of the menu trigger is built from `label`, so `label` is a string, not a node. Menu items go in `children`.
+`SplitButton` is a primary action with a menu button for its variants next to it, as **two separate buttons**. The accessible name of the menu button is built from `label`, so `label` is a string, not a node. Menu items go in `children`.
 
 ## When to use
 
@@ -38,9 +38,9 @@ sourceHash: 982b0da00a2f
 
 ## Public API
 
-- `label` is a **string**: the label of the primary action and the source of the name of the menu trigger.
+- `label` is a **string**: the label of the primary action and the source of the name of the menu button.
 - `icon` is the icon on the left of the primary action. If a button can enter `loading`, give it an icon from the start: otherwise the loading indicator adds a slot, and the label shifts.
-- `onClick` is called only by the primary action; the menu trigger does not call it.
+- `onClick` is called only by the primary action; the menu button does not call it.
 - `variant`, `tone`, `size` are the same axes as on `Button` and mean the same thing.
 - `disabled` and `loading` disable **both** buttons and close a menu that is already open — and **do not bring it back** when `disabled` or `loading` is lifted: otherwise the menu would open by itself once a submission ended.
 - `placement` is the side the panel opens to, `bottom end` by default. The side values of `Menu` are narrowed here: a panel that slides sideways lands on top of the primary action.
@@ -57,20 +57,20 @@ two. These are two separate controls.
 
 ## Why `label` is a string
 
-The name of the menu trigger is built from the label. A node would give a name
+The name of the menu button is built from the label. A node would give a name
 that does not exist — or would require a second prop with the same label as a
 string. One label would live in two places and drift apart at the first edit.
 
 ## Keyboard
 
-- **Two tab stops, not one.** Tab goes to the primary action, the next Tab to the menu trigger. The whole rationale of the component rests on this: a single button whose right part opens a menu would leave the second outcome unreachable from the keyboard.
-- The menu opens from the menu trigger with Enter, Space and Down Arrow — `MenuTrigger` does this.
-- Escape closes the menu and **returns focus to the menu trigger** instead of sending it to `<body>`.
+- **Two tab stops, not one.** Tab goes to the primary action, the next Tab to the menu button. The whole rationale of the component rests on this: a single button whose right part opens a menu would leave the second outcome unreachable from the keyboard.
+- The menu opens from the menu button with Enter, Space and Down Arrow — `MenuTrigger` does this.
+- Escape closes the menu and **returns focus to the menu button** instead of sending it to `<body>`.
 - Disabling the component while the menu is open closes the panel: otherwise it would look disabled while the items kept working.
 
 ## Accessibility and semantics
 
-- The menu trigger's name comes from the message catalog: `splitButton.more({ action })` → "Другие действия: Экспорт" with `@olddevs/ui/locales/ru`, "More actions: Export" without a provider. Without the action's label, several menu triggers on a page are indistinguishable when read aloud by a screen reader.
-- The menu trigger carries `aria-haspopup` and `aria-expanded` — `MenuTrigger` sets them.
+- The menu button's name comes from the message catalog: `splitButton.more({ action })` → "Другие действия: Экспорт" with `@olddevs/ui/locales/ru`, "More actions: Export" without a provider. Without the action's label, several menu buttons on a page are indistinguishable when read aloud by a screen reader.
+- The menu button carries `aria-haspopup` and `aria-expanded` — `MenuTrigger` sets them.
 - The group does not get `role="group"`: an unnamed group is an extra screen reader announcement, and a name would duplicate the button's label.
 - See `src/components/actions/SplitButton.tsx`, `src/components/actions/SplitButton.stories.tsx`, `tests/split-button.test.tsx`, [Menu](../overlays/menu.md).

package/docs/components/content/data-display.en.md

@@ -117,7 +117,7 @@ the row: a manual `stopPropagation` is not needed. A detail row and the expander
 button do not call the action. A row with an action gets a pointer cursor.
 
 **Expansion is the only axis that could not be added as a layer on top.**
-`DataTable` adds column visibility, order, density and the table bar (`toolbar`)
+`DataTable` adds column visibility, order, density and the table toolbar (`toolbar`)
 from the outside: they change what goes into `Table` through props. A detail row
 lives **inside** `<tbody>`, between the rows of the react-aria collection, and
 cannot be inserted from the outside. The analysis is in

package/docs/components/content/layout-primitives.en.md

@@ -77,9 +77,9 @@ import { AspectRatio, Kbd, ScrollArea, Separator } from "@olddevs/ui";
 
 ### `Kbd`
 
-| Prop   | Default | Meaning                                                             |
-| ------ | ------- | ------------------------------------------------------------------- |
-| `size` | `sm`    | `sm` — inside a menu, `md` — in a standalone shortcuts cheat sheet. |
+| Prop   | Default | Meaning                                                                 |
+| ------ | ------- | ----------------------------------------------------------------------- |
+| `size` | `sm`    | `sm` — inside a menu, `md` — in a standalone keyboard shortcuts dialog. |
 
 `Kbd` renders the Apple modifier symbols (`⌘ ⌥ ⇧ ⌃`) in a string label in a
 proportional font and everything else in a monospace one. The kit's monospace

package/docs/components/content/rich-text-toc.en.md

@@ -67,7 +67,7 @@ export function Article({ html }: { html: string }) {
 ### Which headings are included
 
 - `h1`–`h4` at the top level of the Document and inside a Wrapper.
-- Headings in the columns of a Layout are not included: two headings at the same height in neighboring columns confuse the highlight of the current section. Headings inside custom Blocks and their Islands are not included either: their content is part of the Block, not of the Document's structure.
+- Headings in the columns of a Column layout are not included: two headings at the same height in neighboring columns confuse the highlight of the current section. Headings inside custom Blocks and their Islands are not included either: their content is part of the Block, not of the Document's structure.
 - The `levels` prop narrows the set: `levels={[2, 3]}` keeps only `h2` and `h3`. Other levels are in neither the strip nor the list; an empty array leaves no headings at all.
 - With fewer than two headings (after `levels`) the component renders nothing, and the screen's column stays empty.