@olddevs/ui 4.4.0 → 4.5.1

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;
 }
 
 /** Описания переехавших Инструментов набора — в порядке списка. */

package/src/editor/core/toolOptions.ts

@@ -0,0 +1,211 @@
+import type { PrefixedName } from "./customTool.js";
+import type { ToolDefinition } from "./toolDefinition.js";
+import type { SearchToolState, TocToolState } from "./toolState.js";
+import type { SearchToolCommands, TocToolCommands } from "./toolCommands.js";
+import type { Tool as ToolName } from "./tools.js";
+
+/*
+  Опции Инструмента: `tool()` и карта `RichTextTools`. Модуль серверно-безопасен,
+  как `customTool.ts`: типы и функции над данными, без Tiptap и React. Набор
+  `tools` собирается в серверном модуле экрана рядом с остальной конфигурацией,
+  и Настроенный Инструмент — обычный объект из данных, без функций: его можно
+  отдать клиентскому компоненту через границу RSC, если сами опции — данные.
+*/
+
+/**
+ * Уровень заголовка в опциях Оглавления: 1 — `h1` … 4 — `h4`. Выше четвёртого
+ * Схема кита заголовков не знает.
+ */
+export type TocLevel = 1 | 2 | 3 | 4;
+
+/**
+ * Опции Инструмента `search` (все значения — со стартовыми умолчаниями кита).
+ * Это стартовые флажки поиска вообще, а не только панели: запрос, который
+ * задаёт Команда `setQuery`, берёт не названные в ней флажки отсюда, пока
+ * поиск не закрыт (`close()`, Escape в панели).
+ */
+export interface SearchToolOptions {
+  /**
+   * Панель открывается с включённым флажком «Регистр». Флажок остаётся
+   * переключаемым; кит не запоминает его между открытиями. По умолчанию `false`.
+   */
+  matchCase: boolean;
+  /** Панель открывается с включённым флажком «Слово целиком». По умолчанию `false`. */
+  wholeWord: boolean;
+  /** Панель открывается с включённым переключателем «Регулярное выражение». По умолчанию `false`. */
+  regex: boolean;
+}
+
+/** Опции Инструмента `toc` (ADR-0068). */
+export interface TocToolOptions {
+  /**
+   * Имя CSS-переменной с высотой липкой шапки экрана (ADR-0016): переход к
+   * заголовку ставит его под шапку, а подсветка считает раздел текущим от её
+   * нижнего края. Значение — имя переменной целиком, с двумя дефисами:
+   * `--header-h`. Липкую Панель Редактора это не двигает: она по-прежнему
+   * стоит под `--topbar-h`. По умолчанию `--topbar-h`.
+   */
+  offsetVar: string;
+  /**
+   * Уровни заголовков, которые попадают в Оглавление: подмножество 1–4. Заголовка
+   * другого уровня нет ни в полосе, ни в списке, и отступ пунктов считается
+   * от самого крупного из оставшихся. По умолчанию все четыре.
+   */
+  levels: readonly TocLevel[];
+  /**
+   * Ширина списка — длина CSS или пиксели. Постоянная, а не по самому длинному
+   * заголовку. По умолчанию 240.
+   */
+  listWidth: number | string;
+}
+
+/**
+ * Типы Инструментов Редактора по имени: что экран задаёт при настройке (`options`),
+ * что читает (`state`) и что вызывает (`commands`). Расширяемый интерфейс, как
+ * `Storage` и `Commands` у Tiptap: кит объявляет в нём `search` и `toc`, а
+ * потребитель дописывает свои Инструменты через declaration merging:
+ *
+ * ```ts
+ * declare module "@olddevs/ui/editor" {
+ *   interface RichTextTools {
+ *     acme_note: {
+ *       options: { tone: "info" | "warning" };
+ *       state: { count: number };
+ *       commands: { clear(): boolean };
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * Из карты выводятся типы `useRichTextToolState`, `handle.tool()` и Опции `tool()`
+ * встроенного; Опции своего Инструмента `tool()` берёт из `defaults` его определения.
+ * Инструмент, не дописанный в карту, работает: типизация добровольна.
+ */
+export interface RichTextTools {
+  search: {
+    options: SearchToolOptions;
+    state: SearchToolState;
+    commands: SearchToolCommands;
+  };
+  toc: {
+    options: TocToolOptions;
+    state: TocToolState;
+    commands: TocToolCommands;
+  };
+}
+
+/**
+ * Имена встроенных Инструментов, у которых есть опции: ключи карты, совпадающие
+ * с именами кита. Свой Инструмент, дописанный в карту, сюда не попадает —
+ * настраивается по определению, а не по имени.
+ */
+export type ConfigurableToolName = keyof RichTextTools & ToolName;
+
+/** Опции Инструмента из карты; нет карты или `options` — `never`. */
+type OptionsOf<Name extends ConfigurableToolName> = RichTextTools[Name] extends {
+  options: infer Options;
+}
+  ? Options
+  : never;
+
+/**
+ * Опции, которые экран передаёт `tool()`: каждое поле необязательно, остальное
+ * берётся из умолчаний. Вложенные объекты вкладываются так же, а массивы и
+ * функции — значение целиком (правило слияния, `mergeOptions`).
+ */
+export type ToolOptionsInput<Options> = {
+  [Key in keyof Options]?: Options[Key] extends readonly unknown[] | ((...args: never[]) => unknown)
+    ? Options[Key]
+    : Options[Key] extends object
+      ? ToolOptionsInput<Options[Key]>
+      : Options[Key];
+};
+
+/**
+ * Настроенный Инструмент: запись для `tools`, которую возвращает `tool()`.
+ * Непрозрачная — поля читает только кит. У встроенного это имя и опции, а не
+ * описание: описания встроенных наружу не выходят (ADR-0058, п. 10.3). У своего
+ * Инструмента добавляется определение, которое `tool()` настраивает.
+ */
+export interface ConfiguredTool<Name extends string = ToolName> {
+  /** Метка записи: по ней `tools` отличает Настроенный Инструмент от своего. */
+  readonly configured: true;
+  readonly name: Name;
+  readonly options: Readonly<Record<string, unknown>>;
+  /** Определение своего Инструмента (`defineTool`); у встроенного его нет. */
+  readonly definition?: ToolDefinition;
+}
+
+/**
+ * Слить Опции: вложенные простые объекты сливаются, массивы, функции и всё
+ * остальное заменяются целиком — как `configure` у Tiptap. Значение `undefined`
+ * не в счёт: остаётся то, что было. Новый объект, исходные не меняются (вложенный
+ * объект, которого нет в `given`, остаётся тем же).
+ */
+export function mergeOptions(base: object, given: object): object {
+  // Простой объект — литерал; экземпляры классов, `Date`, React-элементы — значения.
+  const plain = (value: unknown): value is object =>
+    (value as { constructor?: unknown } | null)?.constructor === Object;
+  const result: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(given)) {
+    if (value !== undefined) {
+      result[key] = plain(value) && plain(result[key]) ? mergeOptions(result[key], value) : value;
+    }
+  }
+  return result;
+}
+
+/**
+ * Настроить Инструмент прямо в `tools`: встроенный — по имени, свой — по
+ * определению (`defineTool`).
+ *
+ * ```tsx
+ * <RichTextEditor
+ *   tools={[
+ *     ...RICH_TEXT_PRESETS.full,
+ *     tool("toc", { offsetVar: "--header-h", levels: [2, 3] }),
+ *     tool(mention, { labels: { insert: "Отметить коллегу" } }),
+ *   ]}
+ * />
+ * ```
+ *
+ * Запись включает Инструмент и без имени в `tools`; если в `tools` есть и голое
+ * имя (из пресета), побеждает Настроенный Инструмент. Две записи `tool()` с
+ * одним встроенным именем — ошибка набора, как и две записи одного своего
+ * Инструмента. Место на поверхности не меняется: у встроенного оно
+ * определяется порядком кита, у своего — порядком `tools`. Передавать нужно
+ * только те опции, которые меняются, остальные берутся из умолчаний; вложенные
+ * объекты сливаются, массивы и функции заменяются целиком.
+ *
+ * Опции читаются один раз, вместе с набором, при создании движка. Чтобы сменить
+ * их на лету, пересоздайте Редактор через `key`. Неверное значение встроенной
+ * опции (из JS без типов) заменяется умолчанием, в разработке — один
+ * `console.error`; опции своего Инструмента проверяет его автор.
+ *
+ * Встроенный — только Инструмент с опциями: `search` и `toc`. Серверно-безопасна.
+ */
+export function tool<Name extends ConfigurableToolName>(
+  name: Name,
+  options?: ToolOptionsInput<OptionsOf<Name>>
+): ConfiguredTool<Name>;
+export function tool<Name extends PrefixedName, Options extends object>(
+  definition: ToolDefinition<Name, Options, unknown, object>,
+  options?: ToolOptionsInput<Options>
+): ConfiguredTool<Name>;
+export function tool(
+  entry: ToolName | ToolDefinition,
+  options: Record<string, unknown> = {}
+): ConfiguredTool<string> {
+  return typeof entry === "string"
+    ? { configured: true, name: entry, options }
+    : { configured: true, name: entry.name, options, definition: entry };
+}
+
+/** Запись `tools` — Настроенный Инструмент. `null` и строки — нет. */
+export function isConfiguredTool(entry: unknown): entry is ConfiguredTool<string> {
+  return (
+    typeof entry === "object" &&
+    entry !== null &&
+    (entry as { configured?: unknown }).configured === true
+  );
+}

