@vc-shell/vc-app-skill 2.7.0-pr398.d8bb4ce → 2.8.0-pr399.6ff7b99

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.7.0-pr398.d8bb4ce",
+  "version": "2.8.0-pr399.6ff7b99",
   "description": "AI coding skill for scaffolding and generating VirtoCommerce Shell applications. Works with Claude Code, OpenCode, Gemini, Codex, Cursor.",
   "bin": "./bin/install.cjs",
   "files": [

package/runtime/VERSION

@@ -1 +1 @@
-2.7.0
+2.8.0

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit 0c25dd4eb on 2026-10-26T12:24:22.743Z
+Synced from framework at commit b57bc2f71 on 2026-10-30T15:31:36.432Z

package/runtime/knowledge/docs/core/composables/useBladeWidgets/index.docs.md

@@ -82,17 +82,89 @@ Inline `useBladeWidgets([...])` is fine for one-off widgets, but extracting beco
 
 ### HeadlessWidgetDeclaration
 
-| Field       | Type                                                     | Required | Description                               |
-| ----------- | -------------------------------------------------------- | -------- | ----------------------------------------- |
-| `id`        | `string`                                                 | Yes      | Unique widget identifier                  |
-| `icon`      | `string`                                                 | Yes      | Icon name (e.g., `"lucide-tag"`)          |
-| `title`     | `string`                                                 | Yes      | i18n key or display title                 |
-| `badge`     | `Ref<number \| string> \| ComputedRef<number \| string>` | No       | Badge counter value                       |
-| `loading`   | `Ref<boolean> \| ComputedRef<boolean>`                   | No       | Show loading indicator                    |
-| `disabled`  | `Ref<boolean> \| boolean`                                | No       | Disable the widget                        |
-| `isVisible` | `ComputedRef<boolean> \| Ref<boolean> \| boolean`        | No       | Toggle visibility                         |
-| `onClick`   | `() => void`                                             | No       | Action when widget is clicked             |
-| `onRefresh` | `() => void \| Promise<void>`                            | No       | Called by `refresh(id)` or `refreshAll()` |
+| Field             | Type                                                     | Required | Description                               |
+| ----------------- | -------------------------------------------------------- | -------- | ----------------------------------------- |
+| `id`              | `string`                                                 | Yes      | Unique widget identifier                  |
+| `icon`            | `string`                                                 | Yes      | Icon name (e.g., `"lucide-tag"`)          |
+| `title`           | `string`                                                 | Yes      | i18n key or display title                 |
+| `badge`           | `Ref<number \| string> \| ComputedRef<number \| string>` | No       | Badge counter value                       |
+| `loading`         | `Ref<boolean> \| ComputedRef<boolean>`                   | No       | Show loading indicator                    |
+| `disabled`        | `Ref<boolean> \| boolean`                                | No       | Disable the widget                        |
+| `isVisible`       | `ComputedRef<boolean> \| Ref<boolean> \| boolean`        | No       | Toggle visibility                         |
+| `onClick`         | `() => void`                                             | No       | Action when widget is clicked             |
+| `onRefresh`       | `() => void \| Promise<void>`                            | No       | Called by `refresh(id)` or `refreshAll()` |
+| `alerts`          | `Ref<IWidgetAlert[]> \| ComputedRef<IWidgetAlert[]>`     | No       | Live alerts shown in the widget popup     |
+| `alertsComponent` | `Component`                                              | No       | Popup content instead of the default rows |
+
+### Alerts
+
+A widget with a non-empty `alerts` list shows a dot on its icon, colored by the highest severity. Hovering the widget (desktop) opens a popup with the alerts; clicking the widget still opens the blade. On touch screens the first tap on a widget with alerts opens the popup, which then has an Open button; a second tap on the widget also opens the blade. Widgets without alerts show no popup.
+
+```typescript
+const alerts = computed<IWidgetAlert[]>(() => (outOfStock.value ? [{ id: "stock", severity: "warning", text: t("OFFERS.OUT_OF_STOCK") }] : []));
+
+useBladeWidgets([{ id: "OffersWidget", icon: "lucide-tag", title: "OFFERS.TITLE", alerts }]);
+```
+
+| `IWidgetAlert` field | Type                                           | Required | Description                       |
+| -------------------- | ---------------------------------------------- | -------- | --------------------------------- |
+| `id`                 | `string`                                       | Yes      | Unique within the widget          |
+| `severity`           | `"info" \| "warning" \| "error" \| "critical"` | Yes      | Drives the dot color and row icon |
+| `text`               | `string`                                       | Yes      | Already translated                |
+| `meta`               | `string`                                       | No       | Secondary line (time, reason)     |
+| `onOpen`             | `() => void`                                   | No       | Called on row click               |
+| `action`             | `{ label: string; run: () => void }`           | No       | Inline action button              |
+
+Alerts are data: compute them from what the widget has loaded, and they stay exactly as long as the problem does. When a push means the data changed, refetch it; the alerts follow, together with the badge. A component widget passes the same `alerts` through `useWidgetTrigger`.
+
+```typescript
+const unread = ref<Message[]>([]);
+const load = async () => {
+  unread.value = await api.searchUnread({ entityId: entityId.value });
+};
+
+// A push for this entity: refetch, and the badge and alerts update together
+useBladeNotifications<MessagePush>({
+  types: ["MessagePushNotification"],
+  filter: (m) => m.entityId === entityId.value,
+  onMessage: load,
+});
+
+const alerts = computed<IWidgetAlert[]>(() => unread.value.map((m) => ({ id: m.id!, severity: "info", text: m.content ?? "", onOpen: openMessenger })));
+useWidgetTrigger({ onRefresh: load, alerts });
+```
+
+Widget alerts are independent from the notification bell: the bell lists notifications, the widget lists what is unresolved in its data.
+
+### Custom popup content
+
+The popup shows one row per alert by default. To draw it yourself (message previews, an offer card), pass `alertsComponent`. The alerts still decide the dot and whether the popup opens; the component decides what it shows. It receives `IWidgetAlertsComponentProps`: the `alerts` and a `close()` to call after it opens a blade.
+
+```vue
+<!-- MessagesPreview.vue -->
+<script setup lang="ts">
+import type { IWidgetAlertsComponentProps } from "@vc-shell/framework";
+defineProps<IWidgetAlertsComponentProps>();
+</script>
+
+<template>
+  <div class="tw-p-3">
+    <p
+      v-for="a in alerts"
+      :key="a.id"
+    >
+      {{ a.meta }}: {{ a.text }}
+    </p>
+    <button @click="close()">Open conversation</button>
+  </div>
+</template>
+```
+
+```typescript
+useWidgetTrigger({ onRefresh: load, alerts, alertsComponent: MessagesPreview });
+```
+
+Keyboard opening moves focus to the first button, link or input in the component, so put the main action first or make it a real `<button>`.
 
 ### Returns
 
@@ -116,14 +188,16 @@ useWidgetTrigger({ onRefresh: loadData });
 
 ### IWidgetTrigger
 
-| Field       | Type                          | Required | Description                                       |
-| ----------- | ----------------------------- | -------- | ------------------------------------------------- |
-| `icon`      | `string`                      | No       | Lucide icon name for dropdown rendering           |
-| `title`     | `string`                      | No       | Display title (fallback: widget's title)          |
-| `badge`     | `Ref<number \| string>`       | No       | Reactive badge value                              |
-| `onClick`   | `() => void`                  | No       | Handler called when widget is clicked in dropdown |
-| `onRefresh` | `() => void \| Promise<void>` | No       | Handler called to refresh widget data             |
-| `disabled`  | `Ref<boolean> \| boolean`     | No       | Disabled state                                    |
+| Field             | Type                          | Required | Description                                           |
+| ----------------- | ----------------------------- | -------- | ----------------------------------------------------- |
+| `icon`            | `string`                      | No       | Lucide icon name for dropdown rendering               |
+| `title`           | `string`                      | No       | Display title (fallback: widget's title)              |
+| `badge`           | `Ref<number \| string>`       | No       | Reactive badge value                                  |
+| `onClick`         | `() => void`                  | No       | Handler called when widget is clicked in dropdown     |
+| `onRefresh`       | `() => void \| Promise<void>` | No       | Handler called to refresh widget data                 |
+| `disabled`        | `Ref<boolean> \| boolean`     | No       | Disabled state                                        |
+| `alerts`          | `Ref<IWidgetAlert[]>`         | No       | Live alerts shown in the widget popup (see above)     |
+| `alertsComponent` | `Component`                   | No       | Popup content instead of the default rows (see above) |
 
 ### How It Works
 

package/runtime/knowledge/docs/core/composables/useToolbar/useToolbar.docs.md

@@ -163,18 +163,40 @@ Avoid wrapping `registerToolbarItem` in an `if (hasAccess(...))` check unless yo
 
 ## Cross-blade toolbar management
 
-All methods accept an optional `targetBladeId` second argument. Pass it to register, update, or clear toolbar items on a blade other than the current one:
+All methods accept an optional `targetBladeId` second argument. Pass it to register, update, or clear toolbar items on a blade other than the current one. The id is the blade instance id (`useBlade().id`), generated when the blade opens:
 
 ```typescript
-// Register a button on a specific child blade
-registerToolbarItem({ id: "child-action", title: "Action", clickHandler: () => {} }, "ChildBlade");
+// Register a button on a specific open blade instance
+registerToolbarItem({ id: "child-action", title: "Action", clickHandler: () => {} }, childBladeId);
 
 // Clear another blade's toolbar
-clearBladeToolbarItems("ChildBlade");
+clearBladeToolbarItems(childBladeId);
 ```
 
 Pass `"*"` as the bladeId to register a global item that appears on every blade.
 
+## Adding a button to another module's blade
+
+A module can add a button to a blade it does not own with `registerExternalToolbarItem()`, the toolbar counterpart of `registerExternalWidget()`. `targetBlades` lists blade names (the `name` from `defineBlade`). The button shows on every open instance of those blades and survives the blades closing:
+
+```typescript
+import { registerExternalToolbarItem } from "@vc-shell/framework";
+
+export default defineAppModule({
+  install() {
+    registerExternalToolbarItem({
+      id: "quality-check",
+      title: "Quality check",
+      icon: "lucide-sparkles",
+      targetBlades: ["Products"],
+      clickHandler: () => runCheck(),
+    });
+  },
+});
+```
+
+The name match is case-insensitive. If the blade registers its own item with the same `id`, the blade's item wins. `registerToolbarItem(item, "Products")` does the same for a single blade.
+
 ## Auto-cleanup control
 
 By default, items registered through `useToolbar()` inside a component setup are cleared when that component unmounts (`autoCleanup: true`). Disable this for items that should persist beyond the registering component:

package/runtime/knowledge/docs/core/composables/useWidgets/useWidgets.docs.md

@@ -51,11 +51,11 @@ None.
 
 ### Additional Exports
 
-| Export                                 | Description                                                                                                                                            |
-| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `provideWidgetService()`               | Creates and provides the widget service via Vue injection. Idempotent -- returns existing service if already provided. Cleans up via `onScopeDispose`. |
-| `registerWidget(widget, bladeId)`      | Global pre-registration. Widgets registered this way are picked up when `provideWidgetService()` creates the service. Use in module `install()`.       |
-| `registerExternalWidget(registration)` | Global pre-registration for cross-module widgets. These widgets are rendered in blades owned by other modules.                                         |
+| Export                                 | Description                                                                                                                                                                                                            |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `provideWidgetService()`               | Creates and provides the widget service via Vue injection. Idempotent -- returns existing service if already provided. Cleans up via `onScopeDispose`.                                                                 |
+| `registerWidget(widget, bladeId)`      | Global pre-registration. Widgets registered this way are picked up when `provideWidgetService()` creates the service. Use in module `install()`. Pass a blade name to show the widget on every instance of that blade. |
+| `registerExternalWidget(registration)` | Global pre-registration for cross-module widgets. These widgets are rendered in blades owned by other modules.                                                                                                         |
 
 <!-- internal:start -->
 
@@ -90,7 +90,7 @@ export default {
         component: markRaw(OrderStatusWidget),
         icon: "fas fa-clipboard-check",
       },
-      "order-details", // blade ID where this widget appears
+      "OrderDetails", // blade name (from defineBlade); the widget appears on every open instance of it
     );
   },
 };
