@retailcrm/embed-ui-v1-endpoint 0.9.23 → 0.9.24

package/README.md

@@ -41,6 +41,7 @@ runEndpoint(runner)
 - [`createEndpoint`](./docs/create-endpoint.md) — как вручную создать endpoint с transport и messenger.
 - [`runEndpoint`](./docs/run-endpoint.md) — как поднять endpoint в точке входа веб-воркера одной строкой.
 - [`targets` и `defineTarget`](./docs/targets.md) — как типизировать цели виджетов и маршрутизировать их по target.
+- `@retailcrm/embed-ui-v1-components` `docs/profiles/widgets/WidgetComposition.yml` — как оформлять inline UI виджетов и когда уносить сложность в modal/sidebar.
 - [`menu-placements`](./docs/menu-placements.md) — как описывать меню и пункты навигации для встраиваемых страниц.
 - [`page-routes`](./docs/page-routes.md) — как связывать page `code`, CRM-маршрут и `definePageRunner`.
 - [`layout`](./docs/layout.md) — как выбирать паттерны компоновки страниц, `modal sidebar` и `modal window`, и из каких `v1-components` их собирать.

package/bin/embed-ui-v1-endpoint.mjs

@@ -157,9 +157,11 @@ When working with \`${PACKAGE_NAME}\` in this project:
 5. When the task involves widget targets, target placement, target contexts, target metadata, or choosing a target, use the package MCP server if it is available.
 6. First read \`embed-ui-v1-endpoint://targets\` to discover available target profiles.
 7. Then read the relevant \`embed-ui-v1-endpoint://targets/<encoded-target>\` resource before answering or changing code related to that target.
-8. A project \`.mcp.json\` may require restarting or reconnecting the AI client before MCP resources appear in the current session.
-9. If MCP resources are not available, use the generated YAML profiles from \`./node_modules/${PACKAGE_NAME}/docs/targets/*.yml\` as the fallback source.
-10. Prefer target profiles over guessing target placement, contexts, or semantic intent from names alone.
+8. For widget UI composition, keep inline target content compact: prefer \`UiToolbarButton\`, \`UiToolbarLink\`, short text, and icons; move complex UI into \`UiModalSidebar\` or \`UiModalWindow\`.
+9. If \`@retailcrm/embed-ui-v1-components\` is installed, read its widget composition docs before building widget UI.
+10. A project \`.mcp.json\` may require restarting or reconnecting the AI client before MCP resources appear in the current session.
+11. If MCP resources are not available, use the generated YAML profiles from \`./node_modules/${PACKAGE_NAME}/docs/targets/*.yml\` as the fallback source.
+12. Prefer target profiles over guessing target placement, contexts, or semantic intent from names alone.
 
 Suggested MCP stdio server configuration:
 

package/docs/README.md

@@ -14,6 +14,7 @@
 
 - [`targets` и `defineTarget`](./targets.md) — типизированные цели для виджетов.
 - [`targets/*.yml`](./targets/) — сгенерированные AI-friendly описания встроенных widget targets на английском.
+- `@retailcrm/embed-ui-v1-components` `docs/profiles/widgets/WidgetComposition.yml` — как оформлять inline UI виджетов и когда уносить сложность в modal/sidebar.
 - MCP-сервер `embed-ui-v1-endpoint-mcp` — поставляемый stdio server, который отдаёт `targets/*.yml` как MCP resources.
 - [`menu-placements`](./menu-placements.md) — как описывать меню и пункты навигации, из которых открываются встраиваемые страницы.
 - [`page-routes`](./page-routes.md) — как связывать page `code`, CRM-маршрут и `definePageRunner`.

package/docs/layout.md

@@ -47,10 +47,14 @@
 
 ### Кнопки
 
-- На странице допускается одна основная `Default Primary` кнопка.
-- Отдельно может быть одна `Success Primary`, если сценарий этого требует.
-- Остальные действия рекомендуется оформлять через `Default Secondary`, `Default Tertiary`, `Success Secondary` и похожие менее доминирующие варианты.
-- Если действий много, одно оставляют главным, а остальные уводят во вторичный слой или dropdown.
+- В рамках всей страницы допускается максимум по одной page-level `primary`-кнопке каждого варианта: `Success Primary`, `Default Primary` и `Danger Primary`.
+- `Success Primary` — главное call-to-action страницы: действие, которое создаёт или фиксирует результат, например `Сохранить`, `Применить`, `Создать`. Обычно оно находится в `UiPageFooter`.
+- Если важное действие не является главным commit-действием, используйте `Default Primary`.
+- `Danger Primary` допустим только для одного критичного деструктивного действия.
+- Если важных действий несколько, выберите главное и оформите его как `Success Primary`; остальные переводите в `Default Primary`, `Default Secondary`, `Default Tertiary`, `Success Secondary` или другой менее доминирующий вариант по смыслу.
+- `UiPageHeader` и `UiPageFooter` относятся к одному page-level scope: `UiPageFooter` не сбрасывает лимит сам по себе.
+- Только `UiCollapseBox` с собственным footer создаёт локальный scope: внутри каждого блока может быть одна `Default Primary` для главного действия этой секции.
+- Если действий много, оставьте видимыми только действительно важные, а остальные уводите во вторичный слой или dropdown.
 
 Типичная компонентная основа:
 
@@ -207,6 +211,7 @@
 - Если на странице используются `Collapse`-блоки, дополнительная общая белая подложка вокруг них обычно не нужна.
 - Если подложка видна только ради пары collapse-блоков, от неё следует отказаться.
 - Обычно и общая нижняя панель сохранения не нужна, потому что каждый блок сохраняется отдельно.
+- Каждый `UiCollapseBox` с footer работает как локальная “мини-страница”: в его footer можно использовать одну `Default Primary` кнопку для главного действия секции, а остальные действия оформлять менее доминирующе.
 
 ### Типичный состав
 
@@ -247,6 +252,7 @@
 - `UiModalSidebar` как контейнер `modal sidebar`.
 - Внутри: обычные form/content primitives из `v1-components`.
 - В `footer`: `UiButton` для сохранения, закрытия и удаления.
+- Главное действие сохранения или применения в `footer` обычно оформляется как `Success Primary`; соседние действия должны быть менее доминирующими, если они не являются самостоятельным `Default Primary` или `Danger Primary` по смыслу.
 
 ### Типичный состав
 
@@ -329,7 +335,7 @@
 2. Это список, карточка, карточка с колонками или collapse-настройки?
 3. Нужны ли tabs, или блоки следует оставить на одном полотне?
 4. Нужна ли общая панель сохранения, или каждый блок должен сохраняться отдельно?
-5. Не перегружен ли экран количеством primary-действий?
+5. Есть ли на странице не больше одного page-level `primary`-действия каждого варианта, а дополнительные `Default Primary` находятся только внутри отдельных `UiCollapseBox`?
 6. Держатся ли отступы и расстояния сетки `4px`?
 
 ---

package/docs/menu-placements.md

@@ -29,6 +29,38 @@
 | `route` | Имя или путь CRM-маршрута, если пункт открывается через маршрутизацию host-части. |
 | `visibility` | Условия показа: права, настройки, тариф, доступность фичи. |
 
+## Manifest `pages`
+
+В `extensionrc.json` и payload для RetailCRM API страницы нужно описывать объектами `ConfigurationPage`,
+а не строками. Строковый список page codes достаточен только для runtime runner map на фронтенде; backend API
+и меню страницы ожидают метаданные пункта меню.
+
+Минимальная рабочая форма:
+
+```json
+{
+  "pages": [
+    {
+      "code": "orders-dashboard",
+      "menu": "activity_main_menu",
+      "parentMenuItemCode": "orders",
+      "menuItemOrdering": 100,
+      "menuItemTitle": {
+        "ru": "Заказы",
+        "en": "Orders",
+        "es": "Pedidos"
+      },
+      "pageHelpLink": null
+    }
+  ]
+}
+```
+
+`menu` обязателен для опубликованной страницы: без него backend не сможет открыть route вида
+`/modules/<module-code>/<page-code>`. Для страниц в разделе настроек обычно используется
+`menu: "private_main_menu"` и `parentMenuItemCode: "settings"`. Для страниц в разделе продаж используйте
+`menu: "activity_main_menu"` и соответствующий parent menu item, например `orders`.
+
 ## Пример справочника меню
 
 Конкретные `placement`, `item code` и `route` нужно брать из host/manifest расширения.
@@ -66,4 +98,4 @@ const pageRunner = definePageRunner({
 - [`definePageRunner`](./define-page-runner.md) — как встраиваемая страница получает `code`.
 - [`targets`](./targets.md) — точки встраивания виджетов, не пунктов меню.
 - [`layout`](./layout.md) — когда делать полноценную страницу, а когда `modal sidebar` или `modal window`.
-- [`UiMenuItem`](../../v1-components/docs/profiles/UiMenuItem.yml) — компонент строки меню внутри UI расширения.
+- `@retailcrm/embed-ui-v1-components` `docs/profiles/components/UiMenuItem.yml` — компонент строки меню внутри UI расширения.

package/docs/page-routes.md

@@ -7,6 +7,11 @@
 host/manifest конкретного расширения, поэтому его нужно хранить в справочнике проекта рядом с кодом
 расширения.
 
+В runtime-коде `definePageRunner` сопоставляет page `code` с Vue-компонентом. В `extensionrc.json` этот же
+page `code` нужно описывать объектом manifest `pages[]` с `menu` и, обычно, `menuItemTitle`. Не используйте
+строковую форму `pages: ["orders-dashboard"]` для публикации через RetailCRM API: backend ожидает
+`ConfigurationPage` object, а страница без `menu` не откроется по route `/modules/<module-code>/<page-code>`.
+
 ## Что такое `page code`
 
 `page code` — стабильный идентификатор встраиваемой страницы внутри расширения.
@@ -59,6 +64,23 @@ console.log(settings['system.routing'].routes)
 | `integration-settings` | `embed.page.integration_settings` | `{}` | `settings / integration-settings` | `IntegrationSettingsPage.vue` |
 | `customer-tools` | `embed.page.customer_tools` | `{ customerId }` | `customer/card:actions / customer-tools` | `CustomerToolsPage.vue` |
 
+Пример manifest-записи для страницы:
+
+```json
+{
+  "code": "orders-dashboard",
+  "menu": "activity_main_menu",
+  "parentMenuItemCode": "orders",
+  "menuItemOrdering": 100,
+  "menuItemTitle": {
+    "ru": "Заказы",
+    "en": "Orders",
+    "es": "Pedidos"
+  },
+  "pageHelpLink": null
+}
+```
+
 ## Переход на CRM-маршрут
 
 Если странице нужен переход на другой CRM-маршрут, используйте host API, а не прямую сборку URL.
@@ -76,5 +98,5 @@ const openSettings = (host: HostApi) => {
 
 - [`menu-placements`](./menu-placements.md) — как связать пункт меню, page `code` и маршрут.
 - [`definePageRunner`](./define-page-runner.md) — как page `code` попадает в компонент.
-- [`settings context`](../../v1-contexts/docs/ru/CONCEPT.md) — общий принцип работы контекстов.
-- [`HostApi`](../../v1-types/host.d.ts) — публичный тип host API с `goTo`.
+- `@retailcrm/embed-ui-v1-contexts` `docs/ru/CONCEPT.md` — общий принцип работы контекстов.
+- `@retailcrm/embed-ui-v1-types` `host.d.ts` — публичный тип host API с `goTo`.

package/docs/targets/customer-card-communications-after.yml

@@ -56,6 +56,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/customer-card-inwork-after.yml

@@ -56,6 +56,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/customer-card-inwork-before.yml

@@ -56,6 +56,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/customer-card-phone.yml

@@ -59,6 +59,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-comment-manager-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-common-after.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-common-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-customer-after.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-customer-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-customer-email.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-customer-phone.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-delivery-address.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-delivery-after.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-delivery-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-dimensions-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-list-after.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-list-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-payment-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-card-store-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-mg-delivery-after.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-mg-delivery-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-mg-list-after.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-mg-list-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-mg-payment-after.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets/order-mg-payment-before.yml

@@ -62,6 +62,8 @@ avoid_when:
 
 ai_notes:
   - "Use the target id as the runner registration key."
+  - "Keep UI rendered directly in the widget target compact and predictable: prefer UiToolbarButton, UiToolbarLink, short text, and icons."
+  - "Move complex widget UI such as forms, tables, maps, filters, summaries, and multi-step flows into UiModalSidebar or UiModalWindow."
   - "Use targets[target].contexts as the source of truth for context availability."
   - "Read linked context_resources, action_resources, and custom_context_resources before reasoning about fields, mutations, or custom data."
   - "Do not infer context field shape from the target id, page name, or widget placement."

package/docs/targets.md

@@ -24,6 +24,19 @@
 `target` не является данными заказа, клиента или пользователя. Это только место встраивания.
 Данные нужно брать из контекстов, которые привязаны к этому `target`.
 
+## Оформление виджета в target
+
+Виджет должен добавлять в target простой и предсказуемый inline UI: обычно `UiToolbarButton`,
+`UiToolbarLink`, короткий текст или компактное действие с иконкой. Это сохраняет страницу CRM
+стабильной и не раздувает место встраивания.
+
+Если сценарий требует сложной формы, таблицы, карты, фильтров, summary-блоков или многошагового UI,
+оставьте в target только компактный вход в сценарий, а основную логику перенесите в `UiModalSidebar`
+или `UiModalWindow`.
+
+Подробные правила композиции описаны в `@retailcrm/embed-ui-v1-components`
+`docs/profiles/widgets/WidgetComposition.yml`.
+
 ## Проверка контекстов для `target`
 
 ```ts
@@ -132,5 +145,5 @@ const testTarget = defineTarget('customer/card:test.after', [
 - [`defineWidgetRunner`](./define-widget-runner.md) — как `target` попадает в компонент встраиваемого виджета.
 - [`menu-placements`](./menu-placements.md) — чем пункты меню для страниц отличаются от widget `target`.
 - [`page-routes`](./page-routes.md) — как описывать page `code` и CRM-маршрут.
-- [`CONCEPT`](../../v1-contexts/docs/ru/CONCEPT.md) — общий принцип работы контекстов.
-- [`CUSTOM`](../../v1-contexts/docs/ru/CUSTOM.md) — пользовательский контекст для custom fields.
+- `@retailcrm/embed-ui-v1-contexts` `docs/ru/CONCEPT.md` — общий принцип работы контекстов.
+- `@retailcrm/embed-ui-v1-contexts` `docs/ru/CUSTOM.md` — пользовательский контекст для custom fields.

package/package.json

@@ -5,7 +5,7 @@
     "embed-ui-v1-endpoint-mcp": "bin/embed-ui-v1-endpoint-mcp.mjs"
   },
   "type": "module",
-  "version": "0.9.23",
+  "version": "0.9.24",
   "description": "Endpoint API for integrations in RetailCRM",
   "license": "MIT",
   "author": "RetailDriverLLC <integration@retailcrm.ru>",
@@ -100,17 +100,17 @@
   "peerDependencies": {
     "@omnicajs/vue-remote": "^0.2.24",
     "@remote-ui/rpc": "^1.4",
-    "@retailcrm/embed-ui-v1-contexts": "^0.9.23",
-    "@retailcrm/embed-ui-v1-types": "^0.9.23",
+    "@retailcrm/embed-ui-v1-contexts": "^0.9.24",
+    "@retailcrm/embed-ui-v1-types": "^0.9.24",
     "pinia": "^2.2",
     "vue": "^3.5"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@remote-ui/rpc": "^1.4.7",
-    "@retailcrm/embed-ui-v1-components": "^0.9.23",
-    "@retailcrm/embed-ui-v1-contexts": "^0.9.23",
-    "@retailcrm/embed-ui-v1-types": "^0.9.23"
+    "@retailcrm/embed-ui-v1-components": "^0.9.24",
+    "@retailcrm/embed-ui-v1-contexts": "^0.9.24",
+    "@retailcrm/embed-ui-v1-types": "^0.9.24"
   },
   "devDependencies": {
     "@retailcrm/image-preview": "^1.0.2",