@emailmaker/extensions-react 1.0.111-dev.8 → 1.0.111-dev.9

package/README.md

@@ -15,8 +15,8 @@
 ## ⚙️ Требования
 
 - Современный браузер с поддержкой **ES2015** (и выше)
-- Node.js >= 14
-- React и Ant Design подключаются через [`externals`](https://webpack.js.org/configuration/externals/) или напрямую из `@emailmaker/emailmaker/runtime`
+- Node.js >= 20 (рекомендуется LTS; CLI-шаблон использует `tsx` и Vite/Webpack 5)
+- React и Ant Design в плагине подключаются через `PluginDev` (alias/externals на runtime хоста из `@emailmaker/emailmaker/runtime/*`), а не отдельным npm-пакетом runtime
 
 
 ---
@@ -33,21 +33,39 @@
 
 ## 🔰 Быстрый старт
 
-👉 Самый простой способ начать — использовать [готовый шаблон](https://github.com/emailmaker/simple_plugin):
+👉 Рекомендуемый способ — **CLI** (`@emailmaker/cli`): согласованная структура, Vite/Webpack, app + sandbox, dev/release host.
 
 ```bash
-git clone https://github.com/emailmaker/simple_plugin
-cd simple_plugin
+npx @emailmaker/cli my-plugin --kind plugin --preset advanced --bundler vite --target npm-package --output-dir ./my-plugin
+cd my-plugin
 npm install
 npm run start
 ```
 
-Шаблон включает в себя:
-- Webpack / Vite
+Сгенерированный проект включает:
+- Webpack / Vite (по выбору)
 - React + Ant Design
 - TypeScript
 - Структуру проекта, описанную ниже
 
+Проверка release-сборки без ручного деплоя:
+
+```bash
+npm run build
+npm run start:release
+```
+
+### Альтернатива: пример из репозитория
+
+[Готовый example](https://github.com/emailmaker/simple_plugin) можно клонировать для ознакомления; для новых плагинов предпочтительнее CLI-шаблон.
+
+```bash
+git clone https://github.com/emailmaker/simple_plugin
+cd simple_plugin
+npm install
+npm run start
+```
+
 
 ---
 
@@ -56,18 +74,19 @@ npm run start
 ### 📦 Основные пакеты
 
 ```bash
-npm install @emailmaker/emailmaker @emailmaker/emailmaker/runtime @emailmaker/extensions-app @emailmaker/extensions-react @emailmaker/extensions-sandbox
+npm install @emailmaker/emailmaker @emailmaker/extensions-app @emailmaker/extensions-react @emailmaker/extensions-sandbox
 ```
 
 | Пакет | Назначение | Что экспортирует |
 |-------|------------|------------------|
-| `@emailmaker/emailmaker` | Основной пакет | `init()`, `prefetch()`, типы `IPlugin`, `Instance` |
-| `@emailmaker/emailmaker/runtime` | Общие зависимости | React, ReactDOM, Ant Design и связанные модули |
+| `@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` |
 
-`@emailmaker/ui-kit` ставится отдельно, если плагин использует готовые UI-компоненты платформы.
+`@emailmaker/ui-kit` ставится отдельно (devDependency в CLI-шаблоне), если плагин использует готовые UI-компоненты платформы.
+
+> React и Ant Design в коде плагина импортируются как `react` / `antd`. `PluginDev` в dev/release подставляет runtime хоста через alias/externals — см. раздел «Сборка плагина».
 
 ### Импорты
 
@@ -93,8 +112,8 @@ import type { IPlugin, Instance } from '@emailmaker/emailmaker';
 ## Что обычно ставить
 
 - если у вас обычный React-плагин, ставьте все пакеты из команды выше
-- если используете UI Kit, добавьте еще `@emailmaker/ui-kit`
-- если пишете только sandbox-часть, нужен `@emailmaker/extensions-sandbox`
+- если используете UI Kit, добавьте ещё `@emailmaker/ui-kit`
+- если пишете только sandbox-часть, достаточно main + `@emailmaker/extensions-sandbox`
 
 > Для React-плагинов пакет `@emailmaker/extensions-react` нужен по умолчанию.
 
@@ -198,7 +217,7 @@ module.exports = {
 
 Если release bundle неожиданно стал толстым или target `встраиваемый bundle` не загружается, начните с раздела `Troubleshooting`.
 
-Типы для плагина всё равно собираются отдельно: CLI-шаблон запускает `build:types` и кладёт `dist/index.d.ts` рядом с JS bundle, поэтому TypeScript support сохраняется и для browser/advanced targets.
+Типы для плагина всё равно собираются отдельно: CLI-шаблон запускает `build:types` и кладёт `dist/public-types.d.ts` рядом с JS bundle, поэтому TypeScript support сохраняется и для browser/advanced targets.
 
 ### tsconfig.json
 
@@ -273,27 +292,35 @@ emailmaker.init({
 
 ## 📁 Структура проекта
 
+CLI-шаблон (типичный layout):
+
 ```txt
-plugin-root/
-├── shared/           # Общие типы и интерфейсы
-│   └── interfaces.ts # Идентификаторы сообщений
-├── app/              # UI-часть, взаимодействие с редактором
-│   └── MyPlugin.ts   # Регистрация и логика плагина
-├── sandbox/          # Работа с DOM письма
-│   └── index.ts      # Точка входа для sandbox
-├── test/             # Точка входа для тестирования
+my-plugin/
+├── src/
+│   ├── app/              # UI-часть, взаимодействие с редактором
+│   │   └── MyPlugin.tsx
+│   ├── sandbox/          # Скрипт для DOM письма (отдельная сборка)
+│   │   └── index.ts
+│   ├── dev.tsx           # Локальный debug host (редактор + плагин)
+│   └── public-types.d.ts # Типы плагина для npm / augmentation
+├── config/               # Vite/Webpack: dev host, release, sandbox
+├── scripts/              # dev-runner, build-runner, release-runner, build-types
+├── dist/                 # Сборка app-плагина (+ public-types.d.ts)
+└── package.json
 ```
 
-- `shared` — общие типы для взаимодействия между `app` и `sandbox`
-- `app` — точка входа, из которой можно подключить скрипт sandbox:
+- **`src/app`** — регистрация плагина, панели, работа с API редактора. Отсюда подключается 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`
+- **`src/sandbox`** — код в iframe; собирается отдельным entry (`build:sandbox`), без React.
+- **`src/dev.tsx`** — локальный запуск `emailmaker` с плагином (`npm run start`).
+- **`src/public-types.d.ts`** — `PluginTypeMap`, `Config`, опции; после `npm run build:types` копируется в `dist/public-types.d.ts`.
+
+Общие идентификаторы событий app ↔ sandbox держите в `src/interfaces/` (или аналогичном shared-модуле внутри `src/`).
 
 
 ---
@@ -341,6 +368,24 @@ class TestPlugin implements IPlugin {
 }
 ```
 
+### Sandbox-часть
+
+Скрипт в iframe (`@emailmaker/extensions-sandbox`) использует **упрощённый** lifecycle — без `required()`:
+
+```ts
+import { App } from '@emailmaker/extensions-sandbox';
+import type { IPlugin } from '@emailmaker/extensions-sandbox';
+
+class MyPluginSandbox implements IPlugin {
+  init() { /* ... */ }
+  afterInit?() { /* ... */ }
+  dispose() { /* ... */ }
+}
+
+App.registerPlugin('MyPluginSandbox', MyPluginSandbox);
+```
+
+
 
 ---
 
@@ -493,10 +538,15 @@ elementsApi.insert({
 Добавление новой панели настроек. Например, можно добавить панель которая будет отображаться при клике на элементе в sandbox.
 
 ```ts
+import { createComponentIdentifier } from '@emailmaker/extensions-app';
+
+const SettingsPanelId = createComponentIdentifier('MySettingsPanel');
+// ComponentRegistry.add(SettingsPanelId, MySettingsPanel);
+
 const panel = editor.use('SettingsPanelApi');
 panel.showSettingsPanel({
   content: {
-    type: 'SettingsPanelId',
+    type: SettingsPanelId,
     props: {...}
   },
   caption: 'Настройки',
@@ -513,7 +563,7 @@ panel.showSettingsPanel({
 ```ts
 panel.showSettingsPanel({
   instanceKey: blockUuid,
-  content: { type: 'SettingsPanelId', props: { blockUuid, settings } },
+  content: { type: SettingsPanelId, props: { blockUuid, settings } },
 });
 ```
 
@@ -531,20 +581,30 @@ panel.showSettingsPanel({
 > Интерфейс основан на модалках `Ant Design`
 
 ```ts
+import { createComponentIdentifier } from '@emailmaker/extensions-app';
+import { ComponentRegistry } from '@emailmaker/extensions-react';
+
+const MyPanelId = createComponentIdentifier('MyPanel');
+ComponentRegistry.add(MyPanelId, MyPanel);
+
 const modal = editor.use('ModalApi');
 modal.show({
   title: 'Выбор группы',
   content: {
-    type: 'MyPanel',
-    props: { groups, settings }
-  }
+    type: MyPanelId,
+    props: { groups, settings },
+  },
 });
 ```
 
+Для простого UI можно передать JSX напрямую (см. раздел `extensions-react`).
+
 
 ### EmailSettingsApi
 
-> API для работы с настройками письма. Позволяет получать и изменять настройки внешнего вида письма и стили элементов контента.
+> API для работы с настройками письма (редактор email / emailmaker). В widget-сценариях может быть недоступен.
+
+Позволяет получать и изменять настройки внешнего вида письма и стили элементов контента.
 
 API разделен на два типа методов:
 - **Layout Settings** — настройки письма целиком (фон, ширина, адаптивность)
@@ -605,18 +665,25 @@ msg.send('MY_EVENT', { value: 123 });
 msg.addListener('MY_EVENT', (data) => console.log(data));
 ```
 
-Рекомендуется выносить события в константы и использовать типизацию:
+Выносите имена событий в общий модуль (CLI-шаблон: `src/interfaces/`), чтобы app и sandbox использовали одни и те же строки:
+
+```ts
+// src/interfaces/messages.ts
+export const MY_PLUGIN_UPDATE = 'my-plugin:update' as const;
+
+export type MyPluginUpdatePayload = { text: string };
+```
 
 ```ts
-import { createIdentifier } from 'di';
+// app
+msg.send(MY_PLUGIN_UPDATE, { text: 'hello' });
 
-export const Activate_Product_Settings = createIdentifier<
-  { groupId?: string; visualSettings: VisualSettings }, 
-  void, 
-  void
->('Activate_Product_Settings');
+// sandbox
+messageService.addListener(MY_PLUGIN_UPDATE, (data) => { /* ... */ });
 ```
 
+Тип payload задайте рядом с константой (`MyPluginUpdatePayload`) — отдельный runtime-пакет для идентификаторов не нужен.
+
 
 ### SandboxScriptApi
 
@@ -706,14 +773,17 @@ syncService.commit();
 
 ## 🧱 Регистрация UI компонентов
 
-`ComponentRegistry` нужен, когда вы хотите зарегистрировать React-компонент и потом передавать его в API по идентификатору:
+`ComponentRegistry` нужен, когда вы хотите зарегистрировать React-компонент и потом передавать его в API по **типизированному** идентификатору:
 
 ```ts
+import { createComponentIdentifier } from '@emailmaker/extensions-app';
 import { ComponentRegistry } from '@emailmaker/extensions-react';
 
-ComponentRegistry.add('MyPanel', MyReactPanel);
+const MyPanelId = createComponentIdentifier<{ groups: Group[] }>('MyPanel');
 
-ComponentRegistry.override('MyPanel', (Base) => (props) => (
+ComponentRegistry.add(MyPanelId, MyReactPanel);
+
+ComponentRegistry.override(MyPanelId, (Base) => (props) => (
   <div className="bordered"><Base {...props} /></div>
 ));
 ```
@@ -721,7 +791,7 @@ ComponentRegistry.override('MyPanel', (Base) => (props) => (
 ## Когда использовать
 
 - если хотите просто показать React UI, чаще всего удобнее передать JSX напрямую
-- если нужен `ComponentId`, используйте `ComponentRegistry`
+- если нужен стабильный `ComponentId` для `{ type, props }` — `createComponentIdentifier` + `ComponentRegistry`
 - если UI без React, используйте `DomComponentRegistry`
 
 Пример с JSX:
@@ -735,11 +805,21 @@ settingsPanel.showSettingsPanel({
 });
 ```
 
+Пример с идентификатором:
+
+```ts
+settingsPanel.showSettingsPanel({
+  content: { type: MyPanelId, props: { groups } },
+});
+```
+
 
 ---
 
 ## 🎨 UI Kit
 
+В **коде плагина** импортируйте компоненты из `@emailmaker/ui-kit`. В **release-сборке** `PluginDev` externalizes ui-kit на singleton хоста: `@emailmaker/emailmaker/ui-kit` (отдельно ставить main subpath не нужно).
+
 ### ColorPicker — минимальный пример
 
 Растягивается на ширину родителя (Form.Item, колонку и т.д.) — дополнительный inline-style для ширины не нужен.
@@ -893,7 +973,7 @@ emailmaker.init({
 
 > При множественной инициализации действует принцип «first-write wins» — опции фиксируются при первом создании экземпляра.
 
-CLI-шаблон уже собирает типы отдельно (`npm run build:types`) и публикует `dist/index.d.ts`, поэтому поддержку TypeScript стоит считать частью любого release target, а не только npm/ESM сценария.
+CLI-шаблон уже собирает типы отдельно (`npm run build:types`) и публикует `dist/public-types.d.ts` рядом с JS bundle, поэтому поддержку TypeScript стоит считать частью любого release target, а не только npm/ESM сценария.
 
 ### Расширение Config
 
@@ -940,7 +1020,7 @@ settingsPanel.showSettingsPanel({
 
 ### `--dev` / `--dev-packages`
 
-**Самый частый флаг для разработки:** подставляет **dev**-версии внутренних npm-пакетов (`@emailmaker/*`), которые в шаблонах задаются с 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
@@ -959,8 +1039,8 @@ npx @emailmaker/cli my-plugin --kind plugin --preset advanced --bundler vite --t
 | `--advanced-profile` | Для `--stand-mode advanced`: `subpath`, `shadow-dom`, `umd`. |
 | `--preset` | Шаблон плагина: `minimal` или `advanced`. |
 | `--bundler` | `vite` или `webpack` — сборщик в шаблоне. |
-| `--target` | Поставка плагина: `npm-package`, `browser`, `advanced`. |
-| `--advanced-target` | Доп. цель для режима `advanced` (только webpack), см. справку CLI. |
+| `--target` | Поставка плагина: `npm-package`, `browser`, `advanced` (**`advanced` — только webpack**; у Vite доступны `npm-package` и `browser`). |
+| `--advanced-target` | Для `--target advanced` (только webpack): `async-globals` или `legacy-async-globals`. |
 | `--app` | Идентификатор приложения (`REACT_APP_NAME`), как в монорепозитории; в опубликованном CLI может быть скрыт. |
 | `--output-dir` | Каталог, куда положить сгенерированный проект. |
 | `--output-base` | Базовый каталог: внутри него будет создана папка проекта. |
@@ -977,7 +1057,7 @@ npx @emailmaker/cli --help
 - интерактивный wizard и неинтерактивный запуск;
 - генерация проекта плагина и демо-стендов;
 - шаблоны под **vite** и **webpack**;
-- выбор способа поставки плагина: npm-модуль, браузерный бандл, режим **advanced**.
+- выбор способа поставки плагина: npm-модуль, браузерный bundle (`browser`), режим **advanced** (webpack-only).
 
 ## Основные режимы
 
@@ -1035,7 +1115,14 @@ npx @emailmaker/cli my-plugin --kind plugin --preset advanced --bundler vite --t
 
 Обычно это значит, что dev host использует `PluginDev({ externals: false })`, а release target уже требует runtime contract.
 
-Проверьте:
+Проверьте локально через CLI-шаблон:
+
+```bash
+npm run build
+npm run start:release
+```
+
+Также проверьте:
 
 - target сборки в CLI / config
 - release config для `src/index.ts`
@@ -1080,20 +1167,20 @@ npx @emailmaker/cli my-plugin --kind plugin --preset advanced --bundler vite --t
 - **Externals не работают в dev server**
   > В serve-режиме externals должны быть отключены: `PluginDev({ externals: false })`. Зависимости резолвятся из runtime через alias.
 
-- **ESM output не грузится через `<script>`**
-  > ESM-сборка содержит `import` и не работает как обычный скрипт. Используйте `<script type="module">` или соберите плагин в режиме `global` / `iife`.
+- **ESM output не грузится через обычный `<script>`**
+  > ESM-сборка содержит `import`. Используйте `<script type="module">`, npm-интеграцию или target **browser** (`PluginDev({ externals: 'globals' })`, UMD bundle).
 
-- **Global-плагин: «Cannot read property of undefined»**
-  > Runtime должен быть загружен до плагина. Подключайте плагин через ленивый импорт `() => import(…)` или декларативно `{ type: 'global', url: '…' }`.
+- **Browser/UMD-плагин: «Cannot read property of undefined»**
+  > Runtime хоста должен быть загружен до плагина. Подключайте через npm + lazy import, либо декларативно `{ type: 'umd', url: '…', name: 'MyPlugin', resolve: 'registry' }` (с `pluginRegistry.add`).
 
 - **Не загружаются JS/CSS / iframe не отображается**
   > Проверьте `publicPath` и подключение основного плагина (`VitePlugin` / `WebpackPlugin`). В serve-режиме он обслуживает статику из `node_modules/`.
 
 - **Панель или компонент не отображается**
-  > Убедитесь в регистрации через `ComponentRegistry`.
+  > Убедитесь в регистрации через `ComponentRegistry` и `createComponentIdentifier`.
 
 - **Событие не обрабатывается**
-  > Проверьте подписку на событие в `MessageService`.
+  > Проверьте подписку на событие в `MessageService` и совпадение строковых id в app и sandbox.
 
 - **Изменения в iframe теряются**
   > Не забывайте вызывать `syncService.commit()`.
@@ -1104,7 +1191,7 @@ npx @emailmaker/cli my-plugin --kind plugin --preset advanced --bundler vite --t
 
 **С `externals.json` на `PluginDev`:**
 
-Старый подход с `externals.json` продолжает работать — файл генерируется для обратной совместимости. Но рекомендуем перейти на `PluginDev`: удалите загрузку `externals.json` из конфига и подключите плагин — он настроит externals и alias автоматически.
+Для **новых** проектов используйте только `PluginDev`. Файл `externals.json` в экосистеме остаётся legacy-следом; не подключайте его вручную в Vite-шаблонах.
 
 **С `pluginRegistry.add` на прямой класс:**
 

package/index.js

@@ -503,11 +503,17 @@ function R(e = p()) {
 }
 new w(() => R());
 //#endregion
+//#region packages/extensions-core/identifiers/index.ts
+function z(e) {
+	return h(e);
+}
+z("HANDLE_ATOM_INSERT"), z("SETTINGS_PANEL_EVENT"), z("MODAL_SHOW_EVENT"), z("MODAL_CLOSE_EVENT"), z("MODAL_UPDATE_EVENT");
+//#endregion
 //#region src/extensions/api/src/index.ts
-function z() {
+function B() {
 	return typeof globalThis.crypto?.randomUUID == "function" ? globalThis.crypto.randomUUID() : `component-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
-function B(e = z()) {
+function V(e = B()) {
 	return e;
 }
 //#endregion
@@ -567,7 +573,7 @@ D(S), (function(e) {
 			n.packages[e.id] = e, n.validateAll();
 		}, t.__compat.registerPackage({
 			id: "extensions-react",
-			version: "1.0.111-dev.8",
+			version: "1.0.111-dev.9",
 			requires: {
 				host: "^1.0.105",
 				"extensions-api": "^0.9.0"
@@ -575,6 +581,6 @@ D(S), (function(e) {
 		});
 	}
 })(typeof window < "u" ? window : typeof globalThis < "u" ? globalThis : void 0);
-var V = I(S);
+var H = I(S);
 //#endregion
-export { V as ComponentRegistry, B as createComponentIdentifier };
+export { H as ComponentRegistry, V as createComponentIdentifier };

package/package.json

@@ -10,9 +10,9 @@
     "react-dom": "^18.2.0",
     "@types/react": "^18.2.70",
     "@types/react-dom": "^18.2.0",
-    "@emailmaker/emailmaker": "1.0.111-dev.8",
-    "@emailmaker/extensions-app": "1.0.111-dev.8"
+    "@emailmaker/emailmaker": "1.0.111-dev.9",
+    "@emailmaker/extensions-app": "1.0.111-dev.9"
   },
   "name": "@emailmaker/extensions-react",
-  "version": "1.0.111-dev.8"
+  "version": "1.0.111-dev.9"
 }

package/types.d.ts

@@ -54,11 +54,22 @@ interface IDisposable {
  * Payload for `BlocksApi.handleInject` when a block/structure was inserted in the sandbox
  * (mirrors `application_block_inserted` message data).
  */
-interface BlockInjectInfo {
+interface BlockInjectInfo$1 {
+  /** Editor catalog route (project / template / common / structure path) — same as legacy iframe `type`. */
   type?: string;
+  /** Alias of {@link type} when enriched on the app side. */
+  insertFrom?: string;
   name?: string;
   blockId?: string;
   project?: string;
+  fragmentRole?: 'block' | 'structure';
+  /** Catalog block id (same as {@link blockId} when known). */
+  id?: string;
+  title?: string | null;
+  /** REST / API block taxonomy — not the same as {@link type}. */
+  blockType?: string;
+  /** Host-only metadata (`Block.meta` / `setBlockMeta` on the embedder side). */
+  meta?: Record<string, unknown>;
 }
 /**
  * Context passed to ElementsApi.handleBeforeInject before element (atom) HTML is sent to the iframe.
@@ -73,7 +84,7 @@ interface ElementInsertContext extends Record<string, unknown> {
  * Context passed to BlocksApi.handleBeforeInject before block HTML is sent to the iframe.
  * `insertFrom` is the editor catalog route (e.g. project / template / common), not REST Block.type taxonomy.
  */
-interface BlockInsertContext extends Record<string, unknown> {
+interface BlockInsertContext$1 extends Record<string, unknown> {
   html: string;
   insertFrom?: string;
   fragmentRole?: 'block' | 'structure';
@@ -107,6 +118,8 @@ interface BlockInsertContext extends Record<string, unknown> {
   project_title?: string;
   project_author?: string;
   isAmp?: boolean;
+  /** Host-only metadata (not sent to iframe). */
+  meta?: Record<string, unknown>;
   /** Remaining catalog/API fields not mapped above (shallow copy). */
   catalogExtra?: Record<string, unknown>;
 }
@@ -118,12 +131,14 @@ interface IBlocksApi {
    * Runs before block HTML is posted to the iframe. Listeners receive a mutable context; they may
    * mutate `html` and related fields or return a partial object to merge (SaveEmitter-style).
    */
-  handleBeforeInject(listener: (ctx: BlockInsertContext) => MayBePromise<Partial<BlockInsertContext> | void>, priority?: number, thisArg?: unknown): IDisposable;
+  handleBeforeInject(listener: (ctx: BlockInsertContext$1) => MayBePromise<Partial<BlockInsertContext$1> | void>, priority?: number, thisArg?: unknown): IDisposable;
   /**
-   * Fires after a block or structure was inserted in the sandbox (same channel as `application_block_inserted`).
+   * Fires after a block or structure was inserted in the sandbox.
+   * Payload is enriched on the app shell (incl. `meta`, `insertFrom`, `blockType`) from pending insert context;
+   * iframe only sends a minimal ack on `application_block_inserted`.
    * Does not allow changing markup; use {@link handleBeforeInject} to transform HTML before postMessage.
    */
-  handleInject(listener: (info: BlockInjectInfo) => void, priority?: number, thisArg?: unknown): IDisposable;
+  handleInject(listener: (info: BlockInjectInfo$1) => void, priority?: number, thisArg?: unknown): IDisposable;
 }
 /**
  * Information about an element.