@olddevs/ui 4.3.0 → 4.5.0

package/src/editor/core/handleWatchers.ts

@@ -0,0 +1,72 @@
+import type { RefObject } from "react";
+import type { ToolList } from "./toolDescriptor.js";
+
+/*
+  Хук-селектор не знает, когда у `ref` появится движок: Редактор создаёт его
+  после первого рендера экрана и перерисовывается сам, а экран — нет. Поэтому
+  подписки живут по самому объекту `ref`, который есть с первого рендера, и
+  Редактор сообщает об смене движка по нему.
+
+  Модуль вынесен из `handle.ts` и не знает движка: подписаться на смену движка
+  нужно и `RichTextToc`, а ему Tiptap в бандл не нужен.
+*/
+
+const watchers = new WeakMap<object, Set<() => void>>();
+
+/** Подписка хука на смену движка у Редактора, привязанного к этому `ref`. */
+export function watchHandleEditor(ref: RefObject<unknown>, listener: () => void): () => void {
+  let set = watchers.get(ref);
+  if (!set) watchers.set(ref, (set = new Set()));
+  set.add(listener);
+  return () => void set.delete(listener);
+}
+
+/** Редактор сообщает: движок у `ref` появился или сменился. */
+export function notifyHandleEditor(ref: unknown): void {
+  if (typeof ref !== "object" || ref === null) return;
+  watchers.get(ref)?.forEach((listener) => listener());
+}
+
+/**
+ * Сигналы кита для `useRichTextToolState`: то, что меняется не транзакцией
+ * движка, а интерфейсом Инструмента, и поэтому в движке его не прочитать.
+ * Редактор кладёт их по `ref`, как и сообщение о движке, и хук получает
+ * уведомление той же подпиской.
+ */
+export interface ToolSignals {
+  /** Набор Инструментов этого Редактора: есть ли Инструмент и с какими Опциями. */
+  tools?: ToolList;
+  /** Панель Поиска открыта (состояние React в `RichTextEditor`). */
+  searchOpen?: boolean;
+  /** Индекс текущего раздела Оглавления (вычисляет `TocCore` от прокрутки). */
+  tocAt?: number;
+}
+
+const signals = new WeakMap<object, ToolSignals>();
+
+/**
+ * Редактор сообщает сигналы Инструментов: слитые с прежними, подписчикам идёт то
+ * же уведомление, что и о смене движка.
+ */
+export function publishToolSignals(ref: unknown, next: ToolSignals): void {
+  if (typeof ref !== "object" || ref === null) return;
+  signals.set(ref, { ...signals.get(ref), ...next });
+  notifyHandleEditor(ref);
+}
+
+/**
+ * Редактор размонтирован: его сигналы уходят вместе с ним. Иначе они пережили бы
+ * его в таблице по `ref`, и хук отдавал бы снимок уже не существующего Редактора
+ * (а новый Редактор под тем же `ref` начинал бы с чужих сигналов). Подписчики
+ * получают уведомление: компонент, который из-за размонтирования не
+ * перерисовывается сам, узнаёт о нём только так.
+ */
+export function clearToolSignals(ref: unknown): void {
+  if (typeof ref !== "object" || ref === null || !signals.delete(ref)) return;
+  notifyHandleEditor(ref);
+}
+
+/** Сигналы Инструментов Редактора, привязанного к `ref`. */
+export function toolSignals(ref: object): ToolSignals {
+  return signals.get(ref) ?? {};
+}

package/src/editor/core/nodeNames.ts

@@ -0,0 +1,7 @@
+/**
+ * Имена узлов Схемы, которые знает не только движок. Модуль без Tiptap: имя
+ * нужно и Оглавлению (`features/toc`), которому движок в бандл не нужен.
+ */
+
+/** Имя узла Обёртки в Схеме движка (ADR-0057). */
+export const WRAPPER_NODE = "wrapper";

package/src/editor/core/schema.ts

