@vc-shell/vc-app-skill 2.0.11 → 2.1.0-pr249.229549

package/runtime/knowledge/migration-prompts/table-url-state-migration.md

@@ -0,0 +1,221 @@
+---
+name: table-url-state-migration
+description: AI transformation rules for opting an existing VcDataTable list into URL-query state persistence (sort, search, page) via the composables' stateKey option.
+---
+
+# Table URL State: persist sort / search / page in the blade URL
+
+This retrofit applies to list blades that **already use `VcDataTable`** with the state
+composables (`useDataTableSort`, `useDataTablePagination`, and search) but do **not** yet
+persist the view to the URL. After it, sort, search keyword, and current page survive a
+reload and travel in a shareable link.
+
+It is independent of the VcTable→VcDataTable swap (`datatable-migration`) and of adopting
+the pagination composable (`use-data-table-pagination-migration`). Run those first if the
+file still uses `<VcTable>` or hand-rolled `pages`/`currentPage`.
+
+## Concept
+
+Each state composable accepts an optional `stateKey`. With it set, the composable reads its
+initial value from the blade URL query on creation and writes changes back:
+
+- `useDataTableSort({ stateKey })` → `<stateKey>_sort` (e.g. `createdDate:DESC`)
+- `useTableSearch({ stateKey })` → `<stateKey>_search`
+- `useDataTablePagination({ stateKey })` → `<stateKey>_page` (page 1 is encoded as absent)
+
+The `state-key` **prop** on `<VcDataTable>` is unrelated — it persists column layout to
+`localStorage`. Leave it as-is. The composable `stateKey` is the URL query store.
+
+## Choosing the key
+
+- One key per table, **the same string** across all three composables on that blade.
+- Use snake_case, conventionally `<module>_list` (e.g. `orders_list`). It may equal the
+  table `state-key` prop — they are separate stores.
+- The key must be unique among tables that can be visible simultaneously (a list plus a
+  child list in the same stack), so their query params do not collide.
+
+## Precondition: the blade must be URL-addressable
+
+`stateKey` only does something when the blade has a `url` in `defineBlade`. For a
+non-routable or nested blade (no `url`) the query service is a no-op — skip that file and
+note it in the report rather than adding dead options.
+
+## RULE 1: Add `stateKey` to `useDataTableSort`
+
+**BEFORE:**
+
+```ts
+const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  initialField: "createdDate",
+  initialDirection: "DESC",
+});
+```
+
+**AFTER:**
+
+```ts
+const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  stateKey: "orders_list",
+  initialField: "createdDate",
+  initialDirection: "DESC",
+});
+```
+
+## RULE 2: Own the search keyword with `useTableSearch({ stateKey })`
+
+The keyword must live in a ref that `useTableSearch` controls, bound to
+`v-model:search-value`. Three starting shapes:
+
+**2a — bare `ref("")` in the blade:** replace it.
+
+```ts
+// BEFORE
+const searchValue = ref("");
+// AFTER
+const { searchValue } = useTableSearch({ stateKey: "orders_list" });
+```
+
+**2b — event-driven `@search` with no ref:** the table emits `@search` and a handler loads
+directly. Convert to `v-model:search-value` + a watcher.
+
+```vue
+<!-- BEFORE -->
+<VcDataTable :searchable="true" @search="onSearchChange" />
+<!-- AFTER -->
+<VcDataTable :searchable="true" v-model:search-value="searchValue" />
+```
+
+```ts
+// BEFORE
+async function onSearchChange(keyword: string | undefined) {
+  await loadItems({ ...searchQuery.value, keyword, skip: 0 });
+}
+// AFTER — remove onSearchChange; drive load from the watcher (see RULE 5)
+const { searchValue } = useTableSearch({ stateKey: "orders_list" });
+```
+
+**2c — the deprecated `useTableQueryState().read()` preview form:** delete the manual
+restore block entirely (see RULE 6); the three composables now seed themselves.
+
+In all cases add `v-model:search-value="searchValue"` to the `<VcDataTable>` and keep
+`:searchable="true"`.
+
+## RULE 3: Add `stateKey` to `useDataTablePagination`
+
+If pagination is created in the blade, add the option directly:
+
+```ts
+const pagination = useDataTablePagination({
+  stateKey: "orders_list",
+  pageSize: 20,
+  totalCount,
+});
+```
+
+If pagination is created **inside the list composable** (common when `onPageChange` drives
+the load), thread `stateKey` through as a composable option — the blade still owns the key:
+
+```ts
+// composable
+export function useOrdersList(options?: { pageSize?: number; stateKey?: string }) {
+  // ...
+  const pagination = useDataTablePagination({
+    stateKey: options?.stateKey,
+    pageSize: options?.pageSize ?? 20,
+    totalCount: computed(() => searchResult.value?.totalCount ?? 0),
+    onPageChange: ({ skip }) => loadItems({ ...searchQuery.value, skip }),
+  });
+}
+```
+
+```ts
+// blade
+const { items, pagination, loadItems } = useOrdersList({ stateKey: "orders_list" });
+```
+
+Add the `stateKey?: string` field to the composable's options interface.
+
+## RULE 4: Seed the initial load from the restored values
+
+The first load on mount must read the restored sort, keyword, and page — otherwise the URL
+is restored into the refs but the first fetch ignores them and shows page 1 unfiltered.
+
+```ts
+// BEFORE
+onMounted(() => loadItems({ take: 20, sort: sortExpression.value }));
+// AFTER
+onMounted(() =>
+  loadItems({
+    take: 20,
+    sort: sortExpression.value,
+    keyword: searchValue.value || undefined,
+    skip: pagination.skip,
+  }),
+);
+```
+
+For a `reload()` helper, use `skip: pagination.skip` (not a recomputed skip).
+
+## RULE 5: Reset to page 1 when the search changes — REQUIRED
+
+This is not optional. If the user is on page 3 and types a query that returns fewer pages,
+leaving `_page=3` in the URL makes the next reload request page 3 of the filtered set:
+`skip` overshoots and the table shows an empty "nothing found" state on reload. Resetting to
+page 1 drops `_page` from the URL and keeps the `(search, page)` pair consistent.
+
+```ts
+watch(searchValue, () => pagination.setPage(1));
+// then the reload watcher (debounced) picks up the change:
+watch([sortExpression, searchValue, () => pagination.skip], debounce(load, 300));
+```
+
+If search loads through a separate handler (event-driven apps), call `pagination.setPage(1)`
+at the top of that handler before loading with `skip: 0`. Apply the same reset when a global
+filter changes.
+
+## RULE 6: Remove the deprecated preview API
+
+Delete any `useTableQueryState().read()` or `useTableQueryPersistence` usage and the manual
+ref-seeding it drove — the `stateKey` option replaces it.
+
+```ts
+// DELETE this whole block:
+const restored = useTableQueryState("orders_list").read();
+if (restored.sort) {
+  /* ... */
+}
+if (restored.search) searchValue.value = restored.search;
+if (restored.page) pagination.setPage(restored.page);
+```
+
+Remove the now-unused `useTableQueryState` / `useTableQueryPersistence` import.
+
+## Advanced: a shared list base with two views
+
+Some apps render two datasets (e.g. flat list vs. category tree) through one
+`VcDataTable`-wrapping base component, each with its own `useDataTablePagination`. Pass the
+same `stateKey` to **both** view paginations (only one view is active at a time, so they
+never write the page param simultaneously) and reset the page on search via the unified
+pagination object the base holds (`props.pagination.setPage(1)`).
+
+## What to add
+
+- `stateKey` on `useDataTableSort`, `useDataTablePagination`, and `useTableSearch` (same key)
+- `useTableSearch({ stateKey })` import + `v-model:search-value="searchValue"` binding
+- `watch(searchValue, () => pagination.setPage(1))`
+- `skip: pagination.skip` and `keyword: searchValue.value || undefined` in the initial load
+- `stateKey?: string` on the list composable's options interface (when pagination is there)
+
+## What to remove
+
+- `useTableQueryState().read()` / `useTableQueryPersistence` calls and their imports
+- Event-driven `@search` handlers that only set a keyword and reload (replaced by RULE 2/5)
+- Any manual `currentPage`/`skip` math used purely to restore a page from the URL
+
+## Verification
+
+1. `npx vue-tsc --noEmit` passes.
+2. Sort a column, search, go to page 2 — the URL gains `<key>_sort`, `<key>_search`,
+   `<key>_page`. Reload: the table restores the same view and shows results.
+3. On page 2, type a search — the URL drops `_page` (reset to page 1) and results show.
+4. No `useTableQueryState` / `useTableQueryPersistence` references remain.

