@vc-shell/vc-app-skill 2.0.10 → 2.0.11-pr247.8c6c87f

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.0.10",
+  "version": "2.0.11-pr247.8c6c87f",
   "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/migration-prompts/datatable-migration.md

@@ -11,21 +11,21 @@ Replace the imperative `VcTable` component (columns array, manual sort handlers,
 
 Full prop/event mapping:
 
-| VcTable prop/event         | VcDataTable equivalent                           |
-| -------------------------- | ------------------------------------------------ |
-| `:columns="columns"`       | `<VcColumn>` child components (see RULE 2)       |
-| `:selected-item-id="id"`   | `v-model:active-item-id="id"`                    |
-| `:sort="sortExpression"`   | `v-model:sort-field` + `v-model:sort-order`      |
-| `:multiselect="true"`      | `:selection-mode="'multiple'"`                   |
-| `@selection-changed="fn"`  | `v-model:selection="ref"`                        |
-| `:search-value="val"`      | `:searchable="true"` (internal state)            |
-| `@search:change="fn"`      | `@search="fn"`                                   |
-| `@item-click="fn"`         | `@row-click="fn"` (different signature)          |
-| `@header-click="fn"`       | Remove (sort is declarative via v-model)         |
-| `@scroll:ptr="fn"`         | `:pull-to-refresh="true"` + `@pull-refresh="fn"` |
-| `:pages` + `:current-page` | `:pagination="{ currentPage, pages }"`           |
-| `:active-filter-count`     | Remove (managed by global-filters internally)    |
-| `<!--@vue-generic {T}-->`  | Remove (no longer needed)                        |
+| VcTable prop/event         | VcDataTable equivalent                                                  |
+| -------------------------- | ----------------------------------------------------------------------- |
+| `:columns="columns"`       | `<VcColumn>` child components (see RULE 2)                              |
+| `:selected-item-id="id"`   | `v-model:active-item-id="id"`                                           |
+| `:sort="sortExpression"`   | `v-model:sort-field` + `v-model:sort-order`                             |
+| `:multiselect="true"`      | `:selection-mode="'multiple'"`                                          |
+| `@selection-changed="fn"`  | `v-model:selection="ref"`                                               |
+| `:search-value="val"`      | `v-model:search-value` bound to `useTableSearch({ stateKey? })`         |
+| `@search:change="fn"`      | `@search="fn"` (or drop; use watcher on `searchValue`)                  |
+| `@item-click="fn"`         | `@row-click="fn"` (different signature)                                 |
+| `@header-click="fn"`       | Remove (sort is declarative via v-model)                                |
+| `@scroll:ptr="fn"`         | `:pull-to-refresh="true"` + `@pull-refresh="fn"`                        |
+| `:pages` + `:current-page` | `:pagination="pagination"` from `useDataTablePagination({ stateKey? })` |
+| `:active-filter-count`     | Remove (managed by global-filters internally)                           |
+| `<!--@vue-generic {T}-->`  | Remove (no longer needed)                                               |
 
 **BEFORE:**
 
@@ -310,7 +310,7 @@ The Props interface keeps `columns` — the parent still passes column definitio
 
 ## RULE 3: Sort Composable Replacement
 
-Replace `useTableSort` with `useDataTableSort`. The new composable returns `sortField` and `sortOrder` as separate refs that bind directly to `v-model:sort-field` and `v-model:sort-order`. Remove the `onHeaderClick` handler entirely.
+Replace `useTableSort` with `useDataTableSort`. The new composable returns `sortField` and `sortOrder` as separate refs that bind directly to `v-model:sort-field` and `v-model:sort-order`. Remove the `onHeaderClick` handler entirely. Pass `stateKey` to persist sort to the blade URL (opt-in; omit for no URL persistence).
 
 **BEFORE:**
 
@@ -339,6 +339,7 @@ watch(sortExpression, async () => {
 import { useDataTableSort } from "@vc-shell/framework";
 
 const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  stateKey: "my_list", // optional: persists sort to blade URL
   initialField: "createdDate",
   initialDirection: "DESC",
 });
@@ -684,10 +685,14 @@ Key points:
 - The `@filter` event fires when the user applies filters. The `event.filters` object is keyed by filter `id`, with values matching the selected option values.
 - The active filter count badge is managed internally by VcDataTable — no need for a manual `activeFilterCount` computed.
 
-## RULE 8: Pagination — Manual Calculation → useDataTablePagination
+## RULE 8: Pagination and Search — useDataTablePagination + useTableSearch
 
 Replace manual `pages`/`currentPage` computed properties and `@pagination-click` handlers with the `useDataTablePagination` composable. The composable manages skip/page math internally and returns a reactive pagination object that VcDataTable consumes directly.
 
+Pass `stateKey` to persist the current page to the blade URL (opt-in). The table `state-key` prop is column-layout persistence only and does not control URL query state.
+
+For search, replace a bare `ref("")` with `useTableSearch({ stateKey? })`. The returned `searchValue` ref binds to `v-model:search-value` on VcDataTable. With `stateKey`, the keyword is persisted to the blade URL. Without `stateKey`, it behaves like a plain ref.
+
 **BEFORE (composable):**
 
 ```typescript
@@ -733,6 +738,7 @@ export function useMyList(options?: { pageSize?: number }) {
   });
 
   const pagination = useDataTablePagination({
+    stateKey: "my_list", // optional: persists current page to blade URL
     pageSize,
     totalCount: computed(() => searchResult.value?.totalCount ?? 0),
     onPageChange: ({ skip }) => loadItems({ ...searchQuery.value, skip }),
@@ -778,12 +784,15 @@ const { items, pagination, loadItems, loading } = useMyList();
 - `totalCount`, `pages`, `currentPage` computed from composable return
 - Manual `onPaginationClick` function in blade pages
 - Manual `skip` calculation `(page - 1) * pageSize`
+- Any `useTableQueryPersistence` or `useTableQueryState().read()` calls — URL query persistence is now handled by `stateKey` on the composables
 
 **What to add:**
 
-- `useDataTablePagination` import in composable
+- `useDataTablePagination` import in composable (with optional `stateKey` for URL persistence)
+- `useTableSearch({ stateKey? })` in the blade to replace a bare `ref("")` for search
 - `pagination` object in composable return
 - `:pagination="pagination"` and `@pagination-click="pagination.goToPage"` in template
+- `v-model:search-value="searchValue"` from `useTableSearch` in template
 
 ## Verification