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

package/README.md

@@ -85,6 +85,15 @@ npx @retailcrm/embed-ui-v1-endpoint init-agents
 такого блока там ещё нет. С `--force` можно обновить уже существующий блок
 пакета.
 
+Для project-level skills можно создать `.agents/skills/embed-ui-v1-endpoint-runtime/SKILL.md`:
+
+```bash
+npx @retailcrm/embed-ui-v1-endpoint init-skills
+```
+
+Skill описывает повторяемый workflow для pages/widgets, runner setup, target selection,
+menu hierarchy, page publishing payloads и публичных границ Host API.
+
 ## Инициализация MCP-конфига
 
 Пакет также может сам добавить project-level MCP-настройки в целевой проект:

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { fileURLToPath } from 'node:url'
 import fs from 'node:fs'
 import path from 'node:path'
 import process from 'node:process'
@@ -13,6 +14,8 @@ const README_MCP_SECTION_HEADER = '## MCP For AI Assistants: @retailcrm/embed-ui
 const LEGACY_README_MCP_SECTION_HEADER = '## MCP For AI Assistants'
 const README_MCP_MARKER = 'embed-ui-v1-endpoint://targets'
 const MCP_SERVER_NAME = 'retailcrm-embed-ui-v1-endpoint'
+const SKILL_NAME = 'embed-ui-v1-endpoint-runtime'
+const SKILL_TEMPLATE_PATH = `templates/skills/${SKILL_NAME}/SKILL.md.txt`
 const MCP_BIN_NAME = process.platform === 'win32' ? 'embed-ui-v1-endpoint-mcp.cmd' : 'embed-ui-v1-endpoint-mcp'
 const RELATIVE_MCP_BIN_PATH = `./node_modules/.bin/${MCP_BIN_NAME}`
 const CLAUDE_PROJECT_MCP_BIN_PATH = `\${CLAUDE_PROJECT_DIR:-.}/node_modules/.bin/${MCP_BIN_NAME}`
