@vc-shell/vc-app-skill 2.0.6-pr235.6e1a779 → 2.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.0.6-pr235.6e1a779",
+  "version": "2.0.7",
   "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.0.6
+2.0.7

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit a3ddbc29a on 2026-05-25T13:00:53.288Z
+Synced from framework at commit 1fb1bd541 on 2026-06-04T07:51:39.317Z

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

@@ -136,6 +136,8 @@ The composable holds an **internal ref** (`_items`) that is the source of truth
 
 This two-way sync avoids reactivity issues when the source is a `WritableComputed` wrapping deeply nested properties (e.g., `item.value.productData.assets`).
 
+**`sortOrder` normalization:** items entering from the source are ordered by their current `sortOrder` (items without one stay stable at the end) and reassigned a clean sequential `sortOrder` (`0..n`). This guarantees every item carries a `sortOrder` for display and reordering even when the source provides them without one. The normalization is idempotent, so it does not loop on the `_sync()` writeback.
+
 ## Types
 
 ### `AssetLike`

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

@@ -62,14 +62,14 @@ None.
 
 ### Returns (`ILanguageService`)
 
-| Property / Method        | Type                                         | Description                                                                                                                                     |
-| ------------------------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `currentLocale`          | `ComputedRef<string>`                        | The currently active locale code (e.g., `"en-US"`, `"de-DE"`).                                                                                  |
-| `setLocale`              | `(locale: string) => void`                   | Switches the application locale. This updates `vue-i18n`'s locale and triggers re-rendering of all translated text.                             |
-| `getLocaleByTag`         | `(localeTag: string) => string \| undefined` | Resolves a locale tag to its display string (e.g., `"en-US"` to `"English (United States)"`). Returns `undefined` if the tag is not recognized. |
-| `resolveCamelCaseLocale` | `(locale: string) => string`                 | Converts a locale code to camelCase format (e.g., `"en-US"` to `"enUs"`). Useful for dynamic property access on objects keyed by locale.        |
-| `getFlag`                | `(language: string) => Promise<string>`      | Fetches a flag image URL for the given language/locale. Returns a promise because flags may be loaded lazily.                                   |
-| `getCountryCode`         | `(language: string) => string`               | Extracts the country code from a language tag (e.g., `"en-US"` to `"US"`, `"de-DE"` to `"DE"`).                                                 |
+| Property / Method        | Type                                         | Description                                                                                                                                                                                                                                                                     |
+| ------------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `currentLocale`          | `ComputedRef<string>`                        | The currently active locale code (e.g., `"en-US"`, `"de-DE"`).                                                                                                                                                                                                                  |
+| `setLocale`              | `(locale: string) => void`                   | Switches the application locale. This updates `vue-i18n`'s locale and triggers re-rendering of all translated text.                                                                                                                                                             |
+| `getLocaleByTag`         | `(localeTag: string) => string \| undefined` | Resolves a locale tag to its native display name. Regional tags stay distinct (e.g., `"en-US"` → `"American English"`, `"en-GB"` → `"British English"`); plain codes resolve to the base native name (`"fr"` → `"Français"`). Returns `undefined` if the tag is not recognized. |
+| `resolveCamelCaseLocale` | `(locale: string) => string`                 | Converts a locale code to camelCase format (e.g., `"en-US"` to `"enUs"`). Useful for dynamic property access on objects keyed by locale.                                                                                                                                        |
+| `getFlag`                | `(language: string) => Promise<string>`      | Fetches a flag image URL for the given language/locale. Returns a promise because flags may be loaded lazily.                                                                                                                                                                   |
+| `getCountryCode`         | `(language: string) => string`               | Extracts the country code from a language tag (e.g., `"en-US"` to `"US"`, `"de-DE"` to `"DE"`).                                                                                                                                                                                 |
 
 ### Additional Exports
 

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

