@olddevs/ui 0.0.0-stage → 4.0.0

package/src/editor/core/toolDescriptor.ts

@@ -0,0 +1,359 @@
+import type { Editor, Extensions } from "@tiptap/core";
+import type { ComponentType, ReactNode } from "react";
+import type { UiMessages } from "../../i18n/messages.js";
+import type { IconProps } from "../../icons.js";
+import type { BlockTypeItem } from "./blockTypes.js";
+import type {
+  TextCardRangeAt,
+  CustomTextCardRender,
+  CustomTool,
+  CustomTrigger,
+  PrefixedName,
+} from "./customTool.js";
+import type { EditorExtensionOptions } from "./extensions.js";
+import type { InsertItem } from "./insertItems.js";
+import type { ShortcutCommand, ShortcutGroup } from "./shortcuts.js";
+import type { ToolLoader } from "./toolLoader.js";
+import type { Tool } from "./tools.js";
+
+/**
+ * Внутреннее описание встроенного Инструмента (ADR-0058, п. 10).
+ *
+ * НАДФОРМА. Тип — надмножество будущего публичного описания своего
+ * Инструмента: те же Часть для движка, Признаки Блока и UI-записи, а сверху
+ * привилегии кита, которых своему Инструменту не дают (теги Схемы кита,
+ * модель содержимого, виджеты Панели, своё место в порядке поверхности).
+ * Наружу описания встроенных не экспортируются: публичны только имена и
+ * пресеты.
+ *
+ * ОДИН СПИСОК. `tools` и `preset` разворачиваются в список описаний
+ * (`expandTools`, `features/builtins.ts`), и реестры по имени — движок, Меню
+ * вставки, «¶», справочник сочетаний и следующие за ними — читают его
+ * проекцию (`projectRecords`). Правило «выключенный Инструмент убирает и
+ * кнопку, и Схему» этим держится само: записи и Часть для движка Инструмента,
+ * которого нет в списке, не попадают никуда.
+ *
+ * ПЕРЕЕЗД ПОСТЕПЕННЫЙ. Встроенный Инструмент без описания стоит в списке
+ * заглушкой `legacy` и берётся из старых реестров (`INSERT_ITEMS`, `SHORTCUTS`,
+ * `createEditorExtensions`…). Переезд Инструмента — его записи удаляются из
+ * старых реестров и ложатся в описание в `BUILTIN_TOOLS`; место на поверхности
+ * при этом не меняется — его держит порядок кита этой поверхности
+ * (`INSERT_ORDER`, `BLOCK_TYPE_ORDER`), а не реестр записей.
+ */
+export interface ToolDescriptor {
+  /** Имя Инструмента — то же, что в `tools`; у своего — с Префиксом потребителя. */
+  name: Tool | PrefixedName;
+  /**
+   * Заглушка не переехавшего встроенного: его записи и Часть для движка — в
+   * старых реестрах. Остальные поля у заглушки пусты, кроме `blockActions`:
+   * Действия над Блоком переезжают отдельно от остального и
+   * читаются у всех описаний списка, переехавших и нет (`blockActionsOf`).
+   */
+  legacy?: true;
+
+  /**
+   * Часть для движка: расширения Tiptap Инструмента — Node, Mark, Extension,
+   * плагины ProseMirror. Функция от контекста — привилегия кита: встроенным
+   * нужны мосты `RichTextEditor` (поповер ссылки, Меню вставки, `Alt+F10`).
+   */
+  engine?: (context: ToolEngineContext) => Extensions;
+  /**
+   * Загрузчик Части для движка (`toolLoader.ts`): движок создаётся после
+   * загрузчиков всех описаний списка, и `engine` читает отданное `loaded`.
+   */
+  load?: ToolLoader;
+  /**
+   * Форма Блоков для Скелета, пока загрузчик не отработал (`skeleton.ts`):
+   * лёгкие узлы с той же разметкой и тем же разбором атрибутов, без плагинов
+   * и тяжёлых пакетов. Привилегия ленивого встроенного: без неё его Блоки в
+   * Скелете видны текстом, и поле прыгает по высоте с приходом чанка.
+   */
+  skeleton?: () => Extensions;
+  /** Признаки Блока по имени узла; кит переносит их в spec узла. Нет — обычный Блок. */
+  blocks?: Readonly<Record<string, BlockTraits>>;
+
+  /* UI-записи. */
+
+  /**
+   * Кнопки Панели (фиксированной и плавающей — набор один), флагом — и Меню
+   * выделения. Место встроенной кнопки на Панели — привилегия кита: её
+   * отводит Панель по имени Инструмента (`EditorToolbar.tsx`).
+   */
+  buttons?: readonly KitToolButton[];
+  /** Пункты Меню вставки: «/», «+», «Добавить ›» и «Формат ›» Ручки Блока. */
+  insertItems?: readonly InsertItem[];
+  /** Действия над Блоком в меню Ручки Блока. */
+  blockActions?: readonly BlockAction[];
+  /** Карточки у текста: у встроенных их пока нет, но форма одна (ADR-0058, п. 7.6). */
+  textCards?: readonly TextCardRecord[];
+  /** Символы-триггеры: у встроенных их нет, у своего Инструмента — один (ADR-0064). */
+  triggers?: readonly TriggerRecord[];
+
+  /**
+   * Публичное описание своего Инструмента, из которого собрано это
+   * (`customToolEngine.ts`): по нему набор проверяется при сборке.
+   */
+  custom?: CustomTool;
+
+  /* Привилегии кита. */
+
+  /**
+   * Теги Схемы кита, которые пишет Инструмент (`p`, `h1`–`h4`, `a`, `table`…).
+   * Свой Инструмент их не получает: его HTML — `data-block` и `data-mark`.
+   */
+  kitTags?: readonly string[];
+  /**
+   * Модель содержимого: узлы, которые Документ называет поимённо, а не через
+   * группу `block`, — контейнеры верхнего уровня, как Раскладка и Обёртка
+   * (`document.ts`).
+   */
+  documentContent?: readonly string[];
+  /** Пункты виджета «¶» Панели: у него свои слова и иконки (`blockTypes.ts`). */
+  blockTypes?: readonly BlockTypeItem[];
+  /**
+   * Строки справочника сочетаний для клавиш, которые вешает Часть для движка
+   * (`shortcuts.ts`): у записи сочетание — её поле, а у Метки из движка — нет.
+   */
+  shortcuts?: readonly ShortcutCommand[];
+}
+
+/** Символ-триггер Инструмента в списке описаний: публичная запись и имя владельца для сообщений. */
+export type TriggerRecord = CustomTrigger & { tool: string };
+
+/** Что Часть для движка встроенного получает от `RichTextEditor`. */
+export type ToolEngineContext = Omit<EditorExtensionOptions, "tools">;
+
+type EditorMessages = UiMessages["editor"];
+
+/**
+ * Признаки Блока, которые понимает только кит. Все выключены по умолчанию:
+ * обычный Блок — не контейнер, без «Превратить в», с меню форматирования.
+ */
+export interface BlockTraits {
+  /** Контейнер: Блоки внутри — со своей Ручкой Блока (`blockContainer` в spec узла). */
+  container?: boolean;
+  /** Блок можно превратить в другой: «Формат ›» Ручки Блока и «¶». */
+  turnInto?: boolean;
+  /** Атом без меню форматирования: кнопки Меток над ним не показываются. */
+  plainAtom?: boolean;
+}
+
+/**
+ * Подпись записи — строка или функция от контекста (ADR-0058, п. 6.1). Кит
+ * зовёт её при отрисовке, поэтому смена локали `UiProvider` перерисовывает
+ * запись. Встроенным в контекст кладутся ещё и `messages` кита: форма подписи
+ * у своего и встроенного одна.
+ */
+export type ToolLabel = string | ((context: ToolLabelContext) => string);
+
+export interface ToolLabelContext {
+  /** Локаль `UiProvider` (`useUiLocale`). */
+  locale: string;
+  /** Строки Редактора из каталога кита — для встроенных Инструментов. */
+  messages: EditorMessages;
+}
+
+/** Подпись записи в текущем контексте. */
+export function toolLabel(label: ToolLabel, context: ToolLabelContext): string {
+  return typeof label === "string" ? label : label(context);
+}
+
+/**
+ * Содержимое поповера кнопки. Рамку держит кит: слой, якорь, стек Escape
+ * (ADR-0041), имя рамки — подпись кнопки, возврат фокуса и выделения в
+ * Документ. `close` закрывает поповер тем же путём, что Escape.
+ */
+export type ToolPopover = (props: { editor: Editor; close: () => void }) => ReactNode;
+
+interface ToolButtonFields {
+  /** Стабильный ключ, уникальный среди кнопок Панели. */
+  id: string;
+  label: ToolLabel;
+  icon: ComponentType<IconProps>;
+  /** Доступна ли кнопка сейчас. В нередактируемом поле кит выключает кнопки сам, проверять это здесь не нужно. */
+  can: (editor: Editor) => boolean;
+  /** Есть — кнопка-переключатель с `aria-pressed`; нет — разовое действие. */
+  isActive?: (editor: Editor) => boolean;
+  /** Предикат видимости по контексту; нет — кнопка видна всегда. */
+  isVisible?: (editor: Editor) => boolean;
+  /** Кнопка стоит и в Меню выделения. */
+  selectionMenu?: boolean;
+  /**
+   * Сочетание в нотации Панели (`mod`, `alt`, `shift`, клавиша) — единственный
+   * его источник: кит сам вешает клавишу, пишет её в подсказку,
+   * `aria-keyshortcuts` и справочник сочетаний.
+   */
+  shortcut?: readonly string[];
+}
+
+/**
+ * Кнопка Панели (фиксированной и плавающей — набор один), флагом — и Меню
+ * выделения. Подсказка — подпись и `Kbd` сочетания; `aria-pressed` — только
+ * при `isActive`. Форма та же, что у будущей публичной кнопки своего
+ * Инструмента (ADR-0058, п. 5).
+ *
+ * ДЕЙСТВИЕ ИЛИ ПОПОВЕР — ровно одно из двух. `run` выполняется щелчком и
+ * сочетанием. `popover` открывается щелчком у кнопки, а сочетанием — у
+ * каретки: кнопки на экране может и не быть (`toolbar="none"`, спрятанная
+ * плавающая Панель).
+ */
+export type ToolButton = ToolButtonFields &
+  (
+    | { run: (editor: Editor) => void; popover?: undefined }
+    | { popover: ToolPopover; run?: undefined }
+  );
+
+/**
+ * Кнопка встроенного Инструмента: публичная форма и привилегии кита, которых
+ * своей кнопке не дают.
+ */
+export type KitToolButton = ToolButton & {
+  /**
+   * Группа справочника сочетаний. Нет — строка встаёт в группу Инструмента без
+   * заголовка после групп кита, как у своего Инструмента.
+   */
+  shortcutGroup?: ShortcutGroup;
+  /** Рамка поповера, если она не умолчание кита (у кнопки, по содержимому). */
+  popoverFrame?: {
+    /**
+     * `selection` — рамка всегда у выделения, и щелчком по кнопке тоже: поповер
+     * правит выделенный текст, и стоит у него при любом способе открыть
+     * (поповер ссылки).
+     */
+    anchor?: "selection";
+    /** Классы размера и отступов рамки вместо умолчания `w-auto p-2`. */
+    className?: string;
+  };
+};
+
+/** Действие над Блоком: пункт меню Ручки Блока, в секции Инструмента перед «Удалить». */
+export interface BlockAction {
+  id: string;
+  /** Подпись в локали `UiProvider`: у встроенных — строка каталога, у своих — `ToolLabel`. */
+  label: (messages: EditorMessages, locale: string) => string;
+  icon: ComponentType<IconProps>;
+  /**
+   * Имена Блоков, для которых действие показывается: имя Блока Ручки или
+   * контейнера, в котором он стоит прямо (`blockContainer` в spec узла). Так
+   * «Снять обёртку» с `["wrapper"]` есть и у самой Обёртки, и у Блока в ней.
+   */
+  blocks: readonly string[];
+  /**
+   * Сочетание, которое вешает кит (ADR-0058, п. 5.7): на Блок под кареткой, у
+   * которого действие видно. У встроенных нет.
+   */
+  shortcut?: readonly string[];
+  /** `pos` — позиция Блока Ручки в Документе. */
+  run: (editor: Editor, pos: number) => void;
+  /**
+   * Поповер своего Инструмента у Блока (ADR-0058, п. 5.6). `run` такого
+   * Действия открывает его — меню Ручки и сочетание о поповере не знают.
+   */
+  popover?: (props: { editor: Editor; close: () => void; pos: number }) => ReactNode;
+  isVisible?: (editor: Editor, pos: number) => boolean;
+}
+
+/**
+ * Карточка у текста: диапазон у каретки и тело; рамку держит кит
+ * (`TextCard.tsx`, ADR-0058, п. 7.6–7.11).
+ */
+export interface TextCardRecord {
+  id: string;
+  /** Подпись в локали `UiProvider`: доступное имя рамки и часть фразы о появлении. */
+  label: (messages: EditorMessages, locale: string) => string;
+  rangeAt: TextCardRangeAt;
+  render: CustomTextCardRender;
+}
+
+/**
+ * Развёрнутый набор Инструментов: список описаний и — как `Set` — имена
+ * включённых Инструментов кита.
+ *
+ * Набор имён — тоже проекция списка: реестры, которые ещё фильтруют свои
+ * записи по имени (`tools.has("table")`), читают его без правок. Свои
+ * Инструменты есть только в списке описаний.
+ */
+export interface ToolList extends ReadonlySet<Tool> {
+  /**
+   * Описания включённых Инструментов: встроенные в порядке кита (у не
+   * переехавших — заглушки `legacy`), за ними свои в порядке `tools`.
+   */
+  readonly descriptors: readonly ToolDescriptor[];
+}
+
+/**
+ * Набор из имён кита и списка описаний — единственный способ его собрать:
+ * развернуть `tools` (`expandTools`) или сузить готовый (Скелет).
+ */
+export function toolList(names: Iterable<Tool>, descriptors: readonly ToolDescriptor[]): ToolList {
+  return Object.assign(new Set(names), { descriptors });
+}
+
+/** Описания переехавших Инструментов набора — в порядке списка. */
+export function describedTools(tools: ToolList): readonly ToolDescriptor[] {
+  return tools.descriptors.filter((descriptor) => !descriptor.legacy);
+}
+
+/**
+ * Действия над Блоком набора — проекция списка описаний, в порядке кита. Фильтра
+ * по Блоку здесь нет: имя и предикат видимости спрашивает меню Ручки на
+ * своём Блоке (`blockActionVisible`).
+ */
+export function blockActionsOf(tools: ToolList): readonly BlockAction[] {
+  return tools.descriptors.flatMap((descriptor) => descriptor.blockActions ?? []);
+}
+
+/**
+ * Карточки у текста набора в порядке списка: при равной ширине диапазона
+ * выигрывает та, что раньше, то есть Инструмент раньше в `tools`.
+ */
+export function textCardsOf(tools: ToolList): readonly TextCardRecord[] {
+  return tools.descriptors.flatMap((descriptor) => descriptor.textCards ?? []);
+}
+
+/** Символы-триггеры набора в порядке списка (ADR-0064). */
+export function triggersOf(tools: ToolList): readonly TriggerRecord[] {
+  return tools.descriptors.flatMap((descriptor) => descriptor.triggers ?? []);
+}
+
+/**
+ * Показывается ли действие у Блока `pos`: `block` — имя этого Блока, `container`
+ * — имя контейнера, в котором он стоит прямо (у Блока Документа это сам Документ).
+ */
+export function blockActionVisible(
+  action: BlockAction,
+  editor: Editor,
+  pos: number,
+  block: { name: string; container: string }
+): boolean {
+  return (
+    (action.blocks.includes(block.name) || action.blocks.includes(block.container)) &&
+    (action.isVisible?.(editor, pos) ?? true)
+  );
+}
+
+/**
+ * Записи одной поверхности — проекция списка описаний.
+ *
+ * - `order` — место встроенных Инструментов на поверхности, привилегия кита.
+ *   Инструменты набора вне него идут следом, в порядке списка: так встаёт
+ *   запись, у которой своего места на поверхности нет.
+ * - `legacy` — старый реестр: записи Инструмента, ещё не переехавшего на описание.
+ * - `own` — поле описания с записями этой поверхности.
+ *
+ * Фильтра по включённым Инструментам здесь нет: его держит сам список.
+ */
+export function projectRecords<R>(
+  tools: ToolList,
+  order: readonly Tool[],
+  legacy: (name: Tool) => readonly R[] | undefined,
+  own: (descriptor: ToolDescriptor) => readonly R[] | undefined
+): R[] {
+  const list = tools.descriptors;
+  const placed = order.flatMap((name) => list.filter((descriptor) => descriptor.name === name));
+  const rest = list.filter((descriptor) => !(order as readonly string[]).includes(descriptor.name));
+  return [...placed, ...rest].flatMap(
+    // Заглушка `legacy` бывает только у встроенного: имя — из `Tool`.
+    (descriptor) => (descriptor.legacy ? legacy(descriptor.name as Tool) : own(descriptor)) ?? []
+  );
+}