package/src/editor/core/toolState.ts

@@ -0,0 +1,56 @@
+import type { SearchToolOptions, TocLevel } from "./toolOptions.js";
+
+/*
+  Снимки Состояния встроенных Инструментов: чистые данные для
+  `useRichTextToolState`. Модуль только из типов, серверно-безопасный, как
+  `toolOptions.ts`: карта `RichTextTools` ссылается на него в части `state`.
+  Узлов DOM, позиций ProseMirror и функций в снимках нет — их можно сравнить по
+  значению, сериализовать и передать через границу RSC.
+*/
+
+/** Состояние Инструмента `search` (ADR-0058). */
+export interface SearchToolState {
+  /** Панель Поиска открыта. */
+  open: boolean;
+  /**
+   * Запрос. Закрытие панели убирает запрос и подсветку; без панели запрос ставит
+   * Команда `setQuery`.
+   */
+  query: string;
+  /**
+   * Флажки поиска. Закрытие панели возвращает их к стартовым из Опций
+   * Инструмента, с которыми панель и откроется.
+   */
+  flags: Readonly<SearchToolOptions>;
+  /** Сколько совпадений запроса в Документе. */
+  total: number;
+  /** Индекс текущего совпадения, от 0; `-1` — совпадений нет. */
+  current: number;
+  /**
+   * Текст ошибки, если запрос — неверное регулярное выражение (сообщение движка
+   * JavaScript, не локализованное); иначе `null`. Совпадений при ошибке нет.
+   */
+  error: string | null;
+}
+
+/** Заголовок в Состоянии Инструмента `toc`: пункт списка Оглавления. */
+export interface TocToolHeading {
+  /** Уровень по тегу: 1 для `h1` … 4 для `h4`. */
+  level: TocLevel;
+  /** Текст пункта — текст заголовка без разметки, без крайних пробелов. */
+  text: string;
+  /** Номер пункта в списке Оглавления, от 0; по нему текущий раздел находит свой заголовок. */
+  index: number;
+}
+
+/** Состояние Инструмента `toc` (ADR-0068). */
+export interface TocToolState {
+  /**
+   * Заголовки Документа в порядке чтения — те же, что в полосе и списке Оглавления:
+   * верхний уровень и Обёртки, только уровни из Опции `levels`, без пустых.
+   * Список отдаётся и при одном заголовке, хотя полосы тогда нет.
+   */
+  headings: readonly TocToolHeading[];
+  /** Индекс текущего раздела в `headings`, от 0; `-1` — заголовков нет. Следует за прокруткой. */
+  current: number;
+}