package/runtime/knowledge/patterns/list-blade-pattern.md

@@ -20,12 +20,14 @@ Generic worked example for a typical list blade (search, sort, pagination, row a
       class="tw-grow tw-basis-0"
       :loading="loading"
       :items="xxxList"
-      :total-count="totalCount"
-      :pagination="{ currentPage, pages }"
+      :total-count="pagination.totalCount"
+      :pagination="pagination"
       v-model:active-item-id="selectedItemId"
       state-key="xxx_list"
       v-model:sort-field="sortField"
       v-model:sort-order="sortOrder"
+      v-model:search-value="searchValue"
+      :searchable="true"
       :pull-to-refresh="true"
       :empty-state="{
         icon: 'lucide-<icon>',
@@ -34,7 +36,7 @@ Generic worked example for a typical list blade (search, sort, pagination, row a
         actionHandler: onAddItem,
       }"
       @row-click="onItemClick"
-      @pagination-click="onPaginationClick"
+      @pagination-click="pagination.goToPage"
       @pull-refresh="reload"
     >
       <!-- Each VcColumn is declared explicitly in the template (NOT via v-for).
@@ -87,9 +89,11 @@ Generic worked example for a typical list blade (search, sort, pagination, row a
 
 **Key VcDataTable props:**
 
-- `state-key` — unique string key for persisting column widths/order/visibility to localStorage. Use snake_case module name (e.g., `"team_list"`, `"catalog_list"`).
+- `state-key` — unique string key for persisting column widths/order/visibility to localStorage. Use snake_case module name (e.g., `"team_list"`, `"catalog_list"`). This prop controls column layout only — URL query persistence (sort/search/page) comes from the composables' `stateKey` option.
 - `v-model:active-item-id` — highlights the currently open row. Bind to `selectedItemId` ref.
 - `v-model:sort-field` and `v-model:sort-order` — two-way sort binding from `useDataTableSort`.
+- `v-model:search-value` and `:searchable="true"` — two-way search binding from `useTableSearch`.
+- `:pagination="pagination"` and `@pagination-click="pagination.goToPage"` — pass the reactive object from `useDataTablePagination` directly.
 - `:pull-to-refresh="true"` — enables mobile pull-to-refresh gesture.
 - `:empty-state` — object with `icon`, `title`, `actionLabel`, `actionHandler`.
 
@@ -191,7 +195,8 @@ If the API defines an enum of statuses, populate the map from those values. If s
 ```vue
 <script lang="ts" setup>
 import { ref, computed, watch, onMounted } from "vue";
-import { IBladeToolbar, useBlade, useDataTableSort } from "@vc-shell/framework";
+import { IBladeToolbar, useBlade, useDataTableSort, useDataTablePagination, useTableSearch } from "@vc-shell/framework";
+import { debounce } from "lodash-es";
 import useXxxs from "../composables/useXxxs";
 import { useI18n } from "vue-i18n";
 
@@ -211,19 +216,32 @@ defineBlade({
 // 2. Core composables
 const { openBlade, exposeToChildren, param } = useBlade();
 const { t } = useI18n({ useScope: "global" });
-const { getXxxs, searchQuery, loading, xxxList, currentPage, pages, totalCount } = useXxxs();
+const { getXxxs, loading, xxxList, totalCount } = useXxxs();
 
-// 3. Sort — provides sortField, sortOrder (for VcDataTable v-model), sortExpression (string for API)
+// 3. Sort — stateKey persists sort to blade URL; omit stateKey to opt out
 const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  stateKey: "xxx_list",
   initialField: "createdDate",
   initialDirection: "DESC",
 });
 
-// 4. UI state
+// 4. Search — stateKey persists keyword to blade URL; omit stateKey to opt out
+const { searchValue } = useTableSearch({ stateKey: "xxx_list" });
+
+// 5. Pagination — stateKey persists current page to blade URL; omit stateKey to opt out
+// Note: state-key on <VcDataTable> is column-layout persistence only (localStorage).
+// URL query persistence (sort/search/page) is controlled by the stateKey option here.
+const pagination = useDataTablePagination({
+  stateKey: "xxx_list",
+  pageSize: 20,
+  totalCount,
+});
+
+// 6. UI state
 const selectedItemId = ref<string | undefined>();
 const title = computed(() => t("XXX.PAGES.LIST.TITLE"));
 
-// 5. Toolbar
+// 7. Toolbar
 const bladeToolbar = ref<IBladeToolbar[]>([
   {
     id: "refresh",
@@ -241,7 +259,7 @@ const bladeToolbar = ref<IBladeToolbar[]>([
   },
 ]);
 
-// 6. Status variant mapping (if status column exists)
+// 8. Status variant mapping (if status column exists)
 const statusVariant = (status: string | undefined): "info" | "warning" | "danger" | "success" | "primary" => {
   const map: Record<string, "info" | "warning" | "danger" | "success" | "primary"> = {
     // TODO: adjust status variants to match your API statuses
@@ -256,12 +274,23 @@ const statusVariant = (status: string | undefined): "info" | "warning" | "danger
   return map[status ?? ""] ?? "info";
 };
 
-// 7. Sort reactivity — reload when sort changes
-watch(sortExpression, async (value) => {
-  await getXxxs({ ...searchQuery.value, sort: value });
-});
+// 9. Load function — explicit; called on mount and by watchers
+const load = async () => {
+  await getXxxs({
+    sort: sortExpression.value,
+    keyword: searchValue.value || undefined,
+    skip: pagination.skip,
+    take: 20,
+  });
+};
 
-// 8. Track selected row when param changes (e.g., navigating directly to URL)
+// 10. Reset to page 1 when search changes, then reload
+watch(searchValue, () => pagination.setPage(1));
+
+// 11. Reload when sort, search, or page changes (debounced to coalesce rapid changes)
+watch([sortExpression, searchValue, () => pagination.skip], debounce(load, 300));
+
+// 12. Track selected row when param changes (e.g., navigating directly to URL)
 watch(
   () => param.value,
   () => {
@@ -270,30 +299,15 @@ watch(
   { immediate: true },
 );
 
-// 9. Load data on mount
-onMounted(async () => {
-  await reload();
-});
+// 13. Load data on mount
+onMounted(() => load());
 
-// 10. Reload — reloads current page with current sort
+// 14. Reload helper — used by toolbar and exposed to child blades
 const reload = async () => {
-  await getXxxs({
-    ...searchQuery.value,
-    skip: (currentPage.value - 1) * (searchQuery.value?.take ?? 20),
-    sort: sortExpression.value,
-  });
-};
-
-// 11. Pagination
-const onPaginationClick = async (page: number) => {
-  await getXxxs({
-    ...searchQuery.value,
-    skip: (page - 1) * (searchQuery.value?.take ?? 20),
-    sort: sortExpression.value,
-  });
+  await load();
 };
 
-// 12. Row click → open details blade
+// 15. Row click → open details blade
 const onItemClick = (event: { data: { id?: string } }) => {
   openBlade({
     name: "XxxDetails",
@@ -310,14 +324,14 @@ const onItemClick = (event: { data: { id?: string } }) => {
   });
 };
 
-// 13. Add new item — open details blade with no param (creates new)
+// 16. Add new item — open details blade with no param (creates new)
 function onAddItem() {
   openBlade({
     name: "XxxDetails",
   });
 }
 
-// 14. Expose reload to child blades so details can trigger list refresh after save/delete
+// 17. Expose reload to child blades so details can trigger list refresh after save/delete
 exposeToChildren({ reload });
 </script>
 ```
@@ -334,6 +348,7 @@ exposeToChildren({ reload });
 
 ```ts
 const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  stateKey: "xxx_list", // optional: persists sort to blade URL
   initialField: "createdDate",
   initialDirection: "DESC",
 });
@@ -342,16 +357,45 @@ const { sortField, sortOrder, sortExpression } = useDataTableSort({
 - `sortField` — reactive ref, two-way bound to `VcDataTable` via `v-model:sort-field`
 - `sortOrder` — reactive ref (`"ASC"` | `"DESC"`), two-way bound via `v-model:sort-order`
 - `sortExpression` — computed string `"field:DIR"` (e.g., `"createdDate:DESC"`), passed to the API
+- `stateKey` — when provided, the composable reads the initial sort from the URL and writes back on change
 
-### Sort watcher pattern
+### `useTableSearch` — search with optional URL persistence
 
 ```ts
-watch(sortExpression, async (value) => {
-  await getXxxs({ ...searchQuery.value, sort: value });
+const { searchValue } = useTableSearch({ stateKey: "xxx_list" });
+```
+
+- Returns `searchValue` ref, two-way bound via `v-model:search-value` on `VcDataTable`.
+- With `stateKey`, restores and persists the keyword to the blade URL.
+- Without `stateKey`, behaves like a plain `ref("")`.
+
+### `useDataTablePagination` — pagination with optional URL persistence
+
+```ts
+const pagination = useDataTablePagination({
+  stateKey: "xxx_list", // optional: persists current page to blade URL
+  pageSize: 20,
+  totalCount,
 });
 ```
 
-Watch `sortExpression` (not `sortField`/`sortOrder` separately) to trigger a reload whenever sort changes.
+- Pass `pagination` directly as `:pagination="pagination"` and `@pagination-click="pagination.goToPage"`.
+- Access `pagination.skip` for API calls, `pagination.setPage(1)` to reset on search change.
+- `stateKey` persists the current page to the blade URL; omit to opt out.
+- The table `state-key` prop is column-layout persistence (localStorage) only and is independent.
+
+### Load + watcher pattern
+
+```ts
+const load = async () => {
+  await getXxxs({ sort: sortExpression.value, keyword: searchValue.value || undefined, skip: pagination.skip, take: 20 });
+};
+watch(searchValue, () => pagination.setPage(1));
+watch([sortExpression, searchValue, () => pagination.skip], debounce(load, 300));
+onMounted(() => load());
+```
+
+Watch `[sortExpression, searchValue, () => pagination.skip]` to reload whenever any query dimension changes. Reset to page 1 when search changes before the reload watcher fires.
 
 ### `exposeToChildren`
 

package/runtime/vc-app.md

@@ -1613,6 +1613,7 @@ Map topic headings to migration prompt files and pattern files:
 | Assets API / useAssets / useAssetsManager / use-assets-migration                                                                 | `use-assets-migration`            | `{KNOWLEDGE_BASE}/migration-prompts/use-assets-migration.md`                | `{KNOWLEDGE_BASE}/patterns/assets-management.md`     |
 | Manual Migration Audit / useExternalWidgets / moment / useFunctions / resolveBladeByName / onParentCall / manual-migration-audit | `manual-migration-audit`          | `{KNOWLEDGE_BASE}/migration-prompts/manual-migration-audit.md`              | —                                                    |
 | Pagination / useDataTablePagination / use-data-table-pagination-audit                                                            | `use-data-table-pagination-audit` | `{KNOWLEDGE_BASE}/migration-prompts/use-data-table-pagination-migration.md` | —                                                    |
+| Table URL State / stateKey / useTableQueryState / table-url-state-audit                                                          | `table-url-state-audit`           | `{KNOWLEDGE_BASE}/migration-prompts/table-url-state-migration.md`           | `{KNOWLEDGE_BASE}/patterns/list-blade-pattern.md`    |
 
 Build the `topics` array for the migration-agent using the canonical topic names above.
 

package/runtime/knowledge/docs/core/blade-navigation/table-query-state/useTableQueryState.docs.md

@@ -1,95 +0,0 @@
----
-title: useTableQueryState
-category: composables
-group: data
----
-
-# useTableQueryState
-
-Reads the table view state (`sort`, `search`, `page`) that `VcDataTable` persists to the URL query for URL-addressable blades. A list page calls `read()` in `setup` to seed its own refs from the restored state before its loader runs, so a reload makes one request.
-
-Read-only: writing the view state to the URL stays inside `VcDataTable`. This composable only exposes the restored values to the page.
-
-## When to Use
-
-- A list blade is URL-addressable (workspace or routable) and uses `VcDataTable` with a `state-key`
-- You want a single, coordinated load on reload (sort + search + page restored together)
-- You are wiring the page's combined loader watcher and need the restored seed values
-
-## When NOT to Use
-
-- The table is standalone or its blade has no URL — there is nothing to restore (`read()` returns `{}`)
-- You only need the live view state — that already lives in your own `sortField`/`searchValue`/`currentPage` refs
-- You want to _write_ to the URL — that is automatic; do not persist manually
-
-## Basic Usage
-
-```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);
-
-// Seed refs from the URL before the loader runs.
-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));
-```
-
-## API
-
-### Parameters
-
-| Parameter  | Type                  | Default     | Description                                                               |
-| ---------- | --------------------- | ----------- | ------------------------------------------------------------------------- |
-| `stateKey` | `string \| undefined` | `undefined` | The same `state-key` passed to `VcDataTable` for this table (namespacing) |
-
-### Returns
-
-| Property | Type                    | Description                                                                                            |
-| -------- | ----------------------- | ------------------------------------------------------------------------------------------------------ |
-| `read`   | `() => TableQueryPatch` | Reads the restored `{ sort?, search?, page? }` from the URL. Returns `{}` when no service is available |
-
-`TableQueryPatch`: `{ sort?: string; search?: string; page?: number }` — `sort` is a `"field:ASC"` / `"field:DESC"` expression, `page` is 1-based.
-
-## Details
-
-- **Read in `setup`**: `VcDataTable` does not emit restore events on init; the page reads the state and seeds its refs in `setup`. This avoids a separate load per restored field.
-- **No-op without a service**: When no blade provides the persistence service (standalone table, non-URL blade), `read()` returns `{}`, so you can call it unconditionally.
-- **Write-back is automatic**: View state → URL (debounced `router.replace`) is handled by `VcDataTable` via `useTableQueryPersistence`. Pages do not persist manually.
-
-## Tips
-
-- Call `read()` once, synchronously, before the loader. Seeding after it runs causes an extra load.
-- Use `useDataTablePagination`'s `setPage(n)` to seed the page without firing `onPageChange`.
-- Pass the same `state-key` you give `VcDataTable`, so the URL keys match.
-
-## Related
-
-- [`useDataTableSort`](../../../ui/composables/useDataTableSort.docs.md) — sort state composable for `VcDataTable`
-- [`useDataTablePagination`](../../../ui/composables/useDataTablePagination.docs.md) — pagination state composable (`setPage` for restore seed)
-- `VcDataTable` → _URL query persistence_ — the write-back side of this contract

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.