@@ -0,0 +1,34 @@
+---
+title: usePlatformLocaleSync
+category: composables
+group: user
+---
+
+# usePlatformLocaleSync
+
+One-way reactive bridge from the VirtoCommerce platform's locale storage key (`NG_TRANSLATE_LANG_KEY`, set by AngularJS + angular-translate) to the shell's language service.
+
+Call this composable only when the shell runs embedded inside the platform — `useShellBootstrap` invokes it automatically when `options.isEmbedded === true`. In standalone mode the shell owns its own locale via `VC_LANGUAGE_SETTINGS`, and this composable should not be used.
+
+## When to Use
+
+- Never call directly from feature code. This is a framework-internal sync primitive.
+- It is invoked once per `VcApp` mount from `useShellBootstrap`.
+
+## Behaviour
+
+- Reads `localStorage["NG_TRANSLATE_LANG_KEY"]` via VueUse's `useLocalStorage`, which subscribes to `storage` events for cross-tab reactivity.
+- On setup, if the value is non-empty, calls `LanguageService.setLocale(value)`. `setLocale` normalises the value (e.g. `en-US` → `en-us`), falls back to `en` for unsupported locales, updates `vue-i18n`, reconfigures `vee-validate`, and persists to `VC_LANGUAGE_SETTINGS`.
+- On subsequent changes of the platform key, re-applies the value.
+- Skips empty strings (platform clearing the key does not blank the shell locale).
+- Skips values equal to `currentLocale` to avoid redundant re-configuration.
+
+## How It Works
+
+`useLocalStorage("NG_TRANSLATE_LANG_KEY", "")` returns a `Ref<string>` that VueUse keeps in sync with `localStorage` and the DOM `storage` event (which fires in tabs other than the writer). The composable applies the current ref value once synchronously and then registers a `watch` on it; any cross-tab mutation flows through the ref into `setLocale`.
+
+The watcher is bound to the active effect scope (typically `VcApp`'s setup). When `VcApp` unmounts, the watcher stops; `useLocalStorage` cleans up its own `storage` listener.
+
+## Relationship to `VC_LANGUAGE_SETTINGS`
+
+The sync is strictly one-directional. `setLocale` writes to `VC_LANGUAGE_SETTINGS` as a side effect, but this composable never writes to `NG_TRANSLATE_LANG_KEY`. In embedded mode the in-shell `LanguageSelector` is unreachable (it lives inside `UserDropdownButton`, which is hidden when `isEmbedded` is `true`), so there is no competing writer from the shell side.

package/runtime/knowledge/docs/core/notifications/composables/useBladeNotifications.docs.md

@@ -0,0 +1,184 @@
+---
+title: useBladeNotifications
+category: composables
+group: notifications
+---
+
+# useBladeNotifications
+
+Subscribes a blade to one or more push-notification types from the platform's SignalR stream. The composable returns a reactive list of matching unread messages, an unread count, and a `markAsRead` action. The subscription is bound to the current effect scope, so it disappears the moment the blade closes — no manual unsubscribe.
+
+This is the **Level 2** entry point in the notification system. Level 1 — `defineAppModule({ notifications })` — registers types globally with their toast configuration and is the always-on path. Level 2 layers blade-specific behavior on top of that: refresh a list, update a progress UI, mark a job complete.
+
+## When to use
+
+- A list blade needs to refresh when an entity is created, updated, or deleted elsewhere.
+- A long-running operation has a dedicated blade and the blade should update as `processedCount` / `errorCount` flow in.
+- A blade wants to surface an inline "N new" badge for messages of a specific type.
+- When NOT to use: app-wide toasts already come from the Level 1 module config — the blade does not need to subscribe just to show a toast. Reach for the blade subscription only when you also need to _react_ to the event in code.
+
+## Quick Start
+
+```ts
+import { useBladeNotifications } from "@vc-shell/framework";
+
+useBladeNotifications({
+  types: ["OfferDeletedDomainEvent"],
+  onMessage: () => reload(),
+});
+```
+
+That is the full recipe for "refresh this list when an offer is deleted somewhere in the app." The handler runs once per matching message; the framework cleans up the subscription when the blade unmounts.
+
+## API
+
+### Parameters
+
+```typescript
+interface BladeNotificationOptions<T extends PushNotification = PushNotification> {
+  types: string[];
+  filter?: (msg: T) => boolean;
+  onMessage?: (msg: T) => void;
+}
+```
+
+| Field       | Type                  | Required | Description                                                                                             |
+| ----------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------- |
+| `types`     | `string[]`            | Yes      | Notification types to subscribe to. Must match the `notifyType` field on incoming messages.             |
+| `filter`    | `(msg: T) => boolean` | No       | Narrow the subscription further (for example, only events for the entity this blade is editing).        |
+| `onMessage` | `(msg: T) => void`    | No       | Callback fired once per matching message. Use it to refresh data, mark progress, or update local state. |
+
+### Returns
+
+```typescript
+interface BladeNotificationReturn<T extends PushNotification = PushNotification> {
+  messages: ComputedRef<T[]>;
+  unreadCount: ComputedRef<number>;
+  markAsRead: (msg: T) => void;
+}
+```
+
+| Property      | Type                  | Description                                                                                                             |
+| ------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `messages`    | `ComputedRef<T[]>`    | Realtime messages matching `types` and `filter` that are still unread. Updates reactively as new messages arrive.       |
+| `unreadCount` | `ComputedRef<number>` | `messages.value.length`. Bind to a badge.                                                                               |
+| `markAsRead`  | `(msg: T) => void`    | Mark a specific message as read. Removes it from `messages` (and reduces the global unread badge in the bell dropdown). |
+
+## Typed payloads
+
+Notification payloads often extend `PushNotification` with domain fields. Pass the type parameter so `onMessage` and `messages` are typed:
+
+```ts
+import type { PushNotification } from "@vc-shell/framework";
+
+interface ImportPushNotification extends PushNotification {
+  jobId: string;
+  profileId: string;
+  profileName?: string;
+  processedCount: number;
+  errorCount: number;
+  finished: boolean;
+}
+
+const { messages, markAsRead } = useBladeNotifications<ImportPushNotification>({
+  types: ["ImportPushNotification"],
+  onMessage: (message) => {
+    if (message.finished) {
+      reload();
+      markAsRead(message);
+    }
+  },
+});
+```
+
+## Common patterns
+
+### Refresh a list on any matching event
+
+```ts
+useBladeNotifications({
+  types: ["OfferDeletedDomainEvent"],
+  onMessage: () => reload(),
+});
+```
+
+Drop-in for a list blade that needs to stay in sync with deletions happening anywhere in the app.
+
+### Filter to the entity this blade owns
+
+```ts
+useBladeNotifications<ImportPushNotification>({
+  types: ["ImportPushNotification"],
+  onMessage: (message) => {
+    if (message.profileId !== param.value) return; // not our job
+    if (!message.finished) updateProgress(message);
+    else finalizeImport(message);
+  },
+});
+```
+
+Two open import blades will both receive the stream; each one filters by its own `profileId` so they do not step on each other.
+
+### Drive a manual progress toast
+
+When the platform sends progress updates for a long-running job, you may want to render one persistent toast that you update as messages arrive — instead of letting Level 1 spawn a new toast per event.
+
+Set the Level 1 type to `silent` and drive the toast yourself:
+
+```ts title="src/modules/import/index.ts"
+defineAppModule({
+  notifications: {
+    ImportPushNotification: { toast: { mode: "silent" } },
+  },
+  // ...
+});
+```
+
+```ts title="pages/import-process.vue"
+import { useBladeNotifications, notification } from "@vc-shell/framework";
+
+let toastId: string | undefined;
+
+useBladeNotifications<ImportPushNotification>({
+  types: ["ImportPushNotification"],
+  onMessage: (message) => {
+    const content = message.profileName ? `${message.profileName}: ${message.title}` : message.title;
+
+    if (!toastId) {
+      toastId = notification(content, { timeout: false });
+    } else if (!message.finished) {
+      notification.update(toastId, { content });
+    } else {
+      notification.update(toastId, {
+        content,
+        timeout: 5000,
+        type: message.errorCount ? "error" : "success",
+        onClose: () => (toastId = undefined),
+      });
+    }
+  },
+});
+```
+
+The `notification()` helper returns the toast id; `notification.update` mutates it in place. The bell-dropdown history still grows — `silent` only suppresses the auto-toast.
+
+## Lifecycle
+
+`useBladeNotifications` calls `useNotificationStore().subscribe(...)` and registers `onScopeDispose(unsub)` against the current effect scope. Inside a Vue `setup()` (component or `<script setup>`) the scope is the component's; the subscription dies with the component.
+
+If you call the composable from a manually managed `effectScope()`, the cleanup runs when that scope is stopped. Calling it outside any scope is a bug — the subscription would never be released.
+
+## Tips
+
+- **Listen, do not declare.** `useBladeNotifications` does not register the notification type with the framework. Types must already be declared by some module via `defineAppModule({ notifications })`, otherwise nothing reaches `onMessage`.
+- **`messages` shows only unread.** `markAsRead(msg)` removes a message from `messages` (and from the global unread count). The notification stays in history.
+- **One subscription per call.** Calling `useBladeNotifications` multiple times in the same blade creates independent subscriptions. Combine handlers if you only need one.
+- **Type strings are case-sensitive.** The string in `types` must exactly equal the `notifyType` field on incoming messages.
+
+## Related
+
+- [useNotificationStore](./useNotificationStore.md) — direct store access for app-shell features (dropdown, badge).
+- [useNotificationContext](./useNotificationContext.md) — read the current notification inside a custom template.
+- [useBroadcastFilter](./useBroadcastFilter.md) — control which `SendSystemEvents` broadcasts reach the store.
+- [Notifications concept page.](../../concepts/notifications.md)
+- [Notifications plugin reference.](../../plugins/notifications.md)

package/runtime/knowledge/docs/core/notifications/composables/useBroadcastFilter.docs.md

@@ -0,0 +1,117 @@
+---
+title: useBroadcastFilter
+category: composables
+group: notifications
+---
+
+# useBroadcastFilter
+
+Controls which **broadcast** push notifications reach the store. The platform SignalR hub delivers messages through two channels: `Send` (targeted to a specific user) and `SendSystemEvents` (broadcast to everyone connected). Broadcasts run through the filter installed here; targeted messages are always accepted.
+
+This is the standard mechanism for scoping a multi-tenant app — show a seller only the broadcasts that mention them, hide events from other tenants. Without a filter every broadcast lands in every user's history.
+
+## When to use
+
+- Multi-tenant apps where the same broadcast topic carries events for different tenants (sellers, organizations, departments) and each user should only see their slice.
+- Apps that want to drop noisy `IndexProgressPushNotification` or similar maintenance events for non-admin roles.
+- When NOT to use: filtering targeted notifications. The platform already delivers `Send` messages only to the addressed user; `useBroadcastFilter` does not see them.
+
+## Quick Start
+
+```ts
+import { useBroadcastFilter, useUser } from "@vc-shell/framework";
+import { onMounted } from "vue";
+
+const { user } = useUser();
+const { setBroadcastFilter } = useBroadcastFilter();
+
+onMounted(() => {
+  setBroadcastFilter((msg) => msg.creator === user.value?.userName);
+});
+```
+
+Install the filter once at app bootstrap (or whenever the active user changes). Every incoming broadcast is run through it; messages that return `false` are dropped before they touch history, toasts, or subscribers.
+
+## API
+
+### Returns
+
+```typescript
+interface UseBroadcastFilterReturn {
+  setBroadcastFilter(fn: (msg: PushNotification) => boolean): void;
+  clearBroadcastFilter(): void;
+}
+```
+
+| Method                 | Type                                           | Description                                                                               |
+| ---------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `setBroadcastFilter`   | `((msg: PushNotification) => boolean) => void` | Install the filter. Replaces any previous filter — there is at most one active at a time. |
+| `clearBroadcastFilter` | `() => void`                                   | Remove the filter. All subsequent broadcasts are accepted.                                |
+
+The filter returns `true` to **accept** a message, `false` to **drop** it.
+
+## Common patterns
+
+### Scope by current user
+
+```ts
+onMounted(() => {
+  setBroadcastFilter((msg) => msg.creator === user.value?.userName);
+});
+```
+
+`creator` is the user that originated the event on the platform side. This is the canonical "show me my own broadcasts" filter in multi-tenant back-office apps.
+
+### Scope by tenant id
+
+```ts
+onMounted(() => {
+  setBroadcastFilter((msg) => (msg as TenantPush).sellerId === currentSellerId.value);
+});
+```
+
+When your broadcast payloads carry a tenant id, gate on it instead of `creator`. The cast clarifies typing without expanding `PushNotification` for every caller.
+
+### Re-install on user switch
+
+```ts
+import { watch } from "vue";
+
+watch(
+  () => user.value?.userName,
+  (name) => {
+    if (!name) clearBroadcastFilter();
+    else setBroadcastFilter((msg) => msg.creator === name);
+  },
+  { immediate: true },
+);
+```
+
+If the app supports user switching without a full reload (impersonation, multi-account), re-install the filter on every change. There is only one slot — installing again replaces the previous filter.
+
+### Drop a noisy type entirely
+
+```ts
+setBroadcastFilter((msg) => msg.notifyType !== "IndexProgressPushNotification");
+```
+
+Broadcast-only suppression. To suppress targeted messages too, set `toast: false` or `toast: { mode: "silent" }` on the type's `defineAppModule({ notifications })` config — that controls the toast surface; the history still records the event.
+
+## Behavior
+
+- The filter applies only to messages ingested with the `broadcast: true` flag (the SignalR `SendSystemEvents` channel).
+- Targeted messages (`Send`) bypass the filter entirely.
+- Installing a filter mid-session does not retroactively prune `history` or `realtime`. Past broadcasts stay; only future ones are filtered.
+- The filter is a single function. To compose multiple predicates, `&&` them inside one callback.
+
+## Tips
+
+- **Install once, early.** Setting the filter in `App.vue` `onMounted` (after authentication) is the canonical placement, so messages arriving before the first blade mounts are already scoped.
+- **Filter exceptions go straight to the console.** If your predicate throws, the message is dropped. Wrap the logic if you are reading off potentially missing fields.
+- **Do not query the store from inside the filter.** The store is `useBroadcastFilter`'s parent — calling back into it during ingestion causes re-entrancy.
+
+## Related
+
+- [useNotificationStore](./useNotificationStore.md) — exposes the same set/clear methods plus the rest of the store API.
+- [useBladeNotifications](./useBladeNotifications.md) — blade-scoped subscription that sees broadcasts after filtering.
+- [Notifications concept page — broadcasts.](../../concepts/notifications.md#broadcast-vs-targeted)

package/runtime/knowledge/docs/core/notifications/composables/useNotificationContext.docs.md

@@ -0,0 +1,150 @@
+---
+title: useNotificationContext
+category: composables
+group: notifications
+---
+
+# useNotificationContext
+
+Reads the current `PushNotification` payload inside a custom notification template. The framework provides the message via Vue's `inject()` from the dropdown or toast surface that hosts the template — the composable returns a reactive `ComputedRef` over it.
+
+This is the one piece you write when a notification type registered with `defineAppModule({ notifications: { Type: { template } } })` needs a richer rendering than the default `NotificationTemplate` chrome — for example, formatting a domain-specific status, deriving a colored accent, or wiring a click handler that opens the relevant blade.
+
+## When to use
+
+- Implementing the `template` component for a notification type registered through `defineAppModule({ notifications })`.
+- Reading typed payload fields (status, entity name, job id) to drive the template's layout, color, or actions.
+- When NOT to use: anywhere outside a notification template. The composable throws if the inject context is not present.
+
+## Quick Start
+
+```vue
+<script lang="ts" setup>
+import { PushNotification, NotificationTemplate, useNotificationContext } from "@vc-shell/framework";
+import { computed } from "vue";
+
+interface IOrderPushNotification extends PushNotification {
+  orderId: string;
+  total: number;
+}
+
+const notificationRef = useNotificationContext<IOrderPushNotification>();
+const notification = computed(() => notificationRef.value);
+</script>
+
+<template>
+  <NotificationTemplate
+    :title="notification.title ?? ''"
+    :notification="notification"
+  >
+    <p>Order {{ notification.orderId }} — ${{ notification.total }}</p>
+  </NotificationTemplate>
+</template>
+```
+
+## API
+
+### Parameters
+
+None. The composable is always called without arguments. Generic type parameter narrows the payload shape:
+
+```typescript
+function useNotificationContext<T extends PushNotification = PushNotification>(): ComputedRef<T>;
+```
+
+### Returns
+
+`ComputedRef<T>` — reactive reference to the current `PushNotification` (or your extended subtype via the generic). Update reactively if the same template instance is reused for a refreshed payload (for example, when a progress message is updated through `notification.update`).
+
+## Common patterns
+
+### Compute display strings from payload fields
+
+```vue
+<script lang="ts" setup>
+import { PushNotification, useNotificationContext, NotificationTemplate } from "@vc-shell/framework";
+import { computed } from "vue";
+import { useI18n } from "vue-i18n";
+
+interface IProductPush extends PushNotification {
+  productName?: string;
+  newStatus?: string;
+}
+
+const ctx = useNotificationContext<IProductPush>();
+const notification = computed(() => ctx.value);
+const { t } = useI18n({ useScope: "global" });
+
+const title = computed(() => (notification.value.productName ? `${t("PRODUCTS.PUSH.PRODUCT")} "${notification.value.productName}" ${t("PRODUCTS.PUSH.UPDATE")}` : (notification.value.title ?? "")));
+</script>
+```
+
+### Open a blade on click
+
+```vue
+<script lang="ts" setup>
+import { useBlade, useNotificationContext, NotificationTemplate } from "@vc-shell/framework";
+import { computed } from "vue";
+
+const { openBlade } = useBlade();
+const ctx = useNotificationContext<IOrderPush>();
+const notification = computed(() => ctx.value);
+
+function onClick() {
+  if (!notification.value.orderId) return;
+  openBlade({ name: "OrderDetails", param: notification.value.orderId });
+}
+</script>
+
+<template>
+  <NotificationTemplate
+    :title="notification.title ?? ''"
+    :notification="notification"
+    @click="onClick"
+  >
+    <p>{{ notification.description }}</p>
+  </NotificationTemplate>
+</template>
+```
+
+`NotificationTemplate` re-emits the click event so the host (dropdown row, toast) can close itself before your handler runs.
+
+### Color the template by status
+
+```ts
+const notificationStyle = computed(() => {
+  switch (notification.value.newStatus) {
+    case "Approved":
+      return { color: "var(--success-400)", icon: "lucide-check-circle" };
+    case "RequestChanges":
+      return { color: "var(--danger-400)", icon: "lucide-alert-circle" };
+    case "WaitForApproval":
+      return { color: "var(--warning-600)", icon: "lucide-clock" };
+    default:
+      return { color: "var(--primary-400)", icon: "lucide-bell" };
+  }
+});
+```
+
+`NotificationTemplate` accepts `:color` and `:icon` props that line up with these computeds — the dropdown row and the toast use the same template, so the styling stays consistent across surfaces.
+
+## Where the template runs
+
+Notification templates render in two places:
+
+- **In the bell dropdown**, as one row in the history list.
+- **As a toast**, when the type's `toast.mode` is `"auto"` or `"progress"` (set the mode to `"silent"` to render only in the dropdown).
+
+The template component must be **the same** in both — register it once on `defineAppModule({ notifications })` and the framework reuses it everywhere.
+
+## Tips
+
+- **Always type the generic.** `useNotificationContext<MyPushType>()` enables autocompletion on payload fields. Without it everything degrades to `PushNotification`.
+- **`computed(() => ctx.value)` is idiomatic** in the example apps because consumers want a regular `Ref` shape to pass into child components and template bindings. Direct access via `ctx.value` is fine too.
+- **Do not subscribe inside a template.** The template renders one message; if you need to react to other notifications, do that in a blade with `useBladeNotifications`.
+
+## Related
+
+- [useBladeNotifications](./useBladeNotifications.md) — subscribe to types inside a blade.
+- [useNotificationStore](./useNotificationStore.md) — access the underlying store.
+- [Notifications concept page.](../../concepts/notifications.md)

package/runtime/knowledge/docs/core/notifications/composables/useNotificationStore.docs.md

@@ -0,0 +1,113 @@
+---
+title: useNotificationStore
+category: composables
+group: notifications
+---
+
+# useNotificationStore
+
+!!! warning "Advanced — most apps do not need this"
+Reach for [useBladeNotifications](./useBladeNotifications.md), [useBroadcastFilter](./useBroadcastFilter.md), and the `notifications` option on `defineAppModule` first. The bell dropdown, unread badge, and toast pipeline are already wired by the shell. This composable is an **escape hatch** for the small set of cases where those facades do not fit.
+
+Returns the singleton store that backs the framework's notification system. Direct access exposes the full reactive state plus low-level actions: subscribing, ingesting synthetic messages, controlling the broadcast filter, paging history.
+
+## When to use
+
+There are only two cases where this composable belongs in app code:
+
+- **A test or scripted harness** that needs to push synthetic messages through the same pipeline SignalR uses, via `ingest`. Real-time production code never calls `ingest` directly.
+- **A custom shell** that replaces the framework's bell dropdown entirely — typically a module-federation host with its own chrome — and therefore needs to bind to `history`, `unreadCount`, and `markAllAsRead` outside the default surface. Apps that use the standard `VcApp` shell do not need this; the dropdown is already there.
+
+For everything else — reacting in a blade, gating broadcasts, registering types, displaying a toast — use the facades. Direct store mutations can bypass invariants the facades enforce (broadcast filter, scope-aware cleanup, type validation).
+
+## Quick Start
+
+```ts
+import { useNotificationStore } from "@vc-shell/framework";
+
+const store = useNotificationStore();
+
+await store.loadHistory(50);
+```
+
+## API
+
+The store exposes the full reactive state plus actions. The shape is summarized below; the underlying types live in `core/notifications/store.ts` and `core/notifications/types.ts`.
+
+| Member                   | Type                                                   | Description                                                                                                                                                                |
+| ------------------------ | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registry`               | `Map<string, NotificationTypeConfig>`                  | Notification types registered through `defineAppModule({ notifications })`.                                                                                                |
+| `history`                | `Ref<PushNotification[]>`                              | Full history (server-loaded plus ingested), newest first.                                                                                                                  |
+| `realtime`               | `Ref<PushNotification[]>`                              | Session-only realtime queue from the SignalR hub. Drives `messages` in `useBladeNotifications`.                                                                            |
+| `unreadCount`            | `ComputedRef<number>`                                  | Count of unread items in `history`. Drives the bell badge.                                                                                                                 |
+| `hasUnread`              | `ComputedRef<boolean>`                                 | Convenience boolean over `unreadCount`.                                                                                                                                    |
+| `registerType(t, cfg)`   | `(string, NotificationTypeConfig) => void`             | Register a type. Called by the framework when `defineAppModule({ notifications })` runs — rarely needed manually.                                                          |
+| `ingest(msg, opts?)`     | `(PushNotification, { broadcast?: boolean }?) => void` | Push a message through the same pipeline SignalR uses. Broadcasts pass through the active broadcast filter.                                                                |
+| `setBroadcastFilter(fn)` | `((PushNotification) => boolean) => void`              | Install a filter for broadcast messages. Prefer [useBroadcastFilter](./useBroadcastFilter.md) — same method.                                                               |
+| `clearBroadcastFilter()` | `() => void`                                           | Remove the broadcast filter.                                                                                                                                               |
+| `markAsRead(msg)`        | `(PushNotification) => void`                           | Mark one message as read. Mirrors to the server.                                                                                                                           |
+| `markAllAsRead()`        | `() => Promise<void>`                                  | Optimistic mark-all with rollback on failure.                                                                                                                              |
+| `loadHistory(take?)`     | `(number?) => Promise<void>`                           | Fetch history from the platform. Default page size is 10. The shell already calls this at bootstrap.                                                                       |
+| `subscribe(opts)`        | `({ types, filter?, handler? }) => () => void`         | Low-level pub/sub. Returns an `unsub` function. Inside blades use [useBladeNotifications](./useBladeNotifications.md) — it wraps this and registers cleanup automatically. |
+| `getByType(type)`        | `(string) => PushNotification[]`                       | Filter `history` by `notifyType`.                                                                                                                                          |
+
+## Escape-hatch patterns
+
+### Manually ingest a message (tests, scripted replay)
+
+```ts
+const store = useNotificationStore();
+
+store.ingest({
+  id: "test-1",
+  notifyType: "OrderCreatedDomainEvent",
+  title: "Test order",
+  isNew: true,
+  created: new Date().toISOString(),
+} as PushNotification);
+```
+
+The ingest pipeline runs the configured toast logic and notifies subscribers exactly like a real SignalR message would, so you can verify the end-to-end behavior of `defineAppModule({ notifications })` + `useBladeNotifications` without a live hub.
+
+`ingest` with `{ broadcast: true }` simulates `SendSystemEvents` and runs the broadcast filter; without it the message is treated as targeted and bypasses the filter.
+
+### Custom shell surface (replace the bell dropdown)
+
+When you are building a shell variant that omits the framework's bell dropdown — for example, a module-federation host that renders its own header — bind to the store directly:
+
+```ts
+import { useNotificationStore } from "@vc-shell/framework";
+import { onMounted } from "vue";
+
+const store = useNotificationStore();
+
+onMounted(() => store.loadHistory(100));
+// Use store.history, store.unreadCount, store.markAllAsRead in your own components.
+```
+
+If you are using `VcApp` (the default shell), do **not** do this — the dropdown is already mounted and binding to the same store, so a second surface duplicates what is already on screen.
+
+## Resolution
+
+`useNotificationStore()` resolves in this order:
+
+1. If called inside a Vue component's `setup` (or `app.runWithContext()`), it uses `inject(NotificationStoreKey)`.
+2. Otherwise it returns a module-level singleton created on first call.
+
+The fallback exists so module-federation remotes and standalone scripts see the same store the host app uses.
+
+## Tips
+
+- **Prefer facades.** Every time you find yourself writing `store.subscribe(...)` inside a blade, you want `useBladeNotifications`. Every time you write `store.setBroadcastFilter(...)`, you want `useBroadcastFilter`. The facades exist to keep cleanup, typing, and invariants in one place.
+- **Do not iterate `realtime` for unread counts inside a blade.** That is what `useBladeNotifications` does correctly. Touching `realtime` directly couples your component to shell internals.
+- **`loadHistory` replaces, then merges.** Calling it again pages in more entries and merges them with the existing history.
+- **`markAllAsRead` is optimistic.** The local state flips immediately; if the server call fails the change is rolled back and an error toast surfaces.
+- **Direct store mutations can bypass invariants.** The broadcast filter only runs through `ingest({ broadcast: true })`. Pushing arrays around `history.value` directly is not supported.
+
+## Related
+
+- [useBladeNotifications](./useBladeNotifications.md) — recommended scope-aware subscription. **Start here.**
+- [useBroadcastFilter](./useBroadcastFilter.md) — broadcast acceptance gate.
+- [useNotificationContext](./useNotificationContext.md) — payload access inside templates.
+- [Notifications concept page.](../../concepts/notifications.md)
+- [Notifications plugin reference.](../../plugins/notifications.md)

package/runtime/knowledge/docs/core/plugins/ai-agent/ai-agent.docs.md

@@ -7,16 +7,15 @@ slug: ai-agent
 
 # AI Agent Plugin
 
-Integrates an AI assistant panel (chatbot iframe) into the vc-shell application. Provides blade-aware context passing, bidirectional postMessage communication, and preview/apply workflows.
+Integrates an AI assistant panel (chatbot iframe) into the vc-shell application. Provides blade-aware context passing and bidirectional postMessage communication.
 
 ## Overview
 
-The AI agent plugin embeds an external chatbot via an iframe panel that slides in from the right side of the application. It automatically sends the current blade context (user, active blade, selected items) to the chatbot and handles incoming commands (navigate, preview changes, download files). The plugin is optional -- if no `APP_AI_AGENT_URL` environment variable or `config.url` is provided, it silently skips installation.
+The AI agent plugin embeds an external chatbot via an iframe panel that slides in from the right side of the application. It automatically sends the current blade context (user, active blade, selected items) to the chatbot and handles incoming commands (navigate, download files). The plugin is optional -- if no `APP_AI_AGENT_URL` environment variable or `config.url` is provided, it silently skips installation.
 
 ## When to Use
 
 - Embed an AI assistant chatbot panel into your vc-shell application with automatic blade context passing
-- Enable preview/apply workflows where AI suggests changes and the user confirms them
 - When NOT to use: if you don't have an AI agent backend -- the plugin silently skips when no `APP_AI_AGENT_URL` is set
 
 ## Installation / Registration
@@ -88,10 +87,7 @@ Binds blade data to the AI agent context. Call this in each blade that should pa
 | `dataRef`     | `Ref<T> \| Ref<T[]>` | Data to send (single object for details, array for list) |
 | `suggestions` | `ISuggestion[]`      | Custom suggestion cards for the chatbot UI               |
 
-| Return                       | Type                    | Description                                      |
-| ---------------------------- | ----------------------- | ------------------------------------------------ |
-| `previewState.isActive`      | `ComputedRef<boolean>`  | Whether AI-suggested changes are being previewed |
-| `previewState.changedFields` | `ComputedRef<string[]>` | List of field names with pending changes         |
+The composable returns `void`. It wires the watcher and the unmount cleanup; nothing is exposed to the caller.
 
 ### PostMessage Protocol
 
@@ -103,12 +99,9 @@ Binds blade data to the AI agent context. Call this in each blade that should pa
 **Chatbot to Shell:**
 
 - `CHAT_READY` -- Chatbot finished loading
-- `NAVIGATE_TO_APP` -- Open a specific blade
-- `PREVIEW_CHANGES` -- Preview data changes in the form
-- `APPLY_CHANGES` -- Apply confirmed changes
-- `RELOAD_BLADE` -- Reload the current blade
-- `DOWNLOAD_FILE` -- Download a file (base64)
-- `CHAT_ERROR` -- Error from chatbot
+- `NAVIGATE_TO_APP` -- Open a specific blade (driven by markdown action links in assistant messages)
+- `EXPAND_IN_CHAT` -- Expand an item inline in the chat (markdown action link)
+- `SHOW_MORE` -- Request the next page of a result category (markdown action link)
 
 ## Usage
 
@@ -117,7 +110,7 @@ Binds blade data to the AI agent context. Call this in each blade that should pa
 ```typescript
 // In a details blade
 const product = ref<Product>({});
-const { previewState } = useAiAgentContext({
+useAiAgentContext({
   dataRef: product,
   suggestions: [{ id: "translate", title: "Translate", icon: "translation", prompt: "Translate to English" }],
 });
@@ -149,17 +142,6 @@ onMessage((message) => {
 });
 ```
 
-### Preview State Visual Feedback
-
-```vue
-<template>
-  <VcInput
-    v-model="product.name"
-    :class="{ 'ai-preview': previewState.changedFields.value.includes('name') }"
-  />
-</template>
-```
-
 ## Related
 
 - `framework/core/plugins/ai-agent/services/ai-agent-service.ts` -- core service factory (`createAiAgentService`)

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

@@ -130,9 +130,7 @@ Plugins can register components **before** the host declares the extension point
 2. Later, host calls `defineExtensionPoint("seller:commissions")` -- the store upgrades the entry to "declared" and preserves all previously registered components.
 3. The host's `components` computed ref reactively picks up the registered components.
 
-This means module load order does not matter. Remote modules loaded via Module Federation may install in any sequence, and extensions still work.
-
-> **Dev warning:** In development mode, if a plugin registers into a point that is never declared, a console warning appears: `Extension point "xyz" is not declared.` This helps catch typos in extension point names.
+This means module load order does not matter. Remote modules loaded via Module Federation may install in any sequence, and extensions still work. Plugins typically register in module `install()` at app startup, while hosts declare lazily when their page mounts -- an undeclared entry in between is a normal, expected state.
 
 ### Priority-Based Sorting
 
@@ -517,7 +515,7 @@ add({ id: "my-fields", component: MyFields });
 // Component is registered but never rendered because the host declared "seller:commissions"
 ```
 
-The dev-mode console warning (`Extension point "seller:comissions" is not declared`) will alert you to this. Always check the console in development.
+There is no console warning for this case -- registering before a host declares the point is a supported flow, so the framework cannot tell a typo apart from a host page that simply has not been opened yet. The most reliable protection is to avoid string literals altogether:
 
 > **Tip:** Define constants for your extension point names in a shared file:
 >

package/runtime/knowledge/docs/modules/assets/assets-details.docs.md

@@ -0,0 +1,123 @@
+---
+title: Assets Module
+category: reference
+group: modules
+slug: assets
+---
+
+# Assets Details Module
+
+A built-in child blade for editing a single asset's metadata: display name, alt text (images only), and description. Opened by `AssetsManager` when the user clicks a table row, but also usable standalone from any parent blade that needs single-asset editing.
+
+## Overview
+
+The blade reads an `AssetLike` instance from `options.asset`, exposes a form pre-populated from it, and delegates persistence back to the caller through two callbacks (`assetEditHandler`, `assetRemoveHandler`). The blade itself never mutates the original asset and never talks to the network — the caller decides what saving and removing means.
+
+The module is registered as `AssetsDetailsModule` and exposes the `AssetsDetails` blade (registered globally under the name `"AssetsDetails"`).
+
+## Module Registration
+
+```typescript
+import { AssetsDetailsModule } from "@vc-shell/framework";
+
+// Registered automatically when the framework loads
+// Exposes: AssetsDetails blade component
+```
+
+## Options (via `useBlade`)
+
+The blade reads its configuration from `options` via `useBlade<AssetsDetailsOptions>()` (not props):
+
+| Option               | Type                                          | Description                                                                                                                                   |
+| -------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `asset`              | `AssetLike`                                   | The asset to edit. The blade clones it into local state — the source object is never mutated until `assetEditHandler` is called.              |
+| `disabled`           | `boolean?`                                    | When true, every input is read-only and the toolbar Save/Delete buttons are disabled.                                                         |
+| `hiddenFields`       | `string[]?`                                   | Field names to hide. Supported values: `"name"`, `"altText"`, `"description"`. The header (preview, size, created date, URL) is always shown. |
+| `assetEditHandler`   | `(asset: AssetLike) => void \| Promise<void>` | Called by the toolbar Save button with the edited copy. The blade closes itself after the handler resolves.                                   |
+| `assetRemoveHandler` | `(asset: AssetLike) => Promise<void>`         | Called by the toolbar Delete button. The blade closes itself after the handler resolves.                                                      |
+
+## Usage
+
+### Direct invocation
+
+```typescript
+import { useBlade } from "@vc-shell/framework";
+
+const { openBlade } = useBlade();
+
+openBlade({
+  name: "AssetsDetails",
+  options: {
+    asset: selectedAsset,
+    disabled: !canEdit.value,
+    hiddenFields: ["altText"],
+    assetEditHandler: async (edited) => {
+      await api.updateAsset(edited);
+    },
+    assetRemoveHandler: async (asset) => {
+      await api.deleteAsset(asset.id);
+    },
+  },
+});
+```
+
+### Used by AssetsManager
+
+When `AssetsManager` opens this blade on row click, it wires the manager's mutation methods into the handlers automatically:
+
+```typescript
+// inside AssetsManager
+openBlade({
+  name: "AssetsDetails",
+  options: {
+    asset,
+    disabled: readonly.value,
+    hiddenFields: options.value?.hiddenFields,
+    assetEditHandler: (asset) => manager.updateItem(asset),
+    assetRemoveHandler: (asset) => manager.remove(asset),
+  },
+});
+```
+
+## Header
+
+The header is always rendered above the editable form and is not configurable through `hiddenFields`:
+
+| Element      | Source                                                                                             |
+| ------------ | -------------------------------------------------------------------------------------------------- |
+| Preview      | `VcImage` thumbnail for image extensions (png/jpg/jpeg/svg/gif), colored extension badge otherwise |
+| Size         | `readableSize(asset.size)` — formatted as `KB`/`MB`/`GB`                                           |
+| Created date | `asset.createdDate` rendered with `type="date-ago"`                                                |
+| URL          | `asset.url` displayed as a copyable link with `asset.name` as the visible label                    |
+
+## Form fields
+
+All fields are bound to a local clone of `asset`. They can be hidden individually via `hiddenFields`.
+
+| Field         | Visibility                                        | Notes                                                                                                                          |
+| ------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `name`        | Hidden if `hiddenFields` includes `"name"`        | Required. Edits the **base name only** — the original extension is preserved on save (e.g. editing `report.pdf` keeps `.pdf`). |
+| `altText`     | Image assets only; hide via `"altText"`           | Plain string. Shown only when `asset.typeId === "Image"`.                                                                      |
+| `description` | Hidden if `hiddenFields` includes `"description"` | Multiline textarea.                                                                                                            |
+
+## Toolbar
+
+| Button | Disabled condition                                                                                                  | Action                                                      |
+| ------ | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| Save   | `disabled === true`, the form is invalid, or the form is not dirty (vee-validate `useIsFormValid`/`useIsFormDirty`) | `await assetEditHandler(editedAsset)`, then `closeSelf()`   |
+| Delete | `disabled === true`                                                                                                 | `await assetRemoveHandler(editedAsset)`, then `closeSelf()` |
+
+## Tips
+
+- **Extension is locked.** The `name` input only edits the base name; the original extension is reattached on save. Renaming `photo.png` to `cover` produces `cover.png`.
+- **Required name validation** uses vee-validate's `required` rule. The Save button stays disabled until validation passes.
+- **`assetEditHandler`** is invoked with the edited clone — the original `options.asset` reference is never mutated. Callers should treat the argument as the new state.
+- **`disabled` makes the blade fully read-only:** inputs are disabled and toolbar Save/Delete are disabled regardless of dirtiness.
+- **`hiddenFields` does not enforce required-ness.** Hiding `"name"` skips the validated `<Field>`, so the Save button only depends on form dirtiness.
+
+## Related
+
+- `framework/modules/assets-manager/` -- parent `AssetsManager` blade that opens `AssetsDetails` on row click
+- `framework/core/composables/useAssetsManager/` -- `AssetLike` type definition
+- `framework/core/utilities/assets.ts` -- `isImage`, `readableSize`, `getExtensionColor`, `getExtensionLabel`
+- `framework/ui/components/molecules/vc-field/` -- `VcField` used by the header for size/date/url

package/runtime/knowledge/docs/shell/dashboard/draggable-dashboard/dashboard-widget-skeleton.docs.md

@@ -0,0 +1,33 @@
+---
+title: DashboardWidgetSkeleton
+category: composables
+group: utilities
+internal: true
+---
+
+# DashboardWidgetSkeleton
+
+Internal placeholder card used by `GridstackDashboard` while remote modules are still loading. Mimics the shape of `DashboardWidgetCard` (header with icon + title, stats row, content lines) with a shimmer animation. Not exported from `@vc-shell/framework` — consumed only inside the dashboard organism.
+
+## When to Use
+
+- You won't use this directly. `GridstackDashboard` renders one per `SkeletonItem` while `ModulesReadyKey` resolves to `false`.
+- If you build a custom dashboard layout and want the same loading aesthetic, copy this file rather than importing it — the component is intentionally internal so the dashboard team can change its markup at any time.
+
+## Layout Contract
+
+The skeleton has no props. Its parent positions it via inline `style` (`grid-column` / `grid-row`) inside a 12-column CSS grid. Card height/width is fully determined by the grid cell it occupies, so the skeleton stretches to fill its slot.
+
+## Accessibility
+
+- The wrapper has `aria-hidden="true"` so screen readers ignore the visual placeholders. The parent grid carries `role="status"` + `aria-busy="true"` to announce loading state once.
+- Shimmer animation is disabled when the user prefers reduced motion.
+
+## Design Tokens
+
+Skeleton inherits dashboard card tokens where possible (`--dashboard-widget-card-background`, `--dashboard-widget-card-border-color`, `--dashboard-widget-card-border-radius`, `--dashboard-widget-card-shadow`) so its silhouette matches the real card. Shimmer colors are read from `--neutrals-100` / `--neutrals-200`.
+
+## Related
+
+- [DraggableDashboard](./draggable-dashboard.docs.md) — owns the skeleton grid and decides when to render placeholders.
+- [DashboardWidgetCard](../dashboard-widget-card/dashboard-widget-card.docs.md) — the real card whose shape skeletons imitate.

package/runtime/knowledge/docs/ui/components/organisms/vc-data-table/composables/table-composables.docs.md

@@ -37,7 +37,7 @@ The composables follow a PrimeVue-inspired pattern: each returns reactive state
 
 | Composable               | Purpose                                                                                                                                                                                                                                                         |
 | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `useTableRowReorder`     | Drag-and-drop row reordering with live-swap at 50% vertical threshold. Commits via `dragend` (always fires) with `drop` as preferred path.                                                                                                                      |
+| `useTableRowReorder`     | Drag-and-drop row reordering via SortableJS (touch + mouse). Dragging is restricted to a handle selector. Commits on SortableJS `onEnd` with `{ dragIndex, dropIndex, value }`. Keeps an optimistic `reorderedItems` buffer until the parent updates `items`.   |
 | `useTableColumnsReorder` | Drag-and-drop column reordering with 50% horizontal threshold. Returns `getReorderHeadProps()` for easy binding.                                                                                                                                                |
 | `useTableColumnsResize`  | Weight-based resize: dragging adjusts the weights of the dragged column and its right neighbor without touching other columns. DOM-based px updates during drag for smooth 60fps; commits new weights to `columnState` on mouseup. No `ResizeObserver` scaling. |
 | `useTableSelectionV2`    | Row selection: single, multiple (checkbox), and row-click modes. Emits `RowSelectEvent` / `RowSelectAllEvent`.                                                                                                                                                  |
@@ -160,7 +160,7 @@ register({
 ### Contributor notes
 
 - `useDataTableState`: Guard against save-during-restore loops with the `isRestoring` flag.
-- `useTableRowReorder`: `event.preventDefault()` in `dragover` MUST be called on every event or `drop` never fires.
+- `useTableRowReorder`: powered by SortableJS with `forceFallback: true` so it works on touch. Dragging is limited to the `handle` selector. The optimistic `reorderedItems`/`pendingReorder` buffer makes Vue the source of DOM truth and hides SortableJS's raw DOM mutation until the parent updates `items`.
 - `useTableColumnsResize` applies DOM-level px changes during drag for 60fps performance, then commits final weights to `columnState` on mouseup. No `ResizeObserver` scaling is involved.
 
 <!-- internal:end -->

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

@@ -641,7 +641,7 @@ When `show-all-columns` is `false`, only `image` and `name` remain visible.
 
 ## Row Reorder
 
-Enable drag-and-drop row reordering with a drag handle column:
+Enable drag-and-drop row reordering. A grip handle appears on the left of each row (desktop) or card (mobile) whenever `reorderable-rows` is enabled, and dragging is initiated from that handle. Reorder works on both desktop and touch devices (powered by SortableJS):
 
 ```vue
 <template>
@@ -678,7 +678,7 @@ function onReorder(event: { dragIndex: number; dropIndex: number; value: Product
 </script>
 ```
 
-> **Tip:** The drag handle column renders a grip icon. Without `row-reorder` on a VcColumn, the entire row is draggable (less precise, but works).
+> **Tip:** Setting `:reorderable-rows="true"` is enough — a grip handle is shown automatically and is the only drag affordance (so row clicks, mobile swipe actions, and long-press selection keep working). A dedicated `:row-reorder` VcColumn is optional and simply reserves an aligned column slot for the handle. On mobile, drag the handle to reorder cards.
 
 ---