@emailmaker/extensions-app 0.9.0-dev.1

package/README.md

@@ -0,0 +1,1082 @@
+# 📦 Система плагинов для [emailmaker](https://www.npmjs.com/package/@emailmaker/emailmaker)
+
+Библиотека предоставляет расширяемую архитектуру для создания плагинов для визуального редактора писем emailmaker. Плагины позволяют:
+
+- расширять функциональность редактора;
+- разрабатывать собственные UI-компоненты с использованием экспортированных версий React и Ant Design
+- взаимодействовать с кодом письма в iframe;
+- отображать модальные окна на основе Ant Design в редакторе;
+
+Разработка осуществляется с полной поддержкой **TypeScript**, что обеспечивает строгость типов, модульность и предсказуемость.
+
+
+---
+
+## ⚙️ Требования
+
+- Современный браузер с поддержкой **ES2015** (и выше)
+- Node.js >= 14
+- React и Ant Design подключаются через [`externals`](https://webpack.js.org/configuration/externals/) или напрямую из `@emailmaker/runtime`
+
+
+---
+
+## 📘 Термины
+
+- **sandbox** — часть плагина, работающая внутри iframe, для взаимодействия с содержимым письма.
+- **app** — часть плагина, встроенная в редактор. Отвечает за интерфейс.
+- **pluginRegistry** — механизм регистрации плагинов.
+- **externals** — [способ подключения внешних библиотек в webpack](https://webpack.js.org/configuration/externals/).
+
+
+---
+
+## 🔰 Быстрый старт
+
+👉 Самый простой способ начать — использовать [готовый шаблон](https://github.com/emailmaker/simple_plugin):
+
+```bash
+git clone https://github.com/emailmaker/simple_plugin
+cd simple_plugin
+npm install
+npm run start
+```
+
+Шаблон включает в себя:
+- Webpack / Vite
+- React + Ant Design
+- TypeScript
+- Структуру проекта, описанную ниже
+
+
+---
+
+## 🛠 Установка
+
+### 📦 Основные пакеты
+
+```bash
+npm install @emailmaker/emailmaker @emailmaker/runtime @emailmaker/extensions-app @emailmaker/extensions-react @emailmaker/extensions-sandbox
+```
+
+| Пакет | Назначение | Что экспортирует |
+|-------|------------|------------------|
+| `@emailmaker/emailmaker` | Основной пакет | `init()`, `prefetch()`, типы `IPlugin`, `Instance` |
+| `@emailmaker/runtime` | Общие зависимости | React, ReactDOM, Ant Design и связанные модули |
+| `@emailmaker/extensions-app` | API для app-плагинов | `pluginRegistry`, `DomComponentRegistry`, `ElementsApi`, `SettingsPanelApi`, `ModalApi` |
+| `@emailmaker/extensions-react` | React API для плагинов | `ComponentRegistry`, `createComponentIdentifier()` |
+| `@emailmaker/extensions-sandbox` | API для sandbox-плагинов | `App`, `MessageService`, `SyncService` |
+
+`@emailmaker/ui-kit` ставится отдельно, если плагин использует готовые UI-компоненты платформы.
+
+### Импорты
+
+```typescript
+// React и Antd — обычные импорты
+import React from 'react';
+import { Button } from 'antd';
+
+// UI-компоненты платформы (опционально)
+import { ColorPicker } from '@emailmaker/ui-kit';
+
+// Core API плагинов
+import { pluginRegistry, ElementsApi } from '@emailmaker/extensions-app';
+
+// React-пакет для плагинов
+import { createComponentIdentifier } from '@emailmaker/extensions-app';
+import { ComponentRegistry } from '@emailmaker/extensions-react';
+
+// Типы из основного пакета
+import type { IPlugin, Instance } from '@emailmaker/emailmaker';
+```
+
+## Что обычно ставить
+
+- если у вас обычный React-плагин, ставьте все пакеты из команды выше
+- если используете UI Kit, добавьте еще `@emailmaker/ui-kit`
+- если пишете только sandbox-часть, нужен `@emailmaker/extensions-sandbox`
+
+> Для React-плагинов пакет `@emailmaker/extensions-react` нужен по умолчанию.
+
+
+---
+
+## 🔧 Сборка плагина
+
+Используйте `PluginDev` для настройки бандлера. Он делает две вещи:
+1. **alias** — настраивает React и Ant Design для работы в плагине
+2. **externals** — выносит общие зависимости из бандла
+
+```bash
+npm install @emailmaker/emailmaker
+```
+
+### Таргеты для автора плагина
+
+| Таргет | Что получится | Внутри использует |
+|--------|----------------|-------------------|
+| **npm-пакет** | ESM bundle для package-based интеграции | `'esm'` |
+| **Встраиваемый bundle** | UMD/script-подключение в host | `'globals'` |
+| **Advanced** | Webpack-only async globals compatibility | `'async-globals'` / `'legacy-async-globals'` |
+
+`PluginDev({ externals: false })` используется только для local dev host и не считается release target.
+
+### Типичный проект: serve + build
+
+Самый частый сценарий — плагин в отдельном проекте с двумя режимами:
+
+| Режим | Entry | Externals | Основной плагин |
+|-------|-------|-----------|-----------------|
+| serve | `src/dev.ts` | `false` | Да (статика, iframe) |
+| build | `src/index.ts` | зависит от выбранного target | Нет |
+
+```typescript
+// src/dev.ts — тестовая страница с основным приложением
+import '@emailmaker/emailmaker';
+import { MyPlugin } from './index';
+
+emailmaker.init({ plugins: [MyPlugin] });
+```
+
+**Vite:**
+
+```javascript
+import VitePlugin from '@emailmaker/emailmaker/vite';
+import PluginDev from '@emailmaker/emailmaker/vite/pluginDev';
+
+export default defineConfig(({ command }) => ({
+  plugins: [
+    command === 'serve' && VitePlugin(),
+    PluginDev({ externals: command === 'build' ? 'esm' : false }),
+  ],
+  build: {
+    lib: { entry: 'src/index.ts', formats: ['es'] },
+  },
+}));
+```
+
+**Webpack:**
+
+```javascript
+const WebpackPlugin = require('@emailmaker/emailmaker/webpack');
+const PluginDev = require('@emailmaker/emailmaker/webpack/pluginDev');
+const isDev = process.env.NODE_ENV === 'development';
+
+module.exports = {
+  entry: isDev ? './src/dev.ts' : './src/index.ts',
+  plugins: [
+    isDev && new WebpackPlugin(),
+    new PluginDev({ externals: isDev ? false : 'esm' }),
+  ].filter(Boolean),
+};
+```
+
+> `VitePlugin` / `WebpackPlugin` — основной плагин для хост-приложений. В serve обслуживает iframe, шрифты и статику. В build — копирует их в output.
+
+### Опции PluginDev
+
+| Опция | По умолчанию | Значения |
+|-------|-------------|----------|
+| `externals` | `'esm'` | `'esm'`, `'globals'`, `'async-globals'` (Webpack), `false` |
+| `alias` | `mode-aware` | `true` / `false` |
+
+Для большинства внешних плагинов не выбирайте `externals` вручную — используйте CLI target:
+
+- `npm-пакет` -> `esm`
+- `встраиваемый bundle` -> `globals`
+- `advanced` -> только если host уже требует async/globals контракт Webpack
+
+Для `встраиваемый bundle` и `advanced` рекомендуемый runtime-контракт — descriptor вида `{ type: 'umd', url, name, resolve: 'registry' }`, где `name` совпадает с ключом из `PluginTypeMap`.
+
+### Ручная настройка (без PluginDev)
+
+Нужна только для продвинутой интеграции или собственного бандлерного пайплайна. Основной сценарий для внешнего плагина — отдельный пакет с `PluginDev`.
+
+- `resolve.alias`: `react` → `@emailmaker/runtime/react` (и т.д.) для `esm` / dev; локальные shared internals идут через compat facades runtime
+- `externals`: `@emailmaker/runtime/core`, runtime npm-модули и `@emailmaker/ui-kit`
+- Список модулей: `@emailmaker/runtime/plugin-dev-manifest.json` → `runtimeModules`
+
+Если release bundle неожиданно стал толстым или target `встраиваемый bundle` не загружается, начните с раздела `Troubleshooting`.
+
+Типы для плагина всё равно собираются отдельно: CLI-шаблон запускает `build:types` и кладёт `dist/index.d.ts` рядом с JS bundle, поэтому TypeScript support сохраняется и для browser/advanced targets.
+
+### tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx"
+  }
+}
+```
+
+## Что писать в коде
+
+В коде плагина пишите обычные импорты:
+
+```ts
+import React from 'react';
+import { Button } from 'antd';
+```
+
+А React API для плагинов берите из `@emailmaker/extensions-react`:
+
+```ts
+import { createComponentIdentifier } from '@emailmaker/extensions-app';
+import { ComponentRegistry } from '@emailmaker/extensions-react';
+```
+
+> Обычно достаточно использовать готовый шаблон CLI и не настраивать alias/external вручную.
+
+
+---
+
+## 📂 PublicPath
+
+`publicPath` используется для указания базового URL для загрузки второстепенных скриптов и статики плагина.
+Более подробно прочитать про publicPath можно в секции [publicPath документации webpack](https://webpack.js.org/guides/public-path/)
+
+Внутри плагина:
+
+```ts
+export interface MyPluginOptions {
+  publicPath?: string;
+}
+
+class MyPlugin implements IPlugin {
+  constructor(
+    private editor: Instance,
+    private options: MyPluginOptions = {}
+  ) {}
+
+  init() {
+    if (this.options.publicPath) {
+      const sandboxApi = this.editor.use('SandboxScriptApi');
+      sandboxApi.registerSandboxScript(this.options.publicPath + 'sandbox.js');
+    }
+  }
+}
+```
+
+Подключение плагина с publicPath:
+
+```ts
+emailmaker.init({
+  plugins: [
+    ['MyPlugin', { publicPath: 'https://cdn.example.com/my-plugin/' }]
+  ]
+});
+```
+
+
+---
+
+## 📁 Структура проекта
+
+```txt
+plugin-root/
+├── shared/           # Общие типы и интерфейсы
+│   └── interfaces.ts # Идентификаторы сообщений
+├── app/              # UI-часть, взаимодействие с редактором
+│   └── MyPlugin.ts   # Регистрация и логика плагина
+├── sandbox/          # Работа с DOM письма
+│   └── index.ts      # Точка входа для sandbox
+├── test/             # Точка входа для тестирования
+```
+
+- `shared` — общие типы для взаимодействия между `app` и `sandbox`
+- `app` — точка входа, из которой можно подключить скрипт sandbox:
+
+```ts
+const sandboxApi = this.editor.use('SandboxScriptApi');
+sandboxApi.registerSandboxScript(this.options.publicPath + 'sandbox.js');
+```
+
+- `sandbox/index.ts` — точка входа в скрипт, взаимодействующий с DOM письма. Скрипт должен быть собран отдельной точкой входа, так как он исполняется в изолированной среде iframe.
+- `test/index.tsx` — пример локального запуска редактора `emailmaker` с загрузкой плагина из `app`
+
+
+---
+
+## 🧩 Жизненный цикл плагина
+
+Плагин может быть реализован в виде класса или фабрики. В конструкторе класс получает экземпляр редактора `emailmaker` и должен соответствовать интерфейсу:
+
+```ts
+export interface IPlugin {
+  required?(): void;
+  init?(): Promise<void> | void;
+  afterInit?(): Promise<void> | void;
+  dispose?(): Promise<void> | void;
+}
+```
+
+| Метод         | Назначение |
+|---------------|------------|
+| `required()`  | Указание зависимостей. Не обязательная, можно в init, но в сложных проектах могут быть циклические ссылки |
+| `init()`      | Инициализация плагина. Подключение других плагинов, инициализация ресурсов |
+| `afterInit()` | Методы, вызываемые после инициализации всех плагинов |
+| `dispose()`   | Очистка ресурсов, отписка от событий |
+
+### Пример плагина
+
+```ts
+import type { IPlugin, Instance } from '@emailmaker/emailmaker';
+
+class TestPlugin implements IPlugin {
+  constructor(readonly _editor: Instance) {}
+
+  async init() {
+    try {
+      const sandboxScriptApi = this._editor.use('SandboxScriptApi');
+      // ...
+    } catch (e) {
+      console.error("Ошибка инициализации:", e);
+    }
+  }
+
+  dispose() {
+    // Очистка ресурсов
+  }
+}
+```
+
+
+---
+
+## 🔌 Подключение плагина
+
+### 1. Прямой класс (рекомендуемый)
+
+Самый простой способ — передать класс плагина напрямую:
+
+```ts
+import { MyPlugin } from 'my-plugin-package';
+
+emailmaker.init({
+  plugins: [MyPlugin]
+});
+
+// С опциями (second argument)
+emailmaker.init({
+  plugins: [
+    [MyPlugin, { publicPath: 'https://cdn.example.com/my-plugin/' }]
+  ]
+});
+```
+
+Конструктор плагина (класс или фабрика) принимает `(context, options?)`:
+
+```ts
+class MyPlugin implements IPlugin {
+  constructor(private ctx: Instance, private options?: MyOptions) {}
+}
+
+// Или фабрика
+function myPlugin(ctx: Instance, options?: MyOptions): IPlugin {
+  return { init() { /* ... */ } };
+}
+```
+
+### 2. Ленивая загрузка
+
+Плагин загружается асинхронно — удобно для code-splitting:
+
+```ts
+emailmaker.init({
+  plugins: [
+    () => import('my-plugin-package').then(m => m.MyPlugin)
+  ]
+});
+```
+
+> Результат — обычный Promise, пользователь сам выбирает нужный экспорт.
+
+### 3. Декларативная загрузка по URL
+
+Загрузка плагина по URL без явного импорта:
+
+```ts
+emailmaker.init({
+  plugins: [
+    { type: 'esm', url: 'https://cdn.example.com/my-plugin.js' },
+    { type: 'umd', url: 'https://cdn.example.com/my-plugin.umd.js', name: 'MyPlugin', resolve: 'registry' },
+  ]
+});
+```
+
+| Параметр | Описание |
+|----------|----------|
+| `type` | `'esm'` — ESM модуль (`import()`), `'umd'` — UMD/IIFE (`<script>`) |
+| `url` | URL до скрипта плагина |
+| `name` | Для `resolve: 'registry'` — строковый ключ из `PluginTypeMap`; для legacy `umd`/`window` — ключ в `window` |
+| `resolve` | Опционально. `'module'` (default ESM), `'window'` (legacy default UMD), `'registry'` |
+
+### 4. Регистрация по имени (связь между плагинами)
+
+Если плагин A должен обращаться к плагину B через `editor.use('PluginB')` — используйте `pluginRegistry.add`:
+
+```ts
+// В пакете плагина
+import { pluginRegistry } from '@emailmaker/extensions-app';
+import { MyPlugin } from './MyPlugin';
+
+pluginRegistry.add('MyPlugin', MyPlugin);
+```
+
+```ts
+// В приложении
+emailmaker.init({
+  plugins: ['MyPlugin']
+});
+```
+
+```ts
+// В другом плагине
+const myPlugin = this.editor.use('MyPlugin');
+```
+
+> ⚠️ Для URL-режимов `globals` / `async-globals` используйте `resolve: 'registry'` и `pluginRegistry.add(...)`. Это делает `name` проверяемым через `PluginTypeMap` и убирает зависимость от `window[name]`.
+
+### Метод `use()`
+
+Синхронный метод для получения экземпляра уже загруженного плагина:
+
+```ts
+// По классу (рекомендуемый — полная типизация)
+const myPlugin = this.editor.use(MyPlugin);
+
+// По имени (требует PluginTypeMap и pluginRegistry.add)
+const myPlugin = this.editor.use('MyPlugin');
+```
+
+### Метод `useAsync()`
+
+Асинхронный метод для работы с ленивыми загрузчиками и дескрипторами:
+
+```ts
+const myPlugin = await this.editor.useAsync(
+  () => import('my-plugin').then(m => m.MyPlugin)
+);
+
+const myPlugin = await this.editor.useAsync(
+  { type: 'esm', url: '/plugins/analytics.js' }
+);
+
+const myPluginByKey = await this.editor.useAsync(
+  { type: 'umd', url: '/plugins/my-plugin.umd.js', name: 'MyPlugin', resolve: 'registry' }
+);
+```
+
+
+---
+
+## 📤 API: работа с редактором
+
+### ElementsApi
+
+Добавление элемента в боковую панель. Также имеется возможность изменить текущие компоненты или удалить их.
+
+```ts
+const elementsApi = editor.use('ElementsApi');
+elementsApi.insert({
+  title: "Product",
+  html: "<div>...</div>",
+  name: "product-block",
+  icon: { type: 'IconSun', props: {} }
+});
+```
+
+
+### SettingsPanelApi
+
+Добавление новой панели настроек. Например, можно добавить панель которая будет отображаться при клике на элементе в sandbox.
+
+```ts
+const panel = editor.use('SettingsPanelApi');
+panel.showSettingsPanel({
+  content: {
+    type: 'SettingsPanelId',
+    props: {...}
+  },
+  caption: 'Настройки',
+  deletable: true
+});
+```
+
+Примерная последовательность процесса взаимодействия sandbox и app:
+1. Обработчик клика в sandbox
+2. Отправка события в app через MessageService
+3. Отображение зарегистрированной панели
+4. Отправки изменений из панели в sandbox через MessageService
+
+
+### ModalApi
+
+> Интерфейс основан на модалках `Ant Design`
+
+```ts
+const modal = editor.use('ModalApi');
+modal.show({
+  title: 'Выбор группы',
+  content: {
+    type: 'MyPanel',
+    props: { groups, settings }
+  }
+});
+```
+
+
+### EmailSettingsApi
+
+> API для работы с настройками письма. Позволяет получать и изменять настройки внешнего вида письма и стили элементов контента.
+
+API разделен на два типа методов:
+- **Layout Settings** — настройки письма целиком (фон, ширина, адаптивность)
+- **Content Styles** — стили элементов контента (текст, заголовки, ссылки, кнопки, блоки, карточки)
+
+#### Получение и установка настроек внешнего вида письма:
+
+```ts
+const emailSettingsApi = editor.use('EmailSettingsApi');
+
+// Получить настройки внешнего вида письма
+const layoutSettings = await emailSettingsApi.getEmailLayoutSettings();
+console.log(layoutSettings.backgroundColor); // цвет фона письма
+console.log(layoutSettings.width); // ширина письма {value: 600, dim: 'px'}
+console.log(layoutSettings.responsive); // настройки адаптивности
+
+// Изменить настройки внешнего вида письма
+await emailSettingsApi.setEmailLayoutSettings({
+  backgroundColor: '#ffffff',
+  width: { value: 600, dim: 'px' },
+  responsive: { shutdown: false, styles: true }
+});
+```
+
+#### Получение и установка стилей элементов контента:
+
+```ts
+// Получить стили элементов контента
+const contentStyles = await emailSettingsApi.getEmailContentStyles();
+console.log(contentStyles.text); // стили текста
+console.log(contentStyles.buttons); // стили кнопок
+console.log(contentStyles.block); // стили блоков
+
+// Изменить стили элементов контента
+await emailSettingsApi.setEmailContentStyles({
+  text: { fontSize: 18, color: '#333333' },
+  buttons: { 
+    backgroundColor: '#1890ff', 
+    borderRadius: { all: 8 } 
+  },
+  block: { 
+    padding: { top: 20, right: 20, bottom: 20, left: 20 } 
+  }
+});
+```
+
+> ⚠️ Методы для работы с layout settings (`getEmailLayoutSettings`, `setEmailLayoutSettings`) ждут инициализации письма из iframe перед возвратом или установкой данных, чтобы гарантировать актуальность информации. Методы для работы с content styles не требуют ожидания, так как стили хранятся в объекте письма.
+
+
+### MessageService
+
+> Типизированная надстройка над `postMessage`, для обмена сообщениями между UI и sandbox.
+
+```ts
+const msg = editor.use('MessageService');
+msg.send('MY_EVENT', { value: 123 });
+
+msg.addListener('MY_EVENT', (data) => console.log(data));
+```
+
+Рекомендуется выносить события в константы и использовать типизацию:
+
+```ts
+import { createIdentifier } from 'di';
+
+export const Activate_Product_Settings = createIdentifier<
+  { groupId?: string; visualSettings: VisualSettings }, 
+  void, 
+  void
+>('Activate_Product_Settings');
+```
+
+
+### SandboxScriptApi
+
+Позволяет динамически подключать JS и CSS в iframe, например, для загрузки сторонних библиотек. Также используется для загрузки скрипта, взаимодействующего с DOM письма:
+
+```ts
+const sandboxApi = editor.use('SandboxScriptApi');
+
+const style = sandboxApi.registerSandboxCSS('https://cdn.com/style.css');
+const script = sandboxApi.registerSandboxScript('https://cdn.com/script.js');
+
+// или по коду, если это допустимо CSP
+sandboxApi.registerSandboxScriptCode('console.log("hi")');
+```
+
+⚠️ Использование `registerSandboxScriptCode` может нарушить политику безопасности (CSP). Лучше предпочитать загрузку внешних скриптов через `registerSandboxScript()`.
+
+
+---
+
+## 🧪 Плагины Sandbox
+
+Работают внутри iframe для взаимодействия с DOM письма.
+
+```ts
+import { App } from '@emailmaker/extensions-sandbox';
+import type { IPlugin } from '@emailmaker/extensions-sandbox';
+
+class MyPluginSandbox implements IPlugin {
+  init() {
+    const messageService = App.use('MessageService');
+    
+    messageService.addListener('my-plugin:update', (data) => {
+      const element = document.querySelector('.my-block');
+      if (element) {
+        element.textContent = data.text;
+        App.use('SyncService').commit();
+      }
+    });
+  }
+
+  dispose() {}
+}
+
+App.registerPlugin('MyPluginSandbox', MyPluginSandbox);
+```
+
+> ⚠️ Sandbox работает в изолированном iframe. React-компоненты здесь недоступны — только нативный DOM.
+
+
+### MessageService (внутри sandbox)
+
+Аналогичен UI-версии. Позволяет слушать и отправлять сообщения.
+
+```ts
+import { App } from '@emailmaker/extensions-sandbox';
+
+const messageService = App.use('MessageService');
+
+// Отправка в app
+messageService.send('my-plugin:click', { elementId: '123' });
+
+// Получение из app
+messageService.addListener('my-plugin:update', (data) => {
+  console.log('Received:', data);
+});
+```
+
+
+### SyncService
+
+Для сохранения изменений из DOM в код письма:
+
+```ts
+import { App } from '@emailmaker/extensions-sandbox';
+
+const syncService = App.use('SyncService');
+
+document.querySelector('.title').textContent = 'Updated';
+syncService.commit();
+```
+
+> ⚠️ Все несохранённые (незакоммиченные) изменения могут быть утеряны при следующем рендере.
+
+
+---
+
+## 🧱 Регистрация UI компонентов
+
+`ComponentRegistry` нужен, когда вы хотите зарегистрировать React-компонент и потом передавать его в API по идентификатору:
+
+```ts
+import { ComponentRegistry } from '@emailmaker/extensions-react';
+
+ComponentRegistry.add('MyPanel', MyReactPanel);
+
+ComponentRegistry.override('MyPanel', (Base) => (props) => (
+  <div className="bordered"><Base {...props} /></div>
+));
+```
+
+## Когда использовать
+
+- если хотите просто показать React UI, чаще всего удобнее передать JSX напрямую
+- если нужен `ComponentId`, используйте `ComponentRegistry`
+- если UI без React, используйте `DomComponentRegistry`
+
+Пример с JSX:
+
+```ts
+import { SettingsPanelApi } from '@emailmaker/extensions-app';
+import '@emailmaker/extensions-react';
+
+settingsPanel.showSettingsPanel({
+  content: <MyPanel />,
+});
+```
+
+
+---
+
+## 🎨 UI Kit
+
+```tsx
+import { EmIcons, ColorPicker } from "@emailmaker/ui-kit";
+
+<ColorPicker
+  value={settings.bgColor}
+  onChange={(v) => onChange({ ...settings, bgColor: v })}
+/>
+```
+
+
+---
+
+# ⚛️ `extensions-react`
+
+`@emailmaker/extensions-react` нужен для React-плагинов.
+
+## Что в нем есть
+
+- `ComponentRegistry`
+- `createComponentIdentifier()`
+- поддержка React-компонентов в API
+
+## Что можно делать
+
+После установки пакета вы можете передавать JSX прямо в API:
+
+```ts
+import { SettingsPanelApi } from '@emailmaker/extensions-app';
+import '@emailmaker/extensions-react';
+
+settingsPanel.showSettingsPanel({
+  content: <MyPanel />,
+});
+```
+
+## Когда использовать JSX
+
+Прямой JSX — лучший путь по умолчанию для React-плагина:
+
+```ts
+settingsPanel.showSettingsPanel({
+  content: <MyPanel value={state} />,
+});
+```
+
+Он хорош, когда:
+
+- не нужен стабильный `ComponentId`
+- не нужен `override()`
+- UI используется локально в одном месте
+
+## Когда использовать `ComponentRegistry`
+
+`ComponentRegistry` нужен, если:
+
+- компонент должен быть доступен по `ComponentId`
+- нужна возможность `override()`
+- компонент используется в нескольких местах через `{ type, props }`
+- нужен стабильный идентификатор для контракта между частями плагина
+
+Пример:
+
+```ts
+import { createComponentIdentifier } from '@emailmaker/extensions-app';
+import { ComponentRegistry } from '@emailmaker/extensions-react';
+
+const PanelId = createComponentIdentifier<{ value: string }>('MyPanel');
+
+ComponentRegistry.add(PanelId, MyPanel);
+
+settingsPanel.showSettingsPanel({
+  content: {
+    type: PanelId,
+    props: { value: 'hello' },
+  },
+});
+```
+
+## Короткое правило
+
+- для React-плагина ставьте `@emailmaker/extensions-react`
+- для обычного React UI чаще всего достаточно JSX
+- если нужен идентификатор компонента, используйте `ComponentRegistry`
+
+
+---
+
+## 📦 Расширение типов
+
+### PluginTypeMap
+
+`PluginTypeMap` — **опциональный** механизм для связи между плагинами по строковому имени. Позволяет использовать `editor.use('PluginName')` с автодополнением.
+
+**Когда нужен:**
+- Плагин A обращается к плагину B через `editor.use('PluginB')`
+- URL-режимы `globals` / `async-globals`, если плагин подключается через descriptor с `resolve: 'registry'`
+
+**Когда не нужен:**
+- Плагин подключается напрямую через класс: `plugins: [MyPlugin]`
+- Типизация через `editor.use(MyPlugin)` (прямая ссылка на класс)
+
+```ts
+declare module "@emailmaker/emailmaker" {
+  interface PluginTypeMap {
+    TestPlugin: typeof TestPlugin;
+  }
+}
+```
+
+`PluginTypeMap` наследует все базовые плагины из `BasePluginTypeMap`, поэтому доступны автодополнения для встроенных API (ElementsApi, MessageService, ModalApi и т.д.).
+
+> 💡 Рекомендуем `editor.use(MyPlugin)` с типизацией через класс напрямую. `PluginTypeMap` нужен для `editor.use('Name')` между плагинами и для typed descriptor-ов вида `{ type: 'umd', url, name, resolve: 'registry' }`.
+
+### Опции плагина
+
+Конструктор плагина (класс или фабрика) принимает `(context, options?)`.
+Для типизации используйте `ExtractPluginOptions`:
+
+```ts
+import type { ExtractPluginOptions } from '@emailmaker/emailmaker';
+
+// Опции извлекаются из конструктора
+type MyOpts = ExtractPluginOptions<typeof MyPlugin>;
+```
+
+Опции передаются через кортеж в `plugins`:
+
+```ts
+emailmaker.init({
+  plugins: [
+    [MyPlugin, { theme: 'dark' }]
+  ]
+});
+```
+
+> При множественной инициализации действует принцип «first-write wins» — опции фиксируются при первом создании экземпляра.
+
+CLI-шаблон уже собирает типы отдельно (`npm run build:types`) и публикует `dist/index.d.ts`, поэтому поддержку TypeScript стоит считать частью любого release target, а не только npm/ESM сценария.
+
+### Расширение Config
+
+Публикуйте `.d.ts` вместе с плагином для расширения конфигурации редактора:
+
+```ts
+declare module "@emailmaker/emailmaker" {
+  interface Config {
+    productBlock?: {
+      enabled?: boolean;
+      groups: Group[];
+    };
+  }
+}
+```
+
+### React-компоненты в API
+
+Если в проекте подключен `@emailmaker/extensions-react`, в API можно передавать React-компоненты и JSX напрямую.
+
+Пример:
+
+```ts
+import { SettingsPanelApi } from '@emailmaker/extensions-app';
+import '@emailmaker/extensions-react';
+
+settingsPanel.showSettingsPanel({
+  content: <MyPanel />,
+});
+```
+
+> Если вы пишете React-плагин, просто установите `@emailmaker/extensions-react`.
+
+
+---
+
+# 🧰 CLI
+
+`@emailmaker/cli` — публичный генератор проектов для внешних плагинов и demo-стендов.
+
+## Что умеет CLI
+
+- интерактивный wizard
+- неинтерактивный запуск через аргументы командной строки
+- генерация plugin-проекта
+- генерация stand / stand-closed сценариев
+- шаблоны под `vite` и `webpack`
+- выбор target-а для внешнего плагина: `npm-пакет`, `встраиваемый bundle`, `advanced`
+
+## Основные режимы
+
+### `plugin`
+
+Генерирует внешний плагин с:
+
+- app-частью
+- sandbox-частью
+- local debug host
+- базовой сборкой и scripts
+
+### `stand`
+
+Генерирует тестовый стенд с API и OAuth.
+
+### `stand-closed`
+
+Генерирует стенд для замкнутого контура (`standaloneKey`).
+
+## Preset-ы для plugin
+
+### `minimal`
+
+Минимальный каркас:
+
+- `pluginRegistry`
+- базовая app/sandbox связка
+- без React UI примера
+
+### `advanced`
+
+Расширенный пример:
+
+- React UI
+- `ComponentRegistry` из `@emailmaker/extensions-react`
+- пример регистрации panel/icon
+- пример `SettingsPanelApi` и `MessageService`
+
+## Пример запуска
+
+```bash
+npx @emailmaker/cli my-plugin --preset advanced --bundler vite --target npm-package --output-dir ./my-plugin
+```
+
+## Когда использовать CLI
+
+CLI нужен, если вы хотите:
+
+- быстро стартовать новый внешний плагин
+- не собирать вручную `vite`/`webpack` конфиг
+- сразу получить готовую структуру проекта
+- получить рабочий пример app, sandbox и локальной отладки
+
+
+---
+
+## 🧯 Troubleshooting
+
+### `dist` неожиданно толстый
+
+Проверьте сначала:
+
+- что release target выбран как `npm-пакет` или `встраиваемый bundle`, а не `advanced`
+- что release config использует `PluginDev(...)`, а не ручной `externals`
+- что в bundle не попали `react`, `antd` или runtime subpath-ы как обычные модули
+
+Частая причина: release config собирается без корректного externals/alias режима.
+
+### Плагин работает в `start`, но ломается в release
+
+Обычно это значит, что dev host использует `PluginDev({ externals: false })`, а release target уже требует runtime contract.
+
+Проверьте:
+
+- target сборки в CLI / config
+- release config для `src/index.ts`
+- способ загрузки плагина в host (`npm-пакет` vs `встраиваемый bundle`)
+
+### Browser target не загружается
+
+Проверьте:
+
+- что host заранее загрузил runtime globals
+- что release bundle собран под target `встраиваемый bundle`
+- что sandbox и main bundle публикуются по ожидаемым URL
+
+### Duplicate React / hooks error
+
+Почти всегда это значит, что React попал в bundle плагина вместо runtime externals.
+
+Проверьте:
+
+- используется ли `PluginDev` в release config
+- не отключён ли externals вручную
+- нет ли дополнительных alias/resolve правил, которые обходят runtime contract
+
+### Когда использовать `advanced`
+
+Только если host уже требует Webpack async/globals compatibility.
+
+Для обычного внешнего плагина:
+
+- `npm-пакет` — основной путь
+- `встраиваемый bundle` — для script/UMD загрузки
+- `advanced` — только для совместимости, когда вы точно знаете контракт host
+
+
+---
+
+## ❓ FAQ / Типичные ошибки
+
+- **«Invalid hook call» или два React на странице**
+  > Для обычного плагина используйте стандартные импорты `react` / `antd` и собирайте проект через `PluginDev` с `alias: true` (по умолчанию). Не смешивайте обычные импорты с прямыми импортами из runtime в одном plugin UI.
+
+- **Externals не работают в dev server**
+  > В serve-режиме externals должны быть отключены: `PluginDev({ externals: false })`. Зависимости резолвятся из runtime через alias.
+
+- **ESM output не грузится через `<script>`**
+  > ESM-сборка содержит `import` и не работает как обычный скрипт. Используйте `<script type="module">` или соберите плагин в режиме `global` / `iife`.
+
+- **Global-плагин: «Cannot read property of undefined»**
+  > Runtime должен быть загружен до плагина. Подключайте плагин через ленивый импорт `() => import(…)` или декларативно `{ type: 'global', url: '…' }`.
+
+- **Не загружаются JS/CSS / iframe не отображается**
+  > Проверьте `publicPath` и подключение основного плагина (`VitePlugin` / `WebpackPlugin`). В serve-режиме он обслуживает статику из `node_modules/`.
+
+- **Панель или компонент не отображается**
+  > Убедитесь в регистрации через `ComponentRegistry`.
+
+- **Событие не обрабатывается**
+  > Проверьте подписку на событие в `MessageService`.
+
+- **Изменения в iframe теряются**
+  > Не забывайте вызывать `syncService.commit()`.
+
+---
+
+### 🔄 Миграция с предыдущих версий
+
+**С `externals.json` на `PluginDev`:**
+
+Старый подход с `externals.json` продолжает работать — файл генерируется для обратной совместимости. Но рекомендуем перейти на `PluginDev`: удалите загрузку `externals.json` из конфига и подключите плагин — он настроит externals и alias автоматически.
+
+**С `pluginRegistry.add` на прямой класс:**
+
+До:
+```typescript
+pluginRegistry.add('MyPlugin', MyPlugin);
+// init: plugins: ['MyPlugin']
+```
+
+После (если не нужен `editor.use('MyPlugin')` между плагинами):
+```typescript
+// init: plugins: [MyPlugin]
+```
+
+
+---
+
+## 🔗 Полезные ссылки
+
+- [Webpack](https://github.com/webpack/webpack)
+- [Vite](https://vitejs.dev/)
+- [React](https://github.com/facebook/react)
+- [TypeScript](https://github.com/microsoft/TypeScript)
+- [Ant Design](https://github.com/ant-design/ant-design)
+- [Пример плагина](https://github.com/emailmaker/simple_plugin)
+