### Vue 3 Composition API with `<script setup>`

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/llms/ui-kit/llms-page-builder-prompt.md

Always use the `<script setup>` syntax for Vue 3 Composition API. This example demonstrates props, emits, and reactive state.

```vue
<template>
  <!-- Template -->
</template>

<script setup lang="ts">
import { ref, computed } from "vue";

interface IProps {
  title: string;
  items?: string[];
}

const props = withDefaults(defineProps<IProps>(), {
  items: () => [],
});

const emit = defineEmits<{
  select: [item: string];
}>();

const selectedItem = ref<string | null>(null);

function handleSelect(item: string) {
  selectedItem.value = item;
  emit("select", item);
}
</script>

<style lang="scss">
/* Styles */
</style>
```

--------------------------------

### Install Dependencies

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/README.md

Installs project dependencies using Yarn with the --immutable flag to ensure correct versions.

```bash
yarn install --immutable
```

--------------------------------

### Register Extension Component using EXTENSION_NAMES

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/client-app/shared/common/composables/extensionRegistry/README.md

This example demonstrates the recommended way to register an extension component by importing and utilizing the `EXTENSION_NAMES` constant for type safety and consistency.

```typescript
import { EXTENSION_NAMES } from "@/shared/common/constants/extensionPointsNames.ts";
const { register } = useExtensionRegistry();
register("productCard", EXTENSION_NAMES.productCard.cardButton, { component: MyComponent });
```

--------------------------------

### Module Initialization and Route Registration

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/client-app/modules/README.md

Example of a module's entry point (index.ts) that exports an async init function. This function registers a new route with the Vue Router instance.

```typescript
// modules/your-module/index.ts
import { Router } from "vue-router";
import { I18n } from "@/i18n";

// Define your components
const YourModulePage = () => import("./pages/YourModulePage.vue");
// By using () => import('./pages/YourModulePage.vue'), you ensure that Vue Router can handle the component as a lazy-loaded route, which is the intended usage pattern.

export async function init(router: Router, i18n: I18n): Promise<void> {
  const route = {
    path: "/your-module",
    name: "YourModule",
    component: YourModulePage,
    beforeEnter(to: any, from: any, next: Function) {
      // Add any route guards or logic here
      next();
    },
  };

  router.addRoute(route);
}
```

--------------------------------

### Check Yarn Version

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/README.md

Checks the installed version of Yarn. Ensure it is 4.1.0 or greater.

```bash
yarn -v
```

--------------------------------

### Generate Dependency Graph

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/README.md

Creates a visual representation of the project's dependency graph. Requires graphviz to be installed. The generated graph is saved in the artifacts folder.

```bash
yarn generate:dependency-graph client-app/main.ts client-app/shared/account/components/checkout-default-success-modal.vue
```

--------------------------------

### Add Dev-Only Console Warning in Component File

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/client-app/ui-kit/DEPRECATION.md

Include a dev-only `console.warn` in `<script setup>` after `defineProps` to alert developers running the app locally about the deprecated component.

```vue
defineProps<IProps>();

if (import.meta.env.DEV) {
  // eslint-disable-next-line no-console
  console.warn("[VcSelect] This component is deprecated. Use VcDropdownMenu instead.");
}
```

--------------------------------

### Build for Production

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/README.md

Builds the project with validation and minification for production deployment.

```bash
yarn build
```

--------------------------------

### Build in Development Mode

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/README.md

Builds the project in development mode.

```bash
yarn build:dev
```

--------------------------------

### Uninstall Global Yarn

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/README.md

Uninstalls the globally installed Yarn package manager via npm.

```bash
npm uninstall --global yarn
```

--------------------------------

### Wishlists — `useWishlists()`

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

Composable for managing multiple wishlists (create, rename, delete, add/remove items, share). Supports bulk add, configuration sections for configurable products, and optional auto-refetch after mutations.

```APIDOC
## Wishlists — `useWishlists()`

Composable for managing multiple wishlists (create, rename, delete, add/remove items, share). Supports bulk add, configuration sections for configurable products, and optional auto-refetch after mutations.

```typescript
// client-app/shared/wishlists/composables/useWishlists.ts
import { useWishlists } from "@/shared/wishlists/composables";

const { 
  lists, 
  list, 
  loading, 
  listLoading, 
  fetchWishlists, 
  fetchWishList, 
  fetchSharedWishList, 
  createWishlist, 
  updateWishlist, 
  removeWishlist, 
  addItemsToWishlists, 
  removeItemsFromWishlists, 
  updateItemsInWishlist,
} = useWishlists({ autoRefetch: true });

// Load all wishlists for current user
await fetchWishlists();
// lists.value → WishlistType[]

// Create a new wishlist
const newId = await createWishlist({ name: "Birthday ideas", storeId: "default" });

// Rename a wishlist
await updateWishlist({ listId: newId!, name: "Gift Ideas" });

// Add a product to multiple wishlists
await addItemsToWishlists({
  listIds: [newId!],
  productId: "prod-abc",
  quantity: 1,
});

// Remove items from a wishlist (optimistic local update)
await removeItemsFromWishlists([
  { listId: newId!, productId: "prod-abc" },
]);

// Share / view a shared wishlist by sharing key
await fetchSharedWishList("sharing-key-xyz");
// list.value → shared WishlistType

// Delete a wishlist
const deleted = await removeWishlist(newId!); // returns boolean
```
```

--------------------------------

### Use VcIcon Component

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/llms/ui-kit/llms-detailed.txt

Demonstrates how to use the VcIcon component to display icons. Specify the icon name and optionally its size.

