@emailmaker/extensions-sandbox 1.1.85-dev.9 → 1.1.93

package/README.md

@@ -79,7 +79,7 @@ npm install @emailmaker/emailmaker @emailmaker/extensions-app @emailmaker/extens
 
 | Пакет | Назначение | Что экспортирует |
 |-------|------------|------------------|
-| `@emailmaker/emailmaker` | Основной пакет | `init()`, `preload()`, типы `IPlugin`, `Instance`; runtime React/Ant Design — subpath `@emailmaker/emailmaker/runtime/*` (отдельный npm не нужен) |
+| `@emailmaker/emailmaker` | Основной пакет | `init()`, `prefetch()`, типы `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,11 +205,6 @@ 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)
@@ -217,16 +212,9 @@ 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.
@@ -260,114 +248,6 @@ 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
@@ -564,17 +444,12 @@ 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>`) |
@@ -582,30 +457,6 @@ 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`:
@@ -653,6 +504,10 @@ 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' }
 );
@@ -1165,7 +1020,7 @@ settingsPanel.showSettingsPanel({
 
 ### `--dev` / `--dev-packages`
 
-**Самый частый флаг для разработки:** в сгенерированном проекте пакеты экосистемы получают dist-tag `dev` вместо `latest`. Используйте, когда нужны свежие предрелизные сборки.
+**Самый частый флаг для разработки:** подставляет **dev**-версии внутренних npm-пакетов (`@emailmaker-internal/*`), которые в шаблонах задаются с dist-tag `dev` вместо `latest`. Используйте, когда нужны свежие предрелизные сборки экосистемы.
 
 ```bash
 npx @emailmaker/cli my-plugin --kind plugin --preset advanced --bundler vite --target npm-package --dev --output-dir ./my-plugin
@@ -1281,18 +1136,6 @@ 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.
@@ -1319,7 +1162,7 @@ npm run start:release
 ## ❓ FAQ / Типичные ошибки
 
 - **«Invalid hook call» или два React на странице**
-  > Для обычного плагина используйте стандартные импорты `react` / `antd` и собирайте проект через `PluginDev` с `alias: true` (по умолчанию). Не смешивайте обычные импорты с прямыми импортами из runtime в одном интерфейсе плагина: выбирается что-то одно на весь плагин, подробности — в README пакета runtime.
+  > Для обычного плагина используйте стандартные импорты `react` / `antd` и собирайте проект через `PluginDev` с `alias: true` (по умолчанию). Не смешивайте обычные импорты с прямыми импортами из runtime в одном plugin UI.
 
 - **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.85-dev.9"
+  "version": "1.1.93"
 }