@@ -49,6 +52,7 @@ const MCP_CLIENT_CONFIGS = {
 const HELP_TEXT = `Usage:
   npx ${PACKAGE_NAME} init-agents [target] [options]
   npx ${PACKAGE_NAME} init-config [target] [options]
+  npx ${PACKAGE_NAME} init-skills [target] [options]
 
 Options:
   -f, --force                  Replace existing managed sections and MCP server entries
@@ -58,6 +62,7 @@ Options:
 
 Examples:
   npx ${PACKAGE_NAME} init-agents
+  npx ${PACKAGE_NAME} init-skills
   npx ${PACKAGE_NAME} init-agents ./my-project
   npx ${PACKAGE_NAME} init-agents --force
   npx ${PACKAGE_NAME} init-config ./my-project
@@ -75,6 +80,10 @@ const printMcpNotice = (message) => {
   console.log(`MCP: ${message}`)
 }
 
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+
+const createSkill = () => fs.readFileSync(path.join(packageRoot, SKILL_TEMPLATE_PATH), 'utf8')
+
 const parseArgs = (argv) => {
   const options = {
     command: null,
@@ -457,6 +466,35 @@ const initAgents = (target, force) => {
   console.log(`The ${PACKAGE_NAME} instructions were appended to the end of the file.`)
 }
 
+const initSkills = (target, options) => {
+  if (!fs.existsSync(target)) {
+    throw new Error(`Target path does not exist: ${target}`)
+  }
+
+  const stat = fs.statSync(target)
+
+  if (!stat.isDirectory()) {
+    throw new Error(`Target path is not a directory: ${target}`)
+  }
+
+  const skillPath = path.join(target, '.agents', 'skills', SKILL_NAME, 'SKILL.md')
+  const fileExists = fs.existsSync(skillPath)
+
+  if (fileExists && !options.force) {
+    console.log(`${skillPath} already exists`)
+    console.log('Nothing was changed. Re-run with --force to refresh that skill.')
+    return
+  }
+
+  if (!options.dryRun) {
+    fs.mkdirSync(path.dirname(skillPath), { recursive: true })
+    fs.writeFileSync(skillPath, createSkill(), 'utf8')
+  }
+
+  const action = fileExists ? 'updated' : 'created'
+  console.log(`SKILL: ${options.dryRun ? `would ${action}` : action} ${skillPath}`)
+}
+
 const writeMcpServerConfig = (target, relativePath, rootField, options, serverConfig) => {
   const filePath = path.join(target, relativePath)
   const fileExists = fs.existsSync(filePath)
@@ -573,6 +611,11 @@ const main = () => {
       return
     }
 
+    if (options.command === 'init-skills') {
+      initSkills(options.target, options)
+      return
+    }
+
     throw new Error(`Unknown command: ${options.command}`)
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error))

package/docs/define-page-runner.md

@@ -45,6 +45,22 @@ const pageRunner = definePageRunner({
 
 Если для `code` нет раннера, будет warning в консоль и noop-destroy.
 
+## Runtime-проверка страницы
+
+После первого минимального vertical slice проверяйте страницу внутри CRM host, а не только через build/lint.
+
+Минимальный чек:
+
+- manifest или publish payload содержит page descriptor object с `code`, `menu`, `menuItemTitle` и нужной
+  hierarchy metadata;
+- `code` в `pages[]` совпадает с ключом runner map в `definePageRunner`;
+- локальный dev server отдает `entrypoint` и `stylesheet` URL, которые указаны в extension config;
+- пункт меню появился в CRM и открывает route `/modules/<module-code>/<page-code>`;
+- frontend реально смонтировался в CRM host.
+
+Если ошибка видна только в minified bundle, соберите или отдайте dev bundle без минификации до изменения кода
+по догадке.
+
 ## `beforeMount`
 
 `beforeMount` вызывается после `app.use(pinia)` и до `app.mount(...)`.

package/docs/layout.md

@@ -31,6 +31,8 @@
 - Для контентных подложек базовое правило такое:
   - отступ от верхнего края подложки: `24px`;
   - отступы от левого, правого и нижнего края: `32px`.
+- Эти отступы относятся к белой контентной подложке, а не к корневому wrapper страницы.
+- Корневой wrapper страницы не должен дублировать padding подложки; внешнюю рамку страницы задаёт CRM host layout.
 - Между смысловыми блоками оставляйте заметную дистанцию, а не склеивайте их.
 
 ### Заголовок страницы
@@ -65,6 +67,7 @@
 
 - Основной контент страницы обычно расположен на белых подложках.
 - Подложка должна собирать один смысловой блок, а не случайный набор элементов.
+- Padding `24px 32px 32px` ставится на саму подложку с контентом, а не на общий wrapper страницы.
 - Если на экране есть несколько независимых смысловых секций, предпочтительнее использовать несколько подложек, чем одну перегруженную.
 
 ## 1. Страница со списком сущностей
@@ -103,6 +106,8 @@
 
 - Таблица является главным содержимым списка.
 - Она может листаться, пагинироваться и поддерживать выгрузку.
+- `UiTable` не нужно заворачивать в дополнительную белую подложку: таблица сама задаёт табличную поверхность, границы и внутренние отступы.
+- Wrapper вокруг таблицы допустим только как layout/scroll/width container без собственной белой карточки и без padding подложки.
 - Не следует смешивать в одном списочном экране слишком много “карточной” логики; список должен оставаться в первую очередь инструментом поиска и просмотра.
 
 Типичная компонентная основа:
@@ -337,6 +342,7 @@
 4. Нужна ли общая панель сохранения, или каждый блок должен сохраняться отдельно?
 5. Есть ли на странице не больше одного page-level `primary`-действия каждого варианта, а дополнительные `Default Primary` находятся только внутри отдельных `UiCollapseBox`?
 6. Держатся ли отступы и расстояния сетки `4px`?
+7. Не продублирован ли padding контентной подложки на корневом wrapper страницы?
 
 ---
 

package/docs/menu-placements.md

@@ -61,6 +61,48 @@
 `menu: "private_main_menu"` и `parentMenuItemCode: "settings"`. Для страниц в разделе продаж используйте
 `menu: "activity_main_menu"` и соответствующий parent menu item, например `orders`.
 
+CRM также использует hierarchy из `pages[]` для видимой навигации и breadcrumb-like поведения. Сначала
+моделируйте нужную иерархию через `menu`, `parentMenuItemCode` и `menuItemOrdering`; локальные ссылки внутри
+страницы добавляйте только для дополнительной in-page navigation.
+
+## Payload публикации
+
+При обновлении уже установленного расширения синхронизируйте существующий integration module через
+`/api/v5/integration-modules/{code}/edit`, а не создавайте новый инстанс регистрации. В payload страницы
+должны находиться внутри `integrationModule.integrations.embedJs.pages`:
+
+```json
+{
+  "integrationModule": {
+    "clientId": "client-id-xxx",
+    "integrations": {
+      "embedJs": {
+        "entrypoint": "https://example.test/extension/demo/script",
+        "stylesheet": "https://example.test/extension/demo/stylesheet",
+        "runner": "demo",
+        "pages": [
+          {
+            "code": "orders-dashboard",
+            "menu": "activity_main_menu",
+            "parentMenuItemCode": "orders",
+            "menuItemOrdering": 100,
+            "menuItemTitle": {
+              "ru": "Заказы",
+              "en": "Orders",
+              "es": "Pedidos"
+            },
+            "pageHelpLink": null
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+Если локальный API client не знает DTO для расширенного payload, используйте поддержанный custom/request
+method с обычным JSON-объектом вместо добавления локального DTO, который serializer не умеет обрабатывать.
+
 ## Пример справочника меню
 
 Конкретные `placement`, `item code` и `route` нужно брать из host/manifest расширения.
@@ -92,6 +134,11 @@ const pageRunner = definePageRunner({
 Если host откроет страницу с `code`, которого нет в runner map, `definePageRunner` запишет warning
 в консоль и не смонтирует страницу.
 
+После изменения меню или pages manifest проверьте локальную CRM установку: пункт меню должен появиться,
+route `/modules/<module-code>/<page-code>` должен открываться, а `entrypoint` и `stylesheet` из extension
+config должны отдаваться локальным dev server. При runtime-ошибках в minified bundle сначала включите dev
+bundle или sourcemaps.
+
 Читайте также:
 
 - [`page-routes`](./page-routes.md) — как описывать page `code` и CRM-маршрут.

package/docs/page-routes.md

@@ -12,6 +12,10 @@ page `code` нужно описывать объектом manifest `pages[]` с
 строковую форму `pages: ["orders-dashboard"]` для публикации через RetailCRM API: backend ожидает
 `ConfigurationPage` object, а страница без `menu` не откроется по route `/modules/<module-code>/<page-code>`.
 
+Build/lint успех не доказывает, что страница откроется в CRM. После добавления новой страницы проверьте
+runtime lifecycle в host: page descriptor, menu item, route `/modules/<module-code>/<page-code>`,
+доступность `entrypoint` и `stylesheet`, и фактический mount frontend-кода.
+
 ## Что такое `page code`
 
 `page code` — стабильный идентификатор встраиваемой страницы внутри расширения.
@@ -94,6 +98,10 @@ const openSettings = (host: HostApi) => {
 }
 ```
 
+Breadcrumb-like navigation для module pages строится CRM из hierarchy в `pages[]`: `menu`,
+`parentMenuItemCode`, `menuItemOrdering` и связанных metadata. Не собирайте breadcrumbs вручную внутри
+страницы, если продуктовая задача явно не просит локальную in-page navigation.
+
 Читайте также:
 
 - [`menu-placements`](./menu-placements.md) — как связать пункт меню, page `code` и маршрут.

package/package.json

@@ -5,7 +5,7 @@
     "embed-ui-v1-endpoint-mcp": "bin/embed-ui-v1-endpoint-mcp.mjs"
   },
   "type": "module",
-  "version": "0.9.24",
+  "version": "0.9.26",
   "description": "Endpoint API for integrations in RetailCRM",
   "license": "MIT",
   "author": "RetailDriverLLC <integration@retailcrm.ru>",
@@ -85,7 +85,8 @@
     "bin",
     "dist",
     "docs",
-    "README.md"
+    "README.md",
+    "templates"
   ],
   "scripts": {
     "build": "yarn build:docs && yarn build:code && yarn build:mcp && yarn build:meta",
@@ -100,17 +101,17 @@
   "peerDependencies": {
     "@omnicajs/vue-remote": "^0.2.24",
     "@remote-ui/rpc": "^1.4",
-    "@retailcrm/embed-ui-v1-contexts": "^0.9.24",
-    "@retailcrm/embed-ui-v1-types": "^0.9.24",
+    "@retailcrm/embed-ui-v1-contexts": "^0.9.26",
+    "@retailcrm/embed-ui-v1-types": "^0.9.26",
     "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.24",
-    "@retailcrm/embed-ui-v1-contexts": "^0.9.24",
-    "@retailcrm/embed-ui-v1-types": "^0.9.24"
+    "@retailcrm/embed-ui-v1-components": "^0.9.26",
+    "@retailcrm/embed-ui-v1-contexts": "^0.9.26",
+    "@retailcrm/embed-ui-v1-types": "^0.9.26"
   },
   "devDependencies": {
     "@retailcrm/image-preview": "^1.0.2",

package/templates/skills/embed-ui-v1-endpoint-runtime/SKILL.md.txt

@@ -0,0 +1,48 @@
+---
+name: embed-ui-v1-endpoint-runtime
+description: Use when building, editing, or reviewing RetailCRM JS module endpoint wiring with @retailcrm/embed-ui-v1-endpoint. Covers pages, widgets, runners, targets, menu hierarchy, page publishing payloads, and public Host API boundaries.
+---
+
+# Embed UI v1 Endpoint Runtime
+
+Use this skill before changing JS module endpoint wiring, page registration, widget targets, or Host API navigation.
+
+## Reading order
+
+1. Read project `AGENTS.md` if it exists.
+2. Read `./node_modules/@retailcrm/embed-ui-v1-endpoint/README.md`.
+3. Read `./node_modules/@retailcrm/embed-ui-v1-endpoint/docs/README.md`.
+4. Read the relevant endpoint docs:
+   - `docs/define-runner.md`
+   - `docs/define-page-runner.md`
+   - `docs/define-widget-runner.md`
+   - `docs/page-routes.md`
+   - `docs/menu-placements.md`
+   - `docs/targets.md`
+5. If MCP resources are available, read `embed-ui-v1-endpoint://targets` and then the target profile for the target being changed.
+6. If MCP is not available, use `./node_modules/@retailcrm/embed-ui-v1-endpoint/docs/targets/*.yml` as fallback.
+
+## Workflow
+
+1. Identify whether the task is a page, widget, or shared endpoint runner change.
+2. For pages, keep the runtime runner map and extension config page descriptors aligned by page `code`.
+3. For widgets, choose the exact target from endpoint docs or MCP resources before writing UI.
+4. Use documented public entrypoints such as `@retailcrm/embed-ui-v1-endpoint/remote`; do not import from `dist/*`, source files, or repository-only paths.
+5. Keep widget inline UI compact; use component package widget composition guidance for UI mounted into CRM targets.
+6. After the first page vertical slice, verify it in the CRM host: menu item, `/modules/<moduleCode>/<pageCode>` route, entrypoint URL, stylesheet URL, and actual frontend mount.
+7. If a runtime error appears only in a minified bundle, switch to a dev bundle or sourcemaps before guessing.
+
+## Page and menu checks
+
+- Published page descriptors must be objects, not string page codes.
+- Page descriptors need `code`, `menu`, and usually `menuItemTitle`.
+- Use `parentMenuItemCode` and `menuItemOrdering` to model the intended CRM page/menu hierarchy.
+- Breadcrumb-like navigation is derived by CRM from the page/menu hierarchy passed in the extension config; do not hand-roll breadcrumbs in the page unless the product task explicitly asks for local in-page navigation.
+- For updating an already installed module, use the existing integration module edit/update flow and put pages under `integrationModule.integrations.embedJs.pages`.
+- Build/lint success does not prove page rendering; check the installed module in the CRM host when page routing or menu placement changed.
+
+## Host API checks
+
+- Use public Host API for location, query state, and navigation.
+- Do not depend on internal endpoint runtime stores or private channel state.
+- Keep route names, page codes, and extension descriptor values documented in the project.