@vc-shell/vc-app-skill 2.0.11 → 2.1.0-pr248.6401a93

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.0.11",
+  "version": "2.1.0-pr248.6401a93",
   "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.11
+2.1.0

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit f2225cc27 on 2026-06-22T15:40:33.524Z
+Synced from framework at commit 3a32dc437 on 2026-06-22T17:27:53.738Z

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

@@ -1032,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. 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:
+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 NOT persisted by the table itself -- use the state composables with a matching `stateKey` instead (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">
@@ -1067,58 +1067,78 @@ Listen to state events:
 
 ### 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.
+Sort, search, and the current page are owned by the state composables, not by `VcDataTable`. The `state-key` prop on `VcDataTable` controls column-layout persistence (localStorage/sessionStorage) only.
 
-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).
+To persist query state to the blade URL, use `useDataTableSort`, `useTableSearch`, and `useDataTablePagination` with a matching `stateKey`. Each composable restores its slice from the URL on creation and persists changes via `router.replace` (no history entries added).
 
-- **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.
+- **Namespacing:** URL keys are prefixed with the `stateKey` value -- e.g. `?offers_list_sort=name:DESC&offers_list_search=foo&offers_list_page=2`. Use the same string for all three composables on a given page.
+- **Keys:** `<stateKey>_sort` (`field:ASC` / `field:DESC`), `<stateKey>_search`, `<stateKey>_page` (1-based).
+- **Scope:** sort, search, and page only. Column layout still uses localStorage/sessionStorage; 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.
+Canonical list-page pattern:
 
-```ts
-import { ref, watch } from "vue";
-import { useDataTableSort, useTableQueryState, useFunctions } from "@vc-shell/framework";
+```vue
+<script setup lang="ts">
+import { ref, computed, watch, onMounted } from "vue";
+import { useDataTableSort, useDataTablePagination, useTableSearch } from "@vc-shell/framework";
+
+const STATE_KEY = "offers_list";
 
-const PAGE_SIZE = 20;
-const { debounce } = useFunctions();
 const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  stateKey: STATE_KEY,
   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;
+const { searchValue } = useTableSearch({ stateKey: STATE_KEY });
+
+const searchResult = ref<{ results: Offer[]; totalCount: number }>();
+const totalCount = computed(() => searchResult.value?.totalCount ?? 0);
 
