@olddevs/ui 4.3.0 → 4.5.0

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

@@ -50,10 +50,17 @@
  * разметку решает Схема, и режим её не расширяет. В `basic` его нет: в
  * комментарии кнопка «HTML» без явного запроса экрана — лишняя.
  *
+ * `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",
@@ -85,6 +92,7 @@ export const TOOLS = [
   "source",
   "search",
   "insertMenu",
+  "toc",
 ] as const;
 
 /** Имя инструмента Редактора. Список и смысл каждого — на странице компонента. */
@@ -104,7 +112,8 @@ export type RichTextEditorPreset = "full" | "basic";
  * markdown-шорткатом, чем через меню.
  */
 export const PRESETS: Record<RichTextEditorPreset, readonly Tool[]> = {
-  full: TOOLS,
+  // Все встроенные, кроме Оглавления: его включают только явно (ADR-0068).
+  full: TOOLS.filter((tool) => tool !== "toc"),
   basic: [
     "history",
     "bold",
@@ -122,7 +131,7 @@ export const PRESETS: Record<RichTextEditorPreset, readonly Tool[]> = {
 /**
  * Пресеты наружу — массивами (ADR-0058, п. 1.2): свой набор собирается из них,
  * например `[...RICH_TEXT_PRESETS.full, mergeTagTool]`. Копии заморожены:
- * `PRESETS.full` — это `TOOLS`, и правка массива потребителем меняла бы набор
+ * `PRESETS.full` — почти весь `TOOLS`, и правка массива потребителем меняла бы набор
  * кита во всех Редакторах страницы. Состав пресета — не контракт (ADR-0058,
  * п. 12.5): стабильный набор — точный список имён.
  */

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 }] : []
     )
   );

package/src/editor/features/builtins.ts

@@ -9,11 +9,14 @@ import type { ShortcutCommand } from "../core/shortcuts.js";
 import { CODE_BLOCK_TOOL } from "./code/codeBlockTool.js";
 import { EMOJI_TOOL } from "./emoji/emojiTool.js";
 import { LINK_TOOL } from "./link/linkTool.js";
-import type { CustomTool, ToolEntry } from "../core/customTool.js";
-import { describeCustomTool } from "../core/customToolEngine.js";
+import { devError } from "../../lib/dev-warn.js";
+import type { ToolEntry } from "../core/customTool.js";
+import { describeCustomTool, describeDefinition } from "../core/customToolEngine.js";
 import { toolList, type ToolDescriptor, type ToolList } from "../core/toolDescriptor.js";
+import { isConfiguredTool, mergeOptions, type ConfiguredTool } from "../core/toolOptions.js";
 import { SEARCH_TOOL } from "./search/searchTool.js";
 import { TABLE_TOOL } from "./table/tableTool.js";
+import { TOC_TOOL } from "./toc/tocTool.js";
 import { resolveTools, TOOLS, type RichTextEditorPreset, type Tool } from "../core/tools.js";
 import { unwrapWrapperAt, WRAPPER_NODE } from "./wrapper/wrapper.js";
 
@@ -51,6 +54,8 @@ const BLOCKQUOTE_ITEMS: readonly InsertItem[] = [
  */
 export const BUILTIN_TOOLS: Partial<Record<Tool, ToolDescriptor>> = {
   search: SEARCH_TOOL,
+  // Оглавление несёт только Опции: полоса и список рисуются в `RichTextEditor`.
+  toc: TOC_TOOL,
   /*
     Обёртка переехала только Действием над Блоком, поэтому
     `legacy`: её узел, вставка и сочетания остаются в старых реестрах. «Тон ›» —
@@ -115,31 +120,85 @@ export const BUILTIN_TOOLS: Partial<Record<Tool, ToolDescriptor>> = {
   table: TABLE_TOOL,
 };
 
+/**
+ * Опции Инструмента для Редактора: умолчания описания, поверх них — те, что
+ * передал `tool()`. Значение, не прошедшее проверку, и опция, которой у
+ * Инструмента нет (проверки для неё тоже нет), отбрасываются, в разработке —
+ * одним `console.error` на Инструмент: потребитель на JS обходит типы карты, а
+ * поле от этого не падает.
+ */
+function resolveOptions(
+  descriptor: ToolDescriptor,
+  configured: ConfiguredTool | undefined
+): ToolDescriptor {
+  const { defaults, checks } = descriptor;
+  const given = Object.entries(configured?.options ?? {}).filter(
+    ([, value]) => value !== undefined
+  );
+  const valid = given.filter(([key, value]) => checks?.[key]?.(value));
+  if (valid.length < given.length) {
+    devError(
+      `RichTextEditor: tool "${descriptor.name}": ignored invalid options: ` +
+        given
+          .filter((entry) => !valid.includes(entry))
+          .map(([key]) => key)
+          .join(", ")
+    );
+  }
+  return defaults
+    ? { ...descriptor, options: mergeOptions(defaults, Object.fromEntries(valid)) }
+    : descriptor;
+}
+
 /**
  * Развернуть `tools` (или `preset`) в один список описаний.
  *
  * Имена — те же, что у `resolveTools`: точный `tools` или пресет, неизвестная
- * строка отбрасывается молча. Порядок встроенных — порядок кита (`TOOLS`), а
- * не `tools`: место встроенного на поверхности решает кит. Свои Инструменты
- * (описания в `tools`) идут следом, в порядке `tools` (ADR-0058, п. 5.3);
- * набор имён (`Set`) — только имена кита.
+ * строка отбрасывается молча. Запись `tool()` включает Инструмент так же, как
+ * его имя, а если в `tools` есть и имя (из пресета), и запись, побеждает
+ * Настроенный Инструмент; две записи с одним именем — ошибка набора
+ * (`ToolList.error`). Порядок встроенных — порядок кита (`TOOLS`), а не
+ * `tools`: место встроенного на поверхности решает кит, и Настроенный стоит
+ * там же, где голое имя. Свои Инструменты (описания в `tools`) идут следом, в
+ * порядке `tools` (ADR-0058, п. 5.3); набор имён (`Set`) — только имена кита.
+ *
+ * Опции Инструментов читаются здесь, один раз, вместе с набором.
  */
 export function expandTools(
   preset: RichTextEditorPreset,
   tools: readonly ToolEntry[] | undefined
 ): ToolList {
+  // Настроенные встроенные: запись с определением настраивает свой Инструмент, она ниже.
+  const configured = (tools ?? []).filter(
+    (entry): entry is ConfiguredTool => isConfiguredTool(entry) && !entry.definition
+  );
+  const twice = configured.find((entry, index) =>
+    configured.some((e, i) => i < index && e.name === entry.name)
+  );
   const names = resolveTools(
     preset,
-    tools?.filter((tool): tool is Tool => typeof tool === "string")
+    tools && [
+      ...tools.filter((entry) => typeof entry === "string"),
+      ...configured.map((entry) => entry.name),
+    ]
   );
-  const builtin = TOOLS.filter((name) => names.has(name)).map(
-    (name): ToolDescriptor => BUILTIN_TOOLS[name] ?? { name, legacy: true }
+  const builtin = TOOLS.filter((name) => names.has(name)).map((name) =>
+    resolveOptions(
+      BUILTIN_TOOLS[name] ?? { name, legacy: true },
+      configured.find((entry) => entry.name === name)
+    )
   );
-  const custom = (tools ?? [])
-    .filter((tool): tool is CustomTool => typeof tool === "object" && tool !== null)
-    .map(describeCustomTool);
+  // Свои: определение (с `tool()` и без) и обычное описание; уникальность имени проверяет набор.
+  const custom = (tools ?? []).flatMap((entry) => {
+    if (typeof entry !== "object" || entry === null) return [];
+    if (isConfiguredTool(entry)) {
+      return entry.definition ? describeDefinition(entry.definition, entry.options) : [];
+    }
+    return "defined" in entry ? describeDefinition(entry) : describeCustomTool(entry);
+  });
   return toolList(
     builtin.map((descriptor) => descriptor.name as Tool),
-    [...builtin, ...custom]
+    [...builtin, ...custom],
+    twice && `tool "${twice.name}": two tool() entries share this name`
   );
 }

package/src/editor/features/search/SearchPanel.tsx

@@ -12,9 +12,12 @@ import { useMessages } from "../../../i18n/useMessages.js";
 import { cn } from "../../../lib/cn.js";
 import { GLASS_PANEL_CLASS } from "../../styles/glass.js";
 import type { SearchOptions } from "./searchMatch.js";
-import { revealCurrentMatch } from "./revealMatch.js";
+import { cancelRevealMatch, registerSearchOverlays, scheduleRevealMatch } from "./revealMatch.js";
 import { searchState } from "./searchPlugin.js";
 
+const NO_OPTIONS: SearchOptions = { matchCase: false, wholeWord: false, regex: false };
+const FLAGS = ["matchCase", "wholeWord", "regex"] as const;
+
 export interface SearchPanelProps {
   editor: Editor;
   /**
@@ -27,8 +30,6 @@ export interface SearchPanelProps {
   className?: string;
 }
 
-const NO_OPTIONS: SearchOptions = { matchCase: false, wholeWord: false, regex: false };
-
 /**
  * Панель «Поиск и замена»: немодальная, в углу поля. Состояние
  * поиска — в плагине движка (`searchPlugin.ts`); панель держит только то, что
@@ -44,9 +45,14 @@ const NO_OPTIONS: SearchOptions = { matchCase: false, wholeWord: false, regex: f
  */
 export function SearchPanel({ editor, focus, onClose, className }: SearchPanelProps) {
   const messages = useMessages().editor;
-  const [query, setQuery] = useState(focus.query);
+  /*
+    Запрос и флажки панели — зеркало поиска в движке: на открытии она берёт
+    то, что в нём уже есть (стартовые флажки — Опции Инструмента, запрос — если
+    экран задал его командой), а позже подхватывает такие же правки снаружи.
+  */
+  const [query, setQuery] = useState(() => focus.query || searchState(editor.state)?.query || "");
   const [replacement, setReplacement] = useState("");
-  const [options, setOptions] = useState(NO_OPTIONS);
+  const [options, setOptions] = useState(() => searchState(editor.state)?.options ?? NO_OPTIONS);
   const searchRef = useRef<HTMLInputElement>(null);
   const replaceRef = useRef<HTMLInputElement>(null);
   const panelRef = useRef<HTMLElement>(null);
@@ -60,6 +66,8 @@ export function SearchPanel({ editor, focus, onClose, className }: SearchPanelPr
         current: state?.current ?? -1,
         total: state?.total ?? 0,
         error: state?.error,
+        engineQuery: state?.query ?? "",
+        engineOptions: state?.options ?? NO_OPTIONS,
         editable: current.isEditable,
       };
     },
@@ -91,15 +99,18 @@ export function SearchPanel({ editor, focus, onClose, className }: SearchPanelPr
     разложена и её край можно учесть. Панель и её липкий родитель (Панель
     Редактора) лежат поверх Документа: совпадение под ними не считается видимым.
   */
-  const revealFrame = useRef(0);
-  const reveal = () => {
-    cancelAnimationFrame(revealFrame.current);
-    revealFrame.current = requestAnimationFrame(() => {
-      const panel = panelRef.current;
-      revealCurrentMatch(editor.view.dom, [panel, panel?.parentElement]);
-    });
-  };
-  useEffect(() => () => cancelAnimationFrame(revealFrame.current), []);
+  const reveal = () => scheduleRevealMatch(editor);
+  // Команды Инструмента показывают совпадение тем же путём и обходят эту же панель.
+  useEffect(() => {
+    const unregister = registerSearchOverlays(editor, () => [
+      panelRef.current,
+      panelRef.current?.parentElement,
+    ]);
+    return () => {
+      unregister();
+      cancelRevealMatch(editor);
+    };
+  }, [editor]);
 
   useEffect(() => {
     editor.commands.setSearch(query, options);
@@ -109,6 +120,19 @@ export function SearchPanel({ editor, focus, onClose, className }: SearchPanelPr
     // `reveal` — новая на каждый рендер, но читает только рефы и `editor`.
   }, [editor, query, options]);
 
+  /*
+    Запрос и флажки, заданные в движке мимо панели (команда `setQuery`), встают
+    в поля. Сверка с движком «вживую», а не по снимку `search`: эффект выше уже
+    протолкнул набранное в этом же коммите, и устаревший снимок откатил бы его.
+  */
+  useEffect(() => {
+    const live = searchState(editor.state);
+    if (!live) return;
+    if (live.query !== query) setQuery(live.query);
+    if (FLAGS.some((flag) => live.options[flag] !== options[flag])) setOptions(live.options);
+    // Только на смену поиска в движке; набор в полях уходит в движок эффектом выше.
+  }, [search.engineQuery, search.engineOptions]);
+
   const step = (direction: 1 | -1) => {
     editor.commands.searchStep(direction);
     reveal();

package/src/editor/features/search/revealMatch.ts

@@ -1,5 +1,7 @@
 "use client";
 
+import type { Editor } from "@tiptap/core";
+
 interface Band {
   top: number;
   bottom: number;
@@ -67,3 +69,46 @@ export function revealCurrentMatch(
     delta -= scroller.scrollTop - before;
   }
 }
+
+/** Что лежит поверх Документа у каждого поля: панель поиска, пока она открыта. */
+const overlayProviders = new WeakMap<Editor, () => readonly (Element | null | undefined)[]>();
+const frames = new WeakMap<Editor, number>();
+
+/**
+ * Панель поиска сообщает, что лежит поверх Документа, пока открыта. Команды
+ * Инструмента (`next`, `previous`, `setQuery`) живут вне панели, но должны
+ * обходить её так же. Возвращает снятие регистрации.
+ */
+export function registerSearchOverlays(
+  editor: Editor,
+  overlays: () => readonly (Element | null | undefined)[]
+): () => void {
+  overlayProviders.set(editor, overlays);
+  return () => {
+    if (overlayProviders.get(editor) === overlays) overlayProviders.delete(editor);
+  };
+}
+
+/**
+ * Показать текущее совпадение кадром позже, когда панель уже разложена. Вызовы
+ * одного поля в пределах кадра сливаются в одну прокрутку: панель и команда
+ * Инструмента, сработавшие на один переход, не прокручивают дважды. Фокус не
+ * трогает.
+ */
+export function scheduleRevealMatch(editor: Editor): void {
+  cancelAnimationFrame(frames.get(editor) ?? 0);
+  frames.set(
+    editor,
+    requestAnimationFrame(() => {
+      frames.delete(editor);
+      if (editor.isDestroyed) return;
+      revealCurrentMatch(editor.view.dom, overlayProviders.get(editor)?.() ?? []);
+    })
+  );
+}
+
+/** Отменить отложенную прокрутку (панель закрылась или поле разобрано). */
+export function cancelRevealMatch(editor: Editor): void {
+  cancelAnimationFrame(frames.get(editor) ?? 0);
+  frames.delete(editor);
+}