package/src/editor/core/toolEntryShortcuts.ts

@@ -0,0 +1,66 @@
+"use client";
+
+import { Extension } from "@tiptap/core";
+import { handleBlock } from "./blockCommands.js";
+import { applyInsertItem, type InsertItem } from "./insertItems.js";
+import { keymapName } from "./toolButtons.js";
+import { blockActionVisible, type BlockAction } from "./toolDescriptor.js";
+
+export interface ToolEntryShortcutsOptions {
+  /** Пункты вставки с сочетанием — в порядке списка описаний. */
+  insertItems: readonly InsertItem[];
+  /** Действия над Блоком с сочетанием — в порядке списка описаний. */
+  blockActions: readonly BlockAction[];
+}
+
+/**
+ * Сочетания пунктов вставки и Действий над Блоком описаний (ADR-0058, п. 5.7):
+ * сочетание — поле записи и единственный источник клавиши, поэтому её вешает кит.
+ *
+ * Пункт применяется так же, как из Меню вставки у каретки (`applyInsertItem`:
+ * одна правка, одна отмена). Действие — над Блоком под кареткой, тем же Блоком,
+ * который выбирает Ручка (`handleBlock`), и только там, где оно видно в её
+ * меню: на чужом Блоке клавиша идёт дальше, в Документ.
+ */
+export const ToolEntryShortcuts = Extension.create<ToolEntryShortcutsOptions>({
+  name: "toolEntryShortcuts",
+
+  addOptions: () => ({ insertItems: [], blockActions: [] }),
+
+  addKeyboardShortcuts() {
+    const { editor } = this;
+    const insert = this.options.insertItems.flatMap((item) =>
+      item.shortcut
+        ? [
+            [
+              keymapName(item.shortcut),
+              () => {
+                if (!editor.isEditable) return false;
+                applyInsertItem(editor, item, null);
+                return true;
+              },
+            ] as const,
+          ]
+        : []
+    );
+    const act = this.options.blockActions.flatMap((action) =>
+      action.shortcut
+        ? [
+            [
+              keymapName(action.shortcut),
+              () => {
+                const block = editor.isEditable ? handleBlock(editor.state) : null;
+                if (!block) return false;
+                const name = block.parent.child(block.startIndex).type.name;
+                const place = { name, container: block.parent.type.name };
+                if (!blockActionVisible(action, editor, block.start, place)) return false;
+                action.run(editor, block.start);
+                return true;
+              },
+            ] as const,
+          ]
+        : []
+    );
+    return Object.fromEntries([...insert, ...act]);
+  },
+});

