@doswiftly/storefront-sdk 4.0.0 → 4.2.0

package/src/react/index.ts

@@ -16,6 +16,7 @@
 export { StorefrontProvider, type StorefrontProviderProps } from './providers/storefront-provider';
 export { StorefrontClientProvider, type StorefrontClientProviderProps } from './providers/storefront-client-provider';
 export { CurrencyProvider, type CurrencyProviderProps } from './providers/currency-provider';
+export { LanguageProvider, type LanguageProviderProps } from './providers/language-provider';
 
 // Hooks
 export { useAuth, type UseAuthOptions, type LoginResult, type LogoutResult, type TokenRenewResult } from './hooks/use-auth';
@@ -26,20 +27,45 @@ export { useCurrency } from './hooks/use-currency';
 // Store hooks (Context-based)
 export { useAuthStore, useAuthStoreApi, useAuthHydrated } from './stores/store-context';
 export { useCurrencyStore, useCurrencyStoreApi } from './stores/store-context';
+export { useLanguageStore, useLanguageStoreApi } from './stores/store-context';
 
 // Store types
 export type { AuthStore, CustomerInfo } from './stores/auth.store';
 export type { CurrencyStore, ShopCurrencyData } from './stores/currency.store';
+export type { LanguageStore } from './stores/language.store';
+export type { ShopConfig } from './types/shop-config';
 
 // Selectors
 export { selectCurrency, selectBaseCurrency, selectSupportedCurrencies, selectIsLoaded } from './stores/currency.store';
+export { selectLanguage, selectDefaultLanguage, selectSupportedLanguages, selectLanguageIsLoaded } from './stores/language.store';
 
 // Cookie utilities
-export { getCookie, setCookie, deleteCookie, getCurrencyFromCookieAsync } from './cookies';
+export { getCookie, setCookie, deleteCookie, getCurrencyFromCookieAsync, getCartIdFromCookieAsync } from './cookies';
+
+// Bot protection
+export { useBotProtection } from './hooks/use-bot-protection';
 
 // Generic hooks
 export { useHydrated } from './hooks/use-hydrated';
 export { useDebouncedValue } from './hooks/use-debounced-value';
 
+// Cart store (DI-based)
+export {
+  createCartStore,
+  selectCartId,
+  selectIsCartOpen,
+  selectCartIsLoading,
+} from './stores/cart.store';
+export type {
+  CartState,
+  CartStoreConfig,
+  CartActions,
+  CartData,
+  CartMutationAction,
+  CartLineInput,
+  CartLineUpdateInput,
+} from './stores/cart.store';
+export { CartProvider, useCartStore, useCartStoreApi } from './stores/cart.context';
+
 // Store context helper
 export { createStoreContext } from './helpers/create-store-context';

package/src/react/providers/language-provider.tsx

@@ -0,0 +1,34 @@
+/**
+ * LanguageProvider — initializes language store from Shop data.
+ *
+ * Thin wrapper that calls useLanguageStore.initialize() on mount
+ * with the shop's language configuration from the server.
+ *
+ * NOTE: This only sets defaultLanguage and supportedLanguages.
+ * The active `language` is set by the template's LanguageSyncProvider
+ * which reads locale from the URL (via next-intl) and calls setLanguage().
+ */
+
+'use client';
+
+import React, { useEffect } from 'react';
+import { useLanguageStore } from '../stores/store-context';
+import type { ShopConfig } from '../types/shop-config';
+
+export interface LanguageProviderProps {
+  children: React.ReactNode;
+  shopData: ShopConfig;
+}
+
+export function LanguageProvider({ children, shopData }: LanguageProviderProps) {
+  const initialize = useLanguageStore((s) => s.initialize);
+  const isLoaded = useLanguageStore((s) => s.isLoaded);
+
+  useEffect(() => {
+    if (!isLoaded) {
+      initialize(shopData);
+    }
+  }, [initialize, isLoaded, shopData]);
+
+  return <>{children}</>;
+}

package/src/react/providers/storefront-client-provider.tsx

@@ -15,10 +15,12 @@ import { CartClient } from '../../core/cart/cart-client';
 import { AuthClient } from '../../core/auth/auth-client';
 import { authMiddleware } from '../../core/middleware/auth';
 import { currencyMiddleware } from '../../core/middleware/currency';
+import { languageMiddleware } from '../../core/middleware/language';
+import { botProtectionMiddleware, type BotProtectionTokenProvider } from '../../core/middleware/bot-protection';
 import { retryMiddleware } from '../../core/middleware/retry';
 import { timeoutMiddleware } from '../../core/middleware/timeout';
 import { errorMiddleware } from '../../core/middleware/errors';