@@ -110,7 +110,7 @@ export default {
   install() {
     registerExternalWidget({
       id: "shipping-tracker",
-      targetBlades: ["order-details"], // target blades from other modules
+      targetBlades: ["OrderDetails"], // blade names from other modules
       component: markRaw(ShippingTracker),
       title: "Shipping",
     });

package/runtime/knowledge/docs/core/plugins/extension-points/extension-points.docs.md

@@ -137,12 +137,18 @@ This means module load order does not matter. Remote modules loaded via Module F
 Components are sorted by `priority` (ascending). Lower numbers render first:
 
 ```typescript
-add({ id: "a", component: A, priority: 20 }); // Renders second
-add({ id: "b", component: B, priority: 10 }); // Renders first
-add({ id: "c", component: C }); // priority=0, renders first (tie)
+add({ id: "a", component: A, priority: 20 }); // Renders third
+add({ id: "b", component: B, priority: 10 }); // Renders second
+add({ id: "c", component: C }); // priority=0, renders first
 ```
 
-Default priority is `0`. Components with the same priority render in registration order.
+Default priority is `0`. Components with the same priority render in registration order. Inside one module that is the order of the `add()` calls. Across modules it is the order the modules install in, which can change between page loads when remote modules load asynchronously. When several modules contribute to one extension point, give each component an explicit `priority`, spaced out (10, 20, 30) so a new component can go in between.
+
+To move a component that another module registered, call `add()` with the same `id` and a new `priority`; the entry is replaced and re-sorted.
+
+!!! note "Toolbar sorts the other way"
+
+    Toolbar items put a higher `priority` first. See [useToolbar](../../composables/useToolbar/).
 
 ### Typed Metadata
 

package/runtime/knowledge/docs/core/services/services.docs.md

@@ -32,16 +32,16 @@ Every service follows the same architecture:
 
 ## Services
 
-| Service                        | Factory                                  | Module-level API                                                                                                          | Key Type                                  |
-| ------------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
-| **MenuService**                | `createMenuService()`                    | `addMenuItem()`, `removeRegisteredMenuItem()`, `setMenuBadge()`, `removeMenuBadge()`, `getMenuBadge()`, `getMenuBadges()` | `MenuItem`                                |
-| **WidgetService**              | `createWidgetService()`                  | `registerWidget()`, `registerExternalWidget()`                                                                            | `IWidget` / `IExternalWidgetRegistration` |
-| **ToolbarService**             | `createToolbarService()`                 | `registerToolbarItem()`                                                                                                   | `IToolbarItem`                            |
-| **DashboardService**           | `createDashboardService({ hasAccess? })` | `registerDashboardWidget()`                                                                                               | `DashboardWidget`                         |
-| **SettingsMenuService**        | `createSettingsMenuService()`            | `addSettingsMenuItem()`                                                                                                   | `ISettingsMenuItem`                       |
-| **AppBarWidgetService**        | `createAppBarWidgetService()`            | `addAppBarWidget()`                                                                                                       | `AppBarWidget`                            |
-| **AppBarMobileButtonsService** | `createAppBarMobileButtonsService()`     | (direct API)                                                                                                              | `AppBarButtonContent`                     |
-| **LanguageService**            | `createLanguageService()`                | (direct API)                                                                                                              | locale strings                            |
+| Service                        | Factory                                  | Module-level API                                                                                                          | Key Type                                            |
+| ------------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| **MenuService**                | `createMenuService()`                    | `addMenuItem()`, `removeRegisteredMenuItem()`, `setMenuBadge()`, `removeMenuBadge()`, `getMenuBadge()`, `getMenuBadges()` | `MenuItem`                                          |
+| **WidgetService**              | `createWidgetService()`                  | `registerWidget()`, `registerExternalWidget()`                                                                            | `IWidget` / `IExternalWidgetRegistration`           |
+| **ToolbarService**             | `createToolbarService()`                 | `registerToolbarItem()`, `registerExternalToolbarItem()`                                                                  | `IToolbarItem` / `IExternalToolbarItemRegistration` |
+| **DashboardService**           | `createDashboardService({ hasAccess? })` | `registerDashboardWidget()`                                                                                               | `DashboardWidget`                                   |
+| **SettingsMenuService**        | `createSettingsMenuService()`            | `addSettingsMenuItem()`                                                                                                   | `ISettingsMenuItem`                                 |
+| **AppBarWidgetService**        | `createAppBarWidgetService()`            | `addAppBarWidget()`                                                                                                       | `AppBarWidget`                                      |
+| **AppBarMobileButtonsService** | `createAppBarMobileButtonsService()`     | (direct API)                                                                                                              | `AppBarButtonContent`                               |
+| **LanguageService**            | `createLanguageService()`                | (direct API)                                                                                                              | locale strings                                      |
 
 ## Usage
 

package/runtime/knowledge/docs/shell/components/change-password/change-password.docs.md

@@ -44,7 +44,7 @@ The `ChangePassword` component renders a `VcPopup` with three validated input fi
 
 ### Validation
 
-- Field-level: `required` and `min:6` rules via vee-validate's `Field` component.
+- Field-level: `required` on every field; `min:6` on the new password and its confirmation only. The current password can be any password the account has (one set before the policy changed, or by an administrator), so it isn't checked against the policy for new passwords; the platform verifies it on save.
 - API-level: `validatePassword()` checks the platform's password policy on each input change.
 - Custom checks: confirms that new password matches confirmation and that the new password differs from the current one.
 - Errors are displayed as `IdentityError` codes mapped to i18n keys: `COMPONENTS.CHANGE_PASSWORD.ERRORS.{code}`.
@@ -64,7 +64,7 @@ The `ChangePassword` component renders a `VcPopup` with three validated input fi
 
 | Field            | Validation                           | Description                                    |
 | ---------------- | ------------------------------------ | ---------------------------------------------- |
-| Current Password | `required`, `min:6`                  | Verifies the user knows their current password |
+| Current Password | `required`                           | Verifies the user knows their current password |
 | New Password     | `required`, `min:6`, platform policy | The desired new password                       |
 | Confirm Password | `required`, `min:6`, must match new  | Confirmation of the new password               |
 

package/runtime/knowledge/docs/ui/components/atoms/vc-widget/vc-widget.docs.md

@@ -111,6 +111,14 @@ Badge values above 99 are automatically displayed as "99+".
 | `--widget-border-radius`        | `8px`                 | Corner radius             |
 | `--widget-focus-ring-color`     | `var(--primary-300)`  | Focus ring color          |
 
+## Alert dot and badge highlight
+
+Inside a blade widget strip, `VcWidget` reads per-widget render state provided by the blade (it renders exactly as before elsewhere):
+
+- **Alert dot**: a small dot on the icon (`.vc-widget__alert-dot--danger|--warning|--info`), coloured from the highest alert severity. The dot itself is `aria-hidden`; the widget gets `aria-haspopup="dialog"`, `aria-expanded` for the alert popup, and an `aria-describedby` text such as "2 need attention".
+- **Badge change highlight**: when `value` changes, the badge pulses for about 1.5s (`.vc-widget__badge--changed`). A first change within 2s of mount counts as the initial load and does not pulse. Only inside a blade; a standalone `VcWidget` never pulses. The pulse is disabled under `prefers-reduced-motion`.
+- **Edit mode**: while the widget layout is being edited, the badge and dot are hidden and clicks are blocked.
+
 ## Accessibility
 
 - Renders with `role="button"` and `tabindex="0"` for keyboard interaction

package/runtime/knowledge/docs/ui/components/molecules/vc-dropdown/vc-dropdown.docs.md

@@ -188,6 +188,21 @@ By default, `padded` is `true`, which adds compact padding and rounded item back
 </VcDropdown>
 ```
 
+### Keeping Content Mounted
+
+By default the panel is unmounted while closed. Set `forceMount` to keep it in the DOM, hidden with `display: none` and `inert`, so content inside it (data loads, subscriptions) stays alive. Outside-click and Escape handling only run while the dropdown is open, and a floating panel is repositioned each time it opens.
+
+```vue
+<VcDropdown v-model="isOpen" force-mount>
+  <template #trigger="{ toggle }">
+    <VcButton @click="toggle">Menu</VcButton>
+  </template>
+  <template #items-container>
+    <LiveStatusList />
+  </template>
+</VcDropdown>
+```
+
 ## Recipes
 
 ### Confirmation Dropdown
@@ -331,6 +346,7 @@ By default, `padded` is `true`, which adds compact padding and rounded item back
 | `autoFocusPanel`      | `boolean`                                      | `true`                          | Focus the panel element when opened                            |
 | `padded`              | `boolean`                                      | `true`                          | Apply compact padding and rounded item backgrounds             |
 | `zIndex`              | `number`                                       | `9300`                          | Z-index for the floating panel                                 |
+| `forceMount`          | `boolean`                                      | `false`                         | Keep the panel content mounted (hidden, inert) while closed    |
 
 ## Events
 
@@ -393,8 +409,8 @@ By default, `padded` is `true`, which adds compact padding and rounded item back
 - Floating positioning uses `useFloatingPosition` (a thin wrapper around `@floating-ui/vue`) with `autoUpdate: true` when `floating` is enabled — the panel recalculates its position on scroll/resize.
 - Teleport target is determined by `useTeleportTarget`. When `floating` is `true`, the panel is teleported to avoid z-index stacking context issues.
 - Keyboard navigation (`ArrowDown`, `ArrowUp`, `Home`, `End`, `Enter`/`Space`, `Escape`) is handled in `onPanelKeydown`. Escape also attaches a document-level listener when the dropdown is open to catch events that bubble past the panel.
-- `syncFocusedIndex` is called on open to pre-focus the active item (via `isItemActive`) or the first item.
-- The `VcDropdownItem` internal sub-component (in `_internal/VcDropdownItem.vue`) is used by `VcBreadcrumbs` for its overflow menu items.
+- `syncFocusedIndex` is called on open to pre-focus the active item (via `isItemActive`) or the first item. That cursor is painted only while the panel is `:focus-visible`, so a mouse-opened menu shows no pre-highlighted item.
+- The `VcDropdownItem` internal sub-component (in `_internal/VcDropdownItem.vue`) is used by `VcBreadcrumbs` for its overflow menu items. Its icon placeholder keeps titles aligned only when some item in the list has an icon or check; a list with none renders no icon gutter.
 - Default `zIndex` is `9300` (matches the CSS custom property `--z-critical-floating-panel`).
 
 <!-- internal:end -->

package/runtime/knowledge/docs/ui/components/organisms/vc-blade/vc-blade.docs.md

@@ -449,6 +449,24 @@ Four variants are available: `danger`, `warning`, `info`, `success`. System bann
 
 On mobile, width is forced to `100%`. When `expanded` is `true`, the blade fills all available space.
 
+## Widgets
+
+Registered widgets (see [`useBladeWidgets`](../../../../core/composables/useBladeWidgets/index.docs.md)) are shown in a strip in the blade header on desktop and in a bottom bar on mobile.
+
+- Clicking a widget always opens its blade.
+- A widget with alerts shows a dot on its icon. Hovering it (desktop), tapping it (touch; the next tap or the popup's Open button opens the blade) or pressing ArrowDown on it shows the alerts popup. Widgets without alerts show no popup. Screen readers hear the alert count on the widget and on the chevron when hidden widgets have alerts.
+- The strip holds up to 5 widgets. The rest go to the dropdown behind the chevron (a sheet on mobile). The chevron is visible whenever it has something to show: hidden widgets or Customize. On an unnamed blade whose widgets all fit the strip there is no chevron.
+- On a narrow blade the strip shows only the widgets that fit, and the rest move to the top of the dropdown until there is room again. The saved layout does not change. The toolbar keeps room for at least its "More" button (`--blade-toolbar-buttons-min-width`, 80px by default). While customizing, the strip shows all its widgets and scrolls.
+- Widgets hidden in the dropdown or sheet stay mounted, so their badges, alerts and refresh keep working.
+
+### Customizing the layout
+
+Choose Customize in the dropdown (sheet on mobile) to edit which widgets are on the blade and in what order: the minus and plus buttons move a widget off or onto the strip (plus is disabled while the strip is full), drag changes the order, and arrow keys reorder the focused widget. Reset restores the default layout, Done leaves edit mode. On desktop, closing the dropdown with Escape or the chevron discards the edit. On mobile, swiping the sheet down saves it like Done.
+
+A widget you remove stays in the dropdown. A strip widget that is not shown right now (hidden on this record, or its module has not loaded yet) keeps its slot, and no other widget takes it. An external widget whose module loads after the blade opened appears as soon as the module registers it. New widgets fill free strip slots until the user customizes the blade; after that they appear in the dropdown.
+
+The layout is stored per blade in `localStorage` under `VC_BLADE_WIDGETS_${bladeName.toUpperCase()}`. Blades without a `name` cannot be customized.
+
 ## Recipes
 
 ### Master-Detail (List + Details)

package/runtime/knowledge/docs/ui/components/organisms/vc-sidebar/vc-sidebar.docs.md

@@ -77,6 +77,7 @@ const open = ref(false);
 | `closeThreshold` | `number`                               | `0.3`             | Swipe fraction of panel height needed to dismiss (bottom).                                  |
 | `draggable`      | `boolean`                              | `false`           | Enable swipe-to-dismiss (bottom only).                                                      |
 | `dragHandle`     | `boolean`                              | `false`           | Show iOS-style drag handle bar.                                                             |
+| `forceMount`     | `boolean`                              | `false`           | Keep the panel content mounted (hidden, inert) while closed.                                |
 
 ## Events
 
@@ -117,6 +118,10 @@ When `trapFocus` is true (default), Tab key cycles through focusable elements in
 
 When `position="bottom"` and `draggable` is true, users can swipe the panel down to dismiss it. The `dragHandle` prop adds a visible handle bar at the top of the panel for better affordance.
 
+### Keeping Content Mounted
+
+By default the panel is unmounted while closed. Set `forceMount` to keep it in the DOM, hidden with `display: none` and `inert`, so content inside it (data loads, subscriptions) stays alive. The overlay, focus trap, scroll lock and Escape handling are active only while `modelValue` is true.
+
 ### Size Presets
 
 | Size   | Width (left/right) | Height (bottom) |