package/src/editor/core/toolLoader.ts

@@ -0,0 +1,50 @@
+"use client";
+
+import { devError } from "../../lib/dev-warn.js";
+
+/*
+  Загрузчики Частей для движка (ADR-0058, п. 1.3 и 11.3–11.6).
+
+  Промис кэшируется на самой функции загрузчика, а не на Редакторе: второй
+  Редактор на странице с тем же Инструментом ничего не ждёт и загрузчик не
+  зовёт. Упавший остаётся в кэше упавшим — иначе каждая перерисовка звала бы
+  его снова; заново его зовёт только «Повторить» (`retry`). Механизм общий:
+  встроенный Инструмент с ленивой Частью для движка кладёт свой загрузчик в
+  то же поле описания (`ToolDescriptor.load`).
+*/
+
+/** Загрузчик Части для движка: функция с динамическим импортом. */
+export type ToolLoader = () => Promise<unknown>;
+
+/** Ход загрузки: промис не отклоняется никогда, итог — в `done` или `failed`. */
+export interface ToolLoad {
+  promise: Promise<void>;
+  value?: unknown;
+  done?: true;
+  failed?: true;
+}
+
+const LOADS = new WeakMap<ToolLoader, ToolLoad>();
+
+/** Запустить загрузчик, если он ещё не звался (или упал и это повтор). */
+export function startLoad(loader: ToolLoader, retry?: boolean): ToolLoad {
+  let load = LOADS.get(loader);
+  if (!load || (retry && load.failed)) {
+    const next: ToolLoad = (load = {} as ToolLoad);
+    next.promise = new Promise((resolve) => resolve(loader())).then(
+      (value) => {
+        next.value = value;
+        next.done = true;
+      },
+      (error: unknown) => {
+        next.failed = true;
+        devError("RichTextEditor: a tool loader failed", error);
+      }
+    );
+    LOADS.set(loader, next);
+  }
+  return load;
+}
+
+/** Что отдал загрузчик; до конца загрузки — `undefined`. */
+export const loaded = (loader: ToolLoader): unknown => LOADS.get(loader)?.value;

