@olddevs/ui 0.0.0-stage → 4.0.0

package/docs/api/editor-extension.md

@@ -0,0 +1,308 @@
+---
+category: api
+status: stable
+source: src/editor/index.ts
+---
+
+# API расширения Редактора
+
+## Кратко для AI
+
+Карта того, чем продукт расширяет `RichTextEditor` из `@olddevs/ui/editor`, и граница стабильности этого API. Единица расширения — **свой Инструмент** (`CustomTool`): описание одной возможности Редактора, которое передаётся в `tools` вперемешку с именами кита. Он несёт Блоки и Метки с правилами Схемы (это данные), Часть для движка (расширения Tiptap, сразу или Загрузчиком) и UI-записи: кнопки, Пункты вставки, Действия над Блоком, Карточки у текста. Есть и свой Символ-триггер (`trigger`): `@` для упоминаний открывает тот же список, что `/`. Код экрана управляет полем через Хэндл (`ref`) и хук `useRichTextEditorState`, узнаёт о Готовности и Фокусе поля колбэками `onReady`, `onFocus` и `onBlur`, кладёт своё в Строку статуса (`status`) и сообщает об ошибке командой `showNotice`. Тот же массив `tools` понимают серверная очистка (`sanitizeRichText`, `richTextSchema`) и `RichTextView` с Островами. Всё перечисленное подчиняется semver кита с первого выпуска, HTML-соглашение заморожено, мажор Tiptap — мажор кита (раздел «Стабильность»). Подробности каждого пункта живут на странице [RichTextEditor](../components/inputs/rich-text-editor.md); здесь — карта, граница контракта и рецепты.
+
+```tsx
+import {
+  RICH_TEXT_PRESETS,
+  RichTextEditor,
+  useRichTextEditorState,
+  type CustomTool,
+  type RichTextEditorHandle,
+} from "@olddevs/ui/editor";
+import { sanitizeRichText } from "@olddevs/ui/editor/schema";
+```
+
+Решение — ADR-0058, дополняет ADR-0050. Термины с большой буквы — из [словаря Редактора](../glossary.md#редактор).
+
+## Когда использовать
+
+- Документу нужен свой Блок, Атом или своя Метка: Merge Tag, Embed, карточка товара, комментарий к фрагменту. Их Схема, HTML, Markdown и показ в `RichTextView` описываются одним Инструментом.
+- Своя команда в интерфейсе Редактора: кнопка на Панели, Пункт вставки в «/» и «+», Действие над Блоком в меню Ручки Блока, Карточка у текста.
+- Экран управляет полем: вставляет шаблон у каретки, рисует свою панель, сохраняет при потере фокуса, показывает «Сохранено» и число слов.
+- Сервер хранит Документ со своими Блоками и должен чистить его тем же набором правил, что Редактор.
+
+## Когда не использовать
+
+- Нужное уже есть среди Инструментов кита ([«Инструменты и Пресеты»](../components/inputs/rich-text-editor.md#инструменты-и-пресеты)): передайте имя в `tools`, своё не пишите.
+- Чтобы спрятать встроенную кнопку или пункт, сузьте `tools`. Подменить встроенный Инструмент по имени нельзя: выключите его и поставьте свой под своим именем.
+- Произвольный React в строке Панели и в меню нельзя: кит рисует записи сам, React допускается только в содержимом поповера (кнопки, Пункта вставки, Действия над Блоком) и в Карточке у текста.
+- Во вставку и drop пропом вмешаться нельзя: это делает Часть для движка своего Инструмента ([«Порядок вставки и 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-и-своя-панель-вне-поля)                                                                                                                 |
+| События                                      | `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#остров-своего-блока)                                                                                                                                  |
+
+## Свой Инструмент и HTML-соглашение
+
+Описание одно, внутри две части. **Правила Схемы** — обычные данные без Tiptap: их читают Редактор, серверная очистка и Просмотр. **Часть для движка** — расширения Tiptap целиком (Node, Mark, Extension, плагины ProseMirror, React-вид узла): только поведение, а разбор и вывод HTML ставит кит. Обязательны имя, Часть для движка и правило Схемы для каждого её Node и Mark; остальное — по умолчанию: обычный Блок без Признаков, выгрузка в Markdown его содержимым, ритм абзаца в Просмотре, без UI-записей. Инструмент может не нести Блока вовсе — например, только фильтр вставки.
+
+Всё своё называется с Префиксом потребителя через подчёркивание: Инструмент `acme_mergeTag`, атрибут `acme_size`. В именах кита подчёркивания нет, поэтому своё и встроенное не пересекаются ни в массиве `tools`, ни в сохранённом Документе. HTML своего пишет и читает кит:
+
+| Что           | HTML                                                               |
+| ------------- | ------------------------------------------------------------------ |
+| Блочный Блок  | `<div data-block="acme_card">…</div>`                              |
+| Строчный Атом | `<span data-block="acme_mergeTag"></span>`                         |
+| Метка         | `<span data-mark="acme_comment">…</span>`                          |
+| Атрибут       | `data-acme_size="m"` — значение по правилу: список, шаблон или URL |
+
+Массив `tools` проверяется один раз, при создании движка (с Загрузчиками — когда они отработали). Имя без префикса, совпадение имён, Node или Mark в Части для движка без правила Схемы (и наоборот), запись без обязательного поля дают ошибку поля «Редактор не запустился», а не тихая потеря Блоков при первом сохранении. Неизвестная **строка** в `tools` по-прежнему отбрасывается молча.
+
+## UI-записи
+
+Кит рисует, Инструмент описывает. Поэтому ARIA-роли, одна Tab-остановка Панели, `aria-pressed` (только при `isActive`), подсказка с `Kbd`, рамка поповера и стек Escape у своих записей те же, что у встроенных. У каждой поверхности **одно Отведённое место**, и свои записи стоят в нём **в порядке `tools`**, внутри Инструмента — в порядке массива:
+
+| Запись              | Поле           | Отведённое место                                                                                 |
+| ------------------- | -------------- | ------------------------------------------------------------------------------------------------ |
+| Кнопка              | `buttons`      | Группа Панели перед «Отменить» и «Повторить»; с `selectionMenu: true` — ещё и Меню выделения     |
+| Пункт вставки       | `insertItems`  | Конец своего раздела («Добавить» или «Превратить в») в «/», «+», «Добавить ›» и «Формат ›» Ручки |
+| Действие над Блоком | `blockActions` | Секция меню Ручки Блока перед «Удалить» — у Блоков из `blocks`                                   |
+| Карточка у текста   | `textCards`    | Рамка под диапазоном текста, у которого стоит каретка; открыта не больше одной                   |
+
+- **Подпись** — строка или функция, получающая `{ locale }` (локаль `UiProvider`); каталог сообщений `UiProvider` для сторонних Инструментов не расширяется, переопределение — опциями фабрики Инструмента (рецепт ниже).
+- **Иконка** обязательна у кнопки, пункта и Действия: компонент с контрактом `IconProps` из `@olddevs/ui/icons` или свой.
+- **Поповер** — у кнопки, Пункта вставки и Действия над Блоком ровно одно из `run` и `popover`. Содержимое — функция, получающая `{ editor, close }` (у Действия — ещё `pos` Блока), рамку держит кит: слой оверлея, Стекло всплывающих поверхностей Редактора, стек Escape, имя (подпись записи), возврат фокуса и выделения в Документ. Карточка у текста лежит на том же Стекле, поэтому сплошной фон содержимому не нужен: он закроет подложку. При включённой в системе настройке прозрачности или контраста подложка и так станет сплошной. Поповер встаёт у кнопки (щелчок), у каретки (сочетание кнопки, пункт из «/», «+», «Добавить ›», «Формат ›» и его сочетание) или у Блока (Действие из меню Ручки и его сочетание).
+- **Сочетание** (`shortcut`) — единственный источник: кит вешает клавишу и пишет её в подсказку, `aria-keyshortcuts` и Справочник сочетаний. Клавиши Части для движка в справочник не попадают.
+- **Выключенный Инструмент** уносит свои записи отовсюду.
+
+## Символ-триггер
+
+`trigger` Инструмента — не запись Отведённого места, а вход в тот же список, что и «/»: ввод символа `char` (`@`, `#`) в начале Блока или после пробела открывает у каретки список пунктов, которые Инструмент отдаёт по запросу (`items(query)`, сразу или промисом). Список рисует кит: это тот же компонент, что у Меню вставки, с поиском по набранному, стрелками, `Enter`, `Escape` и строкой «Ничего не найдено». Выбор зовёт `onSelect(item, { editor, range, query })`, и обработчик заменяет `range` (набранное `@запрос`) своим узлом. Внутри слова (`a@b.com`) и в коде список не открывается. Символ — один печатный знак, не `/` и не пробел, уникальный в `tools`; нарушение даёт ошибку массива `tools` (ADR-0064, подробности на странице [RichTextEditor](../components/inputs/rich-text-editor.md#свой-символ-триггер)).
+
+## Хэндл (`ref`), события, Строка статуса
+
+- **Хэндл** (`ref`) — вставка у каретки (`insertHTML`, `insertText` → `boolean`), чтение (`getText`, `getSelectedText`, `isEmpty`, `getHTML`, `getMarkdown`, `getJSON`), фокус (`focus("start" | "end" | "restore")`, `blur`), история (`undo`, `redo`, `canUndo`, `canRedo`), а ещё `clear`, `setMarkdown` и `setJSON` (JSON-конверт → `boolean`) и `openSearch({ replace? })` — открыть панель поиска и замены. Вставка — Правка автора: шаг истории, `onChange` после задержки, предел `maxLength`; за пределом вставка не выполняется. До Готовности методы не бросают ошибок и ничего не меняют: `insertHTML` и `insertText` возвращают `false`. `editor` — сырой Tiptap для команд Меток, Блоков и своих Инструментов; его API следует мажору Tiptap.
+- **`useRichTextEditorState(ref, selector)`** — состояние своей панели: перерисовка только при смене среза, `null` до движка и на сервере.
+- **`onReady()`** — один раз за монтаж, когда наступила Готовность; **`onFocus()`** и **`onBlur()`** — о Фокусе поля целиком (Документ, Панель, поповеры кита, поле HTML); перед `onBlur` отложенный `onChange` выталкивается.
+- **`status`** — React-узел экрана в строке под Документом, у начала; счётчик кита — в конце. Кит строку не озвучивает.
+- **`showNotice({ tone: "status" | "error", text } | null)`** — команда движка: одно Сообщение поля, новое заменяет прежнее; `status` только озвучивается, `error` видна строкой `role="alert"` до следующей Правки автора. Тем же каналом кит сообщает о картинках.
+
+## Загрузчики, Готовность и Скелет
+
+Часть для движка можно отдать Загрузчиком — `engine: () => import("./engine.js").then((m) => m.engine)`: модуль с описанием тогда импортирует и сервер, а Tiptap уходит в отдельный чанк. Загрузка стартует с первого рендера в браузере, промис кэшируется на функции Загрузчика (поэтому Загрузчик — одна функция на модуль). **Готовность** — движок создан и Загрузчики всех включённых Инструментов, своих и тяжёлых встроенных (`codeBlock`, `table`), отработали. До неё поле — **Скелет**: рамка, место Панели и Документ, очищенный Схемой, без ввода и без прыжка высоты; на сервере — рамка без Документа. Сбой Загрузчика — ошибка поля с «Повторить», Документ остаётся виден. Подробно — [«Загрузчик Части для движка»](../components/inputs/rich-text-editor.md#загрузчик-части-для-движка) и [«Скелет»](../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`). Без них Блок выгружается содержимым, Атом — Текстом атома, и текст не теряется.
+- **`RichTextView`** показывает свой Блок очищенным HTML с ритмом абзаца; вид — ваш CSS по `data-block`. **Остров** — клиентский компонент в поле `island` Блока: оживает после монтирования и только если такой Блок есть в Документе; `RichTextView` для этого получает тот же `tools`.
+
+## Стабильность
+
+Граница контракта по ADR-0058, п. 12. По этому разделу ревьюер сверяет тип changeset; записи об API расширения начинаются словами «Редактор, расширение:».
+
+**Экспериментальной метки нет, semver — с первого выпуска.** В контракт входят:
+
+- описание своего Инструмента (`CustomTool` и его поля, в том числе `trigger`), UI-записи и их Отведённые места, правила Схемы (`CustomBlock`, `CustomMark`, `CustomAttribute`), Признаки Блока;
+- HTML-соглашение (`data-block`, `data-mark`, `data-<префикс>_<имя>`);
+- методы Хэндла, `useRichTextEditorState`, колбэки `onReady`, `onFocus`, `onBlur`, проп `status`, команда `showNotice` и тип `FieldNotice`;
+- третий аргумент `sanitizeRichText` и `richTextSchema`, проп `tools` и Остров у `RichTextView`, `markRange`;
+- имена встроенных Инструментов (`ToolName`) и сам факт Пресетов-массивов `RICH_TEXT_PRESETS` — но не их состав (ниже).
+
+**Не входят:** DOM и классы кита вокруг Отведённого места; id встроенных кнопок и пунктов; внутреннее описание встроенных Инструментов (надмножество публичной формы) — наружу оно не экспортируется; точное место записи внутри поверхности; вид Скелета; имена файлов и чанков в `dist`, как любой путь внутри пакета ([«Публичный контракт»](../conventions.md#публичный-контракт)). API сырого `editor` и Части для движка — это API Tiptap, он следует мажору движка.
+
+**Сохранённый Документ не ломают ни minor, ни patch.** HTML-соглашение заморожено: `data-block` и `data-mark` расширяются только добавлением. Если форму придётся сменить, это мажор, и до следующего мажора кит читает обе формы — и разбором движка, и санитайзером.
+
+**Ломающим считается нарушение контракта, а не сдвиг пикселей:**
+
+| Изменение                                                                                 | Версия                                       |
+| ----------------------------------------------------------------------------------------- | -------------------------------------------- |
+| Новое обязательное поле описания                                                          | major                                        |
+| Новый Признак Блока или значение по умолчанию, меняющее поведение уже описанных Блоков    | major                                        |
+| Отказ от «одно Отведённое место на поверхность» или «свои записи в порядке `tools`»       | major                                        |
+| Перенос вида записи на другую поверхность                                                 | major                                        |
+| Смена формы HTML-соглашения                                                               | major, и до следующего мажора читаются обе   |
+| Новый мажор Tiptap — даже без правок в коде кита: ломаются Части для движка у потребителя | major                                        |
+| Удаление Инструмента из Пресета, переименование Инструмента                               | major                                        |
+| Удаление публичного имени                                                                 | major, после `@deprecated` в minor (ниже)    |
+| Новое необязательное поле, новый вид записи, метод Хэндла или колбэк                      | minor                                        |
+| Новый встроенный Инструмент в Пресете                                                     | minor, строка changeset выделена жирным      |
+| Сдвиг Отведённого места внутри поверхности                                                | minor со строкой changeset                   |
+| Подъём нижней границы Tiptap внутри мажора                                                | minor                                        |
+| Ужесточение очистки ради безопасности                                                     | patch или minor с заметкой в migration-notes |
+| Вид Скелета, DOM и классы вокруг Отведённого места                                        | вне контракта                                |
+
+- **Мажор Tiptap — мажор кита.** Кит поддерживает один мажор Tiptap за раз; движка нет в манифесте кита, и диапазон версий (`^3.31.4`) держит потребитель по странице [RichTextEditor](../components/inputs/rich-text-editor.md#установка).
+- **Пресет** — «то, что кит считает полным набором», а не замороженный список. Кому нужен стабильный состав, передаёт точный список имён.
+- **Ужесточение очистки** выходит заметкой в [migration-notes](migration-notes.md): что теперь срезается и как найти такие Документы. Ослабление очистки — отдельное решение, а не вопрос версии.
+- **Сначала пометка, потом удаление.** Замена выходит в minor, старое получает `@deprecated` и одно предупреждение в разработке, удаляется следующим мажором.
+
+## Рецепты
+
+### Своя панель вне поля: `preventDefault` на `mousedown`
+
+Кнопки своей панели вне поля делают `event.preventDefault()` на `mousedown`: фокус остаётся в Документе, и плавающая Панель, Меню выделения и панель картинки не прячутся. Состояние кнопок — из `useRichTextEditorState`, команды — `ref.current?.editor?.chain().focus()…run()`. Пример и подробности — [RichTextEditor, «Своя панель»](../components/inputs/rich-text-editor.md#своя-панель-userichtexteditorstate). Правило «клик в свою панель не снимает выделение» — рецепт, а не свойство поля.
+
+### «Сохранено» в Строке статуса
+
+Автосохранение при потере фокуса и озвучка результата. Живой регион стоит в Строке статуса **постоянно**, меняется только его текст: регион, вставленный вместе с текстом, скринридеры часто не читают. Число слов рядом — без `role`, чтобы не звучать на каждую правку.
+
+```tsx
+import { useRef, useState } from "react";
+import { RichTextEditor, type RichTextEditorHandle } from "@olddevs/ui/editor";
+
+function ArticleBody({
+  initial,
+  save,
+}: {
+  initial: string;
+  save: (html: string) => Promise<void>;
+}) {
+  const ref = useRef<RichTextEditorHandle>(null);
+  const [html, setHtml] = useState(initial);
+  const [saved, setSaved] = useState(false);
+
+  return (
+    <RichTextEditor
+      ref={ref}
+      aria-label="Текст статьи"
+      value={html}
+      onChange={(next) => {
+        setHtml(next);
+        setSaved(false);
+      }}
+      // Перед onBlur отложенный onChange уже вытолкнут, но состояние ещё не
+      // перерисовано: свежий Документ — из Хэндла.
+      onBlur={async () => {
+        await save(ref.current?.getHTML() ?? html);
+        setSaved(true);
+      }}
+      status={
+        <span className="flex gap-3">
+          <span role="status">{saved ? "Сохранено" : ""}</span>
+          <span>{countWords(html)} слов</span>
+        </span>
+      }
+    />
+  );
+}
+```
+
+Ошибку сохранения показывайте там же, где экран показывает ошибки формы: `showNotice` — для событий самого поля (отказ вставки, загрузка файла), и строка `error` уходит с первой Правкой автора. Подробно о строке — [«Строка статуса: `status`»](../components/inputs/rich-text-editor.md#строка-статуса-status).
+
+### Исчезнувшие картинки: сравнение `src` на сервере
+
+Сигнала «картинка удалена из Документа» у Редактора нет и не будет, пока о нём не попросят потребители: отмена, вырезание со вставкой и правка соавтора дали бы ложные срабатывания, а Документ меняют и в обход Редактора: через API-запрос, миграцию, другого клиента. Поэтому загруженные файлы, на которые Документ больше не ссылается, находит сервер: при сохранении он сравнивает URL картинок очищенного Документа с прошлой версией.
+
+```ts
+import { JSDOM } from "jsdom";
+import createDOMPurify from "dompurify";
+import { sanitizeRichText } from "@olddevs/ui/editor/schema";
+import { EDITOR_TOOLS } from "./editor-tools"; // тот же массив, что в `tools` Редактора
+
+const { window } = new JSDOM("");
+const DOMPurify = createDOMPurify(window);
+
+/** Адреса картинок Документа. Разбор — в инертном `template`: скрипты не исполняются. */
+function imageSources(html: string): Set<string> {
+  const template = window.document.createElement("template");
+  template.innerHTML = html;
+  return new Set(
+    [...template.content.querySelectorAll("figure > img[src]")].map((img) =>
+      img.getAttribute("src")!
+    )
+  );
+}
+
+export async function saveDocument(id: string, dirty: string) {
+  const html = sanitizeRichText(dirty, DOMPurify, EDITOR_TOOLS);
+  const before = imageSources((await documents.get(id))?.html ?? "");
+  const after = imageSources(html);
+  await documents.put(id, html);
+  // Не удалять сразу: тот же файл может стоять в другом Документе, черновике или
+  // версии, которую автор вернёт отменой. Пометить — и решить отложенной задачей.
+  await uploads.markUnreferenced(
+    [...before].filter((src) => !after.has(src)),
+    { documentId: id }
+  );
+}
+```
+
+Сравнивайте **очищенный** HTML: только в нём картинка гарантированно `figure > img` с абсолютным URL `http`/`https`. URL своего Блока (атрибут вида `url`) ищется так же — по `[data-block="acme_video"]` и его `data-acme_src`.
+
+### Подписи через опции фабрики
+
+Каталог сообщений `UiProvider` закрыт для сторонних Инструментов, поэтому переводы и переопределения подписей своего Инструмента — опции его фабрики. Подпись-функция получает `{ locale }` и перерисовывается со сменой локали; строка подходит одноязычному приложению.
+
+```tsx
+import { RICH_TEXT_PRESETS, type CustomTool, type CustomToolLabel } from "@olddevs/ui/editor";
+import { MentionIcon } from "@olddevs/ui/icons";
+
+interface MentionLabels {
+  insert: CustomToolLabel;
+}
+
+const DEFAULT_LABELS: MentionLabels = {
+  insert: ({ locale }) => (locale.startsWith("ru") ? "Упоминание" : "Mention"),
+};
+
+// Загрузчик — одна функция на модуль: промис кэшируется на ней.
+const loadEngine = () => import("./mention-engine.js").then((module) => module.engine);
+
+export function mentionTool(options: { labels?: Partial<MentionLabels> } = {}): CustomTool {
+  const labels = { ...DEFAULT_LABELS, ...options.labels };
+  return {
+    name: "acme_mention",
+    engine: loadEngine,
+    blocks: {
+      acme_mention: {
+        kind: "inline",
+        attributes: { acme_id: { kind: "pattern", pattern: "[0-9]+" } },
+      },
+    },
+    insertItems: [
+      {
+        section: "insert",
+        label: labels.insert,
+        icon: MentionIcon,
+        aliases: ["mention", "user"],
+        run: (chain) => chain.insertContent({ type: "acme_mention", attrs: { acme_id: null } }),
+      },
+    ],
+  };
+}
+
+// Экран: массив собирается один раз на модуль, а не в рендере:
+// `tools` читается при создании движка.
+export const EDITOR_TOOLS = [
+  ...RICH_TEXT_PRESETS.full,
+  mentionTool({ labels: { insert: "Отметить коллегу" } }),
+];
+```
+
+Пустая подпись не роняет поле: в разработке — `console.error` с именем Инструмента и записи, а в имя и подсказку встаёт имя Инструмента.
+
+### `modulepreload` для ленивых чанков
+
+Предзагрузки кит не публикует. Чанки Частей для движка (своих Загрузчиков и встроенных `codeBlock` и `table` в `full`) начинают грузиться с первого рендера Редактора, и это время закрывает Скелет. Чтобы чанк пришёл вместе со страницей, поставьте на него `<link rel="modulepreload">` (в React 19 — `preloadModule(url)` из `react-dom`); URL с хешем берите из манифеста своего сборщика: имена чанков кита в контракт не входят. Пример — [RichTextEditor, «Загрузчик Части для движка»](../components/inputs/rich-text-editor.md#загрузчик-части-для-движка); цена сценариев «старт» и «полный» — [«Размер импорта»](../getting-started.md#размер-импорта).
+
+## Ссылки
+
+- Страницы: [RichTextEditor](../components/inputs/rich-text-editor.md), [RichTextView](../components/content/rich-text-view.md), [словарь Редактора](../glossary.md#редактор), [migration-notes](migration-notes.md).
+- Решения: ADR-0058 — API расширения, ADR-0050 — Редактор.
+- Исходник: вход `src/editor/index.ts`, публичная форма своего Инструмента `src/editor/core/customTool.ts`, проверка массива `tools` и проводка `src/editor/core/customToolEngine.ts`, Хэндл `src/editor/core/handle.ts`, хук `src/editor/hooks/useRichTextEditorState.ts`, Сообщение поля `src/editor/core/fieldNotice.ts`, Схема и очистка `src/editor/core/schema.ts`, Острова `src/editor/core/viewIsland.ts`.
+- Тесты: `tests/rich-text-editor-custom-tool.test.tsx` (описание, Схема, проверка массива `tools`), `tests/rich-text-editor-custom-button.test.tsx`, `tests/rich-text-editor-custom-ui.test.tsx` и `tests/rich-text-editor-text-card.test.tsx` (UI-записи), `tests/rich-text-editor-handle.test.tsx` и `tests/rich-text-editor-handle-ssr.test.tsx` (Хэндл и хук), `tests/rich-text-editor-events.test.tsx` (колбэки, порядок вставки и drop), `tests/rich-text-editor-notice.test.tsx` (Строка статуса и Сообщение поля), `tests/rich-text-editor-loaders.test.tsx`, `tests/rich-text-editor-skeleton.test.tsx` и `tests/rich-text-editor-lazy-builtins.test.tsx` (Загрузчики, Скелет, ленивые встроенные), `tests/rich-text-editor-atom-text.test.tsx` (Текст атома), `tests/rich-text-editor-custom-markdown.test.tsx`, `tests/editor-sanitize-tools.test.tsx`, `tests/rich-text-view-island.test.tsx`, `tests/editor-entry.test.ts`; тестовые Инструменты — `tests/editor-test-tools.ts`.