@olddevs/ui 0.0.0-stage → 4.0.1

package/src/editor/features/code/codeBlock.ts

@@ -0,0 +1,188 @@
+"use client";
+
+// Происхождение правил ввода и разбора Markdown: `@tiptap/extension-code-block`
+// (MIT, © 2025 Tiptap GmbH, https://github.com/ueberdosis/tiptap) — выражения
+// ограды и разбор токена `code` перенесены, язык приводится к имени Документа.
+// Лицензия — NOTICE в корне пакета.
+
+import { textblockTypeInputRule } from "@tiptap/core";
+import { CodeBlockLowlight } from "@tiptap/extension-code-block-lowlight";
+import { Plugin, PluginKey, type EditorState } from "@tiptap/pm/state";
+import { ReactNodeViewRenderer } from "@tiptap/react";
+import { CODE_LANGUAGE_TRIGGER, CodeBlockView } from "./CodeBlockView.js";
+import { codeLanguageOf } from "./codeBlockTool.js";
+import { CODE_LANGUAGE_IDS, normalizeCodeLanguage, type CodeLanguageId } from "./codeLanguages.js";
+import { highlightCode, type HighlightTree } from "./lowlight.js";
+
+/** Имя узла — то же, что у блока кода StarterKit: на нём держатся `Tool`, Панель и Меню вставки. */
+export const CODE_BLOCK_NODE = "codeBlock";
+
+export interface RichCodeBlockOptions {
+  /** Перевести фокус в Панель — `Alt+F10` с кнопки языка (`extensions.ts`). */
+  focusToolbar: () => boolean;
+}
+
+/** Блок без языка — текст как есть, одним узлом, без токенов. */
+const plain = (value: string): HighlightTree => ({
+  type: "root",
+  children: [{ type: "text", value }],
+});
+
+/**
+ * Что получает расширение вместо голого lowlight.
+ *
+ * ПОЧЕМУ ОБЁРТКА. Расширение Tiptap на блоке без языка зовёт `highlightAuto` —
+ * угадывает язык по тексту. «Обычный текст» тогда раскрашивался бы как
+ * случайный из шести, а у одинакового текста в Редакторе и в `RichTextView`
+ * была бы разная подсветка: серверный хелпер не угадывает, он подсвечивает
+ * только блоки с языком. Обёртка отдаёт такой блок текстом, а язык Документа
+ * (`html`) переводит в грамматику (`xml`) по `codeLanguages.ts`.
+ */
+const LOWLIGHT = {
+  highlight: (language: string, code: string) => {
+    const id = normalizeCodeLanguage(language);
+    return id ? highlightCode(id, code) : plain(code);
+  },
+  highlightAuto: plain,
+  listLanguages: () => [...CODE_LANGUAGE_IDS],
+};
+
+/** Блоки кода с языком не в форме Документа: псевдоним или неизвестное имя. */
+function strayLanguages(state: EditorState): { pos: number; language: CodeLanguageId | null }[] {
+  const found: { pos: number; language: CodeLanguageId | null }[] = [];
+  state.doc.descendants((node, pos) => {
+    if (node.type.name !== CODE_BLOCK_NODE) return !node.isTextblock;
+    const language = normalizeCodeLanguage(node.attrs.language);
+    if (language !== node.attrs.language) found.push({ pos, language });
+    return false;
+  });
+  return found;
+}
+
+/**
+ * Блок кода с языком и подсветкой (ADR-0051) вместо блока кода
+ * StarterKit. Имя узла, `Mod+Alt+C`, правило ```` ``` ```` и пункты «Блок кода»
+ * в Панели и в Меню вставки остаются прежними.
+ *
+ * ЯЗЫК — ТОЛЬКО ИМЯ ИЗ `codeLanguages.ts` ИЛИ НИЧЕГО. Он приходит из пяти
+ * мест: `value` и вставка HTML (`class="language-py"`), правило ```` ```py ````,
+ * Markdown (```` ```yml ````), вставка из VS Code (`vscode-editor-data`) и
+ * команды движка. Первые три приводятся на входе, остальные — дописанной
+ * транзакцией (`codeLanguageNormalizer`); неизвестный язык становится
+ * «Обычным текстом», и в Документ уходит `<code>` без класса.
+ *
+ * ПОДСВЕТКА — ДЕКОРАЦИИ. Расширение размечает токены `span class="hljs-…"`
+ * поверх текста блока, и в `getHTML()` их нет: в Документе остаётся только
+ * `class="language-…"`. Цвета токенов — тема в `codeTheme.ts`, классами на
+ * контейнере.
+ */
+export const RichCodeBlock = CodeBlockLowlight.extend<RichCodeBlockOptions>({
+  name: CODE_BLOCK_NODE,
+
+  addOptions() {
+    return {
+      ...this.parent!(),
+      lowlight: LOWLIGHT,
+      focusToolbar: () => false,
+    };
+  },
+
+  addAttributes() {
+    return {
+      language: {
+        default: null,
+        parseHTML: codeLanguageOf,
+        rendered: false,
+      },
+    };
+  },
+
+  addInputRules() {
+    // Те же выражения, что у блока кода Tiptap; имя языка — к имени Документа.
+    return [/^```([a-z]+)?[\s\n]$/, /^~~~([a-z]+)?[\s\n]$/].map((find) =>
+      textblockTypeInputRule({
+        find,
+        type: this.type,
+        getAttributes: (match) => ({ language: normalizeCodeLanguage(match[1]) }),
+      })
+    );
+  },
+
+  // Копия разбора блока кода Tiptap: язык ограды — к имени Документа.
+  parseMarkdown: (token, helpers) => {
+    if (
+      token.raw?.startsWith("```") === false &&
+      token.raw?.startsWith("~~~") === false &&
+      token.codeBlockStyle !== "indented"
+    ) {
+      return [];
+    }
+    return helpers.createNode(
+      CODE_BLOCK_NODE,
+      { language: normalizeCodeLanguage(token.lang) },
+      token.text ? [helpers.createTextNode(token.text)] : []
+    );
+  },
+
+  /*
+    ОГРАДА ДЛИННЕЕ ЛЮБОЙ СЕРИИ ОБРАТНЫХ КАВЫЧЕК ВНУТРИ. У Tiptap ограда всегда
+    ```` ``` ````, и блок, который сам содержит ```` ``` ```` (пример README в
+    блоке Markdown, шаблон в блоке кода), выгружался с внутренней оградой,
+    закрывающей внешнюю: обратная загрузка разваливала его на куски. CommonMark
+    закрывает блок только оградой не короче открывающей — поэтому берём на одну
+    кавычку больше самой длинной серии, но не меньше трёх.
+  */
+  renderMarkdown: (node, helpers) => {
+    const text = node.content ? helpers.renderChildren(node.content) : "";
+    const longest = Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
+    const fence = "`".repeat(Math.max(3, longest + 1));
+    const language = (node.attrs?.language as string | null) ?? "";
+    return `${fence}${language}\n${text}\n${fence}`;
+  },
+
+  addKeyboardShortcuts() {
+    return {
+      ...this.parent?.(),
+      /*
+        `Alt+F10` в блоке кода — в кнопку его языка, как на выделенной
+        картинке — в её панель: действие над тем, где стоит каретка, ближе
+        Панели форматирования. Tab для этого не годится: он уводит фокус из
+        поля, а с кнопки повторный `Alt+F10` ведёт дальше, в Панель. Кнопки
+        нет (только чтение) — сочетание уходит дальше, к Панели.
+      */
+      "Alt-F10": ({ editor }) => {
+        const { $from } = editor.state.selection;
+        if ($from.parent.type !== this.type || !editor.isEditable) return false;
+        const block = editor.view.nodeDOM($from.before());
+        const trigger =
+          block instanceof HTMLElement
+            ? block.querySelector<HTMLElement>(`[${CODE_LANGUAGE_TRIGGER}]`)
+            : null;
+        if (!trigger) return false;
+        trigger.focus();
+        return true;
+      },
+    };
+  },
+
+  addProseMirrorPlugins() {
+    return [
+      ...(this.parent?.() ?? []),
+      new Plugin({
+        key: new PluginKey("codeLanguageNormalizer"),
+        appendTransaction: (transactions, _oldState, state) => {
+          if (!transactions.some((transaction) => transaction.docChanged)) return null;
+          const stray = strayLanguages(state);
+          if (stray.length === 0) return null;
+          const { tr } = state;
+          for (const { pos, language } of stray) tr.setNodeAttribute(pos, "language", language);
+          return tr;
+        },
+      }),
+    ];
+  },
+
+  addNodeView() {
+    return ReactNodeViewRenderer(CodeBlockView);
+  },
+});