@@ -3,6 +3,7 @@ import { EDITOR_LAYOUTS } from "../features/layout/columnLayouts.js";
 import { CUSTOM_COLOR_STYLE_PATTERN } from "../features/color/customColor.js";
 import { devWarn } from "../../lib/dev-warn.js";
 import type { CustomAttribute, PrefixedName, ToolEntry } from "./customTool.js";
+import { customToolOf } from "./toolDefinition.js";
 import {
   EDITOR_ALIGNMENTS,
   EDITOR_MARKER_NAMES,
@@ -375,8 +376,10 @@ function customAttributes(
 export function richTextSchema(tools: readonly ToolEntry[] = []): RichTextSchema {
   const customBlocks: Record<PrefixedName, RichTextCustomBlockRules> = {};
   const customMarks: Record<PrefixedName, RichTextCustomMarkRules> = {};
-  for (const tool of tools) {
-    if (typeof tool !== "object" || tool === null) continue;
+  for (const entry of tools) {
+    // Строка — имя кита, Настроенный встроенный — его опции: Схемы у них нет.
+    const tool = customToolOf(entry);
+    if (!tool) continue;
     for (const [name, block] of Object.entries(tool.blocks ?? {})) {
       if (!CUSTOM_NAME.test(name)) continue;
       const kind = block.kind === "inline" ? "inline" : "block";

package/src/editor/core/toolCommands.ts

@@ -0,0 +1,85 @@
+import type { RichTextTools, SearchToolOptions } from "./toolOptions.js";
+
+/*
+  Команды Инструмента: типы того, что экран вызывает через `handle.tool(name)`.
+  Модуль серверно-безопасен, как `toolOptions.ts`: одни типы, без Tiptap и React.
+  Реализации встроенных лежат рядом с их описаниями (`searchTool.ts`, `tocTool.ts`).
+*/
+
+/**
+ * Команды Инструмента `search`. Каждая возвращает `boolean`: выполнена или нет
+ * (HTML-режим, нет совпадений, поле нельзя править). Команды ведут себя как
+ * панель «Поиск и замена»: тот же запрос, те же флажки, та же подсветка.
+ * Запрос и флажки живут в движке, поэтому `setQuery`, `next` и `replace` работают
+ * и без открытой панели — на них можно собрать свой интерфейс поиска.
+ */
+export interface SearchToolCommands {
+  /**
+   * Открыть панель — то же, что кнопка «Поиск» и `Mod+F`. `query` сразу ставит
+   * запрос в поле и в подсветку документа; без него запросом становится текст,
+   * выделенный в одном Блоке. `replace` ставит фокус в поле замены. Флажки на
+   * открытой панели не меняются, на закрытой панель стартует с Опций Инструмента.
+   * `false` — в HTML-режиме (Документа на экране нет).
+   */
+  open(options?: { replace?: boolean; query?: string }): boolean;
+  /**
+   * Закрыть панель и убрать подсветку. Фокус и каретка остаются где были:
+   * в отличие от Escape в панели, команда в Документ их не переводит. Панель,
+   * уже закрытая, — не ошибка: подсветка всё равно убирается.
+   */
+  close(): boolean;
+  /**
+   * Задать запрос. Не названные в `flags` флажки (и флажки со значением
+   * `undefined`) берутся из открытой панели, а если её нет — из Опций
+   * Инструмента. Открытая панель показывает новый запрос
+   * и флажки. Непустой запрос прокручивает к первому совпадению после каретки,
+   * как `next` (прокрутка приходит чуть позже). `true` — запрос применён, даже
+   * если совпадений нет (их число — Состояние Инструмента); `false` — в
+   * HTML-режиме.
+   */
+  setQuery(query: string, flags?: Partial<SearchToolOptions>): boolean;
+  /**
+   * Следующее совпадение по кругу, выделяет его и прокручивает к нему ближайшую
+   * прокручиваемую область поля или окно — как панель, даже когда фокус вне
+   * Документа; фокус при этом не забирается. Прокрутка приходит чуть позже
+   * вызова (микрозадачей и кадром): её код грузится при первом вызове. `false` —
+   * совпадений нет.
+   */
+  next(): boolean;
+  /** Предыдущее совпадение по кругу; выделяет и прокручивает, как `next`. `false` — совпадений нет. */
+  previous(): boolean;
+  /**
+   * Заменить текущее совпадение: одна правка, одна отмена. Текущим становится
+   * следующее. `false` — совпадений нет или поле нельзя править.
+   */
+  replace(text: string): boolean;
+  /** Заменить все совпадения: одна правка, одна отмена. Условия — как у `replace`. */
+  replaceAll(text: string): boolean;
+}
+
+/** Команды Инструмента `toc`. */
+export interface TocToolCommands {
+  /**
+   * Перейти к заголовку списка Оглавления — как клик по пункту. Индекс считается
+   * в том же списке, что и пункты: с учётом `levels`, с нуля, пустые заголовки
+   * пропускаются. В правке каретка встаёт в конец заголовка, в `readOnly` фокус
+   * получает сам заголовок; прокрутка ставит его под липкую шапку (`offsetVar`) и
+   * Панель, подсветка заголовка гаснет.
+   *
+   * `false` — нет заголовка с таким индексом, либо Оглавление ещё не готово: его
+   * UI грузится отдельным куском после создания движка, и в HTML-режиме его нет.
+   * Заголовков меньше двух — не причина отказа: полоса не рисуется, но список
+   * есть, и переход работает.
+   */
+  jumpTo(index: number): boolean;
+}
+
+/**
+ * Команды Инструмента по имени из карты `RichTextTools`. Имя вне карты — `unknown`:
+ * типизация добровольна, Инструмент работает и без неё.
+ */
+export type ToolCommandsOf<Name extends string> = Name extends keyof RichTextTools
+  ? RichTextTools[Name] extends { commands: infer Commands }
+    ? Commands
+    : unknown
+  : unknown;

package/src/editor/core/toolDefinition.ts

@@ -0,0 +1,208 @@
+import type { Editor } from "@tiptap/core";
+import type { CustomTool, PrefixedName, ToolEntry } from "./customTool.js";
+import { isConfiguredTool, mergeOptions } from "./toolOptions.js";
+
+/*
+  Свой Инструмент с Опциями, Состоянием и Командами: `defineTool()`.
+
+  Модуль серверно-безопасен, как `customTool.ts` и `toolOptions.ts`: типы и одна
+  функция над данными, Tiptap здесь — только тип. `defineTool` — сахар над той
+  же формой `CustomTool` (ADR-0058): отдельного пути сборки у определения нет,
+  кит собирает из него обычное описание Инструмента (`describeDefinition`), и
+  все правила своего Инструмента — Префикс потребителя, уникальность имени,
+  проверки набора, загрузчик Части для движка — действуют как были.
+
+  ИМЯ ФАЙЛА — НЕ `defineTool.ts`. Под этим именем сборка потребителя на Next.js
+  15.5 (`check:consumer`) теряла `RichTextEditor` из клиентского манифеста RSC:
+  страница с ним из серверного компонента падала при пререндере. Тот же код под
+  другим именем или внутри соседнего модуля собирается; причина — в сборщике, а
+  не в коде. Переименовывать обратно — только с прогоном `check:consumer`.
+*/
+
+/**
+ * Тело описания своего Инструмента: форма `CustomTool` без имени. Имя задаёт
+ * определение, поэтому оно не может разойтись с тем, под каким определение лежит
+ * в `tools`.
+ */
+export type CustomToolBody = Omit<CustomTool, "name">;
+
+/**
+ * Что получают `state` и `commands` определения: живой движок и Опции этого
+ * Редактора — умолчания `defaults`, слитые с `tool(definition, options)`.
+ */
+export interface ToolDefinitionContext<Options extends object = object> {
+  /** Живой движок: функцию зовут, только когда он создан и не уничтожен. */
+  editor: Editor;
+  /** Опции этого Редактора. Читать, а не менять: объект общий для `create`, `state` и `commands`. */
+  options: Options;
+}
+
+/**
+ * Что автор передаёт `defineTool()`: поля определения без служебной метки.
+ */
+export interface ToolDefinitionInput<
+  Name extends PrefixedName = PrefixedName,
+  Options extends object = object,
+  State = unknown,
+  Commands extends object = object,
+> {
+  /** Имя с Префиксом потребителя, уникальное в `tools`. */
+  name: Name;
+  /** Умолчания Опций: полный набор полей. Из них выводится тип Опций. */
+  defaults: Options;
+  /** Тело описания Инструмента от Опций этого Редактора. */
+  create(options: Options): CustomToolBody;
+  /**
+   * Состояние Инструмента, если оно есть. Экран перерисовывается, только когда
+   * снимок сменился, и экономия работает для простых данных: примитивов, массивов
+   * и простых объектов, их кит сравнивает по значению. `Date`, `Map`, `Set` и
+   * экземпляры классов сравниваются по ссылке: новый экземпляр — новый снимок. Если
+   * функция создаёт такое значение заново на каждый вызов, экран перерисуется на
+   * каждой транзакции (а в худшем случае React уйдёт в цикл): отдавайте простые
+   * данные (`date.toISOString()`, массив из `Map`) или одну и ту же ссылку, пока
+   * данные не изменились.
+   */
+  state?(context: ToolDefinitionContext<Options>): State;
+  /** Команды Инструмента, если они есть. */
+  commands?(context: ToolDefinitionContext<Options>): Commands;
+}
+
+/**
+ * Определение своего Инструмента: то, что возвращает `defineTool()`. Элемент
+ * `tools` — его можно положить туда как есть (с `defaults`) или настроить через
+ * `tool(definition, options)`. Поля читает кит, экрану они не нужны.
+ */
+export interface ToolDefinition<
+  Name extends PrefixedName = PrefixedName,
+  Options extends object = object,
+  State = unknown,
+  Commands extends object = object,
+> extends ToolDefinitionInput<Name, Options, State, Commands> {
+  /** Метка определения: по ней `tools` отличает его от обычного `CustomTool`. */
+  readonly defined: true;
+}
+
+/**
+ * Определить свой Инструмент с Опциями, Состоянием и Командами. Экран настраивает
+ * его тем же `tool()`, что и встроенный, а читает тем же `useRichTextToolState`
+ * и `handle.tool()`:
+ *
+ * ```ts
+ * export const mention = defineTool({
+ *   name: "acme_mention",
+ *   defaults: { labels: { insert: "Mention" }, limit: 5 },
+ *   create: (options) => ({
+ *     engine: () => import("./mentionEngine.js").then((module) => module.engine),
+ *     blocks: { acme_mention: { kind: "inline" } },
+ *     insertItems: [{ section: "insert", label: options.labels.insert, icon: AtIcon, run }],
+ *   }),
+ *   state: ({ editor }) => ({ mentions: countMentions(editor) }),
+ *   commands: ({ editor, options }) => ({ insert: (name: string) => … }),
+ * });
+ *
+ * <RichTextEditor tools={[mention]} />                                         // умолчания
+ * <RichTextEditor tools={[tool(mention, { labels: { insert: "Отметить" } })]} /> // настройка
+ * ```
+ *
+ * - `defaults` — полный набор Опций; тип Опций выводится из него, второй раз его
+ *   объявлять не нужно.
+ * - `create(options)` отдаёт тело описания — ту же форму, что `CustomTool`, без
+ *   имени: Часть для движка, правила Схемы, UI-записи. Зовётся один раз на запись
+ *   `tools` (определение само или объект, что вернул `tool(definition, options)`):
+ *   кит запоминает результат, и Остров, замкнутый над Опциями, один и тот же на
+ *   каждом рендере. Запись, созданная заново на каждом рендере экрана
+ *   (`tools={[tool(mention, …)]}` в теле компонента), для кита новая — выносите
+ *   `tools` из рендера. Загрузчик Части для движка стоит держать константой
+ *   модуля: кэш загрузчика живёт на самой функции, а новая функция на каждый
+ *   вызов `create` загружала бы Часть заново для каждой записи.
+ * - `state({ editor, options })` — Состояние для `useRichTextToolState(ref, name)`.
+ *   Зовётся при каждой транзакции и при каждом чтении хука, поэтому должна быть
+ *   быстрой и без побочных эффектов; вернуть — данные без DOM-узлов. Простые данные
+ *   (примитивы, массивы, простые объекты) сравниваются по значению, всё прочее
+ *   (`Date`, `Map`, `Set`, экземпляры классов) — по ссылке. Нет — у Инструмента нет
+ *   Состояния, и хук отдаёт `null`.
+ * - `commands({ editor, options })` — Команды для `handle.tool(name)`. Зовётся при
+ *   каждом обращении к Хэндлу: только обёртки над движком, без подписок. Команда
+ *   возвращает `boolean`, как у встроенных. Нет — `handle.tool(name)` отдаёт `null`.
+ *
+ * Слияние Опций: вложенные простые объекты сливаются с умолчаниями, массивы и
+ * функции заменяются целиком, как `configure` у Tiptap. Опции читаются один раз,
+ * при создании движка; чтобы сменить их, пересоздайте Редактор через `key`.
+ * Проверять значения Опций должен автор: кит этого не делает.
+ *
+ * Все правила своего Инструмента действуют (ADR-0058): имя с Префиксом
+ * потребителя, имя уникально в `tools` — и две записи одного определения, с
+ * `tool()` и без, тоже ошибка набора. Типизация `useRichTextToolState` и
+ * `handle.tool()` — через карту `RichTextTools`: автор дописывает Инструмент в неё
+ * через `declare module "@olddevs/ui/editor"`; без этого они отдают `unknown`.
+ *
+ * Серверно-безопасна: модуль без Tiptap и React. Определение содержит функции, как
+ * и `CustomTool`, поэтому набор с ним собирается в серверном модуле и отдаётся
+ * клиентскому компоненту только вместе с модулем, а не как проп через границу RSC.
+ */
+export function defineTool<
+  Name extends PrefixedName,
+  Options extends object,
+  State = unknown,
+  Commands extends object = object,
+>(
+  definition: ToolDefinitionInput<Name, Options, State, Commands>
+): ToolDefinition<Name, Options, State, Commands> {
+  return { ...definition, defined: true };
+}
+
+/** Определение, собранное под одни Опции: слитые Опции и `CustomTool` с телом из `create`. */
+interface ResolvedDefinition {
+  options: object;
+  tool: CustomTool;
+}
+
+/** Ключ записи без `tool()`: у неё нет объекта Опций, определение берётся с умолчаниями. */
+const NO_OPTIONS: object = {};
+
+/**
+ * Что уже собрано: определение, затем объект Опций записи `tool()`. Слабые
+ * ссылки — запись, которую экран отпустил, уходит вместе с результатом.
+ */
+const resolved = new WeakMap<ToolDefinition, WeakMap<object, ResolvedDefinition>>();
+
+/**
+ * Определение в обычное описание: Опции этого Редактора (умолчания, слитые с
+ * `given` — опциями `tool()`) и `CustomTool` с телом из `create`. Дальше
+ * Инструмент идёт тем же путём, что и описанный объектом.
+ *
+ * РЕЗУЛЬТАТ ЗАПОМИНАЕТСЯ по паре «определение + объект Опций записи `tool()`»
+ * (записи без `tool()` — по одному определению). `create` — функция автора, и
+ * Остров, замкнутый над Опциями, она создаёт заново на каждый вызов; а
+ * `richTextSchema`, `islandsFor`, `sanitizeRichText` и сборка набора читают
+ * определение каждый на своём рендере. Без запоминания клиентский родитель, что
+ * перерисовывает `RichTextView` с теми же `tools`, получал бы новый тип
+ * компонента на каждый рендер, а React размонтировал бы Остров. Одна запись
+ * `tools` — один `CustomTool`, пока жива запись.
+ */
+export function resolveDefinition(definition: ToolDefinition, given?: object): ResolvedDefinition {
+  const key = given ?? NO_OPTIONS;
+  let byOptions = resolved.get(definition);
+  if (!byOptions) resolved.set(definition, (byOptions = new WeakMap()));
+  let result = byOptions.get(key);
+  if (!result) {
+    const options = mergeOptions(definition.defaults, given ?? {});
+    result = { options, tool: { ...definition.create(options), name: definition.name } };
+    byOptions.set(key, result);
+  }
+  return result;
+}
+
+/**
+ * Описание своего Инструмента из элемента `tools`: обычный объект как есть,
+ * определение — собранное по умолчаниям или Опциям `tool()`. Имя кита и
+ * Настроенный встроенный Инструмент — `undefined`: Схемы и Острова у них нет.
+ * Для сервера: `richTextSchema` и `islandsFor` читают правила только отсюда.
+ */
+export function customToolOf(entry: ToolEntry): CustomTool | undefined {
+  if (typeof entry !== "object" || entry === null) return undefined;
+  if (isConfiguredTool(entry)) {
+    return entry.definition && resolveDefinition(entry.definition, entry.options).tool;
+  }
+  return "defined" in entry ? resolveDefinition(entry).tool : entry;
+}

package/src/editor/core/toolDescriptor.ts

@@ -13,6 +13,7 @@ import type {
 import type { EditorExtensionOptions } from "./extensions.js";
 import type { InsertItem } from "./insertItems.js";
 import type { ShortcutCommand, ShortcutGroup } from "./shortcuts.js";
+import type { ConfigurableToolName, RichTextTools } from "./toolOptions.js";
 import type { ToolLoader } from "./toolLoader.js";
 import type { Tool } from "./tools.js";
 
@@ -55,8 +56,9 @@ export interface ToolDescriptor {
    * Часть для движка: расширения Tiptap Инструмента — Node, Mark, Extension,
    * плагины ProseMirror. Функция от контекста — привилегия кита: встроенным
    * нужны мосты `RichTextEditor` (поповер ссылки, Меню вставки, `Alt+F10`).
+   * Второй аргумент — Опции этого Редактора (`options`), если они есть.
    */
-  engine?: (context: ToolEngineContext) => Extensions;
+  engine?: (context: ToolEngineContext, options?: object) => Extensions;
   /**
    * Загрузчик Части для движка (`toolLoader.ts`): движок создаётся после
    * загрузчиков всех описаний списка, и `engine` читает отданное `loaded`.
@@ -72,6 +74,27 @@ export interface ToolDescriptor {
   /** Признаки Блока по имени узла; кит переносит их в spec узла. Нет — обычный Блок. */
   blocks?: Readonly<Record<string, BlockTraits>>;
 
+  /* Опции. */
+
+  /**
+   * Умолчания Опций встроенного Инструмента: полный набор полей, из которого
+   * `tool()` меняет нужные. Нет — у Инструмента нет Опций. Поле — надформа:
+   * публичные Опции своего Инструмента задаёт `defineTool` (`defaults`).
+   */
+  defaults?: object;
+  /**
+   * Проверки значений Опций по имени поля — по одной на каждое поле `defaults`.
+   * Значение, не прошедшее проверку, заменяется умолчанием (`expandTools`):
+   * потребитель на JS обходит типы карты `RichTextTools`.
+   */
+  checks?: Readonly<Record<string, (value: unknown) => boolean>>;
+  /**
+   * Опции этого Редактора: умолчания, слитые с `tool()`. Ставит `expandTools`
+   * при сборке набора, поэтому описание в реестре — общее на все Редакторы, а
+   * это поле — своё в списке каждого. Читаются один раз, вместе с набором.
+   */
+  options?: object;
+
   /* UI-записи. */
 
   /**
@@ -115,6 +138,52 @@ export interface ToolDescriptor {
    * (`shortcuts.ts`): у записи сочетание — её поле, а у Метки из движка — нет.
    */
   shortcuts?: readonly ShortcutCommand[];
+
+  /* Команды. */
+
+  /**
+   * Команды Инструмента: то, что `handle.tool(name)` отдаёт экрану. Зовётся при
+   * каждом обращении к Хэндлу и обязана быть дешёвой: только обёртки над движком
+   * и мостом, без подписок и состояния. Нет — у Инструмента нет Команд, и
+   * `handle.tool(name)` отдаёт `null`.
+   */
+  commands?: (context: ToolCommandsContext) => object;
+
+  /* Состояние. */
+
+  /**
+   * Состояние Инструмента: снимок для `useRichTextToolState(ref, name)`. Хук
+   * зовёт её на каждую транзакцию и каждое чтение, поэтому она быстрая и без
+   * побочных эффектов. Есть только у своего Инструмента (`defineTool`): снимки
+   * встроенных хук держит у себя (`SNAPSHOTS`), чтобы Поиск и Оглавление не
+   * тянули их код в стартовый кусок Редактора. Нет — Состояния у Инструмента нет.
+   */
+  state?: (editor: Editor) => unknown;
+}
+
+/** Что функция Команд получает от `RichTextEditor`. */
+export interface ToolCommandsContext {
+  /** Живой движок: функцию зовут, только когда он создан и не уничтожен. */
+  editor: Editor;
+  /** Мост к тому, что держит сам `RichTextEditor`: панели и ленивый UI. */
+  bridge: ToolBridge;
+}
+
+/**
+ * Что Команды встроенных берут у `RichTextEditor`: панель Поиска и ядро
+ * Оглавления живут в его React-дереве, а не в движке. Все методы возвращают
+ * `false`, когда сделать нельзя (HTML-режим, UI ещё не загружен). Привилегия
+ * кита: свой Инструмент моста не получает.
+ */
+export interface ToolBridge {
+  /** Открыть панель Поиска; `query` — сразу в поле, без него — выделенный текст. */
+  openSearch: (replace: boolean, query?: string) => boolean;
+  /** Закрыть панель Поиска и убрать подсветку, не трогая фокус. */
+  closeSearch: () => boolean;
+  /** Открыт ли HTML-режим: Документа на экране нет, искать и заменять в нём нельзя. */
+  sourceOpen: () => boolean;
+  /** Перейти к заголовку Оглавления с индексом списка. */
+  jumpToc: (index: number) => boolean;
 }
 
 /** Символ-триггер Инструмента в списке описаний: публичная запись и имя владельца для сообщений. */
@@ -274,6 +343,12 @@ export interface TextCardRecord {
  * Инструменты есть только в списке описаний.
  */
 export interface ToolList extends ReadonlySet<Tool> {
+  /**
+   * Ошибка сборки набора, найденная до движка: две записи `tool()` с одним
+   * именем. Редактор показывает её тем же путём, что ошибки своих Инструментов
+   * (`customToolsError`): строкой поля и `console.error` в разработке.
+   */
+  readonly error?: string;
   /**
    * Описания включённых Инструментов: встроенные в порядке кита (у не
    * переехавших — заглушки `legacy`), за ними свои в порядке `tools`.
@@ -285,8 +360,24 @@ export interface ToolList extends ReadonlySet<Tool> {
  * Набор из имён кита и списка описаний — единственный способ его собрать:
  * развернуть `tools` (`expandTools`) или сузить готовый (Скелет).
  */
-export function toolList(names: Iterable<Tool>, descriptors: readonly ToolDescriptor[]): ToolList {
-  return Object.assign(new Set(names), { descriptors });
+export function toolList(
+  names: Iterable<Tool>,
+  descriptors: readonly ToolDescriptor[],
+  error?: string
+): ToolList {
+  return Object.assign(new Set(names), { descriptors, ...(error !== undefined && { error }) });
+}
+
+/**
+ * Опции встроенного Инструмента этого Редактора: умолчания кита, слитые с
+ * `tool()`. Инструмента нет в наборе или у него нет Опций — `undefined`.
+ */
+export function toolOptions<Name extends ConfigurableToolName>(
+  tools: ToolList,
+  name: Name
+): RichTextTools[Name]["options"] | undefined {
+  const descriptor = tools.descriptors.find((candidate) => candidate.name === name);
+  return descriptor?.options as RichTextTools[Name]["options"] | undefined;
 }
 
 /** Описания переехавших Инструментов набора — в порядке списка. */