```html
<VcIcon name="shopping-cart" :size="24" />
```

--------------------------------

### Click Outside Directive (v-on-click-outside)

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/llms/ui-kit/llms-detailed.txt

Example of using the v-on-click-outside directive to detect clicks that occur outside of the element it's applied to.

```vue
<div v-on-click-outside="handleClickOutside">Click me or outside</div>
```

--------------------------------

### Enable Corepack

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/README.md

Enables the Corepack package manager. Run as administrator on Windows.

```bash
corepack enable
```

--------------------------------

### Input Masking Directive (v-maska)

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/llms/ui-kit/llms-detailed.txt

Example of using the v-maska directive for input masking, powered by the Maska library. Apply it to an input element.

```vue
<input v-maska data-maska="000.000.000.00" />
```

--------------------------------

### Configure Development Backend URL

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/README.md

Sets the backend URL for development by creating a .env.local file and copying the APP_BACKEND_URL from .env.

```dotenv
# .env.local file
APP_BACKEND_URL=[your endpoint, example https://localhost:5001]
```

--------------------------------

### Build with Change Tracking

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/README.md

Builds the project in development mode with continuous change tracking.

```bash
yarn build:watch
```

--------------------------------

### Initialize Analytics Provider Module

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/client-app/core/composables/useAnalytics/README.md

Set up a custom analytics provider by defining an `init` function that adds a tracker to the `useAnalytics` composable. This involves importing events and meta information.

```typescript
import { useAnalytics } from "@/core/composables/useAnalytics";

export async function init(): Promise<void> {
  const { addTracker } = useAnalytics();
  const { events } = await import("./events");

  addTracker({
    meta: {
      name: "my-analytics",
    },
    events,
  });
}
```

--------------------------------

### Register and Use UI Components with `useExtensionRegistry()`

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

Manages a global registry for pluggable UI components. Register components under typed categories and query them at render time. Exposed on `window.VCExtensionRegistry` in development for debugging.

```typescript
// client-app/shared/common/composables/extensionRegistry/useExtensionRegistry.ts
import { useExtensionRegistry } from "@/shared/common/composables/extensionRegistry/useExtensionRegistry";
import MyProductCardButton from "./MyProductCardButton.vue";

const { register, unregister, getComponent, isRegistered, canRender, getEntries } = 
  useExtensionRegistry();

// Register an extension component
register("productCard", "card-button", {
  component: MyProductCardButton,
  props: { variant: "outline" },
  // Optional render condition
  condition: (product) => product.productType === "Physical",
});

// In a template or parent component:
const buttonComponent = getComponent("productCard", "card-button");

// Check and render via global helper (registered by extensionPointsPlugin)
// <ExtensionPoint
//   v-if="$canRenderExtensionPoint('productCard', 'card-button', product)"
//   category="productCard"
//   name="card-button"
//   :product="product"
// />

// Unregister when a module is torn down
unregister("productCard", "card-button");

// Get all registered entries for a category
const allCardExtensions = getEntries("productCard");

```

--------------------------------

### useNavigations()

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

Global composable providing desktop and mobile navigation tree data from various sources, including static config, GraphQL queries, and category-based menus. Supports white-labeling and dynamic schema merging.

```APIDOC
## useNavigations()

### Description
Global composable providing desktop and mobile navigation tree data loaded from `config/menu.json` (static), the Virto Commerce `getMenu` GraphQL query (footer-links, pinned-links), and category-based catalog menu. Supports white-labeling override and dynamic menu schema merging for modules.

### Usage
```typescript
import { useNavigations } from "@/core/composables";

const { 
  desktopMainMenuItems, desktopPurchasingMenuItems, desktopUserMenuItems,
  mobileMainMenuItems, mobileCatalogMenuItem, mobilePreSelectedMenuItem,
  catalogMenuItems, footerLinks, pinnedLinks,
  fetchCatalogMenu, fetchFooterLinks, fetchPinnedLinks,
  markLinkTree, mergeMenuSchema 
} = useNavigations();

// Load catalog menu
await fetchCatalogMenu();
// catalogMenuItems.value → ExtendedMenuLinkType[] (2-level tree)

// Load footer and pinned links
await fetchFooterLinks();
await fetchPinnedLinks();

// Mark active link
const markedLink = markLinkTree(catalogMenuItems.value[0], route, "category");
// markedLink.isActive, markedLink.children[n].isActive

// Merge menu schema (e.g., for modules)
mergeMenuSchema({
  header: {
    desktop: {
      purchasing: {
        children: [{ title: "Purchase Requests", route: { name: "PurchaseRequests" }, priority: 10 }],
      },
    },
  },
});
```
```

--------------------------------

### Theme Context Management with useThemeContext()

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

Manages global reactive store for store configuration, theme settings, and active presets. Loads presets on demand and uses theme settings to drive feature flags.

```typescript
// client-app/core/composables/useThemeContext.ts
import { useThemeContext, getPreset, getPredefinedPreset } from "@/core/composables/useThemeContext";

const { themeContext, modulesSettings, setThemeContext, addPresetToThemeContext } = useThemeContext();

// Access store-level settings
const storeId     = themeContext.value.storeId;
const catalogId   = themeContext.value.catalogId;
const allowAnon   = themeContext.value.storeSettings.anonymousUsersAllowed;

// Access theme UI settings
const zeroPriceEnabled = themeContext.value.settings.zero_price_product_enabled;
const carouselEnabled  = themeContext.value.settings.image_carousel_in_product_card_enabled;

// Load and activate a preset by name
await addPresetToThemeContext("coffee");
// Falls back to default preset from settings_data.json if named preset missing

// Load a preset directly (returns null if not found)
const preset = await getPreset("black-gold");
// preset.colors, preset.font, etc.

// Access module-specific settings (from store backend)
const xApiModule = modulesSettings.value?.find(m => m.moduleId === "VirtoCommerce.XApi");
```