package/src/editor/features/code/codeBlockTool.ts

@@ -0,0 +1,107 @@
+"use client";
+
+import { Node } from "@tiptap/core";
+import { CodeBlockIcon } from "../../../icons.js";
+// Только тип: статический импорт модуля втянул бы чанк в «старт».
+import type * as CodeBlockChunk from "./codeBlock.js";
+import { normalizeCodeLanguage, type CodeLanguageId } from "./codeLanguages.js";
+import { shortcutKeys } from "../../core/shortcuts.js";
+import type { ToolDescriptor } from "../../core/toolDescriptor.js";
+import { loaded } from "../../core/toolLoader.js";
+
+/*
+  Чанк блока кода: расширение с языком и подсветкой, представление узла с
+  шапкой (`CodeBlockView`), lowlight и грамматики highlight.js — около 30 кБ
+  gzip, которые `basic` не платит (ADR-0058, п. 11.1).
+*/
+const loadCodeBlock = () => import("./codeBlock.js");
+
+/**
+ * Язык блока кода из разметки `<pre><code class="…">`: первый класс
+ * `language-*`, который знает Редактор. `evil language-js` даёт JavaScript,
+ * `language-rust` — «Обычный текст». Один разбор у движка (`codeBlock.ts`) и у
+ * формы блока в Скелете (здесь). Не в `codeLanguages.ts`: тот едет и в
+ * `RichTextView`, и в серверный вход Схемы, а им разбор DOM не нужен.
+ */
+export function codeLanguageOf(pre: Element): CodeLanguageId | null {
+  for (const name of pre.firstElementChild?.classList ?? []) {
+    if (!name.startsWith("language-")) continue;
+    const language = normalizeCodeLanguage(name.slice("language-".length));
+    if (language) return language;
+  }
+  return null;
+}
+
+/**
+ * Форма блока кода для Скелета: тот же узел `codeBlock` с тем же разбором языка
+ * и той же разметкой `<pre><code class="language-…">`, но без подсветки,
+ * представления узла и lowlight. Шапку над ним Скелет дописывает сам
+ * (`withCodeHeaders`, `skeleton.ts`).
+ */
+const CodeBlockShape = Node.create({
+  name: "codeBlock",
+  group: "block",
+  content: "text*",
+  marks: "",
+  code: true,
+  defining: true,
+  addAttributes: () => ({
+    language: { default: null, parseHTML: codeLanguageOf, rendered: false },
+  }),
+  parseHTML: () => [{ tag: "pre", preserveWhitespace: "full" }],
+  renderHTML: ({ node }) => [
+    "pre",
+    ["code", node.attrs.language ? { class: `language-${node.attrs.language}` } : {}, 0],
+  ],
+});
+
+/**
+ * Блок кода на описании Инструмента (ADR-0058, п. 11.1): его нет в
+ * `basic`, а Часть для движка тяжелее 10 кБ, поэтому она грузится тем же
+ * загрузчиком, что у своего Инструмента. До загрузки Редактор с блоком кода —
+ * Скелет (`RichTextEditor.tsx`).
+ *
+ * Переехали Часть для движка и пункты Меню вставки. Сочетание `Mod+Alt+C`
+ * вешает расширение, и его строка справочника осталась в `SHORTCUTS`: на неё
+ * ссылаются пункты меню (`shortcutKeys`), «Формат ›» и место строки цитаты
+ * (`MOVED_BEFORE`). Кнопка «Блок кода» меню «…» и «¶» — виджеты Панели, они
+ * переезжают позже (ADR-0058, «Последствия»).
+ */
+export const CODE_BLOCK_TOOL: ToolDescriptor = {
+  name: "codeBlock",
+  load: loadCodeBlock,
+  /*
+    `Alt+F10` блока кода (в кнопку языка) обязан сработать раньше общего
+    `ToolbarFocus`: Части для движка описаний регистрируются после него
+    (`extensions.ts`), а из равных по приоритету Tiptap первым опрашивает
+    зарегистрированное последним.
+  */
+  engine: ({ focusToolbar }) => [
+    (loaded(loadCodeBlock) as typeof CodeBlockChunk).RichCodeBlock.configure({
+      focusToolbar,
+    }),
+  ],
+  skeleton: () => [CodeBlockShape],
+  kitTags: ["pre", "code"],
+  insertItems: [
+    {
+      id: "codeBlock",
+      section: "insert",
+      label: (m) => m.codeBlock,
+      icon: CodeBlockIcon,
+      aliases: ["```", "pre"],
+      markdown: "```",
+      keys: shortcutKeys("codeBlock"),
+      run: (chain) => chain.setCodeBlock(),
+    },
+    {
+      id: "codeBlockFromText",
+      section: "turnInto",
+      label: (m) => m.codeBlock,
+      icon: CodeBlockIcon,
+      aliases: ["```", "pre"],
+      keys: shortcutKeys("codeBlock"),
+      run: (chain) => chain.setCodeBlock(),
+    },
+  ],
+};