package/src/editor/core/tools.ts

@@ -0,0 +1,150 @@
+"use client";
+
+/**
+ * Инструменты Редактора: одна возможность — одна кнопка Панели и одно
+ * расширение Схемы.
+ *
+ * ПОЧЕМУ КНОПКА И РАСШИРЕНИЕ — ОДНО ИМЯ. Спрятанная кнопка без отключённого
+ * расширения ничего не запрещает: подчёркивание пришло бы вставкой из Word,
+ * `Ctrl+U` или markdown-шорткатом. Поэтому выключенный инструмент убирает и то,
+ * и другое (спека, «Набор инструментов»), а набор расширений строится из того
+ * же множества, что и Панель (`extensions.ts`).
+ *
+ * ИМЯ ПРИХОДИТ В ТИП ВМЕСТЕ С ИНСТРУМЕНТОМ, НЕ РАНЬШЕ. Тип входной:
+ * потребитель передаёт значения, а не разбирает их, и расширение объединения
+ * новым именем для него не ломающее. Зато имя без реализации стало бы
+ * молчаливой ловушкой: `tools={["x"]}` компилировался бы и ничего не давал.
+ * Так пришли `link`, `color`, `highlight`, `align`, `table`, `image`, `emoji`,
+ * `layout`, `wrapper` и `source`; зарезервированных имён сейчас нет.
+ *
+ * `heading1` — заголовок первого уровня, надстройка над `heading`:
+ * с ним уровни Блока — 1–4, без него — 2–4. Отдельным инструментом он стоит
+ * потому, что у экрана заголовок страницы чаще уже есть над Редактором, и второй
+ * H1 в нём — ошибка структуры (WCAG 1.3.1), а у документа без своей страницы
+ * (заметка, статья в базе знаний) автору нечем поставить главный заголовок.
+ * Без `heading` его нет вовсе: уровни есть только у Блока заголовка.
+ *
+ * `insertMenu` — Меню вставки (`/` в тексте и «+» на Панели). Своего Блока у
+ * него нет, как у `clearFormatting`: это способ добраться до чужих Блоков, и
+ * выключается он ради поля, где `/` — обычный символ (пути, «и/или»). Пункты
+ * меню берутся из включённых инструментов (`insertItems.ts`).
+ *
+ * `emoji` — кнопка Панели с сеткой эмодзи (`EmojiGrid`). Своей Схемы у него нет,
+ * как у `clearFormatting`: эмодзи — обычный текст, и Схема, санитайзер и
+ * Markdown не меняются. В `basic` его нет: в комментарии системная палитра ОС
+ * ближе, а кнопка занимала бы место у короткого ряда.
+ *
+ * `layout` — Раскладка, Блок из колонок (`layout.ts`). Кнопки Панели у неё нет:
+ * она вставляется из Меню вставки и меню ручки Блока. Выключенный инструмент
+ * убирает узлы из Схемы, и Раскладка из вставки разворачивается в Блоки
+ * подряд. В `basic` её нет: колонки в комментарии — вёрстка, а не текст.
+ *
+ * `wrapper` — Обёртка, Блок-группа других Блоков (`wrapper.ts`), как Wrapper у
+ * Redactor. Кнопки Панели у неё тоже нет — Меню вставки и меню ручки.
+ * Выключенный инструмент разворачивает Обёртку из вставки и `value` в Блоки
+ * подряд. В `basic` её нет по той же причине, что и Раскладки.
+ *
+ * `source` — HTML-режим: кнопка «HTML» фиксированной Панели меняет
+ * Документ на поле с его исходным HTML, а выход применяет правку через Схему,
+ * как входящий `value`. Своей Схемы у него нет, как у `clearFormatting`:
+ * разметку решает Схема, и режим её не расширяет. В `basic` его нет: в
+ * комментарии кнопка «HTML» без явного запроса экрана — лишняя.
+ *
+ * `search` — поиск и замена по Документу: кнопка «Поиск»
+ * фиксированной Панели и `Mod+F` в поле открывают панель в углу поля. Своей
+ * Схемы нет, как у `clearFormatting`. Есть и в `basic`: искать по длинному
+ * описанию нужно и там, а кнопка у правого края ряд не удлиняет.
+ */
+export const TOOLS = [
+  "history",
+  "heading",
+  "heading1",
+  "bold",
+  "italic",
+  "underline",
+  "strike",
+  "code",
+  "superscript",
+  "subscript",
+  "clearFormatting",
+  "link",
+  "color",
+  "highlight",
+  "align",
+  "bulletList",
+  "orderedList",
+  "taskList",
+  "blockquote",
+  "codeBlock",
+  "horizontalRule",
+  "table",
+  "image",
+  "layout",
+  "wrapper",
+  "emoji",
+  "source",
+  "search",
+  "insertMenu",
+] as const;
+
+/** Имя инструмента Редактора. Список и смысл каждого — на странице компонента. */
+export type Tool = (typeof TOOLS)[number];
+
+/** Готовый набор инструментов. */
+export type RichTextEditorPreset = "full" | "basic";
+
+/**
+ * Состав пресетов.
+ *
+ * `basic` — для комментариев и коротких описаний: метки без подчёркивания и
+ * индексов, ссылка, два вида списков, цитата и история правок.
+ *
+ * Меню вставки в `basic` нет: в комментарии `/` чаще значит «и/или» или путь,
+ * чем команду, а из Блоков там только списки и цитата — до них ближе
+ * markdown-шорткатом, чем через меню.
+ */
+export const PRESETS: Record<RichTextEditorPreset, readonly Tool[]> = {
+  full: TOOLS,
+  basic: [
+    "history",
+    "bold",
+    "italic",
+    "strike",
+    "code",
+    "link",
+    "bulletList",
+    "orderedList",
+    "blockquote",
+    "search",
+  ],
+};
+
+/**
+ * Пресеты наружу — массивами (ADR-0058, п. 1.2): свой набор собирается из них,
+ * например `[...RICH_TEXT_PRESETS.full, mergeTagTool]`. Копии заморожены:
+ * `PRESETS.full` — это `TOOLS`, и правка массива потребителем меняла бы набор
+ * кита во всех Редакторах страницы. Состав пресета — не контракт (ADR-0058,
+ * п. 12.5): стабильный набор — точный список имён.
+ */
+export const RICH_TEXT_PRESETS: Readonly<Record<RichTextEditorPreset, readonly Tool[]>> =
+  Object.freeze({
+    full: Object.freeze([...PRESETS.full]),
+    basic: Object.freeze([...PRESETS.basic]),
+  });
+
+/**
+ * Включённые инструменты: точный список `tools`, если он передан, иначе пресет.
+ * Редактор берёт их не отсюда, а списком описаний (`expandTools`,
+ * `features/builtins.ts`), который строится из этих имён.
+ *
+ * Неизвестные имена отбрасываются молча — из JS без типов, или имя из
+ * следующего среза в старой версии кита. Падать из-за лишнего имени незачем:
+ * лишнего инструмента в Редакторе от этого не появится.
+ */
+export function resolveTools(
+  preset: RichTextEditorPreset,
+  tools: readonly Tool[] | undefined
+): ReadonlySet<Tool> {
+  const known = new Set<string>(TOOLS);
+  return new Set((tools ?? PRESETS[preset] ?? PRESETS.full).filter((tool) => known.has(tool)));
+}

