@emailmaker/extensions-react 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/externals.json

@@ -23,6 +23,10 @@
     "promise __emailmaker__.modules",
     "Antd"
   ],
+  "@ant-design/icons/es/components/AntdIcon": [
+    "promise __emailmaker__.modules",
+    "AntDesignIconBase"
+  ],
   "@ant-design/icons": [
     "promise __emailmaker__.modules",
     "AntDesignIcons"
@@ -39,10 +43,6 @@
     "promise __emailmaker__.modules",
     "Dayjs"
   ],
-  "uuid": [
-    "promise __emailmaker__.modules",
-    "Uuid"
-  ],
   "@emailmaker/ui-kit": [
     "promise __emailmaker__.modules",
     "UiKit"

package/index.js

@@ -33,12 +33,16 @@ var a = class e {
 function o(e) {
 	return `service_container_${e}`;
 }
-var s = class e extends a {
+var s = /* @__PURE__ */ new Set();
+function c(e) {
+	s.delete(e);
+}
+var l = class e extends a {
 	_parent;
 	_injectCallbacks = [];
 	_injections = Object.create(null);
 	_runCallbacks(e) {
-		this._injectCallbacks.forEach((t) => t(e));
+		[...this._injectCallbacks].forEach((t) => t(e));
 	}
 	constructor(e = null) {
 		super(), this._parent = e, e && this.addDisposable(e.onInject((e) => this._runCallbacks(e)));
@@ -59,7 +63,7 @@ var s = class e extends a {
 	}
 	_onInject(e, t, n = new a()) {
 		return n.addDisposable(this.onInject((r) => {
-			e === r && (n.dispose(), t(this.getInstance(r)));
+			e === r && !n.isDisposed() && (n.dispose(), t(this.getInstance(r)));
 		})), this._parent && n.addDisposable(this._parent._onInject(e, t, n)), this.addDisposable(n), n;
 	}
 	getInstance(e, t = !0) {
@@ -74,7 +78,24 @@ var s = class e extends a {
 	}
 	getInstanceAsync(e) {
 		let t = this._find(e);
-		return typeof t == "function" ? Promise.resolve(t()) : new Promise((t) => this._onInject(e, () => t(this.getInstance(e))));
+		return typeof t == "function" ? Promise.resolve(t()) : new Promise((t, n) => {
+			let r = {
+				id: String(e),
+				startedAt: Date.now(),
+				origin: void 0,
+				container: this,
+				reject: n
+			};
+			s.add(r), this._onInject(e, () => {
+				c(r), t(this.getInstance(e));
+			});
+		});
+	}
+	failPendingWaits(e) {
+		for (let t of Array.from(s)) t.container === this && (c(t), t.reject(e));
+	}
+	pendingWaits() {
+		return [...s].filter((e) => e.container === this);
 	}
 	addService(e, t) {
 		let n = o(e);
@@ -105,62 +126,70 @@ var s = class e extends a {
 			return new e(n);
 		});
 	}
+	remove(e) {
+		let t = this._injections;
+		delete t[String(e)];
+	}
+	injectListenerCount() {
+		return this._injectCallbacks.length;
+	}
 	dispose() {
-		this._injections = Object.create(null);
+		for (let e of Array.from(s)) e.container === this && c(e);
+		this._injections = Object.create(null), this._injectCallbacks = [], super.dispose();
 	}
 };
 //#endregion
 //#region packages/runtime-core/di/namespace.ts
-function c(e) {
+function u(e) {
 	return e.startsWith("__") ? e : `__${e}__`;
 }
-function l(e) {
+function d(e) {
 	if (typeof globalThis > "u") throw Error("[di] globalThis is required for namespace container access.");
-	let t = c(e), n = globalThis;
+	let t = u(e), n = globalThis;
 	return n[t] ??= {};
 }
 //#endregion
 //#region packages/runtime-core/di/ensureContainer.ts
-function u(e) {
+function f(e) {
 	return typeof e == "object" && !!e && typeof e.inject == "function" && typeof e.getInstance == "function";
 }
-function d(e) {
-	return c(e || "emailmaker");
+function p(e) {
+	return u(e || "emailmaker");
 }
-function f(e) {
-	let t = l(d(e));
-	if (u(t.container)) return t.container;
-	let n = new s(null);
+function m(e) {
+	let t = d(p(e));
+	if (f(t.container)) return t.container;
+	let n = new l(null);
 	return t.container = n, n;
 }
-function p(e) {
-	return f(e);
+function h(e) {
+	return m(e);
 }
 //#endregion
 //#region packages/runtime-core/guid/index.ts
-function m() {
+function g() {
 	let e = (/* @__PURE__ */ new Date()).getTime(), t = typeof performance < "u" && performance.now && performance.now() * 1e3 || 0;
 	return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, function(n) {
 		let r = Math.random() * 16;
 		return e > 0 ? (r = (e + r) % 16 | 0, e = Math.floor(e / 16)) : (r = (t + r) % 16 | 0, t = Math.floor(t / 16)), (n === "x" ? r : r & 3 | 8).toString(16);
 	});
 }
-function h() {
-	return typeof crypto < "u" && typeof crypto.randomUUID == "function" ? crypto.randomUUID() : m();
+function _() {
+	return typeof crypto < "u" && typeof crypto.randomUUID == "function" ? crypto.randomUUID() : g();
 }
 //#endregion
 //#region packages/runtime-core/di/identifier.ts
-function g(e = h()) {
+function v(e = _()) {
 	return e;
 }
 //#endregion
 //#region packages/runtime-core/di/index.ts
-function _() {
+function y() {
 	return "app";
 }
-function v(e) {
+function b(e) {
 	if (typeof globalThis > "u") return;
-	let t = _(), n = globalThis[e] ?? {};
+	let t = y(), n = globalThis[e] ?? {};
 	globalThis[e] = n;
 	let r = n.__diagnostics ??= {}, i = r.diModuleEval ??= {
 		evalCount: 0,
@@ -172,12 +201,12 @@ function v(e) {
 		stack: (/* @__PURE__ */ Error()).stack
 	}), i.evalCount += 1;
 }
-function y() {
+function x() {
 	return "__emailmaker__";
 }
-function b(e, t) {
-	if (v(t), typeof globalThis > "u") return e;
-	let n = _(), r = globalThis, i = r[t] = r[t] || {}, a = i.__diagnostics = i.__diagnostics || {}, o = a.dependencyResolver = a.dependencyResolver || { entries: [] }, s = {
+function S(e, t) {
+	if (b(t), typeof globalThis > "u") return e;
+	let n = y(), r = globalThis, i = r[t] = r[t] || {}, a = i.__diagnostics = i.__diagnostics || {}, o = a.dependencyResolver = a.dependencyResolver || { entries: [] }, s = {
 		container: e,
 		source: "packages/runtime-core/di/index.ts",
 		buildSource: n,
@@ -186,16 +215,16 @@ function b(e, t) {
 	};
 	return o.entries.push(s), e;
 }
-var x;
-function S() {
-	if (x) return x;
-	let e = y();
-	return x = b(f(e), e), x;
+var C;
+function w() {
+	if (C) return C;
+	let e = x();
+	return C = S(m(e), e), C;
 }
-var C = new Proxy({}, { get(e, t, n) {
-	let r = S(), i = Reflect.get(r, t, n);
+var T = new Proxy({}, { get(e, t, n) {
+	let r = w(), i = Reflect.get(r, t, n);
 	return typeof i == "function" ? i.bind(r) : i;
-} }), w = class {
+} }), E = class {
 	_plugins = /* @__PURE__ */ new Map();
 	_listeners = /* @__PURE__ */ new Map();
 	_getOrCreateEntry(e) {
@@ -310,7 +339,7 @@ var C = new Proxy({}, { get(e, t, n) {
 			e.add(t, n);
 		} };
 	}
-}, T = class {
+}, D = class {
 	resolveRegistry;
 	constructor(e) {
 		this.resolveRegistry = e;
@@ -357,7 +386,30 @@ var C = new Proxy({}, { get(e, t, n) {
 	forContext() {
 		return this.target().forContext();
 	}
-}, E = class {
+}, O = v("ComponentRegistry"), k = v("ComponentRegistryGate");
+function A() {
+	return T.getOrCreateInstance(k, () => ({ pending: [] }));
+}
+function j(e) {
+	let t = A();
+	t.factory = e;
+	let n = t.pending.splice(0, t.pending.length);
+	for (let e of n) try {
+		e();
+	} catch (e) {
+		console.error("[extensions] deferred UI call failed once the component registry arrived:", e);
+	}
+}
+function M(e, t = O) {
+	let n = T.getInstance(t);
+	if (n) return n;
+	let r = A().factory;
+	if (!r) throw Error("[extensions] component registry is not loaded yet — UI work starts at init()");
+	return T.getOrCreateInstance(t, r);
+}
+//#endregion
+//#region packages/extensions-core/components/DomComponentRegistry.ts
+var N = class {
 	_factories = /* @__PURE__ */ new Map();
 	add(e, t) {
 		let n = e;
@@ -368,28 +420,28 @@ var C = new Proxy({}, { get(e, t, n) {
 	get(e) {
 		return this._factories.get(e);
 	}
-}, D = g("DomComponentRegistry");
-function O(e, t = D) {
-	return C.getOrCreateInstance(t, () => new E());
+}, P = v("DomComponentRegistry");
+function F(e, t = P) {
+	return T.getOrCreateInstance(t, () => new N());
 }
 //#endregion
 //#region packages/extensions-core/components/ComponentRegistry.ts
-function k(e) {
+function I(e) {
 	return typeof e == "function";
 }
-function A(e) {
+function L(e) {
 	return i(e);
 }
-function j(e) {
-	return typeof e == "function" || A(e);
+function R(e) {
+	return typeof e == "function" || L(e);
 }
-function M(e) {
-	return typeof e == "object" && !!e && "type" in e && "props" in e && !A(e);
+function z(e) {
+	return typeof e == "object" && !!e && "type" in e && "props" in e && !L(e);
 }
-function N(e, t) {
+function B(e, t) {
 	return n(e, t);
 }
-function P(t) {
+function V(t) {
 	return class extends e {
 		_ref = r();
 		_instance;
@@ -407,7 +459,7 @@ function P(t) {
 		}
 	};
 }
-var F = class {
+var H = class {
 	_domComponentRegistry;
 	_components = /* @__PURE__ */ new Map();
 	_domAdapters = /* @__PURE__ */ new Map();
@@ -441,26 +493,26 @@ var F = class {
 		t.component = t.replacers.reduce((e, { replacer: t }) => t(e), void 0);
 	}
 	get(e) {
-		if (j(e)) return e;
+		if (R(e)) return e;
 		let t = e, n = this._components.get(t);
 		if (n?.component) return n.component;
 		let r = this._domComponentRegistry.get(e);
 		if (r) {
 			let e = this._domAdapters.get(t);
-			return e || (e = P(r), this._domAdapters.set(t, e)), e;
+			return e || (e = V(r), this._domAdapters.set(t, e)), e;
 		}
 	}
 	_resolveComponentInput(e) {
 		if (e == null) return null;
-		if (typeof e == "number" || typeof e == "boolean" || A(e)) return e;
+		if (typeof e == "number" || typeof e == "boolean" || L(e)) return e;
 		if (typeof e == "string") {
 			let t = this.get(e);
-			return A(t) ? t : t ? N(t) : e;
+			return L(t) ? t : t ? B(t) : e;
 		}
-		if (k(e)) return N(e);
-		if (M(e)) {
+		if (I(e)) return B(e);
+		if (z(e)) {
 			let t = this.get(e.type);
-			return A(t) ? t : t ? N(t, e.props) : null;
+			return L(t) ? t : t ? B(t, e.props) : null;
 		}
 		return null;
 	}
@@ -469,38 +521,36 @@ var F = class {
 	}
 	getReactElement(e) {
 		let r = this._resolveComponentInput(e);
-		return A(r) ? r : typeof r == "string" || r == null || typeof r == "boolean" || typeof r == "number" ? n(t, null, r) : n(t, null);
+		return L(r) ? r : typeof r == "string" || r == null || typeof r == "boolean" || typeof r == "number" ? n(t, null, r) : n(t, null);
 	}
-}, I = g("ComponentRegistry");
-function L(e, t = I) {
-	return C.getOrCreateInstance(t, () => new F(O(C, D)));
-}
+}, U = () => new H(F(T, P));
+j(U), T.getOrCreateInstance(O, U);
 //#endregion
 //#region src/plugin/registryId.ts
-var R = "PluginRegistry";
+var W = "PluginRegistry";
 //#endregion
 //#region src/plugin/pluginRegistry.ts
-function z(e = p()) {
-	return e.getOrCreateInstance(R, () => new w());
+function G(e = h()) {
+	return e.getOrCreateInstance(W, () => new E());
 }
-new T(() => z());
+new D(() => G()), v("ELEMENT_INSERT_HTML_PIPELINE"), v("BLOCK_INSERT_HTML_PIPELINE");
 //#endregion
 //#region packages/extensions-core/identifiers/index.ts
-function B(e) {
-	return g(e);
+function K(e) {
+	return v(e);
 }
-B("HANDLE_ATOM_INSERT"), B("SETTINGS_PANEL_EVENT"), B("MODAL_SHOW_EVENT"), B("MODAL_CLOSE_EVENT"), B("MODAL_UPDATE_EVENT");
+v("extensions.atomsHandlers"), K("HANDLE_ATOM_INSERT"), v("HeadlessMode"), v("extensions.sandboxExtensions"), v("MESSAGE_SERVICE"), K("SETTINGS_PANEL_EVENT"), K("MODAL_SHOW_EVENT"), K("MODAL_CLOSE_EVENT"), K("MODAL_UPDATE_EVENT");
 //#endregion
 //#region src/extensions/api/src/index.ts
-function V() {
+function q() {
 	return typeof globalThis.crypto?.randomUUID == "function" ? globalThis.crypto.randomUUID() : `component-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
-function H(e = V()) {
+function J(e = q()) {
 	return e;
 }
-O(C);
+F(T);
 //#endregion
 //#region src/extensions/react/src/index.ts
-var U = L(C);
+var Y = M(T);
 //#endregion
-export { U as ComponentRegistry, H as createComponentIdentifier };
+export { Y as ComponentRegistry, J as createComponentIdentifier };

package/package.json

@@ -5,14 +5,14 @@
   "main": "index.js",
   "types": "types.d.ts",
   "dependencies": {
-    "antd": "^6.3.5",
+    "antd": "^6.4.3",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "@emailmaker/emailmaker": "1.1.93",
-    "@emailmaker/extensions-app": "1.1.93"
+    "@emailmaker/emailmaker": "1.1.102",
+    "@emailmaker/extensions-app": "1.1.102"
   },
   "name": "@emailmaker/extensions-react",
-  "version": "1.1.93"
+  "version": "1.1.102"
 }

package/types.d.ts

@@ -322,6 +322,15 @@ interface ISandboxScriptHandle extends IDisposable {
    * lifecycle initialization (`afterInit`).
    */
   readonly ready: Promise<void>;
+  /**
+   * Fires every time the script becomes ready, including the first time.
+   *
+   * The canvas document is recreated for every email, so the script is evaluated again and becomes
+   * ready again — `ready` is a promise and settles only once, for the first canvas. A host that keeps
+   * state in the script subscribes here and sends it again; the editor also replays, on its own, the
+   * last message the host sent to the script after `ready`.
+   */
+  onReady(listener: () => void): IDisposable;
 }
 interface ISandboxScriptApi {
   /**