@olddevs/ui 0.0.0-stage → 4.0.1

package/docs/components/content/notifications.md

@@ -0,0 +1,207 @@
+---
+component: Notifications
+exports: [NotificationItem, NotificationList, NotificationGroup, NotificationCenter]
+category: content
+status: stable
+source: src/components/content/NotificationList.tsx
+story: src/components/content/NotificationList.stories.tsx
+---
+
+# NotificationItem, NotificationList и NotificationCenter
+
+## Кратко для AI
+
+Список событий: что произошло, когда и прочитано ли. Типов событий кит не знает
+— иконка, тон и текст приходят пропами. Группы («Сегодня», «Раньше») приходят
+уже собранными.
+
+## Когда использовать
+
+- Лента уведомлений в поповере, ящике (`Drawer`) или на отдельной странице.
+- Нужно отличать прочитанное от непрочитанного и отмечать прочтение.
+
+## Когда не использовать
+
+- Для временного сообщения о событии — это `toast`: он всплывает и уходит.
+- Для постоянного состояния страницы — это `Alert`, приложения — `Banner`.
+- Для шагов одного процесса — это `Timeline`: там порядок задаёт процесс, а не
+  время, и у шага нет действий.
+
+## Минимальный пример
+
+```tsx
+import { NotificationList, NotificationItem } from "@olddevs/ui";
+
+<NotificationList
+  groups={[
+    {
+      id: "today",
+      label: "Сегодня",
+      children: <NotificationItem title="Публикация не прошла" unread time="5 минут назад" />,
+    },
+  ]}
+  empty={<EmptyState title="Пока тихо" />}
+/>;
+```
+
+## Пропы
+
+`NotificationItem`: `title`, `description`, `time`, `icon`, `media`, `tone`,
+`unread` и **одно из** `actions` / `onAction`.
+
+`NotificationList`: `groups` **или** `children`, `empty`, `aria-label`.
+
+`NotificationCenter`: `title`, `level`, `titleId`, `unreadCount`,
+`filters`, `actions`, `selectedCount`, `onClearSelection`, `selectionActions`,
+`footer`, `children`.
+
+## Превью и иконка — два независимых слота
+
+`icon` говорит, **что** случилось (тип события, тон), `media` — **с чем**
+(превью объекта, о котором событие). Строка показывает оба: иконка слева, превью
+следом, затем текст. Размер превью задаёт сам элемент (`Image` на 36px,
+`Avatar`); слот только не даёт ему сжаться. Если заголовок
+уже называет объект, превью декоративно и получает `alt=""`.
+
+```tsx
+<NotificationItem
+  title="Модерация завершена"
+  icon={<InfoIcon size={16} />}
+  media={<Image src={item.previewUrl} alt="" className="size-9 rounded-md" />}
+/>
+```
+
+## Вся строка — одна кнопка (`onAction`)
+
+`onAction` превращает строку в **одну кнопку на всю площадь**: щелчок, Enter и
+Space вызывают обработчик. Строка по-прежнему `<li>` списка, кнопка лежит внутри
+неё; подложка непрочитанного остаётся на `li`, а наведение и кольцо фокуса —
+на кнопке; кольцо рисуется внутрь строки, потому что снаружи его срезала бы
+прокрутка центра.
+
+- **Имя кнопки — заголовок** и слово «Не прочитано» (`aria-labelledby` на оба
+  узла), а не весь текст: полным содержимым имя вышло бы на полстраницы.
+  **Время и подробности — описание** кнопки (`aria-describedby`), поэтому не
+  теряются.
+- Внутри кнопки нет вложенных интерактивных элементов, а блоки строки — `span`:
+  в `button` допустим только фразовый контент.
+- **Отступы и раскладка строки лежат на кнопке**, а `className` приходит на
+  `<li>`: подложка и граница через него меняются, `px-*`, `py-*` и `gap-*` — нет.
+  Без `onAction` они лежат на самом `li`.
+- **В имя и описание попадают только заголовок, слово «Не прочитано», время и
+  подробности.** `alt` превью и текст иконки в них не входят: важное об объекте
+  («фото Анны К.») пишите в заголовок, а превью оставляйте декоративным.
+- **`onAction` — это кнопка, а не ссылка.** Если щелчок ведёт на адрес и нужны
+  открытие в новой вкладке и клик средней кнопкой мыши, строку оборачивает ссылка снаружи
+  либо переход идёт через `actions` со ссылкой; кнопка с `router.push` этих
+  свойств лишена.
+- Наведение у непрочитанной строки затемняет подложку акцента, у прочитанной —
+  заливает нейтральным цветом.
+- Строка без `onAction` кнопки не содержит — разметка прежняя, без лишних `id`.
+
+```tsx
+<NotificationItem title="Публикация не прошла" unread onAction={() => markRead(id)} />
+```
+
+**С `actions` не сочетается**, и это сказано типом: кнопки внутри кнопки —
+недопустимая разметка. Если нужны и щелчок по строке, и отдельные действия,
+выберите одно: действие на всю строку или кнопки справа.
+
+Потребитель на JS мог передать оба пропа: типы его не остановят. Кит при этом не
+роняет страницу: **побеждает `actions`, `onAction` игнорируется.** Из двух
+потерь выбрана меньшая: `actions` может быть единственным путём к действию
+(«удалить», «открыть»), а щелчок по всей строке — удобство. Сбой виден сразу:
+строка не отзывается на щелчок. В режиме разработки об этом ещё и пишет консоль:
+один раз на загрузку модуля `console.warn` с английским текстом: что передано, что
+победило и как исправить. В продакшн-сборке кит молчит. Правила таких
+предупреждений — [conventions.md](../../conventions.md#предупреждения-в-режиме-разработки).
+
+## Заголовок центра: уровень и `id`
+
+По умолчанию заголовок `NotificationCenter` — обычный текст (`span`): в структуру
+заголовков страницы он не входит. `level` (`2`, `3` или `4`; имя то же, что у
+`SectionHeader`) делает его
+настоящим `<h2>`–`<h4>`: уровень зависит от того, куда центр встал, и знает это
+потребитель. `titleId` ставит `id` на элемент заголовка, чтобы на него ссылался
+`aria-labelledby` поповера или ящика:
+
+```tsx
+<PopoverContent aria-labelledby="bell-title">
+  <NotificationCenter level={2} titleId="bell-title" unreadCount={12}>
+    …
+  </NotificationCenter>
+</PopoverContent>
+```
+
+`titleId` работает и без `level` (`id` встанет на `span`): имя
+контейнера придёт от заголовка, а структуру страницы центр не тронет. Без обоих
+пропов разметка и поведение прежние.
+
+## У центра нет контейнера
+
+`NotificationCenter` — не поповер, не ящик и не страница: он их **содержимое**.
+Потребитель ставит его внутрь существующих `Popover` или `Drawer` либо прямо на
+страницу, и центр не открывает и не закрывает себя — состояние контейнера живёт
+снаружи.
+
+Иначе пришлось бы выбрать один контейнер за все приложения сразу, а в админке
+лента чаще страница, в клиентском приложении чаще поповер.
+
+Массовые действия — существующий `SelectionBar`, а не своя полоса: он уже несёт
+счётчик, снятие выделения, два слота действий и правило «при нуле полосы нет
+вовсе». Липкость у него здесь выключена: в поповере прилипать не к чему.
+
+**Счётчик непрочитанных приходит пропом**, а не считается по строкам: список
+бывает страницей коллекции, и «3» вместо «300» — неправда.
+На экране `Badge` обрезает большое число до «99+», но имя для скринридера остаётся
+точным.
+
+## Непрочитанное слышно, а не только видно
+
+Точка и подложка — сигнал для глаз. Рядом с заголовком непрочитанного события
+встаёт слово из каталога сообщений: без него человек, который цвета не видит, не
+отличит новое событие от старого вовсе. Сама точка `aria-hidden` — иначе
+скринридер объявил бы безымянный узел рядом со словом.
+
+## Группы приходят готовыми
+
+Что такое «вчера», знает локаль и часовой пояс потребителя: у приложения с
+ночными сменами граница суток своя, и считать её в ките значило бы навязать
+чужой календарь.
+
+Группа объявляется **группой с подписью** (`role="group"`), а не заголовком.
+Уровень заголовка (`h2`, `h3`) зависит от того, куда встал список (в поповер, в
+ящик или на страницу), и кит этого не знает. Группа сообщает структуру, не
+занимая уровня.
+
+## Строка ничего не решает сама
+
+Она не навигирует и не отмечает себя прочитанной: и переход, и отметка — действия
+приложения. Приложение передаёт их в `actions` или `onAction` (вся строка — кнопка) либо
+оборачивает строку снаружи.
+
+Время приходит **уже отформатированным**: «5 минут назад» и «вчера в 14:03» собирает
+приложение через `Intl.RelativeTimeFormat` с часовым поясом потребителя.
+
+## Антипаттерны
+
+- Заводить `type: "publication_failed"` вместо `icon` и `tone`: доменные типы
+  событий в кит не переезжают.
+- Отмечать непрочитанное только цветом.
+- Считать группировку внутри компонента.
+- Считать счётчик непрочитанных по видимым строкам.
+- Заворачивать центр в свой поповер внутри кита: контейнер выбирает потребитель.
+- Передавать `onAction` вместе с `actions`: типы запрещают, а на JS победит `actions`
+  (и в разработке консоль предупредит).
+- Класть в `media` или `title` строки-кнопки интерактивные элементы: они окажутся
+  внутри кнопки.
+- Давать поповеру `aria-label` рядом с настоящим заголовком вместо `titleId`: имя
+  разойдётся с видимым заголовком при правке.
+
+## Связанные исходники и проверка
+
+- Исходник: `src/components/content/NotificationList.tsx`
+- Тесты: `tests/notification-list.test.tsx`
+- Витрина: `src/components/content/NotificationList.stories.tsx`, `src/components/content/NotificationCenter.stories.tsx`
+- Тесты центра: `tests/notification-center.test.tsx`
+- Решение: ADR-0027

package/docs/components/content/rich-text-view.en.md

@@ -0,0 +1,325 @@
+---
+component: RichTextView
+exports:
+  [
+    RichTextView,
+    RichTextViewProps,
+    sanitizeRichText,
+    RichTextPurifier,
+    RichTextAttributeHookEvent,
+    richTextSanitizeConfig,
+    RichTextSanitizeConfig,
+    richTextSchema,
+    RichTextSchema,
+    RichTextCustomBlockRules,
+    RichTextCustomMarkRules,
+    highlightCodeBlocks,
+  ]
+category: content
+status: stable
+source: src/editor/RichTextView.tsx
+story: src/editor/RichTextView.stories.tsx
+sourceHash: 167024d9709e
+---
+
+# RichTextView
+
+## Summary for AI
+
+`RichTextView` shows the saved HTML of `RichTextEditor` with the same typography as inside the Editor. **There is no engine**: neither Tiptap nor lowlight is in the module graph, so the component renders in a server component and does not contain `"use client"` itself. The graph has two client parts, both Islands: the "Copy" button on code blocks and (only with the `tools` prop and a custom Block in the Document) the Island of a custom Block (section "Custom Block's Island"). **It does not sanitize HTML**: `html` must arrive from the server already sanitized against the Schema allowlist — `sanitizeRichText(html, DOMPurify)` from `@olddevs/ui/editor/schema` (section "Sanitization on the consumer's server"). It lives in the `@olddevs/ui/editor` entry point, not in the barrel. **It does not highlight code blocks itself**: the server highlights the HTML with `highlightCodeBlocks(html)` from `@olddevs/ui/editor/highlight` after sanitizing, and `RichTextView` colors the finished tokens with the GitHub Light/Dark theme. Every code block has a header with the language on the left and a "Copy" button on the right (section "The "Copy" button and the header").
+
+```tsx
+import { RichTextView } from "@olddevs/ui/editor";
+```
+
+## When to use
+
+- The page shows a Document saved by `RichTextEditor`: an article, a description, a policy.
+- You need the component in a server component, or where pulling in Tiptap just to read is not acceptable.
+
+## When not to use
+
+- The HTML came from a user and the server has not sanitized it — sanitize first (section "Sanitization on the consumer's server"), then show. The component puts everything it receives into the page.
+- For editing, use `RichTextEditor`. Its `readOnly` keeps the engine alive for text that does not change; for a page that only displays the Document, use `RichTextView`.
+- Arbitrary HTML outside the Schema (`style` other than the author's color, `thead`, `caption`, images without `figure`): the typography is built for the Schema's tags, and anything else looks like the browser default.
+- For short single-line text, use `Text`.
+
+## Minimal example
+
+In Next.js, the `@olddevs/ui/editor` entry point must be listed in `optimizePackageImports` on its own line ([getting-started.md](../../getting-started.md#пакет-в-серверных-компонентах)): otherwise the whole Editor with its engine ships to the browser along with the View — 435 kB of `First Load JS` instead of 137 kB.
+
+```tsx
+// Server component: no directive needed.
+import { RichTextView } from "@olddevs/ui/editor";
+
+export default async function ArticlePage({ id }: { id: string }) {
+  const article = await loadArticle(id); // article.html was sanitized on save
+  return <RichTextView html={article.html} className="max-w-prose" />;
+}
+```
+
+## Public API
+
+- `html` — the saved Document, an HTML string. **Not sanitized**: it goes into the markup through `dangerouslySetInnerHTML` as is. An empty string renders an empty container.
+- `className` — added **after** the typography classes and can override them.
+- `surface` — `"theme"` (default) or `"paper"`: Paper, a light area in any theme, see "Surface". The type is `RichTextSurface`.
+- `tools` — the Document's own Tools, the same array as for `RichTextEditor` and `sanitizeRichText`. The View reads only the Islands of custom Blocks from it (`blocks[name].island`, type `CustomIslandProps`); without `tools` the View stays as before (section "Custom Block's Island").
+- Everything else is regular `div` props: `id`, `aria-*`, `data-*`, `ref`. `children` and `dangerouslySetInnerHTML` are not accepted.
+- `highlightCodeBlocks(html)` — server-side highlighting of code blocks, the `@olddevs/ui/editor/highlight` entry point (section "Code block highlighting"). `RichTextView` has no prop for this, on purpose.
+- `sanitizeRichText(html, purify, tools?)` — sanitizes HTML against the Schema with a DOMPurify instance supplied by the consumer; installs the Schema hooks for the duration of the call. The instance type is the structural `RichTextPurifier` (the hook event is `RichTextAttributeHookEvent`). The third argument is the same `tools` array as the Editor's: with it, custom Blocks and Marks are allowed through under their own rules (section "Custom Tools: the third argument"); without it, sanitizing works as before. This is the safe default path (section "Sanitization on the consumer's server").
+- `richTextSchema(tools?)` — the Schema as data for a set of `tools`: the `RICH_TEXT_SCHEMA` fields plus `customBlocks` and `customMarks` — the rules of custom Blocks and Marks (`RichTextCustomBlockRules`, `RichTextCustomMarkRules`). The type is `RichTextSchema`. The `RICH_TEXT_SCHEMA` constant itself is still the kit's Schema.
+- `richTextSanitizeConfig()` — a restrictive sanitizing config for DOMPurify without hooks: safe on its own, but it loses part of the Editor's markup. The type is `RichTextSanitizeConfig`.
+- `sanitizeRichText`, `richTextSchema` and `richTextSanitizeConfig` are data and functions only, with no dependencies; they are safe in a server module. The lightweight entry point is `@olddevs/ui/editor/schema`; they are also available from `@olddevs/ui/editor`.
+
+The typography comes from the same `src/editor/styles/prose.ts` module that attaches classes to the Editor's content, so text looks the same in the Editor and on the page. The classes sit on the container and find tags by name, so the Document's HTML has no classes or `style`. Colors come from the kit's tokens, and the `dark`, `light` and `dim` themes switch on their own. A separate Tailwind `@source` is not needed: the line from [getting-started.md](../../getting-started.md) covers the classes.
+
+## Paper: `surface`
+
+`surface="paper"` is Paper, a light area in any app theme, like [`RichTextEditor`](../inputs/rich-text-editor.md#лист-surface): text, links, palettes, markers, tables, captions and code blocks (GitHub Light) look as in the light theme, and Paper is set off from the page by the app theme's border and shadow. By default (`"theme"`) the Document follows the app theme and does not set a background.
+
+```tsx
+<RichTextView html={cleanHtml} surface="paper" />
+```
+
+**When to use Paper:** a print or PDF preview, displaying an email or a document that will leave the app in its light look. A Document that is only read inside the app stays on `"theme"`. Everything around Paper — page headings, buttons, menus — stays in the app theme: Paper covers only the `RichTextView` container.
+
+The component stays a server component: Paper is classes and attributes on the container (`data-theme="light"`, `data-surface="paper"`), with no `style` and no client code. The same Document on the Paper looks identical in the Editor and here — a test checks this.
+
+## Schema and security
+
+The Schema is the only source of the Editor's allowed markup: the Editor drops everything that is not in it, both on load and on paste. `RichTextView` does **not check** the Schema: it shows HTML without parsing it.
+
+The allowlist of tags and attributes (the table mirrors `src/editor/core/schema.ts` and is checked by a test; the list grows with the set of Blocks and Marks):
+
+<!-- allow-list -->
+
+| What       | Allowed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Blocks     | `p`, `h1`, `h2`, `h3`, `h4`, `ul`, `ol`, `li`, `blockquote`, `hr`, `pre`, `table`, `tbody`, `tr`, `th`, `td`; `label`, `input`, `span` — only inside a checklist item; `div` — there too, plus the Layout and its columns (a Layout only at the top level, a column only directly inside it) and the Wrapper (at the top level and directly in a column, not in another Wrapper); `figure` — an image, with `img` and an optional `figcaption` inside (they do not exist outside `figure`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Marks      | `strong`, `em`, `u`, `s`, `code`, `sup`, `sub`, `mark` (only with a color), `br`, `a`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Attributes | `ol[start]` — only when numbering does not start at 1; `ul[data-type]`, `li[data-type]`, `li[data-checked]` — checklist; `input[type]`, `input[checked]` — its checkbox; `code[class]` — the code block language, only "language-python", "language-typescript", "language-javascript", "language-go", "language-html", "language-json", "language-yaml" or "language-markdown" (no language, no class); `span[data-color]`, `mark[data-color]` — text color and marker, only names from that tag's palette: text colors on `span`, markers on `mark`; `span[style]`, `mark[style]` — the author's custom color, only "color:#rrggbb" and "background-color:#rrggbb", and not together with "data-color"; `p[data-align]`, `h1[data-align]`, `h2[data-align]`, `h3[data-align]`, `h4[data-align]` — Block alignment, center or right; `th[colspan]`, `td[colspan]` — horizontal merge, an integer from 2 to 20; `th[rowspan]`, `td[rowspan]` — vertical, from 2 to 50; `th[data-align]`, `td[data-align]` — column alignment, center or right, on each of its cells; `a[href]` — only "http", "https" or "mailto"; `a[rel]` — always "noopener noreferrer"; `img[src]` — only absolute "http" or "https", no "data:" or "blob:"; `img[alt]` — always, empty for an image without a description; `img[data-width]` — 50, 75 or 100; `div[data-block]` — the Layout ("layout"), its column ("column") and the Wrapper ("wrapper"); `div[data-layout]` — the Layout variant, column shares in percent: "100", "50-50", "33-33-33", "25-25-25-25", "60-40" or "40-60"; `div[data-tone]` — the Wrapper tone, only on it: "neutral", "accent", "success", "warning" or "danger" (no tone, no attribute) |
+
+Tiptap writes a checklist item like this: `<li data-type="taskItem" data-checked="true"><label><input type="checkbox" checked><span></span></label><div><p>…</p></div></li>`. `sanitizeRichText` lets `input`, `label`, `span` and `div` through only inside such an item, and `input` only with `type="checkbox"`.
+
+The Editor writes a table like this: `<table><tbody><tr><th><p>…</p></th></tr><tr><td colspan="2" data-align="center"><p>…</p></td></tr></tbody></table>`. The header row is the first row made of `th`, and a cell has only three attributes: `colspan` and `rowspan` (merging, an integer from 2 to `RICH_TEXT_SCHEMA.tableSpans`: 20 horizontally and 50 vertically; 1 is not written) and `data-align` (column alignment, `center` or `right`, on every cell of the column). A row fully covered by a merge from above stays an empty `<tr></tr>`. `thead`, `tfoot`, `colgroup` and `caption` are not in the Schema, and **by default DOMPurify removes the contents of `thead` and `colgroup` along with the tags**: the header of a third-party table written in `thead` disappears. The Editor does not write `thead`, so for its HTML this is no loss. `tbody`, `tr`, `th` and `td` outside a table are dropped by the HTML parser before sanitizing (the text stays), `style` and `colwidth` are not allowed through, and `colspan` and `rowspan` are let through only by the `sanitizeRichText` hook: on `th` and `td`, and only as digits within the Schema's limits; the bare config does not know them at all. Without such a check, `colspan="10000"` in third-party HTML would expand into 10,000 empty cells for everyone who opens the Document.
+
+There are no other classes, `style` (except the custom color, see below), `aria-*` or `data-*` (except eight Schema names: `data-type` and `data-checked` of the checklist, `data-color` for color, `data-align` for alignment, `data-width` for image width, `data-block` and `data-layout` of the Layout, and `data-tone` of the Wrapper) in the output HTML. An `h1` appears in a Document only if the Editor has the `heading1` Tool (on by default in `full`); a screen that puts an H1 above the Editor turns this Tool off.
+
+**An image** is written by the Editor like this: `<figure><img src="https://…" alt="…" data-width="50"><figcaption>…</figcaption></figure>`. `figcaption` is present only when the caption is not empty, `data-width` only on an image with a set width (`50`, `75` or `100` percent of the Document width, `RICH_TEXT_SCHEMA.imageWidths`; without it, the image keeps its own size, no wider than the Document), and `alt` is always present and empty for an image without a description. The URL must be an absolute `http` or `https` URL (`RICH_TEXT_SCHEMA.imageProtocols`): the Editor never writes `data:` (base64) or `blob:`, and an image never has `style`, `width`, `height` or `class` — neither on `img` nor on `figure`. The Editor does not output a bare `<img>` outside `figure`; `sanitizeRichText` removes it.
+
+**Color and alignment are names, not CSS values.** `data-color` accepts only the names of the Editor's palette, and there are two palettes, one per tag. On `span` (text color): `accent`, `success`, `warning`, `danger`, `lime`, `muted` (`RICH_TEXT_SCHEMA.textColors`); on `mark` (marker): `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red` (`RICH_TEXT_SCHEMA.markerColors`). The Editor menu offers the bright `yellow`, `green` and `pink`; the other six stay readable and are still rendered with their previous values. A name from another tag's palette is not allowed on a tag. Documents saved before the marker palette contain six old names on `mark`; they are converted (`RICH_TEXT_SCHEMA.legacyMarkerColors`, the table is in the [Editor documentation](../inputs/rich-text-editor.md#цвет-маркер-и-выравнивание)): `sanitizeRichText` does this with a hook, and `RichTextView` itself renders an old name in the color it is converted to. `data-align` is `center` or `right` (the Editor does not write `left` and reads it as the absence of the attribute; `RICH_TEXT_SCHEMA.alignments`). The theme supplies the concrete colors, so the same saved text stays legible in `dark`, `light` and `dim`: `RichTextView` and the Editor style `data-color` with the same classes (`prose.ts`). DOMPurify does not check attribute values — the `sanitizeRichText` hooks do.
+
+**The order of Marks on a marker.** The Editor writes the marker as the outermost Mark after the text color (`<span data-color><mark><sup>…`), so the highlight does not shift on superscripts and does not break on a link. `RichTextView` does not rebuild the HTML: a Document saved earlier as `<sup><mark>…</mark></sup>` is shown in the old order, and the part of the marker on the superscript rises with it. The order is corrected when the Document is opened and saved in the Editor.
+
+**A custom color is the only exception to "there is no `style`".** Besides the palette colors, the author can pick any color in `ColorPicker` ("Custom color…" in the Editor's color menu). Such a color has no name, and HTML stores its value in `style`, so it is written into the Document strictly like this: `<span style="color:#ff0000">` for text and `<mark style="background-color:#ffee00">` for a marker. The rule is narrow and is recorded in the Schema (`RICH_TEXT_SCHEMA.customColor.styles`, regular expressions as strings): lowercase letters, exactly six digits, no spaces and no `;`, one declaration per tag, and never together with `data-color` on the same element. The Editor drops any other `style` (`#f00`, `rgb(…)`, `red`, a second declaration next to it, `style` on another tag) on load and paste, and `sanitizeRichText` strips it the same way: the hook checks the tag and the value against the same expressions. The bare `richTextSanitizeConfig()` has no `style` at all: DOMPurify's `ALLOWED_ATTR` is shared by all tags, and without a hook it would let any CSS through.
+
+**The author's color does not change with the theme.** Palette colors are tokens, and one saved text stays legible in `dark`, `light` and `dim`. `#ff0000` is a value: it is the same in every theme, and a color-and-background pair may lose contrast where the author never saw it. The Editor warns about this on selection (4.5:1 contrast with the current theme's background; for a marker, the body text on it is checked), but it does not forbid it and does not recompute the color when the theme changes. If a Document is shown in several themes, use the palette.
+
+The Editor writes a link like this: `<a href="https://…" rel="noopener noreferrer">…</a>`. The URL must be absolute and use the `http`, `https` or `mailto` scheme: the Editor does not accept relative URLs or other schemes (`javascript:`, `data:`, `ftp:`) from `value` or from paste. It does not write `target`: whether to open links in a new tab is decided by the page that displays the Document, not by the Document.
+
+### Sanitization on the consumer's server
+
+Client-side sanitizing does not protect against XSS: a request that bypasses the interface can carry anything. Sanitize HTML **on the server on save** (and ideally on output too, if the database holds old records). DOMPurify is not among the kit's dependencies — you install it yourself, and the kit provides the Schema's policy through the `sanitizeRichText` helper:
+
+```bash
+npm install dompurify jsdom   # or isomorphic-dompurify
+```
+
+```ts
+import { JSDOM } from "jsdom";
+import createDOMPurify from "dompurify";
+import { sanitizeRichText } from "@olddevs/ui/editor/schema";
+
+const DOMPurify = createDOMPurify(new JSDOM("").window);
+
+export function sanitizeDocument(html: string): string {
+  return sanitizeRichText(html, DOMPurify);
+}
+```
+
+`sanitizeRichText(html, purify)` takes a DOMPurify instance as an argument — the kit does not import it, the instance type is structural (`RichTextPurifier`), and `dompurify` with jsdom or `isomorphic-dompurify` fit without casts. For the duration of one call, the helper installs the Schema hooks on the instance and removes them when the call returns: you use one instance for everything (comments, emails), so the Editor's rules do not fire when other code sanitizes with that instance, and your hooks stay in place. The Editor's markup comes through **byte for byte**; the hooks strip everything else: the text from a stripped tag stays, as in the Editor. What they check:
+
+- `label`, `input`, `span` and `div` — only the markup of a checklist item; `input` — only `type="checkbox"`; `ul[data-type]`, `li[data-type]`, `li[data-checked]` — only the checklist values;
+- `ol[start]` — only on `ol`;
+- `code[class]` — only the canonical `language-<name>` from `RICH_TEXT_SCHEMA.codeLanguages`: an alias (`language-py`), an unknown language, a second class and a class on another tag are stripped, and so are `hljs-*` tokens;
+- `span[data-color]` and `mark[data-color]` — only names from that tag's palette; old marker names are converted (`legacyMarkerColors`); a `mark` without a color is stripped;
+- `style` — only `color:#rrggbb` on `span` and `background-color:#rrggbb` on `mark` (`RICH_TEXT_SCHEMA.customColor.styles`), and never together with `data-color`;
+- `data-align` — `center` or `right` on `p`, `h1`–`h4`, `th`, `td`;
+- `colspan` and `rowspan` — only on `th` and `td`, an integer no greater than `RICH_TEXT_SCHEMA.tableSpans`;
+- a link — `href` only `http`, `https` or `mailto`, `rel` always `noopener noreferrer`, an unexpected `target` is stripped, a link without a valid URL becomes text;
+- an image — `img` with an absolute `http`/`https` directly inside `figure` (no `data:` or `blob:`), `data-width` is a preset, `alt` is always present; an `img` outside `figure` is removed, and a `figcaption` outside `figure` loses its tag.
+
+Checked with the real DOMPurify 3.4.16 on jsdom in `tests/editor-sanitize.test.tsx`: a Document with every Block and Mark of the Editor comes through unchanged, while forged input is stripped — Tailwind classes (`class="fixed inset-0"`), `style` on `p`, a `data:` image, a `javascript:` link, a name from another palette, a `label` outside an item, `colspan="10000"` and others.
+
+#### Custom Tools: the third argument
+
+If the Editor works with custom Tools ([RichTextEditor, "Custom Tool"](../inputs/rich-text-editor.md#свой-инструмент)), the server passes **the same `tools` array** to `sanitizeRichText`. The description of a custom Tool is data, and the module with it is imported on the server: sanitizing reads only the Schema rules (`blocks`, `marks`) and does not touch the Engine part. To keep Tiptap out of the server graph too, keep the description in a module with no extension imports — the Engine part is then supplied by a Loader ([RichTextEditor, "Engine part Loader"](../inputs/rich-text-editor.md#загрузчик-части-для-движка)) or built next to the Editor.
+
+```ts
+import { sanitizeRichText } from "@olddevs/ui/editor/schema";
+import { EDITOR_TOOLS } from "./editor-tools"; // the same array as in the Editor's `tools`
+
+export function sanitizeDocument(html: string): string {
+  return sanitizeRichText(html, DOMPurify, EDITOR_TOOLS);
+}
+```
+
+- **A custom Block** comes through as `div[data-block="<name>"]`, an inline Atom as `span[data-block="<name>"]`, a custom Mark as `span[data-mark="<name>"]`. A Block of the wrong kind (an Atom in a `div`, a block-level Block in a `span`) and an unknown name lose their tag; the text stays.
+- **Custom attributes** `data-<name>` — only on their own element and only with a value that follows the rule: from a list, matching a pattern, or a URL that follows the link policy (absolute `http`, `https`, `mailto`). A value with markup (`<`) is never allowed through. An invalid value is stripped together with the attribute, and the element itself stays — the Editor does the same.
+- **Anything extra on a custom Block's element** — `class`, `style`, `data-color`, handlers, an attribute of another Block — are stripped.
+- **The `top` slot** — only the Document's top level: a nested Block (in a quote, a Wrapper, another Block) loses its tag, like a Layout.
+- **Names of the kit's Tools do not narrow the allowlist.** `["bold", acmeCard]` sanitizes the same as `[...RICH_TEXT_PRESETS.full, acmeCard]`: screens with different sets write one Document, and the server must not strip a table that a `full` screen wrote. The server ignores rules with a name that lacks a Consumer prefix: the Editor rejects such a set with a field error, and on the server it must not create a way around the kit's rules.
+- **Without the third argument** sanitizing is the same as before custom Tools: custom Blocks are stripped like any other third-party HTML.
+
+`richTextSchema(tools)` returns the same rules as data — for your own sanitizer or a check on the database side: `customBlocks` (kind, slot, attributes — with defaults filled in) and `customMarks`. There are no Block traits (`container`, `turnInto`, `plainAtom`) in it: that is the Editor's behavior, not what arrives in HTML. Checked in `tests/editor-sanitize-tools.test.tsx`: an Editor Document with custom Blocks, Atom and Mark comes through sanitizing byte for byte, and forged input is stripped the same way the Editor strips it.
+
+**`richTextSanitizeConfig()` is restrictive by default.** This is a config for anyone who passes it to DOMPurify directly, without hooks. DOMPurify's shared `ALLOWED_ATTR` (one list for all tags, and it does not check values) includes only what is harmless on any tag and with any value: `data-type`, `data-checked`, `data-color`, `data-align`, `data-width`, `data-block`, `data-layout`, `data-tone`, `start`, `alt`, `rel` and `href`. `style`, `class`, `src`, `colspan`, `rowspan`, `type`, `checked` and the `input` and `img` tags are allowed only by `sanitizeRichText`, after checking the tag and the value: without a check they would let through any CSS and class, a base64 image and 10,000 empty cells. The bare config is therefore safe, but it loses part of the Editor's markup — the author's color, the code block language, cell merging, checkboxes and images. `ALLOW_DATA_ATTR` and `ALLOW_ARIA_ATTR` are off: by default DOMPurify lets any `data-*` and `aria-*` through. Every call returns new arrays.
+
+The config checks the link URL itself: `ALLOWED_URI_REGEXP` lets only `http:`, `https:` and `mailto:` through — the same policy as the Editor. DOMPurify checks every allowed attribute against this expression except the "URI-safe" ones, and a strict expression would strip `start="3"` or `data-color="danger"`; so the config declares all attributes except URLs safe (`ADD_URI_SAFE_ATTR`). An image URL cannot be restricted by the expression: DOMPurify lets `data:` in the `src` of an `<img>` through, bypassing `ALLOWED_URI_REGEXP` — so `src` is allowed only by the hook.
+
+The sanitizing helpers and the Schema come from the separate lightweight entry point `@olddevs/ui/editor/schema`: it holds the Schema as data (`RICH_TEXT_SCHEMA`, `richTextSchema`), `sanitizeRichText`, `richTextSanitizeConfig()`, their types and the Text card helper `markRange` for describing a custom Tool. It has no React and no Tiptap, so a server without the Editor does not need to install the engine. `@olddevs/ui/editor` still exports the same names, but on a server without a bundler this entry point would load the whole Editor with its engine.
+
+## Code block highlighting
+
+In a Document, a code block carries only the language — `<pre><code class="language-python">…</code></pre>`; there are no highlight tokens in it (ADR-0051). A server helper highlights the saved HTML:
+
+```tsx
+// Server component.
+import { RichTextView } from "@olddevs/ui/editor";
+import { highlightCodeBlocks } from "@olddevs/ui/editor/highlight";
+
+export default async function ArticlePage({ id }: { id: string }) {
+  const article = await loadArticle(id); // article.html was sanitized on save
+  return <RichTextView html={highlightCodeBlocks(article.html)} />;
+}
+```
+
+- **What it does.** In every `<pre><code class="language-…">` in a language the Editor supports (`RICH_TEXT_SCHEMA.codeLanguages`, aliases too), the text is replaced with `<span class="hljs-…">` tokens, parsed by lowlight with the same grammar as in the Editor, and the Block's class is written with the Schema's canonical name: `language-py` and `language-PY` come out as `language-python`, `language-js` as `language-javascript`. The rest of the HTML does not change by a single byte. A Block with no language, with an unknown language, and a Block that already has markup inside stay as they were — so a repeated call changes nothing.
+- **Escaping.** The helper does not parse HTML; it finds Blocks with an expression: inside a Block the Schema allows only text. Entities in the text are decoded (`&lt;`, `&amp;`, `&quot;`, `&#39;`, `&nbsp;`, numeric ones), and the text is escaped again after highlighting: `<script>` in code stays the text `&lt;script&gt;`. A Block with another named entity (`&copy;`) is not highlighted — better without color than with different text. The output has only `span` with `class="hljs-…"`, with no `style`.
+- **The order is sanitize, then highlight.** The helper is built for the Schema's markup that the sanitizer returns, and there are no `hljs-*` tokens in the Schema — `sanitizeRichText` strips them. Highlight after sanitizing: when serving the page, or right after sanitizing on save. If highlighted HTML sits in the database, repeated sanitizing on output returns the Block to bare text, and `highlightCodeBlocks` highlights it again; the Editor, given such HTML in `value`, drops the tokens itself.
+- **Theme.** Token colors are GitHub Light in the `light` theme and GitHub Dark in `dark` and `dim`, as in the Editor: the `.hljs-*` rules are classes on the `RichTextView` container (`src/editor/styles/codeTheme.ts`), and the colors are variables in `styles.css` on elements with `data-theme`. A code block takes the theme of the nearest ancestor with `data-theme`, so `RichTextView` inside a nested `data-theme="light"` within a dark app shows GitHub Light. Neither `style` nor separate CSS is needed.
+- **Cost.** The `@olddevs/ui/editor/highlight` entry point consists of the helper, lowlight, the highlight.js core and eight grammars, and weighs 22.6 kB gzip; Tiptap is not in its graph, and Node loads it without a bundler. Of the kit's peer dependencies, only `react` is in the graph: the entry point's second helper, `highlightCodeNodes` for [`CodeView`](code-view.md#подсветка-кита) (ADR-0052) needs it. `RichTextView` does not import it and stays at 12.0 kB gzip (with the "Copy" Island), which is why highlighting is not a component prop: a flag would not remove the highlighter from the graph, yet every render would pay for it. For the entry point, install only `lowlight` and `highlight.js` (Editor engine packages, not in the kit's manifest).
+
+## The "Copy" button and the header
+
+**Every** `pre > code` Block has a header above the code: the language name on the left and a "Copy" button on the right — the kit's `CopyButton` with the tooltip "Copy code" → "Copied". The button is always there, and there is no prop to turn it off (the owner's decision): the header is part of the Block's look, and in the Editor it is the same ([RichTextEditor](../inputs/rich-text-editor.md#блок-кода)). Both parts are visible without hover, on desktop and on touch screens; the code starts below the header, and the button does not cover it.
+
+**How it works and why the component stays a server component.** `RichTextView` gets no handlers and no state — it is still just a string turned into markup:
+
+1. Next to `dangerouslySetInnerHTML`, it wraps every `<pre><code>` Block in a header **string to string** (`withCodeHeaders`, `src/editor/features/code/codeHeader.ts`): the header consists of the language label (taken from the Editor's language list by the normalized name; the class from the Document does not reach the markup: `language-py` yields "Python", `language-rust` yields an empty label) and an empty Mount point for the button. This is the component's own markup, built **after** sanitizing, so there is nothing for the sanitizer to allow.
+2. If the Document has at least one code block, the component renders the `CodeCopyIsland` Island next to the container (`src/editor/features/code/CodeCopyIsland.tsx`, with its own `"use client"`). A Document without code has no Island at all: no markup, no effect. After mounting, the Island finds the Mount points of **its own** View and inserts a `CodeCopyButton` into each through a portal. On the server and during hydration, the Island renders only an empty inert anchor `<template>` that marks the Island's place. There are no portals yet, so the server markup and the first client pass match, and a page without JS reads the same: the language label and the code are in place, the button is not.
+3. The Island is linked to the Mount points by its place in the tree. The container cannot be passed as a ref: a server component has none. So the Island takes the sibling to the left of its anchor `<template>`, that is, the container of its own View, and looks for Mount points only in it, not through the global `document`: a View in a shadow root or an `iframe` gets its buttons the same way, and the search does not walk the whole page. A Mount point is additionally matched against the View's `useId` identifier (the View has two hooks, `useId` and `useMemo`, and both are allowed in server components). A short HTML fingerprint tells the Island that the Document changed, and then it looks for Mount points again. Two Views on a page do not mix up their buttons.
+
+The client boundary runs along the Island's file, not `RichTextView`: `tests/rich-text-view.test.tsx` requires two such files in the graph, `CodeCopyIsland.tsx` and `ui/BlockIsland.tsx` (and what they pull in — the kit's button and tooltip, `react-dom`, icons and the message catalog), and still forbids `@tiptap/*`, `lowlight` and `highlight.js`; `tests/rsc-gate.test.ts` checks that `RichTextView.tsx` itself has no directive. The Island works in a Next.js server component without a wrapper.
+
+**What gets copied.** The `textContent` of the `code` element — the source code as a string. For a Block without highlighting and for HTML after `highlightCodeBlocks` it is the same text: `span` tokens add no text. This is the rule of ADR-0039: text is copied, not the DOM — otherwise the highlight token boundaries would end up in the clipboard. If the clipboard refuses, the button shows it ("Could not copy").
+
+**A Block without a language has no label.** There is no label because the "Plain text" string comes from the message catalog, and a server component does not have one; an English label for a consumer whose UI is in Russian would be a mistake. The header of such a Block is a single button on the right; in the Editor, in `readOnly` and `disabled` modes, it is the same.
+
+**Keyboard.** The button is in the regular Tab order: it is the only keyboard path here. The tooltip shows on focus and hover, and `Enter` and `Space` copy.
+
+**Cost.** The Island pulls in the kit's button and tooltip, `react-dom` for the portal, and `react-aria-components` for `useLocale` in the message catalog; `@radix-ui/react-tooltip` and `lucide-react` are the kit's required peer dependencies, so no new ones need installing. The `editorView` measurement (`RichTextView` from `@olddevs/ui/editor`, the engine included in the measurement) grew from 1.7 to 8.4 kB gzip on the first measurement: this is the cost of the Island, not of the typography. Since then the View and the shared message catalog have grown, and the measurement is now 12.0 kB against a 12.3 kB budget (ADR-0030). The measurement is static (the entry point's module graph), so the fact that a Document without code blocks does not render the Island does not change the numbers: the Island's file stays in the graph. The savings are on the client: no anchor `<template>` in the markup, no effect, no container walk. The same is true for Next.js: a page's client graph is built from imports, not from what is rendered.
+
+## Tables
+
+The Editor writes `table > tbody > tr > th|td`; a cell has only merging (`colspan`, `rowspan`) and column alignment (`data-align`), see the section "Tables" of the [RichTextEditor](../inputs/rich-text-editor.md#таблицы) page. The styling (borders, cell padding, the header row's backing, cell text alignment by `data-align`) comes from `prose.ts` on the container, so in the Editor and in `RichTextView` a table looks the same. A merged cell is an ordinary cell of a browser table with `colspan`/`rowspan`, with no style of its own.
+
+**On a narrow screen, scrolling happens on the `<table>` itself.** `display: block; max-width: 100%; overflow-x: auto`: a table wider than the block scrolls inside itself and does not stretch the page, the minimum column width is 6 rem (`min-w-24`), so a five-column table on a 375 px screen scrolls instead of squeezing into narrow columns. There is no container around the table, on purpose: `RichTextView` puts the saved HTML in as is, and the Schema knows neither a `div` around the table nor `tabindex`.
+
+The cost of this choice:
+
+- **Table semantics.** On a `table` with `display: block`, some screen readers lose rows and columns. This was fixed long ago in Chrome and Firefox; in Safari with VoiceOver it depends on the version; check with a manual run on your versions. The alternative — `table-layout: fixed` without scrolling — keeps the semantics, but makes all columns equal and narrow and breaks long words, which is worse on a phone.
+- **Focus on a scrollable region.** The axe rule `scrollable-region-focusable` requires that a scrollable block be reachable from the keyboard. In the Editor every cell has a caret, but `RichTextView` has no focusable content: the rule fires on a table that is wider than the screen. This can be fixed only with a container that has `tabindex="0"`, and such a container cannot be put into the saved HTML. If such tables occur on your screen, wrap `RichTextView` in your own container with `overflow-x: auto` and `tabindex="0"`, or keep tables narrow.
+
+## Layout
+
+The Editor's Layout (`div[data-block="layout"]` with the variant in `data-layout` and columns `div[data-block="column"]`, section "Layout" of the [RichTextEditor](../inputs/rich-text-editor.md#раскладка) page) is laid out on the same grid as in the Editor, by `prose.ts` classes on the container, with no `style` in the markup. Columns have no borders: the dashed outline is a cue for the author in the Editor, and the reader needs no boundary. Columns sit side by side when the Document itself is wide (two from 30 rem, three from 40 rem, four from 48 rem), and in a single column in reading order, left to right, when it is narrower. The threshold is a container query on the Document's width: the `RichTextView` root with a Layout becomes a container (`container-type: inline-size`), so in a shrinking context (a flex row item with no width) give it a width. On Paper it is the same grid.
+
+`sanitizeRichText` keeps a Layout where the Editor writes it: only at the top level, with a variant from `RICH_TEXT_SCHEMA.layouts`, and columns only directly inside it; otherwise the wrappers are stripped and the Blocks stay one after another.
+
+## Wrapper
+
+The Editor's Wrapper (`div[data-block="wrapper"]` with Blocks inside, section "Wrapper" of the [RichTextEditor](../inputs/rich-text-editor.md#обёртка) page) without a tone is invisible when displayed: there is no border, the spacing between its Blocks is the same as between the Document's Blocks, and the text reads as if there were no Wrapper. The dashed outline is a cue for the author in the Editor. The Wrapper has no ARIA role.
+
+**A Wrapper with a tone** (`data-tone`: `accent`, `success`, `neutral`, `warning` or `danger`) is visible to the reader too — **in the same look as in the Editor**: a soft tone backing and a 3 px stripe on the left, the text is ordinary Document text, with inner padding like `Alert`. The colors are the `--rte-tone-*` roles of the `prose.ts` classes, with no `style` in the markup; on the Paper they are the light theme's values. The tone adds no ARIA role or `aria-*`: the meaning of the note is carried by a word in its text ("Warning: …"), not by color. `RichTextView` does not style a tone outside these five names — `sanitizeRichText` strips it on the server. The palette, contrast and Markdown are in the section ["Wrapper", "Tone"](../inputs/rich-text-editor.md#тон).
+
+`sanitizeRichText` keeps a Wrapper where the Editor writes it: at the top level and directly in a Layout column, not in another Wrapper, list, quote or table; otherwise the Wrapper is stripped and the Blocks stay one after another. A Layout inside a Wrapper is unwrapped into its Blocks.
+
+## Custom Block
+
+`RichTextView` shows a custom Block (`div[data-block="acme_card"]`, section "Custom Tool" of the [RichTextEditor](../inputs/rich-text-editor.md#свой-инструмент) page) as sanitized HTML and gives it **the same vertical rhythm as a paragraph, and nothing more**: the spacing to the next Block is the same as for a paragraph in the same place (in a Document, a quote, a cell, a column). Blocks inside a custom container Block get the Document's rhythm, as in a Wrapper; inline content (text, Atoms, Marks) gets no spacing. On Paper it is the same.
+
+The look comes from the consumer's CSS, which targets the `data-block` selector and uses the kit's tokens; there are no style fields in the Tool description. Write styles using theme variables — then the Block is the same in the Editor, in `RichTextView` and on the Paper, which switches the tokens itself:
+
+```css
+[data-block="acme_card"] {
+  border: 1px solid var(--line);
+  border-radius: var(--r-sm);
+  padding: 0.75rem;
+}
+```
+
+A node view from the Engine part (a React view) is not used in `RichTextView`: there is no engine here. An inline Atom is shown as whatever is in the HTML: an empty `span` with no text is not visible; a Block can be brought to life in the View with an Island (the next section). The rhythm is checked by `tests/rich-text-paper-css.test.tsx` on the real cascade.
+
+## Custom Block's Island
+
+A custom Block can be brought to life in `RichTextView` with a client component (a button, a player, a collapsible block); the Tool description puts it into the Block's `island` field. Not every Block needs an Island: without it the Block stays sanitized HTML (["Custom Block"](#свой-блок)).
+
+```tsx
+// acme-player.tsx — a module with the directive: the server gets only a reference to the component
+"use client";
+import type { CustomIslandProps } from "@olddevs/ui/editor";
+
+export function AcmePlayer({ attributes, text }: CustomIslandProps) {
+  return <audio controls src={attributes.acme_src} aria-label={text} />;
+}
+```
+
+```tsx
+// acme-tool.ts — the Tool description, shared by the Editor, sanitizing and the View
+import { AcmePlayer } from "./acme-player";
+
+export const acmePlayer: CustomTool = {
+  name: "acme_player",
+  engine: [AcmePlayerNode],
+  blocks: {
+    acme_player: { kind: "block", attributes: { acme_src: { kind: "url" } }, island: AcmePlayer },
+  },
+};
+
+// the page is a server component
+<RichTextView html={safeHtml} tools={[acmePlayer]} />;
+```
+
+**What the component receives** (`CustomIslandProps`): `block` — the Block's name, `attributes` — the attributes declared in the Block's `attributes` that are present in the HTML, by names without `data-` (`acme_src`; the component does not see an undeclared attribute), `text` — the Block's `textContent` from the server HTML. The values are strings from the Document's sanitized HTML: `sanitizeRichText(html, DOMPurify, tools)` checks a value's kind on the server, and without it the Island gets whatever is in `html`.
+
+**How it works and why `RichTextView` stays a server component.** It works the same way as for "Copy" (the section above): the component itself has no state, and the client piece is a separate file with its own directive.
+
+1. The whole Tool description (Engine part, functions) cannot cross the RSC boundary, so `RichTextView` picks only the Islands from `tools`, and only those of Blocks whose `data-block="<name>"` is in the Document (`islandsFor`, `src/editor/core/viewIsland.ts`), and passes references to client components and attribute names to the Island. If there is no `tools`, no `island` on the Block, or no such Block in the Document, there is no Island at all: no anchor `<template>` in the markup, no effect, no loading of the consumer's Island code (the server serializes a reference to a client component only when the Block is there). `island` must be a component from a module with `"use client"`: a server component or a function with a dynamic import is not passed to a client Island.
+2. The Block's server HTML is always in the page. Before hydration, before the Island loads and without JS, the reader sees it — that is, the Block's content as it was saved.
+3. After mounting, the Island (`src/editor/ui/BlockIsland.tsx` and the implementation in `BlockIslandSlots.tsx`, with its own `"use client"`) finds the Blocks of **its own** View the same way "Copy" finds its Mount points: going left from its anchor `<template>`, not through the global `document` — a View in a shadow root or an `iframe` works. In every occurrence of the Block, the content is replaced by the Island; when `tools` changes (the Island is gone) or the Block goes away, the content comes back. If a Block with an Island sits inside another Block with an Island, the outer one comes to life: the component gets its whole text, and the inner one stays as its content.
+4. The Island's state is not reset by a parent re-render: the Island looks for Blocks again only when the Document changed, not `tools` (an inline array literal in the parent does not remount the Island). For this, `RichTextView` keeps the `dangerouslySetInnerHTML` object stable (`useMemo` on the Document): a new object on every re-render would make React rewrite the markup together with the inserted Islands and "Copy" buttons.
+
+**The Island is a separate component**, not the Engine part's React view; the Editor does not read the `island` field.
+
+**Cost.** The Island implementation (`BlockIslandSlots.tsx`) is loaded lazily (`React.lazy`) and is not part of the View's first load: while the chunk is in flight, the Block's server HTML is visible. The static `editorView` measurement includes only the shell and the choice of Islands — about 0.2 kB gzip; Tiptap is still not in the View's graph, which `tests/rich-text-view.test.tsx` checks.
+
+## Accessibility
+
+The component adds no roles: it is a regular `div` with semantic HTML inside — headings, lists, a quote. The Document's headings start with H2 if the Editor worked without `heading1`: the page keeps the H1 itself. A Document with `heading1` contains its own `h1`, and then the page does not put in a second one. An H1 in `RichTextView` is styled with the same typography as in the Editor. If the Document is a separate area of the page, give the container a name through `aria-label` and `role="region"`.
+
+## Anti-patterns
+
+- Putting a string into `html` that has not passed server-side sanitizing.
+- Sanitizing only in the browser before sending: the server does not see it.
+- Using `RichTextEditor readOnly` for a page that only displays the Document: a 295–339 kB gzip engine just to display text ([size table](../../getting-started.md#размер-импорта)).
+- Adding `"use client"` to a file where `RichTextView` is the only component: it is not needed and pulls its neighbors into the client graph (the Island with the "Copy" button is a separate file with its own directive, and `RichTextView` already has it).
+- Passing a server component or a function with a dynamic import to `island`: only a reference to a client component from a module with `"use client"` crosses the RSC boundary.
+- Building your own copy button on top of `RichTextView` or reading text from the Block's DOM: the header and the button are already there, and what gets copied is the code's `textContent`, not the markup.
+
+## Links
+
+- Source: `src/editor/RichTextView.tsx`; header and button — `src/editor/features/code/codeHeader.ts` (header markup), `src/editor/features/code/CodeCopyIsland.tsx` (client Island), `src/editor/features/code/CodeCopyButton.tsx`; the Island of a custom Block — `src/editor/core/viewIsland.ts` (choosing Islands by the Document), `src/editor/ui/BlockIsland.tsx` and `src/editor/ui/BlockIslandSlots.tsx` (client Island); Paper (`surface="paper"`) — `src/editor/styles/surface.ts` and `src/editor/styles/tokens.ts`; typography — `src/editor/styles/prose.ts`, highlight theme — `src/editor/styles/codeTheme.ts`; server highlighting — `src/editor/features/code/highlight.ts`, entry point — `src/editor/highlight-entry.ts`; the Schema as data, `sanitizeRichText` and the sanitizing config — `src/editor/core/schema.ts`, lightweight entry point — `src/editor/schema-entry.ts`.
+- Tests: `tests/rich-text-view.test.tsx` (it also holds the module graph and the table-to-Schema check), `tests/rich-text-view-code-copy.test.tsx` (header, Island, copying), `tests/rich-text-view-island.test.tsx` (the Island of a custom Block), `tests/rich-text-paper.test.tsx` and `tests/rich-text-paper-css.test.tsx` (Paper, `surface="paper"`), `tests/editor-highlight-entry.test.ts` (highlight helper, escaping, entry point graph), `tests/editor-sanitize.test.tsx` (sanitizing with the real DOMPurify: the Editor's markup unchanged, forged input, the bare config), `tests/editor-sanitize-tools.test.tsx` (sanitizing and `richTextSchema` with custom Tools), `tests/rsc-gate.test.ts`.
+- Storybook: `Content/RichTextView`.
+- The Editor — [RichTextEditor](../inputs/rich-text-editor.md); custom Tools, the Island and the semver boundary — [Editor extension API](../../api/editor-extension.md); decisions — ADR-0050, highlighting — ADR-0051, extension — ADR-0058.