diff --git a/docs/arbitrary-html-embed-plan.md b/docs/arbitrary-html-embed-plan.md
new file mode 100644
index 00000000..e02466a8
--- /dev/null
+++ b/docs/arbitrary-html-embed-plan.md
@@ -0,0 +1,95 @@
+# Вставка произвольного HTML/CSS/JS в страницы — анализ и подходы
+
+> Статус: **черновик / обсуждение**. Решение по модели изоляции ещё не принято — см. раздел «Развилка».
+> Исходный кейс: нужно вставлять трекер (счётчик аналитики) на вики-страницы.
+
+## 1. Почему «из коробки» произвольный HTML вставить нельзя
+
+Контент страницы в Docmost хранится не как HTML, а как **ProseMirror JSON** (документ TipTap, синхронизируется через Yjs). Любой путь, которым контент попадает в страницу — ручной ввод, вставка из буфера (paste), импорт Markdown/HTML — проходит парсинг строго по схеме редактора:
+
+`apps/server/src/common/helpers/prosemirror/html/generateJSON.ts:45`
+
+```ts
+PMDOMParser.fromSchema(schema).parse(doc.body, options)
+```
+
+`PMDOMParser.fromSchema` оставляет только те теги, для которых в схеме есть нода/марк с правилом `parseHTML` (`p`, `h1–h6`, списки, `blockquote`, `code`/`pre`, `a`, `strong`/`em`, таблицы, картинки, callout и т.п.). Всё остальное — `<div>`, `<style>`, `<script>`, инлайн-стили, кастомные теги — **молча отбрасывается**, выживает максимум текст внутри.
+
+- Ноды «сырой HTML» в схеме нет (`rawHtml`/`htmlNode` в `packages/editor-ext/src/lib` отсутствуют).
+- `marked` сам по себе HTML пропускает насквозь (санитайзер не подключён в `packages/editor-ext/src/lib/markdown/utils/marked.utils.ts`), но это неважно — финальным фильтром выступает схема ProseMirror на следующем шаге.
+- Единственное, что отдалённо похоже на «вставку HTML» — embed-нода (`packages/editor-ext/src/lib/embed.ts`), но это `<iframe>` на URL известных провайдеров с санитизацией ссылки, а не произвольная разметка.
+
+**Вывод:** чтобы получить произвольный HTML на странице, нужно добавлять в схему редактора отдельную ноду со своим `parseHTML`/`renderHTML` и собственным рендерингом.
+
+## 2. Механика: как добавить такую ноду (одинаково для любого варианта)
+
+По образцу `packages/editor-ext/src/lib/excalidraw.ts`:
+
+1. **Новая нода** в `packages/editor-ext/src/lib/html-embed/`:
+   `Node.create({ name: 'htmlEmbed', group: 'block', atom: true, isolating: true })`.
+   Атрибут `source` (сырой HTML/CSS/JS строкой) с `parseHTML`/`renderHTML` через `data-`-атрибут или base64, чтобы корректно гонялось туда-обратно через HTML↔JSON. Экспорт добавить в `packages/editor-ext/src/index.ts`.
+2. **Регистрация в ДВУХ схемах** (иначе сервер вырежет ноду при сохранении/коллаборации):
+   - клиент: `apps/client/src/features/editor/extensions/extensions.ts`
+   - сервер: `tiptapExtensions` в `apps/server/src/collaboration/collaboration.util.ts:58`
+3. **React NodeView** на клиенте — то, что реально показывает контент. Здесь и зарыта безопасность (см. развилку).
+4. **Markdown-сериализация** (turndown/marked в `packages/editor-ext/src/lib/markdown`) — если нода должна выживать при импорте/экспорте Markdown, иначе там она потеряется.
+5. **UI вставки** — slash-команда/кнопка тулбара + модалка с редактором кода.
+
+## 3. Развилка: модель изоляции (ключевое решение)
+
+«Произвольный JS» в многопользовательской вики — это не фича рендеринга, а **модель доверия**. От выбора зависит весь NodeView и безопасность всего инстанса.
+
+### Вариант A — Sandboxed iframe
+Контент кладётся в `<iframe sandbox="allow-scripts" srcdoc="...">`.
+- JS/CSS работают, но изолированы: нет доступа к DOM вики, кукам, токену сессии, localStorage.
+- Безопасно, stored-XSS закрыт. Так делают HTML-эмбеды в Notion/Confluence.
+- Минусы: скрипт не может управлять самой страницей; авто-высоту приходится решать через `postMessage`.
+
+### Вариант B — Raw-инъекция в DOM страницы
+`dangerouslySetInnerHTML` + выполнение `<script>`.
+- Полная власть: скрипт выполняется в origin вики, может всё.
+- Это **stored-XSS by design**: скрипт любого автора выполняется в браузере каждого читателя с его сессией → кража токенов, захват аккаунтов.
+- Допустимо только на доверенном/одно-пользовательском инстансе.
+
+### Вариант C — Raw-инъекция, но admin-only
+Полная мощь raw-инъекции, но вставка такой ноды разрешена только админам/доверенным ролям; обычные авторы её добавлять не могут. Компромисс между мощью и риском.
+
+## 4. Заработает ли трекер в песочнице? — НЕТ (для настоящего трекера)
+
+Без `allow-same-origin` у iframe **opaque origin** (`null`). Из этого следуют ограничения, ломающие именно трекеры:
+
+| Что делает трекер | В sandbox (`allow-scripts`) |
+|---|---|
+| Загрузить внешний `<script src>` и выполнить | ✅ работает |
+| Отправить запрос/пиксель/`sendBeacon` на свой сервер | ✅ работает (fire-and-forget) |
+| Поставить куку (`document.cookie`) | ❌ блокируется/кидает ошибку |
+| `localStorage` / `sessionStorage` | ❌ `SecurityError` в opaque origin |
+| Прочитать URL / referrer / title **самой вики-страницы** | ❌ видит только `about:srcdoc`, не родителя |
+| Достучаться до DOM страницы (`window.parent`) | ❌ запрещено sandbox'ом |
+
+**Итог:** GA4 / Яндекс.Метрика / Matomo внутри песочницы либо упадут на попытке поставить `_ga`/`_ym`, либо отправят «хит», где страница = `about:srcdoc`, а уникальный посетитель не сохраняется → данные мусорные. Песочница и «считать саму страницу» — взаимоисключающие вещи by design.
+
+Добавлять `allow-same-origin` вместе с `allow-scripts` как «компромисс» нельзя: при одинаковом origin это снимает песочницу полностью (предупреждение MDN) — то есть это та же raw-инъекция окольным путём.
+
+## 5. Что это значит для выбора
+
+- **Цель — аналитика самих вики-страниц** (посещения, поведение, уники) → нужен скрипт в origin вики = **raw-инъекция**. Песочница тут бесполезна в принципе. Риск — stored-XSS, поэтому разумно держать это под **admin-only** (вариант C).
+- **Цель — самодостаточный встроенный виджет** (калькулятор, демка, виджет без кук и без доступа к родителю) → песочницы (вариант A) хватает.
+
+## 6. Возможные направления решения (выбрать позже)
+
+1. **Admin-only raw-инъекция** — нода `htmlEmbed` с полным выполнением скрипта в origin вики; вставка только для админов/доверенных ролей. Трекер работает полноценно (куки, уники, URL страницы). Компромисс мощь/риск.
+2. **Raw-инъекция без ограничений** — любой автор может вставить произвольный JS. Максимум гибкости, но stored-XSS для всех читателей. ОК только если все редакторы полностью доверенные.
+3. **Узкая фича «только трекер», без произвольного JS** — вместо универсальной HTML-ноды поле в настройках для ID счётчика (GA/Метрика), сниппет вставляется в шаблон страницы. Безопасно и решает именно задачу трекинга.
+4. **Sandboxed iframe (вариант A)** — для встраиваемых виджетов; для аналитики самих страниц не годится.
+
+---
+
+### Ссылки на код
+- Парсинг по схеме (фильтр HTML): `apps/server/src/common/helpers/prosemirror/html/generateJSON.ts`
+- Серверный список расширений: `apps/server/src/collaboration/collaboration.util.ts:58`
+- Клиентский список расширений: `apps/client/src/features/editor/extensions/extensions.ts`
+- Реестр нод editor-ext: `packages/editor-ext/src/index.ts`
+- Образец кастомной ноды: `packages/editor-ext/src/lib/excalidraw.ts`
+- Образец iframe-ноды: `packages/editor-ext/src/lib/embed.ts`
+- Markdown ↔ HTML: `packages/editor-ext/src/lib/markdown/`