-function load() {
-  return loadItems({
+const pagination = useDataTablePagination({
+  stateKey: STATE_KEY,
+  pageSize: 20,
+  totalCount,
+});
+
+async function load() {
+  searchResult.value = await api.searchOffers({
     sort: sortExpression.value,
-    keyword: searchValue.value || undefined,
-    skip: (currentPage.value - 1) * PAGE_SIZE,
+    keyword: searchValue.value,
+    skip: pagination.skip,
+    take: pagination.pageSize,
   });
 }
 
-load();
-watch(searchValue, () => (currentPage.value = 1));
-watch([sortExpression, searchValue, currentPage], debounce(load, 300));
+onMounted(() => load());
+watch(sortExpression, () => load());
+</script>
 
-function onPaginationClick(page: number) {
-  currentPage.value = page;
-}
+<template>
+  <VcDataTable
+    :items="searchResult?.results ?? []"
+    :total-count="pagination.totalCount"
+    :pagination="pagination"
+    v-model:sort-field="sortField"
+    v-model:sort-order="sortOrder"
+    v-model:search-value="searchValue"
+    @pagination-click="pagination.goToPage"
+    state-key="offers_list"
+  >
+    <VcColumn
+      id="name"
+      header="Name"
+      sortable
+    />
+    <VcColumn
+      id="createdDate"
+      header="Created"
+      sortable
+    />
+  </VcDataTable>
+</template>
 ```
 
-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.
+The `state-key` on `VcDataTable` here persists column layout to localStorage; the `stateKey` passed to the composables persists query state to the URL. Both use the same string value but serve different purposes.
 
 ---
 

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

@@ -29,6 +29,7 @@ import { useDataTablePagination } from "@vc-shell/framework";
 const pagination = useDataTablePagination({
   pageSize: 20,
   totalCount: computed(() => searchResult.value?.totalCount ?? 0),
+  onPageChange: ({ skip }) => loadItems({ ...searchQuery.value, skip }),
 });
 ```
 
@@ -36,30 +37,29 @@ 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)
 
-| Option         | Type                                              | Default     | Description                                      |
-| -------------- | ------------------------------------------------- | ----------- | ------------------------------------------------ |
-| `totalCount`   | `MaybeRefOrGetter<number>`                        | _required_  | Total item count from API response               |
-| `pageSize`     | `MaybeRefOrGetter<number>`                        | `20`        | Items per page                                   |
-| `onPageChange` | `(state: { page: number; skip: number }) => void` | `undefined` | Event callback fired when `goToPage()` is called |
+| Option         | Type                                              | Default     | Description                                                                            |
+| -------------- | ------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------- |
+| `stateKey`     | `string \| undefined`                             | `undefined` | When set, restores and persists the current page to the blade URL query under this key |
+| `totalCount`   | `MaybeRefOrGetter<number>`                        | _required_  | Total item count from API response                                                     |
+| `pageSize`     | `MaybeRefOrGetter<number>`                        | `20`        | Items per page                                                                         |
+| `onPageChange` | `(state: { page: number; skip: number }) => void` | `undefined` | Event callback fired when `goToPage()` is called                                       |
 
 ### 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`                                  |
-| `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`                           |
+| 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` | Set the page without firing `onPageChange` (used to seed from a URL restore) |
+| `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.
 
@@ -67,43 +67,38 @@ All properties are auto-unwrapped by `reactive()` — no `.value` access needed
 
 ```vue
 <script setup lang="ts">
-import { ref, computed, watch } from "vue";
-import { useDataTablePagination, useDataTableSort, useTableQueryState } from "@vc-shell/framework";
+import { ref, computed, watch, onMounted } from "vue";
+import { useDataTablePagination, useDataTableSort } from "@vc-shell/framework";
+
+const STATE_KEY = "products_list";
 
 // Data layer
 const searchResult = ref<{ results: Item[]; totalCount: number }>();
 
-async function loadItems(query: { sort?: string; keyword?: string; skip?: number }) {
-  searchResult.value = await api.search({ take: 20, ...query });
+async function loadItems() {
+  searchResult.value = await api.search({
+    sort: sortExpression.value,
+    skip: pagination.skip,
+    take: pagination.pageSize,
+  });
 }
 
-// State only — no self-loading callback.
-const pagination = useDataTablePagination({
-  pageSize: 20,
-  totalCount: computed(() => searchResult.value?.totalCount ?? 0),
-});
+// Sort state
 const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  stateKey: STATE_KEY,
   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 },
-);
+
+// Pagination state
+const pagination = useDataTablePagination({
+  stateKey: STATE_KEY,
+  pageSize: 20,
+  totalCount: computed(() => searchResult.value?.totalCount ?? 0),
+});
+
+onMounted(() => loadItems());
+watch(sortExpression, () => loadItems());
 </script>
 
 <template>
@@ -112,12 +107,6 @@ watch(
     :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"
   >
@@ -151,6 +140,7 @@ export function useOffers() {
   const pagination = useDataTablePagination({
     pageSize: 20,
     totalCount: computed(() => searchResult.value?.totalCount ?? 0),
+    onPageChange: ({ skip }) => loadOffers({ ...searchQuery.value, skip }),
   });
 
   return {
@@ -161,7 +151,7 @@ export function useOffers() {
 }
 ```
 
-The blade owns the single loader watch (reading `pagination.skip` with sort/search) and binds:
+Blade then simply binds:
 
 ```vue
 <VcDataTable :total-count="pagination.totalCount" :pagination="pagination" @pagination-click="pagination.goToPage" />
@@ -170,12 +160,12 @@ The blade owns the single loader watch (reading `pagination.skip` with sort/sear
 ## 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 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.
+- **Event callback, not load**: `onPageChange` is an event notification (like VueUse's `useOffsetPagination`). The composable does not know about data fetching -- it just notifies.
 - **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.
+- **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.
 - **Why `reactive()` and not `ref()`**: Pagination is a cohesive group of properties always used together (`pagination.xxx`). `reactive()` is the Vue-idiomatic choice for such objects. `useDataTableSort` returns `ref()`s because its properties are destructured and used with `v-model` individually.
+- **URL state (stateKey)**: When `stateKey` is provided, the composable reads the current page from the blade URL query on creation (via `setPage`, which does not fire `onPageChange`) and persists it on every `goToPage` call. Without `stateKey`, behavior is unchanged.
 
 ## Tips
 

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

@@ -46,10 +46,11 @@ const { sortField, sortOrder, sortExpression, resetSort } = useDataTableSort({
 
 ### Parameters (Options)
 
-| Option             | Type              | Default     | Description                       |
-| ------------------ | ----------------- | ----------- | --------------------------------- |
-| `initialField`     | `string`          | `undefined` | Column field to sort by initially |
-| `initialDirection` | `"ASC" \| "DESC"` | `undefined` | Initial sort direction            |
+| Option             | Type                  | Default     | Description                                                                |
+| ------------------ | --------------------- | ----------- | -------------------------------------------------------------------------- |
+| `stateKey`         | `string \| undefined` | `undefined` | When set, restores and persists sort to the blade URL query under this key |
+| `initialField`     | `string`              | `undefined` | Column field to sort by initially                                          |
+| `initialDirection` | `"ASC" \| "DESC"`     | `undefined` | Initial sort direction                                                     |
 
 ### Returns
 
@@ -74,26 +75,25 @@ When `sortOrder` is `0`, `sortExpression` returns `undefined` regardless of `sor
 
 ```vue
 <script setup lang="ts">
-import { ref, watch } from "vue";
+import { ref, watch, onMounted } from "vue";
 import { useDataTableSort } from "@vc-shell/framework";
 
 const { sortField, sortOrder, sortExpression, resetSort } = useDataTableSort({
+  stateKey: "products_list",
   initialField: "createdDate",
   initialDirection: "DESC",
 });
 
 const items = ref([]);
 const loading = ref(false);
-const currentPage = ref(1);
-const PAGE_SIZE = 20;
 
-async function loadItems(query: { sort?: string; skip?: number }) {
+async function loadItems() {
   loading.value = true;
   try {
     const response = await api.searchProducts({
-      sort: query.sort, // e.g. "createdDate:DESC" or undefined
-      skip: query.skip ?? 0,
-      take: PAGE_SIZE,
+      sort: sortExpression.value, // e.g. "createdDate:DESC" or undefined
+      skip: 0,
+      take: 20,
     });
     items.value = response.results;
   } finally {
@@ -101,13 +101,8 @@ async function loadItems(query: { sort?: string; skip?: number }) {
   }
 }
 
-// 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 },
-);
+onMounted(() => loadItems());
+watch(sortExpression, () => loadItems());
 </script>
 
 <template>
@@ -141,13 +136,13 @@ watch(
 - **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. 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.
+- **Stateless regarding data**: The composable only manages the sort field and direction. Combine it with your own data-fetching logic using `watch(sortExpression, ...)`.
+- **URL state (stateKey)**: When `stateKey` is provided, the composable reads its slice from the blade URL query on creation and writes back on every change (via `router.replace`). Without `stateKey`, behavior is unchanged -- `sortField` and `sortOrder` are plain refs with no URL interaction.
 
 ## Tips
 
 - Always mark columns as `sortable` in your `<VcColumn>` definitions for the sort indicator icon to appear.
-- 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.
+- Use `{ immediate: true }` on the `watch(sortExpression, ...)` call to trigger the initial data load with the correct sort on mount.
 - 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