--------------------------------

### Bootstrap Application Runner

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

The entry point for the Virto Commerce Frontend application. It wires together Vue plugins, fetches initial page context, and mounts the Vue app. Ensure the '#app' element exists in the DOM.

```typescript
// client-app/main.ts  ← entry point
import runner from "./app-runner";
void runner();
```

```typescript
// app-runner.ts (simplified)
import { createApp, h, provide } from "vue";
import { DefaultApolloClient } from "@vue/apollo-composable";
import { apolloClient, getPageContext } from "@/core/api/graphql";
import {
  useCurrency, useDarkMode, useThemeContext,
  useNavigations, useWhiteLabeling,
} from "@/core/composables";
import { useLanguages } from "@/core/composables/useLanguages";
import { createI18n } from "@/i18n";
import { createRouter } from "@/router";
import { uiKit } from "@/ui-kit";
import App from "./App.vue";

export default async () => {
  const appElement = document.querySelector<HTMLElement>("#app");
  if (!appElement) return;

  const app = createApp(
    { setup() { provide(DefaultApolloClient, apolloClient); }, render: () => h(App) },
    { ...appElement.dataset },
  );

  app.use(authPlugin);

  const { themeContext, setThemeContext, addPresetToThemeContext } = useThemeContext();
  const { initLocale, resolveLocale, fetchLocaleMessages, mergeLocalesMessages,
          currentMaybeShortLocale, defaultStoreCulture, resolvePossibleLocale,
          getUrlWithoutPossibleLocale } = useLanguages();
  const { currentCurrency } = useCurrency();

  const possibleCultureName = resolvePossibleLocale(location.pathname);
  const permalink = getUrlWithoutPossibleLocale(location.pathname).replace(/^\/+/, "") || "/";

  // Single combined backend request — store + user + slugInfo
  const [pageContext] = await Promise.all([
    getPageContext({ domain: location.hostname, userId: savedUserId, permalink, cultureName: possibleCultureName }),
    fallback.setMessage(),
  ]);

  setThemeContext(pageContext.store);        // theme config + store settings
  setUser(pageContext.user);                // bootstrap authenticated user

  const cultureName = resolveLocale();
  const i18n = createI18n(cultureName, currentCurrency.value.code, fallback);
  await initLocale(i18n, cultureName);

  const router = createRouter({
    base: defaultStoreCulture.value === cultureName ? "" : currentMaybeShortLocale.value,
  });

  app.use(head).use(i18n).use(permissionsPlugin)
     .use(extensionPointsPlugin).use(contextPlugin, themeContext.value)
     .use(configPlugin, themeContext.value).use(uiKit)
     .use(applicationInsightsPlugin, { router }).use(router);

  await router.isReady();
  app.mount(appElement);
};

```

--------------------------------

### Product Listing and Filtering with useProducts

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

Utilize `useProducts` for dynamic product catalog management. It supports pagination (infinite scroll or load-more), faceted search, various filters (in-stock, purchased-before, branches), and URL query parameter synchronization.

```typescript
import { useProducts } from "@/shared/catalog/composables";
import { CATALOG_PAGINATION_MODES } from "@/shared/catalog/constants/catalog";

const { 
  products,
  facets,
  totalProductsCount,
  pagesCount,
  currentPage,
  productsFilters,
  fetchingProducts,
  fetchingMoreProducts,
  localStorageInStock,
  sortQueryParam,
  searchQueryParam,
  hasSelectedFilters,
  fetchProducts,
  fetchMoreProducts,
  applyFilters,
  resetFacetAndControlsFilters,
  showFiltersSidebar,
  hideFiltersSidebar,
  isFiltersSidebarVisible,
  openBranchesModal,
  getFacets,
} = useProducts({
  withFacets: true,
  withImages: true,
  withZeroPrice: false,
  useQueryParams: true,
  catalogPaginationMode: CATALOG_PAGINATION_MODES.infiniteScroll,
});

// Fetch first page in a category
await fetchProducts({
  categoryId: "cat-electronics",
  itemsPerPage: 16,
  sort: "priority:desc",
  filter: "price:[10 TO 500]",
  cultureName: "en-US",
  currencyCode: "USD",
  storeId: "Electronics",
});

// Load more (infinite scroll)
await fetchMoreProducts({
  categoryId: "cat-electronics",
  itemsPerPage: 16,
  page: currentPage.value + 1,
});

// Apply user-selected facets & controls
await applyFilters({
  inStock: true,
  purchasedBefore: false,
  branches: ["warehouse-1"],
  facets: productsFilters.value.facets,
  filters: productsFilters.value.filters,
});

// Reset all filters
await resetFacetAndControlsFilters();
```

--------------------------------

### Clone VirtoCommerce Frontend Repository

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/README.md

Clones the vc-frontend repository to a specified local directory.

```bash
git clone https://github.com/VirtoCommerce/vc-frontend.git "C:\vc-frontend\"
```

--------------------------------

### Theme Context

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

Global reactive store for the Virto Commerce store configuration, theme settings, and active preset. Loads presets on demand from `/assets/presets/*.json` with an in-memory cache. Theme settings drive feature flags across the entire app.