package/src/editor/features/code/codeHeader.ts

@@ -0,0 +1,97 @@
+import { codeLanguage, normalizeCodeLanguage } from "./codeLanguages.js";
+
+/*
+  ШАПКА БЛОКА КОДА — одна полоса над кодом, общая у Редактора и у
+  `RichTextView`. Слева язык, справа «Копировать»; код начинается
+  сразу под полосой, и кнопки его не перекрывают. Полоса — хром блока:
+  `select-none`, в выделение и в копию она не попадает.
+
+  ОДНА КАРТОЧКА ИЗ ДВУХ ЧАСТЕЙ: у шапки скруглены верхние углы и своя рамка,
+  а `pre` под ней теряет верхнюю рамку и верхнее скругление (`prose.ts` рисует
+  ему целую). Класс обёртки и правила `prose.ts` живут в одном варианте
+  `[&_pre]`, поэтому Tailwind ставит `border-top-width` и верхние радиусы ПОСЛЕ
+  `border-width` и `border-radius` — порядок решает свойство, а не очерёдность
+  в строке. Низ шапки — линия из токена разделителя `--rte-hr`, она тише рамки.
+
+  Строки литеральные и целиком: Tailwind читает исходники как текст.
+*/
+
+/** Обёртка блока: сам `pre` внутри теряет верх рамки. */
+export const CODE_BLOCK_CLASS = "[&_pre]:rounded-t-none [&_pre]:border-t-0";
+
+export const CODE_HEADER_CLASS =
+  "flex h-7 items-center justify-between gap-2 rounded-t-(--rte-radius) border " +
+  "border-(--rte-code-border) border-b-(--rte-hr) bg-(--rte-code-block-background) " +
+  "px-1 font-sans text-xs text-(--rte-code-block-foreground) select-none " +
+  // Кнопки шапки (язык, «Копировать») — хром внутри Документа: `ghost`-кнопка
+  // кита красит текст и наведение токенами темы ПРИЛОЖЕНИЯ, а они от вложенного
+  // `data-theme` не пересчитываются — на листе `surface="paper"` в тёмном
+  // приложении светлая иконка легла бы на белую шапку. Роли `--rte-*` лист
+  // переназначает (`EDITOR_PAPER_TOKENS_CLASS`), поэтому текст и наведение —
+  // ими. `button` под классом специфичнее классов кнопки, и её
+  // словарь тонов не трогается.
+  "[&_button]:text-(--rte-secondary) " +
+  "[&_button:is([data-hovered],:hover)]:bg-(--rte-control-hover)";
+
+/** Гнездо кнопки справа: строчная коробка иначе поднимала бы иконку по базовой линии. */
+export const CODE_SLOT_CLASS = "inline-flex items-center";
+
+/**
+ * Подпись языка слева; отступ тот же, что у кнопки языка в Редакторе, цвет —
+ * той же ролью `--rte-secondary`, что у кнопок шапки.
+ */
+export const CODE_LABEL_CLASS = "px-1.5 leading-6 font-semibold text-(--rte-secondary)";
+
+/**
+ * Блок кода в форме Документа: `<pre><code …>…</code></pre>` — с классом языка
+ * или без; внутри `code` и токены подсветки, и голый текст. Закрывающий `</pre>`
+ * внутри кода не встречается: текст экранирован.
+ */
+const BLOCK = /<pre>(<code(?: class="language-([\w+#-]+)")?>[\s\S]*?)<\/pre>/g;
+
+const escapeAttribute = (value: string) => value.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+
+/**
+ * Есть ли в Документе хоть один блок кода — тот, что получит шапку
+ * `withCodeHeaders`. По нему `RichTextView` решает, рисовать ли остров
+ * «Копировать»: текстовому Документу остров не нужен. Выражение то же, что у
+ * шапки, — новое, а не общее: у глобального выражения `test` сдвигает
+ * `lastIndex`.
+ */
+export function hasCodeBlocks(html: string): boolean {
+  return new RegExp(BLOCK.source).test(html);
+}
+
+/**
+ * Шапка у каждого блока кода сохранённого Документа — строка в строку, на
+ * сервере, при показе.
+ *
+ * ЗАЧЕМ РАЗМЕТКОЙ, А НЕ КЛИЕНТОМ. Подпись языка и сама полоса приходят в HTML
+ * страницы: без JS документ читается так же, а место под кнопку не
+ * появляется после гидрации и не двигает текст. Клиентский островок
+ * (`CodeCopyIsland`) только вставляет кнопку в пустое гнездо
+ * `data-code-copy`; значение атрибута — идентификатор этого просмотра, чтобы
+ * два просмотра на странице не делили гнёзда.
+ *
+ * Название языка — из данных `codeLanguages.ts` по ПРИВЕДЁННОМУ имени, а не
+ * подставленная из строки Документа: чужой класс в разметку не попадает. Блок
+ * без языка и с неизвестным остаётся без подписи — каталог сообщений серверному
+ * компоненту недоступен, а «Plain text» без перевода у русскоязычного
+ * потребителя вышло бы на английском.
+ *
+ * Строка сюда приходит уже очищенной (она так же идёт в `innerHTML`); хелпер
+ * новых источников разметки не открывает: в неё попадают только константы
+ * модуля, подпись из списка языков и идентификатор просмотра с экранированием.
+ */
+export function withCodeHeaders(html: string, hostId: string): string {
+  return html.replace(BLOCK, (_block, inner: string, name: string | undefined) => {
+    const label = name ? (codeLanguage(normalizeCodeLanguage(name))?.label ?? "") : "";
+    return (
+      `<div class="${CODE_BLOCK_CLASS}" data-code-block>` +
+      `<div class="${CODE_HEADER_CLASS}" data-code-header>` +
+      `<span class="${CODE_LABEL_CLASS}">${label}</span>` +
+      `<span class="${CODE_SLOT_CLASS}" data-code-copy="${escapeAttribute(hostId)}"></span>` +
+      `</div><pre>${inner}</pre></div>`
+    );
+  });
+}

