@vc-shell/vc-app-skill 2.0.10 → 2.0.11-pr247.0f1e741

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.0.10",
+  "version": "2.0.11-pr247.0f1e741",
   "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.10
+2.0.11

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit fde3a68db on 2026-06-15T11:34:22.939Z
+Synced from framework at commit f2225cc27 on 2026-06-22T15:40:33.524Z

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

@@ -115,6 +115,6 @@ This results in page names like `[Operations Console] Dashboard` instead of just
 ## Related
 
 - `vue3-application-insights` -- underlying plugin that initializes the Application Insights SDK
-- [useUserManagement](../useUserManagement/useUserManagement.docs.md) -- provides current user context for telemetry enrichment
+- `useUserManagement` -- provides current user context for telemetry enrichment
 - [useErrorHandler](../useErrorHandler/useErrorHandler.docs.md) -- automatically tracks exceptions to Application Insights
 - [useWebVitals](../useWebVitals/useWebVitals.docs.md) -- Core Web Vitals can be piped to Application Insights via a custom callback

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

@@ -103,15 +103,16 @@ Without the generic, `options.value` defaults to `Record<string, unknown> | unde
 
 These are reactive `ComputedRef` values that reflect the current blade's state. Accessing them outside blade context throws a runtime error.
 
-| Property   | Type                                               | Description                                                                                                                                                |
-| ---------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`       | `ComputedRef<string>`                              | The current blade's unique ID within the blade stack                                                                                                       |
-| `param`    | `ComputedRef<string \| undefined>`                 | Route parameter passed when the blade was opened                                                                                                           |
-| `options`  | `ComputedRef<TOptions \| undefined>`               | Additional options object passed to the blade. Type is `Record<string, unknown>` by default; provide a generic to get a typed ref: `useBlade<MyOptions>()` |
-| `query`    | `ComputedRef<Record<string, string> \| undefined>` | URL query parameters scoped to this blade                                                                                                                  |
-| `closable` | `ComputedRef<boolean>`                             | `true` when this blade has a parent (i.e., can be closed)                                                                                                  |
-| `expanded` | `ComputedRef<boolean>`                             | `true` when this blade is the active (rightmost) blade                                                                                                     |
-| `name`     | `ComputedRef<string>`                              | The blade's registered component name                                                                                                                      |
+| Property           | Type                                               | Description                                                                                                                                                                                                                                                                                    |
+| ------------------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`               | `ComputedRef<string>`                              | The current blade's unique ID within the blade stack                                                                                                                                                                                                                                           |
+| `param`            | `ComputedRef<string \| undefined>`                 | Route parameter passed when the blade was opened                                                                                                                                                                                                                                               |
+| `activeChildParam` | `ComputedRef<string \| undefined>`                 | The `param` of the direct child blade opened from this blade (the entity currently shown in the details pane), or `undefined`. Reactive and reload-safe. Bind it to a list table's `:active-item-id` to highlight the open entity's row — it stays correct across reloads, unlike a local ref. |
+| `options`          | `ComputedRef<TOptions \| undefined>`               | Additional options object passed to the blade. Type is `Record<string, unknown>` by default; provide a generic to get a typed ref: `useBlade<MyOptions>()`                                                                                                                                     |
+| `query`            | `ComputedRef<Record<string, string> \| undefined>` | URL query parameters scoped to this blade                                                                                                                                                                                                                                                      |
+| `closable`         | `ComputedRef<boolean>`                             | `true` when this blade has a parent (i.e., can be closed)                                                                                                                                                                                                                                      |
+| `expanded`         | `ComputedRef<boolean>`                             | `true` when this blade is the active (rightmost) blade                                                                                                                                                                                                                                         |
+| `name`             | `ComputedRef<string>`                              | The blade's registered component name                                                                                                                                                                                                                                                          |
 
 #### Navigation Methods (work everywhere)
 
@@ -387,6 +388,30 @@ onDeactivated(() => {
 });
 ```
 