```APIDOC
## Theme Context — `useThemeContext()`

### Description
Global reactive store for the Virto Commerce store configuration, theme settings, and active preset. Loads presets on demand from `/assets/presets/*.json` with an in-memory cache. Theme settings drive feature flags across the entire app (zero-price products, browser targets, image carousels, etc.).

### Usage
```typescript
import { useThemeContext, getPreset, getPredefinedPreset } from "@/core/composables/useThemeContext";

const { themeContext, modulesSettings, setThemeContext, addPresetToThemeContext } = useThemeContext();

// Access store-level settings
const storeId     = themeContext.value.storeId;
const catalogId   = themeContext.value.catalogId;
const allowAnon   = themeContext.value.storeSettings.anonymousUsersAllowed;

// Access theme UI settings
const zeroPriceEnabled = themeContext.value.settings.zero_price_product_enabled;
const carouselEnabled  = themeContext.value.settings.image_carousel_in_product_card_enabled;

// Load and activate a preset by name
await addPresetToThemeContext("coffee");
// Falls back to default preset from settings_data.json if named preset missing

// Load a preset directly (returns null if not found)
const preset = await getPreset("black-gold");
// preset.colors, preset.font, etc.

// Access module-specific settings (from store backend)
const xApiModule = modulesSettings.value?.find(m => m.moduleId === "VirtoCommerce.XApi");
```
```

--------------------------------

### Import formatPrice Utility

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/llms/ui-kit/llms-detailed.txt

Import the formatPrice utility function from the UI Kit's utilities directory. This function is used for formatting prices.

```typescript
import { formatPrice } from "@/ui-kit/utilities"
```

--------------------------------

### Manage Navigation Data with `useNavigations`

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

Load and manage desktop and mobile navigation trees from static config, GraphQL, and category data. Supports dynamic merging and marking active links.

```typescript
// client-app/core/composables/useNavigations.ts
import { useNavigations } from "@/core";

const { 
  desktopMainMenuItems,
  desktopPurchasingMenuItems,
  desktopUserMenuItems,
  mobileMainMenuItems,
  mobileCatalogMenuItem,
  mobilePreSelectedMenuItem,
  catalogMenuItems,
  footerLinks,
  pinnedLinks,
  fetchCatalogMenu,
  fetchFooterLinks,
  fetchPinnedLinks,
  markLinkTree,
  mergeMenuSchema,
} = useNavigations();

// Load catalog menu (categories or custom list from XAPI settings)
await fetchCatalogMenu();
// catalogMenuItems.value → ExtendedMenuLinkType[] (2-level tree)

// Load footer and pinned links
await fetchFooterLinks();
await fetchPinnedLinks();

// Mark active link in current route (for mobile breadcrumb highlighting)
const markedLink = markLinkTree(catalogMenuItems.value[0], route, "category");
// markedLink.isActive, markedLink.children[n].isActive

// Modules can add menu items at runtime
mergeMenuSchema({
  header: {
    desktop: {
      purchasing: {
        children: [{ title: "Purchase Requests", route: { name: "PurchaseRequests" }, priority: 10 }],
      },
    },
  },
});
```

--------------------------------

### Initialize Dark Mode Preference

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/index.html

This script checks and applies the dark mode preference based on local storage and system settings. It runs automatically on page load.

```javascript
(function() { var darkAvailable = false; try { darkAvailable = JSON.parse(localStorage.getItem('vc-dark-available')); } catch(e) { console.warn(e); } if (!darkAvailable) return; var mode = localStorage.getItem('vc-color-mode'); var isDark = mode === 'dark' || (mode !== 'light' && globalThis.matchMedia('(prefers-color-scheme: dark)').matches); if (isDark) { document.documentElement.classList.add('dark'); } })();
```

--------------------------------

### Manage Multiple Wishlists with `useWishlists()`

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

Use `useWishlists` to manage multiple wishlists. It supports creating, renaming, deleting, adding/removing items, and sharing. Configure `autoRefetch` for automatic updates after mutations. Ensure lists are fetched before performing operations.

```typescript
import { useWishlists } from "@/shared/wishlists/composables";

const { 
  lists, 
  list, 
  loading, 
  listLoading, 
  fetchWishlists, 
  fetchWishList, 
  fetchSharedWishList, 
  createWishlist, 
  updateWishlist, 
  removeWishlist, 
  addItemsToWishlists, 
  removeItemsFromWishlists, 
  updateItemsInWishlist,
} = useWishlists({ autoRefetch: true });

// Load all wishlists for current user
await fetchWishlists();
// lists.value → WishlistType[]

// Create a new wishlist
const newId = await createWishlist({ name: "Birthday ideas", storeId: "default" });

// Rename a wishlist
await updateWishlist({ listId: newId!, name: "Gift Ideas" });

// Add a product to multiple wishlists
await addItemsToWishlists({
  listIds: [newId!],
  productId: "prod-abc",
  quantity: 1,
});

// Remove items from a wishlist (optimistic local update)
await removeItemsFromWishlists([
  { listId: newId!, productId: "prod-abc" },
]);

// Share / view a shared wishlist by sharing key
await fetchSharedWishList("sharing-key-xyz");
// list.value → shared WishlistType

// Delete a wishlist
const deleted = await removeWishlist(newId!); // returns boolean
```

--------------------------------

### Sign In / Sign Out with useSignMeIn() / useSignMeOut()

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

Handles the high-level sign-in flow by calling useAuth.authorize(), fetching user data, merging carts, and managing currency. Sign out clears cache, tokens, and broadcasts a page reload.

```typescript
// client-app/shared/account/composables/useSignMeIn.ts
import { useSignMeIn } from "@/shared/account";
import { useAuth } from "@/core/composables/useAuth";

const { signIn, loading, errors, resetErrors } = useSignMeIn();
const { authorize } = useAuth();

async function handleLogin(email: string, password: string) {
  resetErrors();
  await authorize(email, password);    // step 1: get tokens
  if (!errors.value?.length) {
    await signIn();                    // step 2: merge cart + redirect
  }
}
// errors.value → IdentityErrorType[] with code + description

// Sign out — clears Apollo cache, tokens, locale pin, broadcasts page reload
import { useSignMeOut } from "@/shared/account";
const { signMeOut } = useSignMeOut();
await signMeOut();
// All tabs reload automatically via BroadcastChannel
```

--------------------------------

### Initialize Module in App Runner

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/client-app/modules/README.md

Import and call the module's init function within the application's runner to integrate it. Ensure the necessary dependencies like router and i18n are passed.

```typescript
// client-app/app-runner.ts

// Import the module's init function
import { init as initYourModule } from "@/modules/your-module";

...

initYourModule(router, i18n);

```

--------------------------------

### Basic Analytics Tracking

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/client-app/core/composables/useAnalytics/README.md

Import and use the `useAnalytics` composable to track predefined events. Ensure the composable is imported correctly.

```typescript
import { useAnalytics } from "@/core/composables/useAnalytics";

const { analytics } = useAnalytics();

// Track a predefined event
analytics("viewItem", product, { currency: "USD" });
```

--------------------------------

### Initialize Google Analytics

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/client-app/modules/google-analytics/README.md

Basic initialization of the Google Analytics module. Ensure this is called during application startup.

```typescript
// client-app/app-runner.ts
import { init as initGoogleAnalytics } from "@/modules/google-analytics";

... 

await initGoogleAnalytics();
```

--------------------------------

### Register an Extension Component

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/client-app/shared/common/composables/extensionRegistry/README.md

Import `useExtensionRegistry` and use the `register` function to add a component to a specific extension point. It's recommended to use `EXTENSION_NAMES` for consistent identifiers.

```typescript
import { useExtensionRegistry } from "@/shared/common/composables/useExtensionRegistry";
import { EXTENSION_NAMES } from "@/shared/common/constants/extensionPointsNames.ts";
const { register } = useExtensionRegistry();
register("productCard", EXTENSION_NAMES.productCard.cardButton, { component: MyComponent });
```

--------------------------------

### Access Module Settings with `useModuleSettings`

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

This memoized composable reads Virto Commerce module settings from the store context, allowing you to enable/disable features based on backend configuration. Use it to dynamically control application behavior.

```typescript
import { useModuleSettings } from "@/core/composables/useModuleSettings";

// Example: Hotjar module
const SETTINGS_MAPPING = {
  "Hotjar.EnableTracking": "isEnabled",
  "Hotjar.ClientId": "clientId",
} as const;

const { isEnabled, getSettingValue, getModuleSettings, hasModuleSettings } = 
  useModuleSettings("VirtoCommerce.Hotjar");

if (isEnabled("Hotjar.EnableTracking")) {
  const clientId = getSettingValue("Hotjar.ClientId"); // string | number | boolean | null
  initHotjar(clientId as string);
}

// Get all mapped settings at once
const { isEnabled: hotjarOn, clientId } = getModuleSettings(SETTINGS_MAPPING);

// Check if the module is configured in this store
if (hasModuleSettings.value) {
  console.log("Hotjar module is installed");
}

// Example: checking intent search
import { INTENT_SEARCH_MODULE_ID, INTENT_SEARCH_ENABLED_KEY } from "@/core/constants/modules";
const { isEnabled: isIntentSearchEnabled } = useModuleSettings(INTENT_SEARCH_MODULE_ID);
const intentSearchActive = isIntentSearchEnabled(INTENT_SEARCH_ENABLED_KEY);

```

--------------------------------

### useAuth()

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

Global composable managing OAuth 2.0 Bearer tokens (access + refresh) persisted in localStorage. Supports password, refresh_token, external_sign_in, and impersonate grant types. Automatically broadcasts unauthorized events cross-tab.

```APIDOC
## useAuth()

### Description
Global composable managing OAuth 2.0 Bearer tokens (access + refresh) persisted in `localStorage`. Supports `password`, `refresh_token`, `external_sign_in`, and `impersonate` grant types. Automatically broadcasts unauthorized events cross-tab.

### Methods
- **authorize(email, password)**: Sign in with username + password.
- **refresh(organizationId?)**: Refresh access token. Optionally switch organization.
- **unauthorize()**: Revoke tokens and clear localStorage.
- **isExpired()**: Check if the token is expired.
- **isAuthorizing()**: Check if currently authorizing.
- **errors**: Reactive object containing identity errors on failure.
- **headers**: Reactive object containing `{ Authorization: "Bearer <token>" }` for fetch calls.

### Usage
```typescript
import { useAuth } from "@/core/composables/useAuth";

const { authorize, refresh, unauthorize, isExpired, headers } = useAuth();

// Sign in
await authorize("john@example.com", "SecurePass1!");

// Refresh token
await refresh();

// Use headers in fetch
const res = await fetch("/api/custom", { headers: headers.value });
```
```

--------------------------------

### Manage User State and Account Mutations with useUser

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

Provides global reactive state for user authentication, permissions, and corporate membership. Supports account mutations like registration, password management, invitations, and organization switching. Broadcasts cross-tab events for user lock or password expiry.

```typescript
import { useUser } from "@/shared/account";

const { 
  user,
  isAuthenticated,
  isCorporateMember,
  isOrganizationMaintainer,
  organization,
  operator,
  userGroups,
  loading,
  fetchUser,
  updateUser,
  registerUser,
  registerOrganization,
  forgotPassword,
  resetPassword,
  changePassword,
  inviteUser,
  registerByInvite,
  sendVerifyEmail,
  confirmEmail,
  switchOrganization,
  checkPermissions,
} = useUser();

// Register a new user account
const result = await registerUser({
  firstName: "Jane",
  lastName: "Doe",
  email: "jane@example.com",
  userName: "jane.doe",
  password: "Secure!1",
});
// result.succeeded === true on success

// Register with organization
await registerOrganization({
  firstName: "Jane",
  lastName: "Doe",
  email: "jane@example.com",
  userName: "jane.doe",
  password: "Secure!1",
  organizationName: "Acme Corp",
});

// Check a specific permission
if (checkPermissions("order:manage")) {
  // user has permission
}

// Send password reset email
await forgotPassword({ email: "jane@example.com", resetPasswordUrlPath: "/reset-password" });

// Reset password using token from email
await resetPassword({ userId: "u-1", token: "abc123", password: "NewPass!1" });

// Change password for authenticated user
const res = await changePassword({ userId: user.value.id, oldPassword: "old", newPassword: "new" });

// Switch to a different organization (refreshes tokens)
await switchOrganization("org-456");

```

--------------------------------

### Check for Missing Locale Keys

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/README.md

Compares locale files against a source-of-truth file to identify missing keys. Ensure all language files have the same keys as the source for consistency. Warnings indicate missing translations that need review.

```bash
yarn check-locales --source en.json -- path/to/locales_folder path/to/**/locales
```

--------------------------------

### Vue 3 Page Template with UI Kit Components

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/llms/ui-kit/llms-page-builder-prompt.md

Demonstrates correct usage of UI Kit components like VcContainer, VcBreadcrumbs, VcTypography, VcInput, and VcButton within a Vue 3 Composition API template. It highlights the use of mock data and BEM classes for layout and spacing only.

```vue
<template>
  <!-- ✅ CORRECT - Use UI Kit components -->
  <VcContainer class="my-page">
    <VcBreadcrumbs :items="breadcrumbs" class="mb-3"></VcBreadcrumbs>

    <!-- ✅ UI Kit components for everything -->
    <VcTypography tag="h1">Page Title</VcTypography>

    <div class="my-page__content">
      <!-- ✅ UI Kit input, not custom -->
      <VcInput v-model="email" label="Email" />
      <VcButton variant="primary">Save</VcButton>
    </div>
  </VcContainer>