package/src/editor/features/code/codeLanguages.ts

@@ -0,0 +1,62 @@
+/**
+ * Языки блока кода ДАННЫМИ (ADR-0051): единственное место, где
+ * Редактор знает, какие языки бывают.
+ *
+ * НОВЫЙ ЯЗЫК — СТРОКА ЗДЕСЬ И ГРАММАТИКА В `lowlight.ts`. Схема
+ * (`RICH_TEXT_SCHEMA.codeLanguages`), меню языка у блока, разбор вставки и
+ * Markdown, серверный хелпер подсветки читают этот список, а не свои копии.
+ * Забытую грамматику ловит тип: `lowlight.ts` держит `Record` по `grammar`.
+ *
+ * `id` — то, что уходит в Документ (`class="language-<id>"`) и в Markdown
+ * (```` ```<id> ````); `grammar` — имя грамматики highlight.js, когда оно не
+ * совпадает с `id` (HTML подсвечивает грамматика `xml`). `aliases` — короткие
+ * и чужие имена, которые приходят из Markdown, вставки и сохранённого HTML и
+ * приводятся к `id` при загрузке: `py` в Документе не остаётся.
+ *
+ * ИМЕНА ЯЗЫКОВ — ДАННЫЕ, А НЕ СТРОКИ КАТАЛОГА. «Python» и «YAML» не
+ * переводятся; через каталог идёт только «Обычный текст» — блок без языка.
+ *
+ * Модуль серверно-безопасен: данные и чистая функция, без импортов.
+ */
+export const CODE_LANGUAGES = [
+  { id: "python", label: "Python", grammar: "python", aliases: ["py"] },
+  { id: "typescript", label: "TypeScript", grammar: "typescript", aliases: ["ts"] },
+  { id: "javascript", label: "JavaScript", grammar: "javascript", aliases: ["js"] },
+  { id: "go", label: "Go", grammar: "go", aliases: ["golang"] },
+  { id: "html", label: "HTML", grammar: "xml", aliases: ["htm"] },
+  // JSON — рядом с YAML: оба про данные. Псевдонимов нет намеренно:
+  // `jsonc` и `json5` — это комментарии и хвостовые запятые, которых грамматика
+  // JSON не знает, и такой блок честнее показать «Обычным текстом», чем
+  // подсвеченным с ошибками.
+  { id: "json", label: "JSON", grammar: "json", aliases: [] },
+  { id: "yaml", label: "YAML", grammar: "yaml", aliases: ["yml"] },
+  { id: "markdown", label: "Markdown", grammar: "markdown", aliases: ["md"] },
+] as const;
+
+export type CodeLanguage = (typeof CODE_LANGUAGES)[number];
+export type CodeLanguageId = CodeLanguage["id"];
+export type CodeLanguageGrammar = CodeLanguage["grammar"];
+
+/** Имена языков в порядке меню — то, что бывает в `class="language-…"`. */
+export const CODE_LANGUAGE_IDS: readonly CodeLanguageId[] = CODE_LANGUAGES.map(({ id }) => id);
+
+/**
+ * Имя языка из чужого источника — к имени Документа. Регистр и пробелы по
+ * краям не важны (```` ```Python ````), псевдоним становится именем (`yml` →
+ * `yaml`). Неизвестный язык — `null`, то есть «Обычный текст»: блок остаётся,
+ * класса у него нет, и санитайзеру такой класс пропускать незачем.
+ */
+export function normalizeCodeLanguage(raw: unknown): CodeLanguageId | null {
+  if (typeof raw !== "string") return null;
+  const name = raw.trim().toLowerCase();
+  if (!name) return null;
+  const found = CODE_LANGUAGES.find(
+    ({ id, aliases }) => id === name || (aliases as readonly string[]).includes(name)
+  );
+  return found?.id ?? null;
+}
+
+/** Описание языка по имени Документа; `null` — «Обычный текст». */
+export function codeLanguage(id: CodeLanguageId | null): CodeLanguage | null {
+  return CODE_LANGUAGES.find((language) => language.id === id) ?? null;
+}

