@olddevs/ui 4.3.0 → 4.5.0

package/src/editor/RichTextEditor.tsx

@@ -16,6 +16,7 @@ import {
   useId,
   useImperativeHandle,
   useLayoutEffect,
+  useCallback,
   useMemo,
   useRef,
   useState,
@@ -31,7 +32,8 @@ import { BlockHandle } from "./ui/BlockHandle.js";
 import { expandTools } from "./features/builtins.js";
 import {
   createHandleMethods,
-  notifyHandleEditor,
+  clearToolSignals,
+  publishToolSignals,
   type RichTextEditorHandleMethods,
 } from "./core/handle.js";
 import { EditorToolbar, ToolbarSkeleton } from "./ui/EditorToolbar.js";
@@ -46,18 +48,19 @@ import { customToolsError, FALLBACK_EXTENSIONS } from "./core/customToolEngine.j
 import { startLoad, type ToolLoad } from "./core/toolLoader.js";
 import { skeletonHtml } from "./core/skeleton.js";
 import { Button } from "../components/actions/Button.js";
-import { devError } from "../lib/dev-warn.js";
+import { devError, devWarn } from "../lib/dev-warn.js";
 import { describeImageNotice } from "./features/image/imageNotice.js";
 import { insertItemsFor } from "./core/insertItems.js";
 import type { CustomColorKind } from "./features/color/customColor.js";
 import { isImageSelection } from "./features/image/image.js";
 import { ImagePopover } from "./features/image/ImagePopover.js";
 import { ImageToolbar } from "./features/image/ImageToolbar.js";
-import { textCardsOf, triggersOf } from "./core/toolDescriptor.js";
+import { textCardsOf, toolOptions, triggersOf, type ToolBridge } from "./core/toolDescriptor.js";
 import type { ToolPopoverRequest } from "./core/toolButtons.js";
 import type { TextCardControl } from "./ui/TextCard.js";
 import { SelectionPopover } from "./ui/ToolButtonView.js";
 import { tableChunk } from "./features/table/tableTool.js";
+import { stickyOffset } from "./features/toc/stickyOffset.js";
 import { replaceWithMarkdown } from "./core/markdown.js";
 import {
   documentFromJSON,
@@ -107,6 +110,15 @@ const TextCard = lazy(() =>
  * `basic`, который меряется бюджетом «старта». Плагин подсветки и сочетания
  * маленькие и стоят в движке сразу.
  */
+/*
+  Ядро Оглавления (Инструмент `toc`) — ленивым чанком: его включают единицы, а
+  полоса со списком и `HoverCard` стоили бы каждому Редактору ~5 kB gzip на
+  старте. Чанк приходит, только когда Инструмент включён и движок готов.
+*/
+const TocCore = lazy(() =>
+  import("./features/toc/RichTextToc.js").then((module) => ({ default: module.TocCore }))
+);
+
 const SearchPanel = lazy(() =>
   import("./features/search/SearchPanel.js").then((module) => ({ default: module.SearchPanel }))
 );
@@ -243,14 +255,18 @@ export interface RichTextEditorProps {
    * клавиш, ни markdown-шорткатом, ни вставкой.
    *
    * Вперемешку с именами кита — описания своих Инструментов (`CustomTool`):
-   * `[...RICH_TEXT_PRESETS.full, mergeTagTool]`. Неизвестное имя отбрасывается
+   * `[...RICH_TEXT_PRESETS.full, mergeTagTool]`. Встроенный Инструмент с
+   * Опциями (`search`, `toc`) настраивается записью `tool()`:
+   * `[...RICH_TEXT_PRESETS.full, tool("toc", { levels: [2, 3] })]` — запись
+   * включает Инструмент и без имени, а имя из пресета уступает ей; две записи
+   * `tool()` с одним именем — ошибка поля. Неизвестное имя отбрасывается
    * молча; описание с ошибкой (имя без Префикса потребителя, совпадение имён,
    * Часть для движка мимо правил Схемы) — ошибка поля: движок не создаётся,
    * значение формы остаётся входящим, причина — в консоли разработчика.
    *
-   * `preset` и `tools` читаются при создании движка: Схема ProseMirror после
-   * этого не меняется. Чтобы сменить набор у живого поля, перемонтируйте его
-   * (`key`) — история правок при этом теряется.
+   * `preset` и `tools`, а с ними и Опции Инструментов, читаются при создании
+   * движка: Схема ProseMirror после этого не меняется. Чтобы сменить набор у
+   * живого поля, перемонтируйте его (`key`) — история правок при этом теряется.
    */
   tools?: readonly ToolEntry[];
   /**
@@ -351,6 +367,9 @@ export interface RichTextEditorHandle extends RichTextEditorHandleMethods {
    * Открыть панель «Поиск и замена» из кода экрана — то же, что
    * кнопка «Поиск» и `Mod+F`; `replace` — фокус в поле замены. Без Инструмента
    * `search`, в HTML-режиме и до монтажа — ничего.
+   *
+   * @deprecated Работает как `handle.tool("search")?.open(options)`; в разработке
+   * один раз предупреждает об этом в консоли. Будет удалён в 5.0.
    */
   openSearch(options?: { replace?: boolean }): void;
   /**
@@ -651,6 +670,8 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
       replace: boolean;
       query: string;
     } | null>(null);
+    /** Переход ядра Оглавления (`TocCore`): есть, пока оно смонтировано. */
+    const tocJumpRef = useRef<((index: number) => boolean) | null>(null);
     const sourceFieldRef = useRef<HTMLTextAreaElement>(null);
     const sourceTextRef = useRef<string | null>(null);
     const sourceBaseRef = useRef("");
@@ -783,8 +804,9 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
     const openSource = () => {
       const current = editorRef.current;
       if (!current) return;
-      // Документа на экране не будет — искать в нём негде.
-      if (searchPanel) closeSearch(false);
+      // Документа на экране не будет — искать в нём негде. Подсветка бывает и без
+      // панели (команда `setQuery`): `next()` в скрытом Документе вышла бы удачной.
+      if (enabledTools.has("search")) closeSearch(false);
       const text = writeSource(current);
       switchFocusRef.current = "source";
       setSource({ text, minHeight: current.view.dom.getBoundingClientRect().height });
@@ -805,18 +827,25 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
 
     /*
       Открыть панель поиска: кнопка Панели, `Mod+F`/`Mod+Alt+F` из движка и
-      `openSearch()` Хэндла. Выделенный текст одного Блока становится запросом,
+      команда `open` Инструмента. Выделенный текст одного Блока становится запросом,
       как в редакторах кода; выделение через Блоки — нет: запрос не переходит
-      границу Блока, и такой текст не нашёлся бы. В HTML-режиме Документа на
-      экране нет — искать негде, и `Mod+F` остаётся браузеру.
+      границу Блока, и такой текст не нашёлся бы. Явный `query` команды главнее
+      выделения. В HTML-режиме Документа на экране нет — искать негде, и `Mod+F`
+      остаётся браузеру.
     */
-    const openSearch = (replace: boolean): boolean => {
+    const openSearch = (replace: boolean, query?: string): boolean => {
       const current = editorRef.current;
       if (!current || !enabledTools.has("search") || sourceTextRef.current !== null) return false;
       const { $from, $to, empty } = current.state.selection;
-      const query =
+      const selected =
         !empty && $from.sameParent($to) ? current.state.doc.textBetween($from.pos, $to.pos) : "";
-      setSearchPanel((previous) => ({ token: (previous?.token ?? 0) + 1, replace, query }));
+      setSearchPanel((previous) => ({
+        token: (previous?.token ?? 0) + 1,
+        replace,
+        query: query ?? selected,
+      }));
+      // Подсветка и переходы — сразу, не дожидаясь ленивой панели.
+      if (query !== undefined) current.commands.setSearch(query);
       return true;
     };
     const openSearchRef = useRef(openSearch);
@@ -838,6 +867,7 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
         chain.clearSearch().run();
       }
       setSearchPanel(null);
+      return true;
     };
 
     // Пункты Меню вставки — из того же замороженного набора, что и Схема.
@@ -994,6 +1024,54 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
           }
         : { maxHeight: areaLength };
 
+    /*
+      Оглавление в левом поле (Инструмент `toc`, ADR-0068). Полоса липнет под
+      фиксированной Панелью: её высота меряется, потому что Панель переносит
+      ряд кнопок на узком поле. В прокручиваемом поле край — верх области.
+    */
+    const tocOptions = toolOptions(enabledTools, "toc");
+    const tocOn = enabledTools.has("toc") && tocOptions !== undefined;
+    const tocOffsetVar = tocOptions?.offsetVar ?? "--topbar-h";
+    const [toolbarShell, setToolbarShell] = useState<HTMLDivElement | null>(null);
+    const [toolbarHeight, setToolbarHeight] = useState(0);
+    useEffect(() => {
+      if (!toolbarShell || typeof ResizeObserver === "undefined") {
+        setToolbarHeight(toolbarShell?.offsetHeight ?? 0);
+        return;
+      }
+      const observer = new ResizeObserver(() => setToolbarHeight(toolbarShell.offsetHeight));
+      observer.observe(toolbarShell);
+      return () => observer.disconnect();
+    }, [toolbarShell]);
+    /*
+      Нижний край липкого верха поля: шапка приложения и Панель над Документом.
+      Не `null` никогда, даже без шапки: иначе переход ушёл бы в `scrollIntoView`,
+      а тот двигает и страницу вокруг поля с `maxHeight`. В прокручиваемом поле
+      подсветка и переход считают от верха области и этот край не используют.
+    */
+    const tocStickyTop = useCallback(
+      () => (stickyOffset(tocOffsetVar) ?? 0) + toolbarHeight,
+      [tocOffsetVar, toolbarHeight]
+    );
+    /*
+      Переход в правке ставит каретку в конец заголовка, как структура документа
+      в Google Docs: с ним можно сразу писать. Прокрутку делает Оглавление, а
+      движок не прокручивает, чтобы не спорить с ним.
+      В `readOnly` каретки нет — фокус на заголовок ставит само Оглавление.
+    */
+    const tocFocusHeading = useCallback((heading: HTMLElement) => {
+      const current = editorRef.current;
+      if (!current || current.isDestroyed || !current.isEditable) return false;
+      const inside = current.view.posAtDOM(heading, 0);
+      const end = inside + current.state.doc.resolve(inside).parent.content.size;
+      current.commands.setTextSelection(end);
+      // `view.focus()`, а не команда `focus`: та ставит фокус кадром позже, и
+      // пункт списка, отпускающий фокус после клика, отдал бы его странице.
+      // ProseMirror фокусирует без прокрутки — прокрутку делает Оглавление.
+      current.view.focus();
+      return true;
+    }, []);
+
     /*
       `Alt+F10` — фокус на первое доступное действие Панели. Плавающую Панель
       клавиша показывает сама, не дожидаясь задержки показа: человек с
@@ -1294,22 +1372,36 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
       };
     }, [throttle, name]);
 
-    useImperativeHandle(
-      ref,
-      () => ({
+    const toolBridge: ToolBridge = {
+      openSearch,
+      // Фокус и каретку не трогаем: команду зовёт код экрана, а не автор в панели.
+      closeSearch: () => closeSearch(false),
+      sourceOpen: () => sourceTextRef.current !== null,
+      jumpToc: (index) => tocJumpRef.current?.(index) ?? false,
+    };
+
+    useImperativeHandle(ref, () => {
+      const methods = createHandleMethods({
         editor,
-        ...createHandleMethods({
-          editor,
-          editable,
-          known: () => knownRef.current,
-          initialDocument: () => initialDocumentRef.current,
-          tables: enabledTools.has("table"),
-          sourceOpen: () => sourceTextRef.current !== null,
-          sourceField: () => sourceFieldRef.current,
-          applySource: () => applySourceRef.current(),
-          rewriteSource,
-          fieldEmpty,
-        }),
+        editable,
+        known: () => knownRef.current,
+        initialDocument: () => initialDocumentRef.current,
+        tables: enabledTools.has("table"),
+        sourceOpen: () => sourceTextRef.current !== null,
+        sourceField: () => sourceFieldRef.current,
+        applySource: () => applySourceRef.current(),
+        rewriteSource,
+        fieldEmpty,
+        commands: (name) => {
+          const descriptor = enabledTools.descriptors.find((entry) => entry.name === name);
+          return editor && !editor.isDestroyed && descriptor?.commands
+            ? descriptor.commands({ editor, bridge: toolBridge })
+            : null;
+        },
+      });
+      return {
+        editor,
+        ...methods,
         getHTML: () => {
           applySourceRef.current();
           return editor ? serialize(editor) : knownRef.current;
@@ -1343,7 +1435,12 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
           rewriteSource(editor);
           return true;
         },
-        openSearch: (options) => void openSearchRef.current(options?.replace ?? false),
+        openSearch: (options) => {
+          devWarn(
+            'RichTextEditor: handle.openSearch() is deprecated; use handle.tool("search")?.open() instead'
+          );
+          methods.tool("search")?.open(options);
+        },
         clear: () => {
           if (!editor) return;
           throttle.cancel();
@@ -1356,11 +1453,20 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
           emit("");
           rewriteSource(editor);
         },
-      }),
-      [editor, editable, throttle]
+      };
+    }, [editor, editable, throttle]);
+    /*
+      Хуки `useRichTextEditorState` и `useRichTextToolState` не видят смену
+      движка у `ref` сами — сообщаем. Тем же сообщением идут сигналы кита для
+      Состояния Инструмента: набор Инструментов и открытость панели Поиска.
+    */
+    const searchOpen = searchPanel !== null;
+    useEffect(
+      () => publishToolSignals(ref, { tools: enabledTools, searchOpen }),
+      [ref, editor, enabledTools, searchOpen]
     );
-    // Хук `useRichTextEditorState` не видит смену движка у `ref` сам — сообщаем.
-    useEffect(() => notifyHandleEditor(ref), [ref, editor]);
+    // Размонтирование (и смена `ref`) забирает сигналы: хук экрана отдаёт `null`.
+    useEffect(() => () => clearToolSignals(ref), [ref]);
 
     /*
       Готовность (спека, словарь): один раз за монтаж, когда движок создан.
@@ -1395,6 +1501,15 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
     const leaveTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
     useEffect(() => () => clearTimeout(leaveTimerRef.current), []);
 
+    /** Цель Оглавления — Документ движка; объект новый с каждым движком. */
+    const tocTarget = useMemo(
+      () => ({
+        get current() {
+          return editor && !editor.isDestroyed ? (editor.view.dom as HTMLElement) : null;
+        },
+      }),
+      [editor]
+    );
     const searchPanelElement = (className: string) =>
       editor &&
       searchPanel && (
@@ -1450,7 +1565,7 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
               `z-[1]` — внутри поля, а не ступень стека слоёв: Панель не
               оверлей и должна оставаться ниже любого из них.
             */
-            <div className={TOOLBAR_SHELL_CLASS}>
+            <div ref={setToolbarShell} className={TOOLBAR_SHELL_CLASS}>
               <EditorToolbar
                 editor={editor}
                 tools={enabledTools}
@@ -1511,7 +1626,43 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
             style={areaStyle}
           >
             {/* В HTML-режиме Документ скрыт, но смонтирован: движок и история живы. */}
-            <EditorContent editor={editor} hidden={sourceOpen} />
+            {tocOn ? (
+              /*
+                Левое поле Оглавления: колонка есть, только пока есть полоса —
+                `TocCore` с меньше чем двумя заголовками не рисует ничего, и
+                текст стоит у края, как без Инструмента (ADR-0068, п. 2).
+              */
+              <div className="flex items-start">
+                {editor && !sourceOpen && (
+                  <Suspense fallback={null}>
+                    <TocCore
+                      target={tocTarget}
+                      offsetVar={tocOptions.offsetVar}
+                      levels={tocOptions.levels}
+                      listWidth={tocOptions.listWidth}
+                      stickyTop={tocStickyTop}
+                      focusHeading={tocFocusHeading}
+                      alignToFirstHeading
+                      onCurrentChange={(tocAt) => publishToolSignals(ref, { tocAt })}
+                      editor={editor}
+                      jumpRef={tocJumpRef}
+                      data-toc-gutter=""
+                      className="sticky mr-3 shrink-0"
+                      style={{
+                        top: scrolls
+                          ? "0.5rem"
+                          : `calc(var(${tocOffsetVar}, 0px) + ${toolbarHeight}px + 0.5rem)`,
+                      }}
+                    />
+                  </Suspense>
+                )}
+                <div className="min-w-0 flex-1">
+                  <EditorContent editor={editor} hidden={sourceOpen} />
+                </div>
+              </div>
+            ) : (
+              <EditorContent editor={editor} hidden={sourceOpen} />
+            )}
             {!editor && (
               /*
               Скелет (ADR-0058, п. 11.4): до Готовности и при сбое загрузчика —
@@ -1737,7 +1888,15 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
             ref={hiddenRef}
             type="hidden"
             name={name}
-            defaultValue={initial}
+            /*
+              Значение скрытого поля пишет Редактор (`emit`, эффекты движка), а
+              не React. Но React на КАЖДОМ обновлении заново ставит `defaultValue`,
+              а у `type="hidden"` это и есть его значение: любой рендер родителя
+              откатывал бы поле формы к входящей строке. Поэтому после монтажа в
+              `defaultValue` уходит то, что уже лежит в поле, — React видит равенство
+              и ничего не трогает. Серверный рендер и первый кадр несут `initial`.
+            */
+            defaultValue={hiddenRef.current?.value ?? initial}
             // Выключенное поле не уходит в форму — как нативное. Поле только
             // для чтения уходит: это показанное значение, а не недоступный
             // контрол.

package/src/editor/RichTextView.tsx

@@ -31,7 +31,8 @@ export interface RichTextViewProps extends Omit<
   surface?: RichTextSurface;
   /**
    * Свои Инструменты Документа — тот же массив, что у `RichTextEditor` и
-   * `sanitizeRichText`. Просмотр читает из него только Острова своих Блоков
+   * `sanitizeRichText`; Настроенный Инструмент (`tool()`) в нём допустим и
+   * Просмотром игнорируется. Просмотр читает из него только Острова своих Блоков
    * (`blocks[имя].island`): Блок, у которого он есть и который есть в
    * Документе, оживает клиентским компонентом, а серверный HTML Блока виден до
    * загрузки и без JS. Остальное в описании Просмотру не нужно. Без `tools`, и

package/src/editor/core/containers.ts

@@ -2,6 +2,7 @@
 
 import type { Node as PmNode, NodeType, ResolvedPos } from "@tiptap/pm/model";
 import { TextSelection, type Transaction } from "@tiptap/pm/state";
+import { WRAPPER_NODE } from "./nodeNames.js";
 
 /**
  * Общее у контейнерных Блоков — Раскладки (`layout.ts`, ADR-0056) и Обёртки
@@ -13,12 +14,13 @@ import { TextSelection, type Transaction } from "@tiptap/pm/state";
  * арифметика позиций не разъезжались молча.
  */
 
-/**
- * Имя узла Обёртки в Схеме движка. Живёт здесь, а не в `wrapper.ts`: оно же
- * входит в общий список ниже, а `wrapper.ts` импортирует этот модуль —
- * определение там дало бы цикл импортов. `wrapper.ts` его реэкспортирует.
- */
-export const WRAPPER_NODE = "wrapper";
+/*
+  Имя узла Обёртки живёт в `nodeNames.ts`, без Tiptap: его читает и Оглавление.
+  Не в `wrapper.ts`: оно же входит в общий список ниже, а `wrapper.ts`
+  импортирует этот модуль — определение там дало бы цикл импортов. `wrapper.ts`
+  его реэкспортирует.
+*/
+export { WRAPPER_NODE };
 
 /**
  * Узлы, внутри которых контейнерного Блока нет ни одного: Обёртка, цитата,

package/src/editor/core/customTool.ts

@@ -3,6 +3,8 @@ import type { Mark } from "@tiptap/pm/model";
 import type { EditorState } from "@tiptap/pm/state";
 import type { ComponentType, ReactNode } from "react";
 import type { IconProps } from "../../icons.js";
+import type { ToolDefinition } from "./toolDefinition.js";
+import type { ConfiguredTool } from "./toolOptions.js";
 import type { Tool as ToolName } from "./tools.js";
 
 /*
@@ -428,8 +430,12 @@ export type CustomToolButton = CustomToolButtonFields &
       }
   );
 
-/** Элемент `tools`: имя Инструмента кита или описание своего. */
-export type ToolEntry = ToolName | CustomTool;
+/**
+ * Элемент `tools`: имя Инструмента кита, Настроенный Инструмент (`tool()`),
+ * определение своего Инструмента (`defineTool()`) или описание своего
+ * Инструмента обычным объектом.
+ */
+export type ToolEntry = ToolName | ConfiguredTool<string> | ToolDefinition | CustomTool;
 
 /**
  * Годится ли значение атрибута по его виду (`CustomAttribute`). Живёт в

package/src/editor/core/customToolEngine.ts

@@ -34,6 +34,7 @@ import {
   type ToolLabel,
   type ToolList,
 } from "./toolDescriptor.js";
+import { resolveDefinition, type ToolDefinition } from "./toolDefinition.js";
 import { markdownFallback } from "./customMarkdown.js";
 import { CUSTOM_ATTRIBUTE_NAME, CUSTOM_NAME, customElement } from "./schema.js";
 import { loaded } from "./toolLoader.js";
@@ -237,6 +238,22 @@ export function describeCustomTool(tool: CustomTool): ToolDescriptor {
   };
 }
 
+/**
+ * Внутреннее описание Инструмента из определения (`defineTool`): тело из
+ * `create` и имя определения собираются в обычный `CustomTool` и идут тем же
+ * путём, а Опции этого Редактора — умолчания, слитые с `tool()`, — достаются
+ * `create`, `state` и `commands`.
+ */
+export function describeDefinition(definition: ToolDefinition, given: object = {}): ToolDescriptor {
+  const { options, tool } = resolveDefinition(definition, given);
+  return {
+    ...describeCustomTool(tool),
+    options,
+    state: definition.state && ((editor) => definition.state!({ editor, options })),
+    commands: definition.commands && (({ editor }) => definition.commands!({ editor, options })),
+  };
+}
+
 /**
  * Набор движка, который `RichTextEditor` собирает при ошибке набора: движок
  * нужен хуку `useEditor` в любом случае, но наружу он не выходит.
@@ -311,7 +328,7 @@ export interface CustomToolsError {
 }
 
 /**
- * Ошибка сборки набора своих Инструментов или `null` (ADR-0058, п. 1.5, 2.4).
+ * Ошибка сборки набора Инструментов или `null` (ADR-0058, п. 1.5, 2.4).
  *
  * Имя без Префикса потребителя, совпадение имён, Node или Mark Части для
  * движка без правил Схемы (и правило без них), атрибут, которого нет в
@@ -325,6 +342,8 @@ export interface CustomToolsError {
  * Исключение движка — отдельно, в `cause`: текст — ключ «один раз» у `devError`.
  */
 export function customToolsError(tools: ToolList, extensions: Extensions): CustomToolsError | null {
+  // Ошибка, найденная при развороте `tools` (две записи `tool()` с одним именем), идёт тем же путём.
+  if (tools.error) return { message: tools.error };
   const custom = tools.descriptors.flatMap((descriptor) => descriptor.custom ?? []);
   if (custom.length === 0) return null;
   // Имена Инструментов и имена Блоков и Меток — разные пространства: Инструмент

package/src/editor/core/extensions.ts

@@ -268,7 +268,8 @@ export function createEditorExtensions(options: EditorExtensionOptions): Extensi
     (`codeBlockTool.ts`): его расширение здесь, после `ToolbarFocus`, и
     опрашивается раньше.
   */
-  for (const descriptor of described) extensions.push(...(descriptor.engine?.(options) ?? []));
+  for (const descriptor of described)
+    extensions.push(...(descriptor.engine?.(options, descriptor.options) ?? []));
   // Сочетания кнопок описаний вешает кит: поле записи — их единственный источник.
   const buttons = described.flatMap((descriptor) => descriptor.buttons ?? []);
   // Поповер пункта вставки и Действия открывает та же команда, что у кнопки.

package/src/editor/core/handle.ts

@@ -4,9 +4,17 @@ import { createNodeFromContent, type JSONContent } from "@tiptap/core";
 import { closeHistory } from "@tiptap/pm/history";
 import type { Fragment } from "@tiptap/pm/model";
 import type { Editor } from "@tiptap/react";
-import type { RefObject } from "react";
 import { textBetween } from "./atomText.js";
 import { isRichTextDocument, type RichTextDocument } from "./jsonDocument.js";
+import type { ToolCommandsOf } from "./toolCommands.js";
+import type { RichTextTools } from "./toolOptions.js";
+
+export {
+  clearToolSignals,
+  notifyHandleEditor,
+  publishToolSignals,
+  watchHandleEditor,
+} from "./handleWatchers.js";
 
 /**
  * Плоские методы Хэндла (ADR-0058, раздел 8): то, что экран делает с Редактором
@@ -80,6 +88,19 @@ export interface RichTextEditorHandleMethods {
   canUndo(): boolean;
   /** Есть ли что повторить. Без Инструмента `history` и до монтажа — `false`. */
   canRedo(): boolean;
+  /**
+   * Команды Инструмента: `handle.tool("search")?.open({ query: "TODO" })`,
+   * `handle.tool("toc")?.jumpTo(2)`. Тип Команд выводится из имени по карте
+   * `RichTextTools`. `null`, если Инструмента нет в наборе `tools`, у него нет
+   * Команд или движок ещё не создан, — поэтому Команды выключенного Инструмента
+   * недоступны и в типах (`?.`), и во время работы.
+   *
+   * Каждая Команда возвращает `boolean`: выполнена или нет (HTML-режим, нет
+   * совпадений, нет заголовка, поле нельзя править) — как `insertHTML`. Имя вне
+   * карты (свой Инструмент без типизации) даёт `unknown`.
+   */
+  tool<Name extends keyof RichTextTools>(name: Name): ToolCommandsOf<Name> | null;
+  tool(name: string): unknown;
 }
 
 /** Что Хэндлу нужно от Редактора: движок и то, что знает только он. */
@@ -108,6 +129,8 @@ export interface HandleHost {
   rewriteSource: (editor: Editor) => void;
   /** Пуст ли Документ по правилу кита, с учётом неприменённой правки поля HTML. */
   fieldEmpty: (editor: Editor) => boolean;
+  /** Команды Инструмента набора; `null` — Инструмента или Команд нет (`ToolDescriptor.commands`). */
+  commands: (name: string) => object | null;
 }
 
 /** Тег целиком; комментарий и содержимое `script`/`style`/`template` разбор Схемой не видит. */
@@ -285,27 +308,7 @@ export function createHandleMethods(host: HandleHost): RichTextEditorHandleMetho
     redo: () => history("redo"),
     canUndo: () => available("undo"),
     canRedo: () => available("redo"),
+    // Типы Команд выводятся из карты, а реализация знает только имя.
+    tool: host.commands as RichTextEditorHandleMethods["tool"],
   };
 }
-
-/*
-  Хук-селектор не знает, когда у `ref` появится движок: Редактор создаёт его
-  после первого рендера экрана и перерисовывается сам, а экран — нет. Поэтому
-  подписки живут по самому объекту `ref`, который есть с первого рендера, и
-  Редактор сообщает об смене движка по нему.
-*/
-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());
-}