</template>

<script setup lang="ts">
// ❌ NEVER import UI Kit components
// import VcButton from "..."; // WRONG!

// ✅ Only use ref, computed, and Vue APIs
import { ref } from "vue";

// For templates, use mock data
const email = ref("user@example.com");
</script>

<style lang="scss">
// BEM class matches file name: my-page.vue → .my-page
.my-page {
  &__content {
    // ✅ ONLY spacing
    @apply mt-8 space-y-4;
  }

  // ❌ NO styling like this:
  // @apply bg-white shadow-lg rounded border;
}
</style>
```

--------------------------------

### useUser()

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

Global reactive state for the current user: authentication status, permissions, corporate membership, and all account mutations. Broadcasts cross-tab events on user lock or password expiry.

```APIDOC
## useUser()

### Description
Global reactive state for the current user: authentication status, permissions, corporate membership, and all account mutations (register, forgot/reset/change password, invite, impersonate switch). Broadcasts cross-tab events on user lock or password expiry.

### State
- **user**: Current user object.
- **isAuthenticated**: Boolean indicating if the user is authenticated.
- **isCorporateMember**: Boolean indicating if the user is a corporate member.
- **isOrganizationMaintainer**: Boolean indicating if the user is an organization maintainer.
- **organization**: Current organization object.
- **operator**: Current operator object.
- **userGroups**: Array of user groups.
- **loading**: Boolean indicating if data is being loaded.

