@emailmaker/extensions-sandbox 1.1.93 → 1.1.102

package/README.md

@@ -79,7 +79,7 @@ npm install @emailmaker/emailmaker @emailmaker/extensions-app @emailmaker/extens
 
 | Пакет | Назначение | Что экспортирует |
 |-------|------------|------------------|
-| `@emailmaker/emailmaker` | Основной пакет | `init()`, `prefetch()`, типы `IPlugin`, `Instance`; runtime React/Ant Design — subpath `@emailmaker/emailmaker/runtime/*` (отдельный npm не нужен) |
+| `@emailmaker/emailmaker` | Основной пакет | `init()`, `preload()`, типы `IPlugin`, `Instance`; runtime React/Ant Design — subpath `@emailmaker/emailmaker/runtime/*` (отдельный npm не нужен) |
 | `@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` |
@@ -205,6 +205,11 @@ module.exports = {
 - `встраиваемый bundle` -> `globals`
 - `advanced` -> только если host уже требует async/globals контракт Webpack
 
+`globals` читает зависимости из глобального реестра **синхронно**, когда выполняется скрипт
+плагина. Хост готовит реестр сам, если грузит плагин по URL через `init()` или `useAsync()`; при
+ручной вставке `<script>` дождитесь `preload()` — подробности в разделе
+`Подключение плагина`.
+
 Для `встраиваемый bundle` и `advanced` рекомендуемый runtime-контракт — descriptor вида `{ type: 'umd', url, name, resolve: 'registry' }`, где `name` совпадает с ключом из `PluginTypeMap`.
 
 ### Ручная настройка (без PluginDev)
@@ -212,9 +217,16 @@ module.exports = {
 Нужна только для продвинутой интеграции или собственного бандлерного пайплайна. Основной сценарий для внешнего плагина — отдельный пакет с `PluginDev`.
 
 - `resolve.alias`: `react` → `@emailmaker/emailmaker/runtime/react` (и т.д.) для `esm` / dev; локальные shared internals идут через compat facades runtime; UI-kit (`@emailmaker/ui-kit`) → **`@emailmaker/emailmaker/ui-kit`** (singleton bytes на main, не `runtime/@scope/ui-kit`)
-- `externals`: `@emailmaker/emailmaker/runtime/core`, runtime npm-модули; ui-kit external → **`@emailmaker/emailmaker/ui-kit`** (глобальный ключ `UiKit` в `runtimeExports`, см. манифест)
+- `externals`: `@emailmaker/emailmaker/runtime-core`, runtime npm-модули; ui-kit external → **`@emailmaker/emailmaker/ui-kit`** (глобальный ключ `UiKit` в `runtimeExports`, см. манифест)
 - Список модулей: `@emailmaker/emailmaker/runtime/plugin-dev-manifest.json` → `runtimeModules`
 
+**Иконки — особый случай.** Общим (singleton) обязан быть только класс
+`@ant-design/icons/es/components/AntdIcon`: он вычисляет иконку, читая `IconContext`, и вторая его
+копия сломает тему. Сам каталог из восьми с лишним сотен определений singleton'ом не является —
+каждый потребитель берёт его себе и вытрясает неиспользуемое. Поэтому обычный
+`import { UserOutlined } from '@ant-design/icons'` в плагине законен: в сборку попадут только взятые
+иконки, а общая машинерия придёт из продукта. `PluginDev` разводит эти два случая сам.
+
 Если release bundle неожиданно стал толстым или target `встраиваемый bundle` не загружается, начните с раздела `Troubleshooting`.
 
 Типы для плагина всё равно собираются отдельно: CLI-шаблон запускает `build:types` и кладёт `dist/public-types.d.ts` рядом с JS bundle, поэтому TypeScript support сохраняется и для browser/advanced targets.
@@ -248,6 +260,114 @@ import { ComponentRegistry } from '@emailmaker/extensions-react';
 > Обычно достаточно использовать готовый шаблон CLI и не настраивать alias/external вручную.
 
 
+---
+
+# Совместимость: как плагин встречается с редактором
+
+Одна страница на вопрос «что с чем работает». Всё остальное в этом разделе — подробности.
+
+## Главное правило
+
+Плагин и редактор обязаны использовать **один экземпляр** React, antd и ui-kit. Не потому, что так
+аккуратнее: компоненты плагина рисуются внутри дерева редактора, и если экземпляры разные, хуки
+вызываются против чужого диспетчера. На странице это выглядит как
+`Cannot read properties of null (reading 'useState')` — падает не панель плагина, а весь интерфейс.
+
+Сводить их вручную не нужно: этим занимается `PluginDev` в сборке плагина.
+
+## Формат плагина × способ подключения
+
+| Формат плагина | Как подключается | Где берёт React, antd, ui-kit |
+|---|---|---|
+| **ESM** (npm-пакет, собирается вместе с хостом) | импортом: `plugins: [MyPlugin]` или `useAsync(() => import(…))` | `PluginDev` переписывает импорты на подпути продукта |
+| **UMD / globals** (файл по URL) | `{ type: 'umd', url, name, resolve: 'registry' }` | из реестра `window.emailmaker.modules` на странице |
+| ~~**ESM по URL**~~ | **не поддерживается** | — |
+
+**Почему `{ type: 'esm', url }` не работает.** В собранном ESM-плагине остаются имена подпутей
+продукта (`@emailmaker/emailmaker/runtime/*`). Браузеру разрешать их нечем: карту импортов
+продукт не выдаёт. Плагин в формате ESM подключают как npm-пакет, собирая вместе с хостом.
+
+## Что приходит из продукта, а что собирается в плагин
+
+| Зависимость | Откуда берётся | Почему так |
+|---|---|---|
+| `react`, `react-dom` | из продукта (`@emailmaker/emailmaker/runtime/react`) | один диспетчер хуков на страницу |
+| `antd` | из продукта | контексты темы и формы общие |
+| `@emailmaker/ui-kit` | из продукта (`@emailmaker/emailmaker/ui-kit`) | общий `ThemeProvider`, стили вставляются один раз |
+| `@ant-design/icons` — **класс `AntdIcon`** | из продукта | читает `IconContext`; вторая копия ломает тему |
+| `@ant-design/icons` — **каталог иконок** | собирается в плагин | каждый берёт только те иконки, что использует |
+| всё остальное | собирается в плагин | к общему состоянию отношения не имеет |
+
+## Как проверить, что всё сошлось
+
+Сборка хоста сама скажет, если в граф попала вторая копия React или ui-kit: плагин хоста
+(Vite/webpack) печатает предупреждение с именем файла-виновника и обоими путями. Молчание на сборке
+— признак того, что копии сведены.
+
+Плагин **на глобалах** при этом ничего не импортирует и в графе не появляется: он берёт зависимости
+из реестра уже на странице, и проверять там нечего.
+
+## Вход редактора тоже участвует
+
+Редактор подключают двумя способами, и не с каждым работает ESM-плагин:
+
+| Вход редактора | ESM-плагин | Плагин на глобалах |
+|---|---|---|
+| **ESM** (собирается вместе с хостом) | да | да |
+| **UMD** (`<script>` на странице) | **нет** | да |
+
+**Почему UMD-вход и ESM-плагин не сходятся.** UMD-вход несёт React внутри себя и объявляет его на
+странице сам. ESM-плагин собирает ваш сборщик, и подпуть `@emailmaker/emailmaker/runtime/react`
+он разрешает в копию внутри пакета. Это два разных файла с двумя диспетчерами хуков — тот самый
+`Cannot read properties of null (reading 'useState')`, падающий вместе со всем интерфейсом.
+
+Сборка про это молчать обязана: UMD-редактор подключён скриптом и в граф сборки хоста не входит, а
+в момент сборки плагина ещё неизвестно, какой вход выберет хост. Поэтому **редактор говорит сам** —
+при инициализации он сверяет копии и, найдя вторую, пишет в консоль, что нашёл и как это чинить.
+
+Чинится любым из двух способов: собрать плагин **на глобалах** — тогда он возьмёт React из реестра
+`window.emailmaker.modules` на странице, — либо подключить **ESM-вход** редактора и
+собрать оба одним сборщиком.
+
+## Что бывает, если собрать плагин без `PluginDev`
+
+Плагин соберётся, сборка хоста пройдёт — и редактор упадёт на странице. Ровно этот случай:
+
+- в плагине остались `import 'react'` и `import '@emailmaker/ui-kit'` как есть;
+- сборщик хоста разрешил их из `node_modules` проекта — это **вторые** копии;
+- редактор при этом работает на своих, вендоренных.
+
+Лечится добавлением `PluginDev` в конфигурацию сборки плагина (`externals: 'esm'`) либо сборкой
+плагина на глобалах.
+
+## Ваши настройки резолва редактора не касаются
+
+Внутри пакета React адресуется **путём** к копии, которая лежит в нём же, а не именем `react`.
+Следствий два, и оба в вашу пользу:
+
+- `resolve.dedupe`, `resolve.alias`, `resolve.modules` и Module Federation `shared` работают у вас
+  так, как вы их написали. Мы не занимаем имя `react` и ничего у вас не перехватываем.
+- Редактор не зависит от того, что вы с этим именем делаете: своя копия достаётся ему при любой
+  конфигурации сборки, в том числе если наш плагин у вас не подключён.
+
+Одно исключение — `sharedReact` ниже: им вы просите обратного.
+
+## Общий React (необязательно)
+
+Плагин хоста умеет обратное: отдать редактору **ваш** React вместо вендоренного —
+`VitePlugin({ sharedReact: true })` или `new WebpackPlugin({ sharedReact: true })`.
+
+| | по умолчанию | `sharedReact: true` |
+|---|---|---|
+| React редактора | свой, внутри пакета | ваш |
+| требования к вашему React | нет | мажорная версия 19 |
+| Strict Mode и dev-сборка React | не касаются редактора | касаются |
+| antd | свой, внутри пакета | свой, внутри пакета |
+| вес поставки | как есть | меньше примерно на 98 КБ gzip |
+
+Версия проверяется до сборки: несовпадение мажора будет названо в предупреждении.
+
+
 ---
 
 ## 📂 PublicPath
@@ -444,12 +564,17 @@ emailmaker.init({
 ```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' },
   ]
 });
 ```
 
+> **По URL работает `umd` с `resolve: 'registry'`.** Вариант `{ type: 'esm', url }` в браузере не
+> поддерживается: в собранном ESM-плагине остаются имена подпутей продукта
+> (`@emailmaker/emailmaker/runtime/*`), а разрешить их браузеру нечем — карту импортов
+> продукт не выдаёт. ESM-плагин подключают как npm-пакет: способами 1 и 2 выше, собирая его вместе
+> с хостом.
+
 | Параметр | Описание |
 |----------|----------|
 | `type` | `'esm'` — ESM модуль (`import()`), `'umd'` — UMD/IIFE (`<script>`) |
@@ -457,6 +582,30 @@ emailmaker.init({
 | `name` | Для `resolve: 'registry'` — строковый ключ из `PluginTypeMap`; для legacy `umd`/`window` — ключ в `window` |
 | `resolve` | Опционально. `'module'` (default ESM), `'window'` (legacy default UMD), `'registry'` |
 
+#### Кто готовит runtime до запуска скрипта
+
+Плагин, собранный под `globals` (targets `встраиваемый bundle` и `advanced`), читает
+`window.__emailmaker__.modules.Antd` **синхронно** — в момент, когда выполняется его скрипт.
+До этого момента в реестре лежат ожидания: часть runtime приезжает по требованию, чтобы первый
+экран не платил за то, чем не пользуется.
+
+Если плагин подключён через `init({ plugins: [...] })` или `useAsync(...)`, делать ничего не
+нужно: хост сам дожидается готовности runtime перед тем, как выполнить скрипт. Тормозится только
+загрузка такого плагина, остальное приложение работает своим ходом.
+
+Если же вы вставляете `<script>` с плагином сами, мимо API — дождитесь `preload()`:
+
+```ts
+import { preload } from '@emailmaker/emailmaker';
+
+await preload();
+document.head.appendChild(Object.assign(document.createElement('script'), {
+  src: 'https://cdn.example.com/my-plugin.umd.js',
+}));
+```
+
+Плагинов на `esm` это не касается: их импорты разрешает сборщик, ждать им нечего.
+
 ### 4. Регистрация по имени (связь между плагинами)
 
 Если плагин A должен обращаться к плагину B через `editor.use('PluginB')` — используйте `pluginRegistry.add`:
@@ -504,10 +653,6 @@ 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' }
 );
@@ -733,6 +878,22 @@ App.registerPlugin('MyPluginSandbox', MyPluginSandbox);
 
 > ⚠️ Sandbox работает в изолированном iframe. React-компоненты здесь недоступны — только нативный DOM.
 
+### Скрипт живёт одно письмо
+
+Документ холста пересоздаётся на каждое письмо: скрипт песочницы выполняется заново, и ничего из
+прошлого письма в нём не остаётся. `handle.ready` — обещание, оно разрешается один раз, для первого
+холста. Чтобы узнавать о готовности каждый раз, подпишитесь на `onReady`:
+
+```ts
+const script = sandboxApi.registerSandboxScript(url);
+script.onReady(() => {
+  messageService.send('my-plugin:settings', mySettings);
+});
+```
+
+Последнее, что вы отправили скрипту после его готовности, редактор повторяет в новый холст сам —
+по каждому ключу сообщения. `onReady` нужен для состояния, которое вы считаете заново.
+
 
 ### MessageService (внутри sandbox)
 
@@ -845,6 +1006,20 @@ import { Form, FormColorField } from "@emailmaker/ui-kit";
 </Form>
 ```
 
+### Значки
+
+Значки ui-kit берите по одному из подпути `icons` — в сборку плагина попадут только те, что вы
+используете. В release-сборке этот путь уходит на `@emailmaker/emailmaker/ui-kit/icons` хоста.
+
+```tsx
+import { AIRequests, Sun } from "@emailmaker/ui-kit/icons";
+
+<AIRequests />
+```
+
+`<EmIcons icon="Sun" />` тоже работает, но подтягивает весь каталог значков и пишет в консоль
+предупреждение.
+
 
 ---
 
@@ -1020,7 +1195,7 @@ settingsPanel.showSettingsPanel({
 
 ### `--dev` / `--dev-packages`
 
-**Самый частый флаг для разработки:** подставляет **dev**-версии внутренних npm-пакетов (`@emailmaker-internal/*`), которые в шаблонах задаются с dist-tag `dev` вместо `latest`. Используйте, когда нужны свежие предрелизные сборки экосистемы.
+**Самый частый флаг для разработки:** в сгенерированном проекте пакеты экосистемы получают dist-tag `dev` вместо `latest`. Используйте, когда нужны свежие предрелизные сборки.
 
 ```bash
 npx @emailmaker/cli my-plugin --kind plugin --preset advanced --bundler vite --target npm-package --dev --output-dir ./my-plugin
@@ -1136,6 +1311,18 @@ npm run start:release
 - что release bundle собран под target `встраиваемый bundle`
 - что sandbox и main bundle публикуются по ожидаемым URL
 
+### Плагин на `globals` падает: вместо `antd` приходит объект с `then`
+
+Значит скрипт плагина выполнился раньше, чем хост подготовил реестр runtime. Часть runtime
+приезжает по требованию, и до этого момента в `window.__emailmaker__.modules` лежат
+ожидания, а не значения.
+
+Проверьте:
+
+- плагин подключён через `init({ plugins: [{ type, url, ... }] })` или `useAsync(...)` — тогда
+  хост дожидается готовности сам;
+- если `<script>` вставляете вы, перед вставкой вызван `await preload()`.
+
 ### Duplicate React / hooks error
 
 Почти всегда это значит, что React попал в bundle плагина вместо runtime externals.
@@ -1162,7 +1349,7 @@ npm run start:release
 ## ❓ FAQ / Типичные ошибки
 
 - **«Invalid hook call» или два React на странице**
-  > Для обычного плагина используйте стандартные импорты `react` / `antd` и собирайте проект через `PluginDev` с `alias: true` (по умолчанию). Не смешивайте обычные импорты с прямыми импортами из runtime в одном plugin UI.
+  > Для обычного плагина используйте стандартные импорты `react` / `antd` и собирайте проект через `PluginDev` с `alias: true` (по умолчанию). Не смешивайте обычные импорты с прямыми импортами из runtime в одном интерфейсе плагина: выбирается что-то одно на весь плагин, подробности — в README пакета runtime.
 
 - **Externals не работают в dev server**
   > В serve-режиме externals должны быть отключены: `PluginDev({ externals: false })`. Зависимости резолвятся из runtime через alias.

package/package.json

@@ -5,5 +5,5 @@
   "main": "index.js",
   "types": "types.d.ts",
   "name": "@emailmaker/extensions-sandbox",
-  "version": "1.1.93"
+  "version": "1.1.102"
 }