package/src/editor/features/code/highlight.ts

@@ -0,0 +1,109 @@
+import { normalizeCodeLanguage } from "./codeLanguages.js";
+import { highlightCode, type HighlightTree } from "./lowlight.js";
+
+/**
+ * Блок кода в форме Редактора: `<pre><code class="language-…">` и внутри —
+ * только экранированный текст. Схема не пускает в блок кода ни меток, ни
+ * переносов `<br>`, и `getHTML()` пишет его ровно так; DOMPurify при очистке
+ * форму не меняет.
+ *
+ * `[^<]*` — НЕ УПРОЩЕНИЕ, А ЗАСЛОН. Блок, внутри которого уже есть разметка
+ * (подсвеченный раньше, написанный руками), под выражение не подходит и
+ * остаётся как был. Отсюда идемпотентность: второй проход не находит ни одного
+ * блока с голым текстом.
+ */
+const CODE_BLOCK = /<pre><code class="language-([\w+#-]+)">([^<]*)<\/code><\/pre>/g;
+
+/**
+ * Сущности, которые пишут сериализаторы DOM (`innerHTML` браузера, jsdom у
+ * DOMPurify, `getHTML()` Tiptap) в тексте: `&amp;`, `&lt;`, `&gt;`, `&nbsp;`,
+ * плюс кавычки и числовые — их пишут другие санитайзеры.
+ */
+const NAMED: Record<string, string> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+};
+
+/**
+ * Текст блока из HTML. `null` — встретилась именованная сущность вне списка
+ * (`&copy;`): без полной таблицы HTML её не раскрыть так, как раскроет браузер,
+ * и блок лучше оставить неподсвеченным, чем показать другой текст.
+ */
+function decode(html: string): string | null {
+  let unknown = false;
+  const text = html.replace(/&(#x[\da-f]+|#\d+|[a-z][a-z\d]*);/gi, (entity, body: string) => {
+    if (body[0] === "#") {
+      const code =
+        body[1] === "x" || body[1] === "X" ? parseInt(body.slice(2), 16) : Number(body.slice(1));
+      return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : entity;
+    }
+    const named = NAMED[body];
+    if (named === undefined) unknown = true;
+    return named ?? entity;
+  });
+  return unknown ? null : text;
+}
+
+const escapeText = (text: string) =>
+  text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+const escapeAttribute = (value: string) => value.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+
+type HighlightNode = HighlightTree["children"][number];
+
+/**
+ * Дерево lowlight в HTML.
+ *
+ * ПОЧЕМУ СВОЙ СЕРИАЛИЗАТОР, А НЕ `hast-util-to-html`. Дерево lowlight узкое:
+ * текст и `span` с `className` — больше в нём ничего не бывает. Под это хватает
+ * десяти строк, а `hast-util-to-html` — ещё одна опциональная зависимость
+ * потребителя с полудюжиной своих пакетов ради разметки, которой здесь нет.
+ * Текст экранируется всегда (`&`, `<`, `>`), значение класса — в кавычках с
+ * экранированием; `style` и прочие свойства узла не пишутся вовсе.
+ */
+function serialize(nodes: readonly HighlightNode[]): string {
+  return nodes
+    .map((node) => {
+      if (node.type === "text") return escapeText(node.value);
+      if (node.type !== "element") return "";
+      const className = node.properties.className;
+      const classes = Array.isArray(className) ? className.join(" ") : "";
+      return `<span class="${escapeAttribute(classes)}">${serialize(node.children)}</span>`;
+    })
+    .join("");
+}
+
+/**
+ * Подсветить блоки кода в сохранённом Документе — для `RichTextView` и любой
+ * другой страницы показа (ADR-0051).
+ *
+ * В каждом `<pre><code class="language-…">` на языке Редактора текст
+ * заменяется токенами `<span class="hljs-…">`; цвета им даёт тема на
+ * контейнере `RichTextView` (`codeTheme.ts`). Остальной HTML не трогается ни
+ * на байт. Блок без языка, на неизвестном языке или уже с разметкой внутри
+ * остаётся как был — поэтому повторный вызов ничего не меняет.
+ *
+ * ПОРЯДОК: СНАЧАЛА ОЧИСТКА, ПОТОМ ПОДСВЕТКА. Хелпер ищет блоки выражением, а не
+ * разбором HTML, и рассчитан на разметку Схемы, которую отдаёт санитайзер.
+ * Токенов `hljs-*` в Схеме нет, и `sanitizeRichText` их снимает: очистка после
+ * подсветки вернула бы блок к голому тексту.
+ *
+ * Модуль серверно-безопасен: строка в строку, без DOM, React и Tiptap. Зовут
+ * его на сервере — при выдаче страницы или при сохранении, рядом с очисткой.
+ */
+export function highlightCodeBlocks(html: string): string {
+  return html.replace(CODE_BLOCK, (block, name: string, escaped: string) => {
+    const language = normalizeCodeLanguage(name);
+    const code = language ? decode(escaped) : null;
+    if (!language || code === null || code === "") return block;
+    const tokens = serialize(highlightCode(language, code).children);
+    // Класс — каноническое имя Схемы, а не строка из Документа: `language-PY`
+    // подсвечен как Python и должен им же и называться — иначе очистка `sanitizeRichText`
+    // снимет класс, а шапка и тема прочтут блок не так, как его подсветили.
+    return `<pre><code class="language-${language}">${tokens}</code></pre>`;
+  });
+}