### Methods
- **fetchUser()**: Fetches user data.
- **updateUser(userData)**: Updates user data.
- **registerUser(userData)**: Registers a new user account.
- **registerOrganization(userData)**: Registers a new user with an organization.
- **forgotPassword(emailData)**: Sends a password reset email.
- **resetPassword(passwordData)**: Resets the password using a token.
- **changePassword(passwordData)**: Changes the password for an authenticated user.
- **inviteUser(userData)**: Invites a user to the organization.
- **registerByInvite(userData)**: Registers a user by invitation.
- **sendVerifyEmail(email)**: Sends an email verification link.
- **confirmEmail(token)**: Confirms the user's email.
- **switchOrganization(organizationId)**: Switches the user to a different organization.
- **checkPermissions(permission)**: Checks if the user has a specific permission.

### Usage
```typescript
import { useUser } from "@/shared/account/composables/useUser";

const { registerUser, forgotPassword, checkPermissions, switchOrganization } = useUser();

// Register user
await registerUser({
  firstName: "Jane",
  lastName: "Doe",
  email: "jane@example.com",
  userName: "jane.doe",
  password: "Secure!1",
});

// Check permissions
if (checkPermissions("order:manage")) {
  // user has permission
}

// Switch organization
await switchOrganization("org-456");
```
```

--------------------------------

### Notifications — `useNotifications()`

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

Global, stackable notification system with four severity levels, auto-close timers, grouping, single/singleGroup/singleInGroup deduplication, and imperative close handles.

```APIDOC
## Notifications — `useNotifications()`

Global, stackable notification system with four severity levels, auto-close timers, grouping, single/singleGroup/singleInGroup deduplication, and imperative close handles.