+### Highlight the row of the open child blade
+
+Bind `activeChildParam` to the table's `active-item-id` so the row of the currently open details blade is highlighted — including after a page reload:
+
+```vue
+<script setup lang="ts">
+const { openBlade, activeChildParam } = useBlade();
+
+function onRowClick(e: { data: { id: string } }) {
+  openBlade({ name: "Details", param: e.data.id });
+}
+</script>
+
+<template>
+  <VcDataTable
+    :items="items"
+    :active-item-id="activeChildParam"
+    @row-click="onRowClick"
+  >
+    <!-- columns -->
+  </VcDataTable>
+</template>
+```
+
 ### Error Management
 
 Display or clear error banners on the blade:

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

@@ -200,7 +200,7 @@ const { isMobile } = useResponsive();
 
 ## Migration
 
-See [migration guide #36](../../../../migration/36-use-responsive.md) for automated codemod and manual migration instructions.
+See [migration guide #36](https://github.com/VirtoCommerce/vc-shell/blob/main/migration/36-use-responsive.md) for automated codemod and manual migration instructions.
 
 ## Related
 

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

@@ -167,5 +167,5 @@ trackRequest("my-request-2");
 ## Related
 
 - [`useConnectionStatus`](../useConnectionStatus/useConnectionStatus.docs.md) — offline detection (binary online/offline)
-- [`registerInterceptors`](../../interceptors/index.ts) — the fetch wrapper that calls `trackRequest`/`untrackRequest`
+- [`registerInterceptors`](https://github.com/VirtoCommerce/vc-shell/blob/main/framework/core/interceptors/index.ts) — the fetch wrapper that calls `trackRequest`/`untrackRequest`
 - `notification` from `@shared/components/notifications` — the notification system used to display the warning

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

@@ -173,6 +173,6 @@ async function fetchCustomEndpoint(url: string) {
 
 ## Related
 
-- [useUserManagement](../useUserManagement/useUserManagement.docs.md) -- extended API with sign-in, password reset, token validation (for auth pages)
+- `useUserManagement` -- extended API with sign-in, password reset, token validation (for auth pages)
 - [usePermissions](../usePermissions/) -- permission checks based on user roles
 - `UserDetail` from `@core/api/platform` -- the user detail type returned by the API

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

@@ -207,7 +207,7 @@ store.registerType("CatalogExportCompleted", {
 });
 ```
 
-Custom templates access the notification via `useNotificationContext()` composable — no props needed. See [NotificationTemplate docs](../../shell/components/notification-template/notification-template.docs.md) for template examples.
+Custom templates access the notification via `useNotificationContext()` composable — no props needed. See the `NotificationTemplate` component for template examples.
 
 ### Subscribing in a blade
 

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

@@ -35,7 +35,7 @@ The blade reads its configuration from `options` via `useBlade<AssetsManagerOpti
 | `disabled`     | `boolean?`               | When true, hides upload/delete actions and disables reordering                           |
 | `hiddenFields` | `string[]?`              | Fields to hide in the detail view                                                        |
 
-> **Breaking change:** The old options (`assets`, `loading`, `assetsUploadHandler`, `assetsEditHandler`, `assetsRemoveHandler`) have been removed. Pass a single `manager` instance instead. See [migration guide #32](../../../migration/32-use-assets-manager.md).
+> **Breaking change:** The old options (`assets`, `loading`, `assetsUploadHandler`, `assetsEditHandler`, `assetsRemoveHandler`) have been removed. Pass a single `manager` instance instead. See [migration guide #32](https://github.com/VirtoCommerce/vc-shell/blob/main/migration/32-use-assets-manager.md).
 
 ## Usage
 

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

@@ -376,6 +376,8 @@ For server-side "select all" that includes items not currently visible:
 </VcDataTable>
 ```
 
+> **Opt-in.** The "Select all N items" banner is shown only when you bind `selectAllActive` (via `v-model:selectAllActive` or a one-way `:selectAllActive`). Its default is `undefined`, so a table that passes `totalCount` only for pagination never surfaces the banner.
+
 ```ts
 const allSelected = ref(false);
 
@@ -1030,7 +1032,7 @@ async function loadNextPage() {
 !!! tip "Use unique state keys"
 Every table in your application must have a distinct `state-key`. Two tables sharing the same key will silently overwrite each other's persisted column widths, order, and hidden/shown column lists.
 
-Persist column widths, column order, and column visibility across page reloads. Sort, filters, pagination, selection, and search input are session-scoped — they are deliberately excluded from the persisted state so the blade owns them through its own URL or store:
+Persist column widths, column order, and column visibility across page reloads. Column layout is stored in `localStorage`/`sessionStorage` (keyed by `state-key`). Sort, search, and the current page are persisted separately — to the **URL query** — automatically when the table is rendered inside a URL-addressable blade (see [URL query persistence](#url-query-persistence) below). Selection, column filters, and other transient state are session-scoped and are deliberately excluded from any persistence:
 
 ```vue
 <VcDataTable :items="products" state-key="product-list">
@@ -1063,6 +1065,61 @@ Listen to state events:
 
 > **Tip:** Each table in your application should have a unique `state-key`. If two tables share the same key, they will overwrite each other's persisted state.
 
+### URL query persistence
+
+When a table is rendered inside a URL-addressable blade (a workspace or routable blade whose address appears in the address bar), its sort, search, and current page are persisted to the URL query string. Reloading the page or sharing the link restores that view.
+
+Writing the view state to the URL is automatic — you do not wire it up. Tables outside a blade (or in a blade with no URL) do not persist (no-op). Reading it back on reload is done by the page (see below).
+
+- **Namespacing:** query keys are prefixed with the table's `state-key` if set, otherwise with the blade's URL segment — e.g. `?offers_sort=name:DESC&offers_search=foo&offers_page=2`. Give each table a unique `state-key` when several tables can be visible at once (the same rule as column-layout persistence).
+- **Keys:** `<ns>_sort` (`field:ASC` / `field:DESC`), `<ns>_search`, `<ns>_page` (1-based).
+- **History:** changes use `router.replace`, so they do not add browser-history entries.
+- **Scope:** only sort, search, and page. Column layout still uses `localStorage`/`sessionStorage` (above); column filters and selection are not persisted.
+
+The page reads the persisted values with `useTableQueryState(stateKey)`, seeds its sort/search/page refs in `setup`, and loads once. The table does not push the restored values back into the page, so a reload runs a single request rather than one per restored field.
+
+```ts
+import { ref, watch } from "vue";
+import { useDataTableSort, useTableQueryState, useFunctions } from "@vc-shell/framework";
+
+const PAGE_SIZE = 20;
+const { debounce } = useFunctions();
+const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  initialField: "createdDate",
+  initialDirection: "DESC",
+});
+const searchValue = ref<string>();
+const currentPage = ref(1);
+
+// Restore from the URL, then load once.
+const restored = useTableQueryState("offers_list").read();
+if (restored.sort) {
+  const [field, dir] = restored.sort.split(":");
+  sortField.value = field;
+  sortOrder.value = dir === "DESC" ? -1 : 1;
+}
+if (restored.search) searchValue.value = restored.search;
+if (restored.page) currentPage.value = restored.page;
+
+function load() {
+  return loadItems({
+    sort: sortExpression.value,
+    keyword: searchValue.value || undefined,
+    skip: (currentPage.value - 1) * PAGE_SIZE,
+  });
+}
+
+load();
+watch(searchValue, () => (currentPage.value = 1));
+watch([sortExpression, searchValue, currentPage], debounce(load, 300));
+
+function onPaginationClick(page: number) {
+  currentPage.value = page;
+}
+```
+
+If a blade cannot be reopened on reload (e.g. a non-routable blade, or an intermediate blade that is not on the restored URL path), its table query params have no owner — they are automatically dropped from the URL once the restored blades have mounted, so the address bar never accumulates stale query keys.
+
 ---
 
 ## Row Actions
@@ -1345,15 +1402,15 @@ function onRowRemove(event: { data: Product; index: number; cancel: () => void }
 
 ### Selection
 
-| Prop                 | Type                     | Default | Description                                                                                       |
-| -------------------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------------- |
-| `selection`          | `T \| T[]`               | --      | Selected item(s). Use with `v-model:selection`.                                                   |
-| `selectionMode`      | `"single" \| "multiple"` | --      | Row selection mode.                                                                               |
-| `isRowSelectable`    | `(data: T) => boolean`   | --      | Per-row function to disable selection.                                                            |
-| `compareSelectionBy` | `"equals" \| "field"`    | --      | Compare items by deep equality or by `dataKey` field.                                             |
-| `selectAll`          | `boolean`                | `false` | Enable "select all" header checkbox.                                                              |
-| `selectAllActive`    | `boolean`                | `false` | Whether "select all" (including non-visible items) is active. Use with `v-model:selectAllActive`. |
-| `activeItemId`       | `string`                 | --      | ID of the highlighted row. Use with `v-model:activeItemId`.                                       |
+| Prop                 | Type                     | Default     | Description                                                                                                                                                                                                  |
+| -------------------- | ------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `selection`          | `T \| T[]`               | --          | Selected item(s). Use with `v-model:selection`.                                                                                                                                                              |
+| `selectionMode`      | `"single" \| "multiple"` | --          | Row selection mode.                                                                                                                                                                                          |
+| `isRowSelectable`    | `(data: T) => boolean`   | --          | Per-row function to disable selection.                                                                                                                                                                       |
+| `compareSelectionBy` | `"equals" \| "field"`    | --          | Compare items by deep equality or by `dataKey` field.                                                                                                                                                        |
+| `selectAll`          | `boolean`                | `false`     | Enable "select all" header checkbox.                                                                                                                                                                         |
+| `selectAllActive`    | `boolean`                | `undefined` | "Select all" (including non-visible items) active state. Binding it (e.g. `v-model:selectAllActive`) opts the table into the cross-page "Select all N items" banner; left unbound, the banner never appears. |
+| `activeItemId`       | `string`                 | --          | ID of the highlighted row. Use with `v-model:activeItemId`.                                                                                                                                                  |
 
 ### Sorting
 

package/runtime/knowledge/docs/ui/composables/useDataTablePagination.docs.md

@@ -29,7 +29,6 @@ import { useDataTablePagination } from "@vc-shell/framework";
 const pagination = useDataTablePagination({
   pageSize: 20,
   totalCount: computed(() => searchResult.value?.totalCount ?? 0),
-  onPageChange: ({ skip }) => loadItems({ ...searchQuery.value, skip }),
 });
 ```
 
@@ -37,6 +36,8 @@ const pagination = useDataTablePagination({
 <VcDataTable :items="items" :total-count="pagination.totalCount" :pagination="pagination" @pagination-click="pagination.goToPage" />
 ```
 
+> **Note:** Let `@pagination-click` only update the page (`goToPage`) and load from one watcher that reads `pagination.skip` together with sort and search — see the recipe below. `onPageChange` (load on each page change) still works for simple tables, but do not combine it with that watcher or the page loads twice.
+
 ## API
 
 ### Parameters (Options)
@@ -49,15 +50,16 @@ const pagination = useDataTablePagination({
 
 ### Returns (`reactive()` object)
 
-| Property      | Type                     | Description                                   |
-| ------------- | ------------------------ | --------------------------------------------- |
-| `currentPage` | `number`                 | Current 1-based page number (writable)        |
-| `pages`       | `number` (readonly)      | Total number of pages                         |
-| `skip`        | `number` (readonly)      | Current skip offset for API calls             |
-| `pageSize`    | `number` (readonly)      | Resolved page size                            |
-| `totalCount`  | `number` (readonly)      | Resolved total item count                     |
-| `goToPage`    | `(page: number) => void` | Navigate to page; fires `onPageChange`        |
-| `reset`       | `() => void`             | Reset to page 1; does NOT fire `onPageChange` |
+| Property      | Type                     | Description                                                             |
+| ------------- | ------------------------ | ----------------------------------------------------------------------- |
+| `currentPage` | `number`                 | Current 1-based page number (writable)                                  |
+| `pages`       | `number` (readonly)      | Total number of pages                                                   |
+| `skip`        | `number` (readonly)      | Current skip offset for API calls                                       |
+| `pageSize`    | `number` (readonly)      | Resolved page size                                                      |
+| `totalCount`  | `number` (readonly)      | Resolved total item count                                               |
+| `goToPage`    | `(page: number) => void` | Navigate to page; fires `onPageChange`                                  |
+| `setPage`     | `(page: number) => void` | Seed the page WITHOUT firing `onPageChange` — use for pull-restore seed |
+| `reset`       | `() => void`             | Reset to page 1; does NOT fire `onPageChange`                           |
 
 All properties are auto-unwrapped by `reactive()` — no `.value` access needed in script or template.
 
@@ -65,30 +67,43 @@ All properties are auto-unwrapped by `reactive()` — no `.value` access needed
 
 ```vue
 <script setup lang="ts">
-import { ref, computed } from "vue";
-import { useDataTablePagination, useDataTableSort } from "@vc-shell/framework";
+import { ref, computed, watch } from "vue";
+import { useDataTablePagination, useDataTableSort, useTableQueryState } from "@vc-shell/framework";
 
 // Data layer
 const searchResult = ref<{ results: Item[]; totalCount: number }>();
-const searchQuery = ref({ take: 20, skip: 0 });
 
-async function loadItems(query?: Partial<typeof searchQuery.value>) {
-  searchQuery.value = { ...searchQuery.value, ...query };
-  searchResult.value = await api.search(searchQuery.value);
+async function loadItems(query: { sort?: string; keyword?: string; skip?: number }) {
+  searchResult.value = await api.search({ take: 20, ...query });
 }
 
-// Pagination state
+// State only — no self-loading callback.
 const pagination = useDataTablePagination({
   pageSize: 20,
   totalCount: computed(() => searchResult.value?.totalCount ?? 0),
-  onPageChange: ({ skip }) => loadItems({ skip }),
 });
-
-// Sort state
 const { sortField, sortOrder, sortExpression } = useDataTableSort({
   initialField: "createdDate",
   initialDirection: "DESC",
 });
+const searchValue = ref<string>();
+
+// Restore from the URL, then load once. setPage seeds the page without loading.
+const restored = useTableQueryState("product-list").read();
+if (restored.sort) {
+  const [field, dir] = restored.sort.split(":");
+  sortField.value = field;
+  sortOrder.value = dir === "DESC" ? -1 : 1;
+}
+if (restored.search) searchValue.value = restored.search;
+if (restored.page) pagination.setPage(restored.page);
+
+// One loader reading sort + search + page.
+watch(
+  () => ({ sort: sortExpression.value, keyword: searchValue.value || undefined, skip: pagination.skip }),
+  (query) => loadItems(query),
+  { immediate: true },
+);
 </script>
 
 <template>
@@ -97,6 +112,12 @@ const { sortField, sortOrder, sortExpression } = useDataTableSort({
     :total-count="pagination.totalCount"
     :pagination="pagination"
     @pagination-click="pagination.goToPage"
+    @search="
+      (kw) => {
+        searchValue = kw;
+        pagination.setPage(1);
+      }
+    "
     v-model:sort-field="sortField"
     v-model:sort-order="sortOrder"
   >
@@ -130,7 +151,6 @@ export function useOffers() {
   const pagination = useDataTablePagination({
     pageSize: 20,
     totalCount: computed(() => searchResult.value?.totalCount ?? 0),
-    onPageChange: ({ skip }) => loadOffers({ ...searchQuery.value, skip }),
   });
 
   return {
@@ -141,7 +161,7 @@ export function useOffers() {
 }
 ```
 
-Blade then simply binds:
+The blade owns the single loader watch (reading `pagination.skip` with sort/search) and binds:
 
 ```vue
 <VcDataTable :total-count="pagination.totalCount" :pagination="pagination" @pagination-click="pagination.goToPage" />
@@ -150,7 +170,8 @@ Blade then simply binds:
 ## Details
 
 - **`reactive()` return**: The composable wraps its return in `reactive()`, so all `Ref`/`ComputedRef` properties are auto-unwrapped. Access with `pagination.pages` (not `pagination.pages.value`). This allows the object to be passed directly as `:pagination` prop to VcDataTable without intermediate conversion.
-- **Event callback, not load**: `onPageChange` is an event notification (like VueUse's `useOffsetPagination`). The composable does not know about data fetching — it just notifies.
+- **Event callback, not load**: `onPageChange` is an event notification (like VueUse's `useOffsetPagination`). The composable does not fetch data. With a single loader watcher you usually omit it and read `pagination.skip` from the watcher instead.
+- **`setPage` vs `goToPage`**: `goToPage(n)` updates the page and fires `onPageChange`; `setPage(n)` updates it without the callback. Use `setPage` to seed the page from a URL restore so the seed itself does not load.
 - **No auto-clamp**: When `totalCount` decreases (e.g. after deletion), `currentPage` is NOT automatically clamped. Call `reset()` or `goToPage(1)` explicitly after mutations.
 - **reset() is silent**: `reset()` sets `currentPage = 1` but does NOT fire `onPageChange`. This prevents accidental double-fetches when the consumer resets pagination during a reload.
 - **Pure without callback**: Omit `onPageChange` and the composable works as pure state — useful for unit tests or when the consumer prefers to watch properties reactively.

package/runtime/knowledge/docs/ui/composables/useDataTableSort.docs.md

@@ -84,14 +84,16 @@ const { sortField, sortOrder, sortExpression, resetSort } = useDataTableSort({
 
 const items = ref([]);
 const loading = ref(false);
+const currentPage = ref(1);
+const PAGE_SIZE = 20;
 
-async function loadItems() {
+async function loadItems(query: { sort?: string; skip?: number }) {
   loading.value = true;
   try {
     const response = await api.searchProducts({
-      sort: sortExpression.value, // e.g. "createdDate:DESC" or undefined
-      skip: 0,
-      take: 20,
+      sort: query.sort, // e.g. "createdDate:DESC" or undefined
+      skip: query.skip ?? 0,
+      take: PAGE_SIZE,
     });
     items.value = response.results;
   } finally {
@@ -99,8 +101,13 @@ async function loadItems() {
   }
 }
 
-// Reload whenever sort changes; { immediate: true } loads data on mount
-watch(sortExpression, () => loadItems(), { immediate: true });
+// Load from one watcher that reads sort together with search and page, so changing
+// several at once is a single request. { immediate: true } also does the first load.
+watch(
+  () => ({ sort: sortExpression.value, skip: (currentPage.value - 1) * PAGE_SIZE }),
+  (query) => loadItems(query),
+  { immediate: true },
+);
 </script>
 
 <template>
@@ -134,12 +141,13 @@ watch(sortExpression, () => loadItems(), { immediate: true });
 - **Sort expression format**: `sortExpression` returns `"field:DIRECTION"` when both `sortField` and a non-zero `sortOrder` are set, otherwise `undefined`. This format is directly compatible with VirtoCommerce Platform search endpoints.
 - **Reset behavior**: `resetSort()` restores `sortField` and `sortOrder` to the values passed at construction time. If no initial options were provided, both are cleared.
 - **Numeric order convention**: `VcDataTable` uses PrimeVue's numeric sort order convention (`1`/`-1`/`0`). This composable encapsulates the mapping so call sites never need to handle the numeric values directly.
-- **Stateless regarding data**: The composable only manages the sort field and direction. Combine it with your own data-fetching logic using `watch(sortExpression, ...)`.
+- **Stateless regarding data**: The composable only manages the sort field and direction. Read `sortExpression` from the same loader watcher that reads search and page, instead of giving sort its own `watch(sortExpression, load)`. See VcDataTable → URL query persistence.
 
 ## Tips
 
 - Always mark columns as `sortable` in your `<VcColumn>` definitions for the sort indicator icon to appear.
-- Use `{ immediate: true }` on the `watch(sortExpression, ...)` call to trigger the initial data load with the correct sort on mount.
+- Use `{ immediate: true }` on the combined loader watcher to trigger the initial (or URL-restored) data load with the correct sort on mount.
+- On reload, seed `sortField`/`sortOrder` from `useTableQueryState(stateKey).read().sort` (`"field:DIR"`) before the loader watcher, so restore costs a single request.
 - Call `resetSort()` alongside any "clear all filters" action to keep sort state consistent with the rest of the filter UI.
 
 ## Related

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

@@ -1,34 +0,0 @@
----
-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

@@ -1,184 +0,0 @@
----
-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

@@ -1,117 +0,0 @@
----
-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

@@ -1,150 +0,0 @@
----
-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

@@ -1,113 +0,0 @@
----
-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/modules/assets/assets-details.docs.md

@@ -1,123 +0,0 @@
----
-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

@@ -1,33 +0,0 @@
----
-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.