package/src/editor/core/viewIsland.ts

@@ -0,0 +1,35 @@
+import type { ComponentType } from "react";
+import type { CustomIslandProps, CustomTool, ToolEntry } from "./customTool.js";
+
+/*
+  Острова своих Блоков в Просмотре (ADR-0058, п. 3.3).
+
+  Модуль серверный: `RichTextView` выбирает из `tools` лишь то, что нужно
+  острову, и отдаёт клиентскому компоненту ссылки на Острова — описание целиком
+  (Часть для движка, функции) через границу RSC не пройдёт. Выбор идёт по
+  Документу, как `hasCodeBlocks` у «Копировать»: Остров Блока, которого в
+  Документе нет, в клиентский граф не попадает, а значит, и его код не грузится.
+*/
+
+/** Остров одного своего Блока: имя Блока, компонент и объявленные атрибуты. */
+export interface ViewIsland {
+  block: string;
+  island: ComponentType<CustomIslandProps>;
+  /** Объявленные атрибуты Блока (имя — вид значения, данные): их имена получит компонент. */
+  attributes: Readonly<Record<string, unknown>> | undefined;
+}
+
+/**
+ * Острова, нужные этому Документу. Блок в очищенном HTML всегда записан как
+ * `data-block="<имя>"` в двойных кавычках (так пишет сериализатор DOM), поэтому
+ * проверка — подстрока, без разбора разметки. Нет `tools`, нет Острова у Блока
+ * или Блока нет в Документе — пустой список, и клиентского острова нет вовсе.
+ */
+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 }]) =>
+      island && html.includes(`data-block="${block}"`) ? [{ block, island, attributes }] : []
+    )
+  );
+}