```typescript
// client-app/shared/notification/composables/useNotifications.ts
import { useNotifications } from "@/shared/notification";

const { info, success, warning, error, close, clear, update, stack } = useNotifications();

// Basic notifications
const closeInfo    = info({ text: "Loading your data…" });
const closeSuccess = success({ text: "Order placed successfully!", duration: 5000 });
const closeWarning = warning({ text: "Stock is low for this item." });
const closeError   = error({ text: "Payment failed. Please try again." });

// Auto-close after 3 seconds
success({ text: "Saved!", duration: 3000 });

// Deduplicated notifications (only one of this group at a time)
error({ text: "Session expired.", singleGroup: true, group: "auth-errors" });

// Close a specific notification programmatically
closeSuccess();  // or: close("notification-id")

// Update a notification in-place (e.g. progress update)
const closeProgress = info({ text: "Uploading… 0%" });
// later:
update("notification-id", { text: "Uploading… 75%" });

// Clear all notifications in a group
clear("auth-errors");

// Read the current stack reactively
// stack.value → INotificationExtended[]
```
```

--------------------------------

### Modal System — `useModal()`

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

Lightweight modal stack: push any component + props onto a reactive stack; the `ModalStack` organism renders them in order. Returns a close handle and restores keyboard focus to the trigger element on close.

```APIDOC
## Modal System — `useModal()`

Lightweight modal stack: push any component + props onto a reactive stack; the `ModalStack` organism renders them in order. Returns a close handle and restores keyboard focus to the trigger element on close.

```typescript
// client-app/shared/modal/composables/useModal.ts
import { useModal } from "@/shared/modal";
import MyDialogComponent from "@/shared/catalog/components/product-details-dialog.vue";

const { openModal, closeModal, modalStack } = useModal();

// Open a modal — returns a close handle
const closeHandle = openModal({
  component: MyDialogComponent,
  props: {
    productId: "prod-123",
    onConfirm(data: unknown) {
      console.log("Confirmed:", data);
      closeHandle();
    },
    onCancel() {
      closeHandle();
    },
  },
  triggerElement: document.activeElement as HTMLElement, // focus restored on close
});

// Close by handle
closeHandle();

// Close the topmost modal
closeModal();

// Close a specific modal by id
openModal({ id: "confirm-delete", component: ConfirmModal, props: {} });
closeModal("confirm-delete");

// The stack is reactive — use in templates to conditionally show a backdrop
// modalStack.value.length > 0
```
```

--------------------------------

### createRouter()

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

Creates a Vue Router instance with HTML5 history mode and a locale-aware base path. It enforces authentication and organization membership before each navigation and redirects authenticated users away from public-only routes.

```APIDOC
## createRouter()

### Description
Creates a Vue Router instance with HTML5 history mode and a locale-aware base path. Before each navigation it enforces authentication, organization membership, and redirects authenticated users away from public-only routes (sign-in, sign-up) to the Catalog page or a saved return URL.

### Usage
```typescript
import { createRouter } from "@/router";

const router = createRouter({ base: "/" });
```
```

--------------------------------

### useAnalytics()

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

Global event bus for eCommerce analytics. Allows registering multiple tracker implementations and dispatches events to all registered trackers. Skips events in development mode.

```APIDOC
## useAnalytics()

### Description
Global event bus for eCommerce analytics. Any number of tracker implementations (e.g., Google Analytics, Hotjar) can be registered; each event is dispatched to every registered tracker. Silently skips events in development mode.

### Usage
```typescript
import { useAnalytics } from "@/core/composables/useAnalytics";
import type { TrackerType } from "@/core/types/analytics";

const { analytics, addTracker } = useAnalytics();

// Register a custom tracker
const myTracker: TrackerType = {
  meta: { name: "MyTracker" },
  events: {
    addItemToCart: async (product, quantity) => { /* ... */ },
    removeItemFromCart: async (product) => { /* ... */ },
    placeOrder: async (order) => { /* ... */ },
    clearCart: async (cart) => { /* ... */ },
    addBulkItemsToCart: async (items, context) => { /* ... */ },
    updateCartItem: async (sku, newQty, oldQty) => { /* ... */ },
  },
};

addTracker(myTracker);

// Dispatch events
analytics("addItemToCart", product, 1);
analytics("placeOrder", completedOrder);
```
```

--------------------------------

### Generate Bundle Size Map

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/README.md

Analyzes and generates a map of chunk sizes (e.g., vendor.js, index.js) for optimization. Results are saved in the artifacts folder.

```bash
yarn generate:bundle-map
```

--------------------------------

### Configure Queued Mutations Link

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/client-app/core/api/graphql/config/links/queued-mutations/README.md

Configure the link with specific mutation targets, debounce time, and custom merge logic. The `createQueueTarget` helper ensures type safety for mutation variables.

```typescript
const myConfig: IQueueTargetConfig<MyMutationVariables> = {
  debounceMs: 1000,
  mergeQueued: (a, b) => {
    // Custom merge logic with full type safety for MyMutationVariables
    return { ...a, ...b };
  },
};

createQueuedMutationsLink({
  targets: [
    createQueueTarget("MyMutation", myConfig),
  ],
})
```

--------------------------------

### Import useFocusManagement Composable

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/llms/ui-kit/llms-detailed.txt

Import the useFocusManagement composable from the UI Kit's composables directory. This composable helps manage focus within components.

```typescript
import { useFocusManagement } from "@/ui-kit/composables"
```

--------------------------------

### Product Catalog Operations

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

Provides a feature-rich composable for paginated product listing with faceted search, filters, and URL query parameter synchronization. Supports infinite scroll or load-more pagination.

```APIDOC
## Product Catalog Operations