-import { useAuthStoreApi, useCurrencyStoreApi } from '../stores/store-context';
+import { useAuthStoreApi, useCurrencyStoreApi, useLanguageStoreApi } from '../stores/store-context';
 import type { StorefrontClient, StorefrontClientConfig, Middleware } from '../../core/client/types';
 
 export interface StorefrontClientContextValue {
@@ -34,18 +36,25 @@ export interface StorefrontClientProviderProps {
   config: StorefrontClientConfig;
   /**
    * Additional middleware to prepend to the default pipeline.
-   * Default pipeline: auth → currency → [custom] → retry → timeout → errors
+   * Default pipeline: auth → currency → bot-protection → [custom] → retry → timeout → errors
    */
   middleware?: Middleware[];
+  /** Bot protection token provider (created by StorefrontProvider) */
+  botProtection?: BotProtectionTokenProvider | null;
+  /** Operations that require bot protection (from shop query) */
+  botProtectionOperations?: string[];
 }
 
 export function StorefrontClientProvider({
   children,
   config,
   middleware: customMiddleware = [],
+  botProtection,
+  botProtectionOperations,
 }: StorefrontClientProviderProps) {
   const authStore = useAuthStoreApi();
   const currencyStore = useCurrencyStoreApi();
+  const languageStore = useLanguageStoreApi();
 
   const value = useMemo(() => {
     const client = createStorefrontClient({
@@ -54,6 +63,14 @@ export function StorefrontClientProvider({
         // Header middleware (runs first)
         authMiddleware(() => authStore.getState().accessToken),
         currencyMiddleware(() => currencyStore.getState().currency),
+        languageMiddleware(() => languageStore.getState().language),
+        // Bot protection (if configured)
+        ...(botProtection && botProtectionOperations?.length
+          ? [botProtectionMiddleware({
+              tokenProvider: botProtection,
+              protectedOperations: botProtectionOperations,
+            })]
+          : []),
         // Custom middleware from props
         ...customMiddleware,
         // Infrastructure middleware (runs last)
@@ -68,7 +85,7 @@ export function StorefrontClientProvider({
 
     return { client, cartClient, authClient };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [config.apiUrl, config.shopSlug, authStore, currencyStore]);
+  }, [config.apiUrl, config.shopSlug, authStore, currencyStore, languageStore]);
 
   return (
     <StorefrontClientContext.Provider value={value}>

package/src/react/providers/storefront-provider.tsx

@@ -29,11 +29,16 @@
 'use client';
 
 import React, { useRef } from 'react';
-import { AuthStoreContext, CurrencyStoreContext } from '../stores/store-context';
+import { AuthStoreContext, CurrencyStoreContext, LanguageStoreContext } from '../stores/store-context';
 import { createAuthStore } from '../stores/auth.store';
 import { createCurrencyStore } from '../stores/currency.store';
+import { createLanguageStore } from '../stores/language.store';
 import { StorefrontClientProvider, type StorefrontClientProviderProps } from './storefront-client-provider';
 import { CurrencyProvider, type CurrencyProviderProps } from './currency-provider';
+import { LanguageProvider } from './language-provider';
+import { createBotProtectionManager } from '../../core/bot-protection/create-manager';
+import { BotProtectionContext } from '../bot-protection/bot-protection-context';
+import { BotProtectionWidget } from '../bot-protection/bot-protection-widget';
 
 export interface StorefrontProviderProps extends StorefrontClientProviderProps {
   shopData: CurrencyProviderProps['shopData'];
@@ -45,6 +50,12 @@ export interface StorefrontProviderProps extends StorefrontClientProviderProps {
    * Read from cookies() in a Server Component (layout.tsx) and pass here.
    */
   initialIsAuthenticated?: boolean;
+  /**
+   * Server-side language hint — pass the URL locale from next-intl params.
+   * Eliminates flash of wrong language on first render by initializing the
+   * language store with the correct value from the server.
+   */
+  initialLanguage?: string;
 }
 
 export function StorefrontProvider({
@@ -53,18 +64,35 @@ export function StorefrontProvider({
   middleware,
   shopData,
   initialIsAuthenticated,
+  initialLanguage,
 }: StorefrontProviderProps) {
   const authStoreRef = useRef(createAuthStore(initialIsAuthenticated));
   const currencyStoreRef = useRef(createCurrencyStore());
+  const languageStoreRef = useRef(createLanguageStore(initialLanguage));
+  const botProtectionRef = useRef(
+    shopData.botProtection ? createBotProtectionManager(shopData.botProtection) : null,
+  );
 
   return (
     <AuthStoreContext.Provider value={authStoreRef.current}>
       <CurrencyStoreContext.Provider value={currencyStoreRef.current}>
-        <StorefrontClientProvider config={config} middleware={middleware}>
-          <CurrencyProvider shopData={shopData}>
-            {children}
-          </CurrencyProvider>
-        </StorefrontClientProvider>
+        <LanguageStoreContext.Provider value={languageStoreRef.current}>
+          <StorefrontClientProvider
+            config={config}
+            middleware={middleware}
+            botProtection={botProtectionRef.current}
+            botProtectionOperations={shopData.botProtection?.protectedOperations}
+          >
+            <BotProtectionContext.Provider value={{ manager: botProtectionRef.current }}>
+              <CurrencyProvider shopData={shopData}>
+                <LanguageProvider shopData={shopData}>
+                  <BotProtectionWidget manager={botProtectionRef.current} />
+                  {children}
+                </LanguageProvider>
+              </CurrencyProvider>
+            </BotProtectionContext.Provider>
+          </StorefrontClientProvider>
+        </LanguageStoreContext.Provider>
       </CurrencyStoreContext.Provider>
     </AuthStoreContext.Provider>
   );

package/src/react/stores/cart.context.ts

@@ -0,0 +1,10 @@
+'use client';
+
+import { createStoreContext } from '../helpers/create-store-context';
+import type { CartState } from './cart.store';
+
+export const {
+  Provider: CartProvider,
+  useStore: useCartStore,
+  useApi: useCartStoreApi,
+} = createStoreContext<CartState>('CartStore');

package/src/react/stores/cart.store.ts

@@ -0,0 +1,254 @@
+/**
+ * Cart Store — DI-based cart state management with cookie persistence.
+ *
+ * SDK orchestrates cart lifecycle (init, mutations, error handling).
+ * Template provides CartActions implementation via DI (getActions getter).
+ * Cart ID persisted in cookie (SSR/edge visible) — follows currency store pattern.
+ *
+ * @example
+ * ```typescript
+ * import { createCartStore, type CartActions } from '@doswiftly/storefront-sdk/react';
+ *
+ * const actions: CartActions = {
+ *   fetchCart: async (cartId) => api.getCart(cartId),
+ *   createCart: async () => api.createCart().then(c => c.id),
+ *   addLines: async (cartId, lines) => api.addLines(cartId, lines),
+ *   updateLines: async (cartId, lines) => api.updateLines(cartId, lines),
+ *   removeLines: async (cartId, lineIds) => api.removeLines(cartId, lineIds),
+ * };
+ *
+ * const store = createCartStore({ getActions: () => actions });
+ * ```
+ */
+
+import { createStore } from 'zustand/vanilla';
+import type { CartLineInput, CartLineUpdateInput } from '../../core/cart/types';
+import { CART_COOKIE_NAME, CART_COOKIE_MAX_AGE } from '../../core/cart/cookie-config';
+import { getCookie, setCookie, deleteCookie } from '../cookies';
+
+// Re-export input types from core for convenience
+export type { CartLineInput, CartLineUpdateInput } from '../../core/cart/types';
+
+// ---------------------------------------------------------------------------
+// DI Contract
+// ---------------------------------------------------------------------------
+
+/** Minimal cart data returned by DI actions. */
+export interface CartData {
+  id: string;
+  totalQuantity: number;
+}
+
+/** DI contract — template implements these methods. */
+export interface CartActions {
+  /** Fetch cart by ID. Return null if cart expired/not found. */
+  fetchCart: (cartId: string) => Promise<CartData | null>;
+  /** Create new empty cart. Return new cart ID. */
+  createCart: () => Promise<string>;
+  /** Add line items. Return updated cart or throw. */
+  addLines: (cartId: string, lines: CartLineInput[]) => Promise<CartData>;
+  /** Update line quantities. Return updated cart or throw. */
+  updateLines: (cartId: string, lines: CartLineUpdateInput[]) => Promise<CartData>;
+  /** Remove line items. Return updated cart or throw. */
+  removeLines: (cartId: string, lineIds: string[]) => Promise<CartData>;
+}
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+/** Action names passed to mutation callbacks. */
+export type CartMutationAction = 'initCart' | 'addToCart' | 'updateQuantity' | 'removeFromCart';
+
+export interface CartStoreConfig {
+  /** Getter for DI actions — called on every operation (not captured). */
+  getActions: () => CartActions;
+  /** Called after successful mutation. */
+  onMutationSuccess?: (action: CartMutationAction, cart: CartData) => void;
+  /** Called on mutation error. */
+  onMutationError?: (action: CartMutationAction, error: unknown) => void;
+}
+
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+
+export interface CartState {
+  // State
+  cartId: string | null;
+  isOpen: boolean;
+  isLoading: boolean;
+  error: unknown | null;
+
+  // UI Actions (pure state, no side effects)
+  openCart: () => void;
+  closeCart: () => void;
+  toggleCart: () => void;
+
+  // Orchestrated Actions (call DI via getActions)
+  initCart: () => Promise<void>;
+  addToCart: (lines: CartLineInput[]) => Promise<void>;
+  updateQuantity: (lines: CartLineUpdateInput[]) => Promise<void>;
+  removeFromCart: (lineIds: string[]) => Promise<void>;
+  clearCart: () => void;
+}
+
+// ---------------------------------------------------------------------------
+// Selectors
+// ---------------------------------------------------------------------------
+
+export const selectCartId = (state: CartState) => state.cartId;
+export const selectIsCartOpen = (state: CartState) => state.isOpen;
+export const selectCartIsLoading = (state: CartState) => state.isLoading;
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createCartStore(config: CartStoreConfig) {
+  // Deduplication: shared Promise in closure (not in state)
+  let initPromise: Promise<void> | null = null;
+
+  // Read initial cartId from cookie (client-side only, returns null on server)
+  const initialCartId = getCookie(CART_COOKIE_NAME);
+
+  // Clean up old localStorage entry from pre-cookie era (v1 persist)
+  if (typeof localStorage !== 'undefined') {
+    try { localStorage.removeItem('cart-storage'); } catch { /* ignore */ }
+  }
+
+  async function performInit(
+    set: (partial: Partial<CartState> | ((state: CartState) => Partial<CartState>)) => void,
+    get: () => CartState,
+  ): Promise<void> {
+    const actions = config.getActions();
+    set({ isLoading: true, error: null });
+
+    try {
+      const currentCartId = get().cartId;
+
+      if (currentCartId) {
+        const cart = await actions.fetchCart(currentCartId);
+        if (cart) {
+          // Cart exists — keep current cartId
+          set({ isLoading: false });
+          return;
+        }
+        // Cart expired — fall through to create
+      }
+
+      // No cart or expired — create new
+      const newCartId = await actions.createCart();
+      set({ cartId: newCartId, isLoading: false, error: null });
+    } catch (error) {
+      set({ error, isLoading: false });
+      config.onMutationError?.('initCart', error);
+    }
+  }
+
+  const store = createStore<CartState>()(
+    (set, get) => ({
+      // State — initialCartId from cookie
+      cartId: initialCartId,
+      isOpen: false,
+      isLoading: false,
+      error: null,
+
+      // UI Actions
+      openCart: () => set({ isOpen: true }),
+      closeCart: () => set({ isOpen: false }),
+      toggleCart: () => set((state) => ({ isOpen: !state.isOpen })),
+
+      // Orchestrated: initCart (deduplicated)
+      initCart: async () => {
+        if (initPromise) return initPromise;
+        initPromise = performInit(set, get).finally(() => {
+          initPromise = null;
+        });
+        return initPromise;
+      },
+
+      // Orchestrated: addToCart (auto-init if no cartId)
+      addToCart: async (lines: CartLineInput[]) => {
+        const actions = config.getActions();
+        set({ isLoading: true, error: null });
+
+        try {
+          let cartId = get().cartId;
+          if (!cartId) {
+            await get().initCart();
+            cartId = get().cartId;
+          }
+          if (!cartId) {
+            throw new Error('Failed to initialize cart');
+          }
+
+          const cart = await actions.addLines(cartId, lines);
+          set({ isLoading: false, error: null });
+          config.onMutationSuccess?.('addToCart', cart);
+        } catch (error) {
+          set({ error, isLoading: false });
+          config.onMutationError?.('addToCart', error);
+        }
+      },
+
+      // Orchestrated: updateQuantity (error if no cartId)
+      updateQuantity: async (lines: CartLineUpdateInput[]) => {
+        const actions = config.getActions();
+        const cartId = get().cartId;
+
+        if (!cartId) {
+          const err = new Error('Cannot update quantity: no cart exists');
+          set({ error: err });
+          config.onMutationError?.('updateQuantity', err);
+          return;
+        }
+
+        set({ isLoading: true, error: null });
+        try {
+          const cart = await actions.updateLines(cartId, lines);
+          set({ isLoading: false, error: null });
+          config.onMutationSuccess?.('updateQuantity', cart);
+        } catch (error) {
+          set({ error, isLoading: false });
+          config.onMutationError?.('updateQuantity', error);
+        }
+      },
+
+      // Orchestrated: removeFromCart (silent return if no cartId)
+      removeFromCart: async (lineIds: string[]) => {
+        const cartId = get().cartId;
+        if (!cartId) return;
+
+        const actions = config.getActions();
+        set({ isLoading: true, error: null });
+        try {
+          const cart = await actions.removeLines(cartId, lineIds);
+          set({ isLoading: false, error: null });
+          config.onMutationSuccess?.('removeFromCart', cart);
+        } catch (error) {
+          set({ error, isLoading: false });
+          config.onMutationError?.('removeFromCart', error);
+        }
+      },
+
+      // clearCart — reset all state
+      clearCart: () => {
+        set({ cartId: null, isOpen: false, isLoading: false, error: null });
+      },
+    }),
+  );
+
+  // Sync cartId changes to cookie (like currency store pattern)
+  store.subscribe((state, prevState) => {
+    if (state.cartId !== prevState.cartId) {
+      if (state.cartId) {
+        setCookie(CART_COOKIE_NAME, state.cartId, { maxAge: CART_COOKIE_MAX_AGE });
+      } else {
+        deleteCookie(CART_COOKIE_NAME);
+      }
+    }
+  });
+
+  return store;
+}

package/src/react/stores/currency.store.ts

@@ -7,15 +7,14 @@
  */
 
 import { createStore } from 'zustand/vanilla';
+import type { ShopConfig } from '../types/shop-config';
+import { CURRENCY_COOKIE_NAME, CURRENCY_COOKIE_MAX_AGE } from '../../core/currency/cookie-config';
+import { getCookie, setCookie } from '../cookies';
 
-export interface ShopCurrencyData {
-  currencyCode: string;
-  supportedCurrencies: string[];
-  localeToCurrencyMap?: Array<{
-    locale: string;
-    currency: string;
-  }>;
-}
+/**
+ * @deprecated Use ShopConfig instead. Kept for backward compatibility of type exports.
+ */
+export type ShopCurrencyData = ShopConfig;
 
 export interface CurrencyStore {
   // State
@@ -25,29 +24,10 @@ export interface CurrencyStore {
   isLoaded: boolean;
 
   // Actions
-  initialize: (shopData: ShopCurrencyData) => void;
+  initialize: (shopData: ShopConfig) => void;
   setCurrency: (currency: string) => void;
 }
 
-/**
- * Get currency from cookie (client-side).
- */
-function getCurrencyFromCookie(): string | null {
-  if (typeof document === 'undefined') return null;
-  const match = document.cookie.match(/(?:^|;\s*)preferred-currency=([^;]*)/);
-  return match ? decodeURIComponent(match[1]) : null;
-}
-
-/**
- * Set currency in cookie (client-side).
- */
-function setCurrencyCookie(currency: string): void {
-  if (typeof document === 'undefined') return;
-  const maxAge = 365 * 24 * 60 * 60; // 1 year
-  const secure = typeof location !== 'undefined' && location.protocol === 'https:' ? ';secure' : '';
-  document.cookie = `preferred-currency=${encodeURIComponent(currency)};max-age=${maxAge};path=/;samesite=lax${secure}`;
-}
-
 export const createCurrencyStore = () =>
   createStore<CurrencyStore>()((set, get) => ({
     baseCurrency: null,
@@ -55,9 +35,9 @@ export const createCurrencyStore = () =>
     currency: null,
     isLoaded: false,
 
-    initialize: (shopData: ShopCurrencyData) => {
+    initialize: (shopData: ShopConfig) => {
       // 1. Try saved currency from cookie (SSR-safe)
-      const saved = getCurrencyFromCookie();
+      const saved = getCookie(CURRENCY_COOKIE_NAME);
 
       // 2. Try to detect from browser locale
       let detected: string | undefined;
@@ -86,7 +66,7 @@ export const createCurrencyStore = () =>
 
       // Ensure cookie is set if we determined a currency
       if (finalCurrency && !saved) {
-        setCurrencyCookie(finalCurrency);
+        setCookie(CURRENCY_COOKIE_NAME, finalCurrency, { maxAge: CURRENCY_COOKIE_MAX_AGE });
       }
     },
 
@@ -99,7 +79,7 @@ export const createCurrencyStore = () =>
       }
 
       set({ currency });
-      setCurrencyCookie(currency);
+      setCookie(CURRENCY_COOKIE_NAME, currency, { maxAge: CURRENCY_COOKIE_MAX_AGE });
     },
   }));
 

package/src/react/stores/language.store.ts

@@ -0,0 +1,90 @@
+/**
+ * Language store factory — tracks active language for SDK middleware.
+ *
+ * Creates a vanilla Zustand store (not a React hook singleton).
+ * Instance is created in StorefrontProvider via useRef and provided
+ * through React Context — eliminates module duplication in Turbopack.
+ *
+ * KEY PRINCIPLE: URL is the single source of truth for language.
+ * - next-intl middleware uses `preferred-language` cookie (custom name via localeCookie.name)
+ * - This store tracks the active language for SDK X-Lang header
+ * - setLanguage() persists to `preferred-language` cookie
+ * - initialize() sets defaultLanguage and supportedLanguages from Shop query
+ * - setLanguage() is called by LanguageSyncProvider when URL locale changes
+ *
+ * Single `preferred-language` cookie serves both:
+ * - next-intl middleware (locale detection/routing, via localeCookie.name override)
+ * - SDK language store (X-Lang header, framework-agnostic)
+ */
+
+import { createStore } from 'zustand/vanilla';
+import type { ShopConfig } from '../types/shop-config';
+import { LANGUAGE_COOKIE_NAME, LANGUAGE_COOKIE_MAX_AGE } from '../../core/language/cookie-config';
+import { getCookie, setCookie } from '../cookies';
+
+export interface LanguageStore {
+  // State
+  defaultLanguage: string | null;
+  supportedLanguages: string[];
+  language: string | null;
+  isLoaded: boolean;
+
+  // Actions
+  initialize: (shopData: ShopConfig) => void;
+  setLanguage: (language: string) => void;
+}
+
+export const createLanguageStore = (initialLanguage?: string | null) =>
+  createStore<LanguageStore>()((set, get) => ({
+    defaultLanguage: null,
+    supportedLanguages: [],
+    language: initialLanguage ?? null,
+    isLoaded: false,
+
+    initialize: (shopData: ShopConfig) => {
+      const supported = shopData.supportedLanguages ?? [];
+      const current = get().language;
+      const saved = getCookie(LANGUAGE_COOKIE_NAME);
+
+      // Priority: current (from initialLanguage/URL) > cookie (validated) > default
+      const finalLanguage =
+        current && (supported.length === 0 || supported.includes(current))
+          ? current
+          : saved && (supported.length === 0 || supported.includes(saved))
+            ? saved
+            : shopData.defaultLanguage ?? null;
+
+      set({
+        defaultLanguage: shopData.defaultLanguage ?? null,
+        supportedLanguages: supported,
+        language: finalLanguage,
+        isLoaded: true,
+      });
+
+      // Persist cookie if determined from fallback (not already saved)
+      if (finalLanguage && finalLanguage !== saved) {
+        setCookie(LANGUAGE_COOKIE_NAME, finalLanguage, { maxAge: LANGUAGE_COOKIE_MAX_AGE });
+      }
+    },
+
+    setLanguage: (language: string) => {
+      const { supportedLanguages } = get();
+      // Validate vs supported (bypass if empty — LanguageSyncProvider may call before initialize)
+      if (supportedLanguages.length > 0 && !supportedLanguages.includes(language)) {
+        console.warn(`[LanguageStore] Language ${language} not supported`);
+        return;
+      }
+      if (get().language === language) return;
+      setCookie(LANGUAGE_COOKIE_NAME, language, { maxAge: LANGUAGE_COOKIE_MAX_AGE });
+      set({ language });
+    },
+  }));
+
+// ---------------------------------------------------------------------------
+// Selectors (for use with useLanguageStore(selector))
+// ---------------------------------------------------------------------------
+
+export const selectLanguage = (state: LanguageStore) => state.language;
+export const selectDefaultLanguage = (state: LanguageStore) => state.defaultLanguage;
+export const selectSupportedLanguages = (state: LanguageStore) => state.supportedLanguages;
+export const selectLanguageIsLoaded = (state: LanguageStore) => state.isLoaded;