package/src/editor/core/tools.ts

@@ -52,13 +52,15 @@
  *
  * `toc` — Оглавление в левом поле рамки (ADR-0068): полоса и список
  * `RichTextToc`, липкие под Панелью или в прокручиваемом поле. Своей Схемы нет.
+ * Настраивается записью `tool("toc", { offsetVar, levels, listWidth })`.
  * В пресеты не входит — ни в `full`, ни в `basic`: оно меняет раскладку поля,
  * и обновление кита не должно сдвигать текст там, где его не просили.
  *
  * `search` — поиск и замена по Документу: кнопка «Поиск»
  * фиксированной Панели и `Mod+F` в поле открывают панель в углу поля. Своей
  * Схемы нет, как у `clearFormatting`. Есть и в `basic`: искать по длинному
- * описанию нужно и там, а кнопка у правого края ряд не удлиняет.
+ * описанию нужно и там, а кнопка у правого края ряд не удлиняет. Стартовые
+ * флажки панели задаёт запись `tool("search", { matchCase, wholeWord, regex })`.
  */
 export const TOOLS = [
   "history",

package/src/editor/core/viewIsland.ts

@@ -1,5 +1,6 @@
 import type { ComponentType } from "react";
-import type { CustomIslandProps, CustomTool, ToolEntry } from "./customTool.js";
+import type { CustomIslandProps, ToolEntry } from "./customTool.js";
+import { customToolOf } from "./toolDefinition.js";
 
 /*
   Острова своих Блоков в Просмотре (ADR-0058, п. 3.3).
@@ -26,9 +27,9 @@ export interface ViewIsland {
  * или Блока нет в Документе — пустой список, и клиентского острова нет вовсе.
  */
 export function islandsFor(tools: readonly ToolEntry[] | undefined, html: string): ViewIsland[] {
-  // Строка из `tools` — имя Инструмента кита: поля `blocks` у неё нет, и она отсеивается сама.
-  return (tools ?? []).flatMap((tool) =>
-    Object.entries((tool as CustomTool).blocks ?? {}).flatMap(([block, { island, attributes }]) =>
+  // Строка из `tools` — имя Инструмента кита, Настроенный встроенный — его опции: блоков у них нет.
+  return (tools ?? []).flatMap((entry) =>
+    Object.entries(customToolOf(entry)?.blocks ?? {}).flatMap(([block, { island, attributes }]) =>
       island && html.includes(`data-block="${block}"`) ? [{ block, island, attributes }] : []
     )
   );