### Description
Composable function for paginated product listing with advanced features like faceted search, various filters (in-stock, purchased-before, branch), URL query parameter sync, and flexible pagination (infinite scroll or load-more).

### Methods
- `useProducts(options)`: Initializes the product catalog composable with configuration options.
  - `withFacets`: Boolean to include facets in the response.
  - `withImages`: Boolean to include product images.
  - `withZeroPrice`: Boolean to include products with zero price.
  - `useQueryParams`: Boolean to sync with URL query parameters.
  - `catalogPaginationMode`: Sets the pagination mode (e.g., `CATALOG_PAGINATION_MODES.infiniteScroll`).
- `fetchProducts(params)`: Fetches the initial list of products based on provided parameters.
- `fetchMoreProducts(params)`: Fetches the next page of products.
- `applyFilters(filters)`: Applies selected filters and controls to the product list.
- `resetFacetAndControlsFilters()`: Resets all applied filters and controls.
- `showFiltersSidebar()`: Shows the filters sidebar.
- `hideFiltersSidebar()`: Hides the filters sidebar.
- `openBranchesModal()`: Opens a modal for selecting branches.
- `getFacets()`: Retrieves the available facets.

### State
- `products`: Reactive reference to the list of products.
- `facets`: Reactive reference to the available facets.
- `totalProductsCount`: Total number of products matching the criteria.
- `pagesCount`: Total number of pages.
- `currentPage`: Current page number.
- `productsFilters`: Reactive reference to the current filters and controls.
- `fetchingProducts`: Boolean indicating if products are being fetched.
- `fetchingMoreProducts`: Boolean indicating if more products are being loaded.
- `localStorageInStock`: Boolean related to in-stock status in local storage.
- `sortQueryParam`: Reactive reference for the sort query parameter.
- `searchQueryParam`: Reactive reference for the search query parameter.
- `hasSelectedFilters`: Boolean indicating if any filters are selected.
- `isFiltersSidebarVisible`: Boolean indicating if the filters sidebar is visible.

### Example Usage
```typescript
import { useProducts } from "@/shared/catalog/composables";
import { CATALOG_PAGINATION_MODES } from "@/shared/catalog/constants/catalog";

const { products, facets, totalProductsCount, pagesCount, currentPage, productsFilters, fetchingProducts, fetchingMoreProducts, localStorageInStock, sortQueryParam, searchQueryParam, hasSelectedFilters, fetchProducts, fetchMoreProducts, applyFilters, resetFacetAndControlsFilters, showFiltersSidebar, hideFiltersSidebar, isFiltersSidebarVisible, openBranchesModal, getFacets } = useProducts({
  withFacets: true,
  withImages: true,
  withZeroPrice: false,
  useQueryParams: true,
  catalogPaginationMode: CATALOG_PAGINATION_MODES.infiniteScroll,
});

// Fetch first page in a category
await fetchProducts({
  categoryId: "cat-electronics",
  itemsPerPage: 16,
  sort: "priority:desc",
  filter: "price:[10 TO 500]",
  cultureName: "en-US",
  currencyCode: "USD",
  storeId: "Electronics",
});

// Load more (infinite scroll)
await fetchMoreProducts({
  categoryId: "cat-electronics",
  itemsPerPage: 16,
  page: currentPage.value + 1,
});

// Apply user-selected facets & controls
await applyFilters({
  inStock: true,
  purchasedBefore: false,
  branches: ["warehouse-1"],
  facets: productsFilters.value.facets,
  filters: productsFilters.value.filters,
});

// Reset all filters
await resetFacetAndControlsFilters();
```
```

--------------------------------

### Import useModal Composable

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/llms/ui-kit/llms-detailed.txt

Import the useModal composable from the UI Kit's composables directory. This is necessary for using modal-related functionalities.

```typescript
import { useModal } from "@/ui-kit/composables"
```

--------------------------------

### Manage Page Head and SEO with `usePageHead()`

Source: https://context7.com/virtocommerce/vc-frontend/llms.txt

A wrapper around `@unhead/vue`'s `useHead` that applies store-aware title templates and normalizes meta tags for any page.

```typescript
// client-app/core/composables/usePageHead.ts
import { usePageHead } from "@/core/composables";
import { computed } from "vue";

// In a page component setup()
const { product } = useProduct("prod-123");

usePageHead({
  title: computed(() => product.value?.name ?? ""),
  meta: {
    description: computed(() => product.value?.description ?? ""),
    keywords: computed(() => product.value?.metaKeywords ?? ""),
    // robots: "noindex" for private pages
  },
});
// <title>iPhone 15 | My Store</title>
// <meta name="description" content="..." />

```

--------------------------------

### Import useComponentId Composable

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/llms/ui-kit/llms-detailed.txt

Import the useComponentId composable from the UI Kit's composables directory. This is used for generating unique component IDs.

```typescript
import { useComponentId } from "@/ui-kit/composables"
```

--------------------------------

### Vue Template Placeholders

Source: https://github.com/virtocommerce/vc-frontend/blob/dev/llms/ui-kit/llms-page-builder-prompt.md

Use plain text directly within UI Kit components for placeholders. Localization will be handled separately.

```vue
<template>
  <!-- ✅ CORRECT - Use plain text placeholders -->
  <VcButton>Save</VcButton>
  <VcTypography>Product Catalog</VcTypography>
  <VcInput label="Email" placeholder="Enter your email" />
</template>

```