package/src/editor/features/code/highlightNodes.ts

@@ -0,0 +1,65 @@
+import { createElement, type ReactNode } from "react";
+import { normalizeCodeLanguage } from "./codeLanguages.js";
+import { CODE_THEME_CLASS } from "../../styles/codeTheme.js";
+import { highlightCode, type HighlightTree } from "./lowlight.js";
+
+type HighlightNode = HighlightTree["children"][number];
+
+/**
+ * Дерево lowlight в узлы React: текст — текстом, токен — `span` с его
+ * классами `hljs-…` и больше ничем. Свойства узла, кроме класса, не
+ * переносятся, как и в сериализаторе `highlightCodeBlocks` (`highlight.ts`).
+ *
+ * Дети уходят в `createElement` списком аргументов, а не массивом: так React
+ * не просит ключей, а порядок токенов не меняется никогда.
+ */
+function toNodes(nodes: readonly HighlightNode[]): ReactNode[] {
+  return nodes.map((node) => {
+    if (node.type === "text") return node.value;
+    if (node.type !== "element") return null;
+    const className = node.properties.className;
+    const classes = Array.isArray(className) ? className.join(" ") : undefined;
+    return createElement("span", { className: classes }, ...toNodes(node.children));
+  });
+}
+
+/**
+ * Подсветить код для `CodeView` (ADR-0052) — той же грамматикой и
+ * той же темой, что блок кода Редактора и `RichTextView`.
+ *
+ * ```tsx
+ * <CodeView code={source} title="main.py" copyable>
+ *   {highlightCodeNodes(source, "python")}
+ * </CodeView>
+ * ```
+ *
+ * УЗЛЫ, А НЕ СТРОКА HTML. Код у `CodeView` обычно недоверенный — ответ API,
+ * тело вебхука, — и строка вела бы потребителя к `dangerouslySetInnerHTML`.
+ * Здесь текст кода становится текстовым узлом React и экранируется им же.
+ *
+ * Язык — по правилам Редактора (`codeLanguages.ts`): регистр, пробелы и
+ * псевдонимы не важны. Неизвестный язык и пустой код дают `null`, а не код
+ * строкой: тогда `children` у `CodeView` пуст, и он рисует код как есть — с
+ * нумерацией строк, которой при разметке нет.
+ *
+ * КОРЕНЬ С МАРКЕРОМ И ТЕМОЙ. Токены завёрнуты в один `span` с атрибутом
+ * `data-code-highlight` и классами темы (`codeTheme.ts`). Тема стоит на корне,
+ * а не на `CodeView`: разметку чужого подсветчика — даже с теми же классами
+ * `hljs-…` — она не перекрашивает. Маркер читает `CodeView`, чтобы взять фон
+ * темы подсветки: цвета GitHub не держат контраста на подложке кода кита.
+ *
+ * Хуков и `"use client"` нет: хелпер зовут и в серверном компоненте, и в
+ * клиентском.
+ */
+export function highlightCodeNodes(code: string, language: string): ReactNode {
+  const id = normalizeCodeLanguage(language);
+  if (!id || code === "") return null;
+  return createElement(
+    "span",
+    {
+      "data-code-highlight": "",
+      className: `${CODE_THEME_CLASS.trim()} text-(--rte-code-block-foreground)`,
+    },
+    ...toNodes(highlightCode(id, code).children)
+  );
+}