@lovalingo/lovalingo 0.5.5 → 0.5.7

package/dist/components/LanguageSwitcher.js

@@ -161,7 +161,8 @@ export const LanguageSwitcher = ({ locales, currentLocale, onLocaleChange, posit
         gap: '6px',
     };
     const flagButtonStyles = (locale) => ({
-        pointerEvents: 'auto',
+        // Why: the panel stays mounted for the close animation, so buttons must be non-interactive while hidden.
+        pointerEvents: isOpen ? 'auto' : 'none',
         width: '32px',
         height: '32px',
         borderRadius: '50%',
@@ -206,7 +207,7 @@ export const LanguageSwitcher = ({ locales, currentLocale, onLocaleChange, posit
                         e.currentTarget.style.transform = 'scale(1)';
                     }, "aria-label": `Switch to ${locale.toUpperCase()}`, title: locale.toUpperCase(), tabIndex: isOpen ? 0 : -1 }, LANGUAGE_FLAGS[locale] || '🏳️')))),
                 (branding?.required || branding?.enabled) && (React.createElement("div", { style: badgeRowStyles, "aria-label": "Lovalingo branding" },
-                    React.createElement("a", { href: branding.href || 'https://lovalingo.com', target: "_blank", rel: "noreferrer", style: badgeLinkStyles, tabIndex: isOpen ? 0 : -1, "aria-label": "Localized by Lovalingo", title: "Localized by Lovalingo" },
+                    React.createElement("a", { href: branding.href || 'https://lovalingo.com', target: "_blank", rel: "noreferrer", style: { ...badgeLinkStyles, pointerEvents: isOpen ? 'auto' : 'none' }, tabIndex: isOpen ? 0 : -1, "aria-label": "Localized by Lovalingo", title: "Localized by Lovalingo" },
                         React.createElement("span", { style: {
                                 width: '16px',
                                 height: '16px',
@@ -220,8 +221,9 @@ export const LanguageSwitcher = ({ locales, currentLocale, onLocaleChange, posit
                                 flexShrink: 0,
                             } },
                             React.createElement("svg", { width: "16", height: "16", viewBox: "0 0 512 512", fill: "none", "aria-hidden": "true" },
-                                React.createElement("path", { d: "M215.657 429.489C270.707 422.73 289.644 339.333 278 244.5C266.356 149.667 228.54 79.3089 173.49 86.0682C118.44 92.8275 83.253 175.184 94.8971 270.017C106.541 364.85 160.607 436.248 215.657 429.489Z", stroke: "#FFFFFF", strokeWidth: "44", strokeLinecap: "round", strokeLinejoin: "round" }),
-                                React.createElement("path", { d: "M168.218 408.885C188.661 447.333 263.959 447.277 336.399 408.759C408.84 370.242 450.992 307.849 430.549 269.401C410.106 230.953 334.808 231.009 262.368 269.526C189.927 308.044 147.775 370.437 168.218 408.885Z", stroke: "#FFFFFF", strokeWidth: "44", strokeLinecap: "round", strokeLinejoin: "round" }))),
+                                React.createElement("path", { d: "M256 480C379.712 480 480 379.712 480 256C480 132.288 379.712 32 256 32C132.288 32 32 132.288 32 256C32 379.712 132.288 480 256 480Z", fill: "#DA2576" }),
+                                React.createElement("path", { d: "M226.321 415.004C277.097 408.769 294.564 331.846 283.824 244.374C273.084 156.903 238.204 92.0061 187.427 98.2407C136.65 104.475 104.194 180.439 114.934 267.911C125.674 355.383 175.544 421.238 226.321 415.004Z", fill: "white", stroke: "white", strokeWidth: "10" }),
+                                React.createElement("path", { d: "M182.564 395.999C201.42 431.462 270.873 431.411 337.69 395.883C404.508 360.356 443.388 302.806 424.531 267.342C405.675 231.879 336.223 231.931 269.405 267.458C202.588 302.986 163.708 370.535 182.564 395.999Z", fill: "white", stroke: "white", strokeWidth: "10" }))),
                         React.createElement("span", null,
                             branding.label || 'Localized by',
                             " ",

package/dist/components/LovalingoProvider.d.ts

@@ -1 +1,10 @@
-export { LovalingoProvider } from "./AixsterProvider";
+import React from 'react';
+import { LovalingoConfig } from '../types';
+interface LovalingoProviderProps extends LovalingoConfig {
+    children: React.ReactNode;
+    sitemap?: boolean;
+    seo?: boolean;
+    navigateRef?: React.MutableRefObject<((path: string) => void) | undefined>;
+}
+export declare const LovalingoProvider: React.FC<LovalingoProviderProps>;
+export {};

package/dist/components/LovalingoProvider.js

@@ -1 +1,610 @@
-export { LovalingoProvider } from "./AixsterProvider";
+import React, { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { LovalingoContext } from '../context/LovalingoContext';
+import { LangRoutingContext } from '../context/LangRoutingContext';
+import { LovalingoAPI } from '../utils/api';
+import { applyActiveTranslations, setMarkerEngineExclusions, startMarkerEngine } from '../utils/markerEngine';
+import { warnDebug } from '../utils/logger';
+import { isNonLocalizedPath, stripLocalePrefix } from '../utils/nonLocalizedPaths';
+import { processPath } from '../utils/pathNormalizer';
+import { useBundleLoading } from '../hooks/provider/useBundleLoading';
+import { useNavigationPrefetch } from '../hooks/provider/useNavigationPrefetch';
+import { useLinkAutoPrefix } from '../hooks/provider/useLinkAutoPrefix';
+import { usePageviewTracking } from '../hooks/provider/usePageviewTracking';
+import { useSitemapLinkTag } from '../hooks/provider/useSitemapLinkTag';
+import { LanguageSwitcher } from './LanguageSwitcher';
+const LOCALE_STORAGE_KEY = 'Lovalingo_locale';
+const LOADING_BG_STORAGE_PREFIX = "Lovalingo_loading_bg_color";
+const BRANDING_STORAGE_PREFIX = "Lovalingo_branding_enabled";
+export const LovalingoProvider = ({ children, apiKey: apiKeyProp, publicAnonKey, defaultLocale, locales, apiBase = 'https://cdn.lovalingo.com', routing = 'path', // Default to path mode (SEO-friendly, recommended)
+autoPrefixLinks = true, overlayBgColor, autoApplyRules = true, switcherPosition = 'bottom-right', switcherOffsetY = 20, switcherTheme = 'dark', editMode: initialEditMode = false, editKey = 'KeyE', pathNormalization = { enabled: true }, // Enable by default
+mode = 'dom', // Default to legacy DOM mode for backward compatibility
+sitemap = true, // Default: true - Auto-inject sitemap link tag
+seo = true, // Default: true - Can be disabled per project entitlements
+navigateRef, // For path mode routing
+ }) => {
+    const metaKey = typeof document !== "undefined"
+        ? document.querySelector('meta[name="lovalingo-public-anon-key"]')?.content?.trim() || ""
+        : "";
+    const resolvedApiKey = (typeof apiKeyProp === "string" && apiKeyProp.trim().length > 0
+        ? apiKeyProp
+        : typeof publicAnonKey === "string" && publicAnonKey.trim().length > 0
+            ? publicAnonKey
+            : globalThis
+                .__LOVALINGO_PUBLIC_ANON_KEY__ ||
+                globalThis.__LOVALINGO_API_KEY__ ||
+                metaKey ||
+                "");
+    const rawLocales = Array.isArray(locales) ? locales : [];
+    // Stabilize locale lists even when callers pass inline arrays (e.g. locales={["en","de"]})
+    // so effects/callbacks don't re-run every render.
+    const localesKey = rawLocales.join(",");
+    const allLocales = useMemo(() => {
+        const base = rawLocales.includes(defaultLocale) ? rawLocales : [defaultLocale, ...rawLocales];
+        return Array.from(new Set(base));
+    }, [defaultLocale, localesKey, rawLocales]);
+    // Why: read locale synchronously from the URL to avoid an initial default-locale render (EN → FR flash) before effects run.
+    const [locale, setLocaleState] = useState(() => {
+        if (typeof window === "undefined")
+            return defaultLocale;
+        if (routing === "path") {
+            const pathLocale = window.location.pathname.split("/")[1];
+            if (pathLocale && allLocales.includes(pathLocale)) {
+                return pathLocale;
+            }
+        }
+        else if (routing === "query") {
+            const params = new URLSearchParams(window.location.search);
+            const queryLocale = params.get("t") || params.get("locale");
+            if (queryLocale && allLocales.includes(queryLocale)) {
+                return queryLocale;
+            }
+        }
+        try {
+            const stored = localStorage.getItem(LOCALE_STORAGE_KEY);
+            if (stored && allLocales.includes(stored)) {
+                return stored;
+            }
+        }
+        catch {
+            // ignore
+        }
+        return defaultLocale;
+    });
+    const [editMode, setEditMode] = useState(initialEditMode);
+    const enhancedPathConfig = useMemo(() => (routing === "path" ? { ...pathNormalization, supportedLocales: allLocales } : pathNormalization), [allLocales, pathNormalization, routing]);
+    const apiRef = useRef(new LovalingoAPI(resolvedApiKey, apiBase, enhancedPathConfig));
+    useEffect(() => {
+        apiRef.current = new LovalingoAPI(resolvedApiKey, apiBase, enhancedPathConfig);
+    }, [apiBase, enhancedPathConfig, resolvedApiKey]);
+    const routingConfig = useContext(LangRoutingContext);
+    const [entitlements, setEntitlements] = useState(() => apiRef.current.getEntitlements());
+    const { trackPageviewOnce } = usePageviewTracking({ apiRef, resolvedApiKey });
+    const lastNormalizedPathRef = useRef("");
+    const historyPatchedRef = useRef(false);
+    const originalHistoryRef = useRef(null);
+    const onNavigateRef = useRef(() => undefined);
+    const isInternalNavigationRef = useRef(false);
+    const loadingBgStorageKey = `${LOADING_BG_STORAGE_PREFIX}:${resolvedApiKey || "anonymous"}`;
+    const brandingStorageKey = `${BRANDING_STORAGE_PREFIX}:${resolvedApiKey || "anonymous"}`;
+    const readBrandingCache = () => {
+        try {
+            const cached = (localStorage.getItem(brandingStorageKey) || "").trim();
+            if (cached === "0")
+                return false;
+            if (cached === "1")
+                return true;
+        }
+        catch {
+            // ignore
+        }
+        return true;
+    };
+    const [brandingEnabled, setBrandingEnabled] = useState(readBrandingCache);
+    const getCachedLoadingBgColor = useCallback(() => {
+        const configured = (overlayBgColor || "").toString().trim();
+        if (/^#[0-9a-fA-F]{6}$/.test(configured))
+            return configured;
+        try {
+            const cached = localStorage.getItem(loadingBgStorageKey) || "";
+            if (/^#[0-9a-fA-F]{6}$/.test(cached.trim()))
+                return cached.trim();
+        }
+        catch {
+            // ignore
+        }
+        return "#ffffff";
+    }, [loadingBgStorageKey, overlayBgColor]);
+    const setCachedLoadingBgColor = useCallback((color) => {
+        const next = (color || "").toString().trim();
+        if (!/^#[0-9a-fA-F]{6}$/.test(next))
+            return;
+        try {
+            localStorage.setItem(loadingBgStorageKey, next);
+        }
+        catch {
+            // ignore
+        }
+    }, [loadingBgStorageKey]);
+    useEffect(() => {
+        // Why: make `overlayBgColor` the source of truth while keeping the existing cache key for backwards compatibility.
+        const configured = (overlayBgColor || "").toString().trim();
+        if (!/^#[0-9a-fA-F]{6}$/.test(configured))
+            return;
+        setCachedLoadingBgColor(configured);
+    }, [overlayBgColor, setCachedLoadingBgColor]);
+    const setCachedBrandingEnabled = useCallback((enabled) => {
+        try {
+            localStorage.setItem(brandingStorageKey, enabled === false ? "0" : "1");
+        }
+        catch {
+            // ignore
+        }
+    }, [brandingStorageKey]);
+    useEffect(() => {
+        setBrandingEnabled(readBrandingCache());
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [brandingStorageKey]);
+    const config = {
+        apiKey: resolvedApiKey,
+        publicAnonKey: resolvedApiKey,
+        defaultLocale,
+        locales: allLocales,
+        apiBase,
+        routing,
+        autoPrefixLinks,
+        overlayBgColor,
+        switcherPosition,
+        switcherOffsetY,
+        switcherTheme,
+        editMode: initialEditMode,
+        editKey,
+        pathNormalization,
+        mode,
+        autoApplyRules,
+    };
+    const setDocumentLocale = useCallback((nextLocale) => {
+        try {
+            const html = document.documentElement;
+            if (!html)
+                return;
+            html.setAttribute("lang", nextLocale);
+            const rtlLocales = new Set(["ar", "he", "fa", "ur"]);
+            html.setAttribute("dir", rtlLocales.has(nextLocale) ? "rtl" : "ltr");
+        }
+        catch {
+            // ignore
+        }
+    }, []);
+    const isSeoActive = useCallback(() => {
+        // Prop can force-disable SEO; server can also disable per project.
+        const serverEnabled = entitlements?.seoEnabled;
+        if (serverEnabled === false)
+            return false;
+        return seo !== false;
+    }, [entitlements, seo]);
+    // Marker engine: always mark full DOM content for deterministic pipeline extraction.
+    useEffect(() => {
+        const stop = startMarkerEngine({ throttleMs: 120 });
+        return () => stop();
+    }, []);
+    // Detect locale from URL or localStorage
+    const detectLocale = useCallback(() => {
+        // 1. Check URL first based on routing mode
+        if (routing === 'path') {
+            // Path mode: language is in path (/en/pricing, /fr/about)
+            const pathLocale = window.location.pathname.split('/')[1];
+            if (allLocales.includes(pathLocale)) {
+                return pathLocale;
+            }
+        }
+        else if (routing === 'query') {
+            // Query mode: language is in query param (/pricing?t=fr)
+            const params = new URLSearchParams(window.location.search);
+            const queryLocale = params.get('t') || params.get('locale');
+            if (queryLocale && allLocales.includes(queryLocale)) {
+                return queryLocale;
+            }
+        }
+        // 2. Check localStorage (fallback for all routing modes)
+        try {
+            const storedLocale = localStorage.getItem(LOCALE_STORAGE_KEY);
+            if (storedLocale && allLocales.includes(storedLocale)) {
+                return storedLocale;
+            }
+        }
+        catch (e) {
+            // localStorage might be unavailable (SSR, private browsing)
+            warnDebug('localStorage not available:', e);
+        }
+        // 3. Default locale
+        return defaultLocale;
+    }, [allLocales, defaultLocale, routing]);
+    // Fetch entitlements early so SEO can be enabled even on default locale
+    useEffect(() => {
+        if (locale !== defaultLocale)
+            return;
+        if (entitlements)
+            return;
+        let cancelled = false;
+        (async () => {
+            const bootstrap = await apiRef.current.fetchBootstrap(locale, window.location.pathname + window.location.search);
+            if (cancelled)
+                return;
+            if (bootstrap?.entitlements)
+                setEntitlements(bootstrap.entitlements);
+            if (bootstrap?.loading_bg_color)
+                setCachedLoadingBgColor(bootstrap.loading_bg_color);
+            if (bootstrap?.entitlements?.brandingRequired) {
+                setBrandingEnabled(true);
+                setCachedBrandingEnabled(true);
+            }
+            else if (typeof bootstrap?.branding_enabled === "boolean") {
+                setBrandingEnabled(bootstrap.branding_enabled);
+                setCachedBrandingEnabled(bootstrap.branding_enabled);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [defaultLocale, entitlements, locale, setCachedBrandingEnabled, setCachedLoadingBgColor]);
+    const applySeoBundle = useCallback((bundle, hreflangEnabled) => {
+        try {
+            const head = document.head;
+            if (!head)
+                return;
+            if (!bundle)
+                return;
+            const seo = (bundle?.seo && typeof bundle.seo === "object" ? bundle.seo : {});
+            const alternates = (bundle?.alternates && typeof bundle.alternates === "object" ? bundle.alternates : {});
+            const setOrCreateMeta = (attrs, content) => {
+                const key = attrs.name ? `meta[name="${attrs.name}"]` : attrs.property ? `meta[property="${attrs.property}"]` : "";
+                const selector = key || "meta";
+                const existing = selector ? head.querySelector(selector) : null;
+                const el = existing || document.createElement("meta");
+                for (const [k, v] of Object.entries(attrs)) {
+                    el.setAttribute(k, v);
+                }
+                el.setAttribute("content", content);
+                if (!existing)
+                    head.appendChild(el);
+            };
+            const setOrCreateTitle = (value) => {
+                const existing = head.querySelector("title");
+                if (existing) {
+                    existing.textContent = value;
+                    return;
+                }
+                const el = document.createElement("title");
+                el.textContent = value;
+                head.appendChild(el);
+            };
+            const getString = (value) => (typeof value === "string" && value.trim() ? value.trim() : "");
+            const title = getString(seo.title);
+            if (title)
+                setOrCreateTitle(title);
+            const description = getString(seo.description);
+            if (description)
+                setOrCreateMeta({ name: "description" }, description);
+            const robots = getString(seo.robots);
+            if (robots)
+                setOrCreateMeta({ name: "robots" }, robots);
+            const ogTitle = getString(seo.og_title);
+            if (ogTitle)
+                setOrCreateMeta({ property: "og:title" }, ogTitle);
+            const ogDescription = getString(seo.og_description);
+            if (ogDescription)
+                setOrCreateMeta({ property: "og:description" }, ogDescription);
+            const ogImage = getString(seo.og_image);
+            if (ogImage)
+                setOrCreateMeta({ property: "og:image" }, ogImage);
+            const ogImageAlt = getString(seo.og_image_alt);
+            if (ogImageAlt)
+                setOrCreateMeta({ property: "og:image:alt" }, ogImageAlt);
+            const twitterCard = getString(seo.twitter_card);
+            if (twitterCard)
+                setOrCreateMeta({ name: "twitter:card" }, twitterCard);
+            const twitterTitle = getString(seo.twitter_title);
+            if (twitterTitle)
+                setOrCreateMeta({ name: "twitter:title" }, twitterTitle);
+            const twitterDescription = getString(seo.twitter_description);
+            if (twitterDescription)
+                setOrCreateMeta({ name: "twitter:description" }, twitterDescription);
+            const twitterImage = getString(seo.twitter_image);
+            if (twitterImage)
+                setOrCreateMeta({ name: "twitter:image" }, twitterImage);
+            const twitterImageAlt = getString(seo.twitter_image_alt);
+            if (twitterImageAlt)
+                setOrCreateMeta({ name: "twitter:image:alt" }, twitterImageAlt);
+            const canonicalHref = typeof seo.canonical_url === "string" && seo.canonical_url.trim()
+                ? seo.canonical_url.trim()
+                : typeof alternates.canonical === "string" && alternates.canonical.trim()
+                    ? alternates.canonical.trim()
+                    : "";
+            const languages = alternates.languages && typeof alternates.languages === "object" ? alternates.languages : {};
+            const hasAnyAlternate = Boolean(alternates.xDefault) || Object.values(languages).some(Boolean);
+            if (!canonicalHref && !(hreflangEnabled && hasAnyAlternate))
+                return;
+            // Why: search engines may ignore hreflang/canonical when multiple conflicting tags exist (we want sitemap + head parity).
+            head
+                .querySelectorAll('link[rel="canonical"], link[rel="alternate"][hreflang], link[data-Lovalingo="hreflang"], link[data-Lovalingo="canonical"]')
+                .forEach((el) => el.remove());
+            if (canonicalHref) {
+                const canonical = document.createElement("link");
+                canonical.rel = "canonical";
+                canonical.href = canonicalHref;
+                canonical.setAttribute("data-Lovalingo", "canonical");
+                head.appendChild(canonical);
+            }
+            if (!hreflangEnabled)
+                return;
+            for (const [lang, href] of Object.entries(languages)) {
+                if (!href)
+                    continue;
+                const link = document.createElement("link");
+                link.rel = "alternate";
+                link.hreflang = lang;
+                link.href = href;
+                link.setAttribute("data-Lovalingo", "hreflang");
+                head.appendChild(link);
+            }
+            if (alternates.xDefault) {
+                const xDefault = document.createElement("link");
+                xDefault.rel = "alternate";
+                xDefault.hreflang = "x-default";
+                xDefault.href = alternates.xDefault;
+                xDefault.setAttribute("data-Lovalingo", "hreflang");
+                head.appendChild(xDefault);
+            }
+        }
+        catch {
+            // ignore SEO errors
+        }
+    }, []);
+    // Keep <html lang> in sync and apply default-locale SEO (non-default locales use the bootstrap payload).
+    useEffect(() => {
+        setDocumentLocale(locale);
+        if (locale !== defaultLocale)
+            return;
+        if (!isSeoActive())
+            return;
+        void apiRef.current.fetchSeoBundle(locale).then((bundle) => {
+            applySeoBundle(bundle, Boolean(entitlements?.hreflangEnabled));
+        });
+    }, [applySeoBundle, defaultLocale, entitlements, isSeoActive, locale, setDocumentLocale]);
+    const { isLoading, isNavigatingRef, loadData } = useBundleLoading({
+        apiRef,
+        resolvedApiKey,
+        defaultLocale,
+        routing,
+        allLocales,
+        nonLocalizedPaths: routingConfig.nonLocalizedPaths,
+        enhancedPathConfig,
+        mode,
+        autoApplyRules,
+        isSeoActive,
+        applySeoBundle,
+        setEntitlements,
+        setBrandingEnabled,
+        setCachedBrandingEnabled,
+        setCachedLoadingBgColor,
+        getCachedLoadingBgColor,
+    });
+    useEffect(() => {
+        onNavigateRef.current = () => {
+            trackPageviewOnce(window.location.pathname + window.location.search);
+            const nextLocale = detectLocale();
+            const normalizedPath = processPath(window.location.pathname, enhancedPathConfig);
+            const normalizedPathChanged = normalizedPath !== lastNormalizedPathRef.current;
+            lastNormalizedPathRef.current = normalizedPath;
+            // Why: bundles are path-scoped, so SPA navigations within the same locale must trigger a reload for the new route.
+            if (normalizedPathChanged && nextLocale !== defaultLocale && !isInternalNavigationRef.current) {
+                void loadData(nextLocale, locale);
+                return;
+            }
+            if (nextLocale !== locale) {
+                setLocaleState(nextLocale);
+                if (!isInternalNavigationRef.current) {
+                    void loadData(nextLocale, locale);
+                }
+            }
+            else if (mode === "dom" && nextLocale !== defaultLocale) {
+                applyActiveTranslations(document.body);
+            }
+        };
+    }, [defaultLocale, detectLocale, enhancedPathConfig, loadData, locale, mode, trackPageviewOnce]);
+    // SPA router hook-in: patch History API once (prevents stacked wrappers → request storms).
+    useEffect(() => {
+        if (typeof window === "undefined")
+            return;
+        if (historyPatchedRef.current)
+            return;
+        historyPatchedRef.current = true;
+        const historyObj = window.history;
+        const originalPushState = historyObj.pushState.bind(historyObj);
+        const originalReplaceState = historyObj.replaceState.bind(historyObj);
+        originalHistoryRef.current = { pushState: originalPushState, replaceState: originalReplaceState };
+        const safeOnNavigate = () => {
+            try {
+                onNavigateRef.current();
+            }
+            catch {
+                // ignore
+            }
+        };
+        historyObj.pushState = ((...args) => {
+            const ret = originalPushState(...args);
+            safeOnNavigate();
+            return ret;
+        });
+        historyObj.replaceState = ((...args) => {
+            const ret = originalReplaceState(...args);
+            safeOnNavigate();
+            return ret;
+        });
+        window.addEventListener("popstate", safeOnNavigate);
+        window.addEventListener("hashchange", safeOnNavigate);
+        return () => {
+            const originals = originalHistoryRef.current;
+            if (originals) {
+                historyObj.pushState = originals.pushState;
+                historyObj.replaceState = originals.replaceState;
+            }
+            window.removeEventListener("popstate", safeOnNavigate);
+            window.removeEventListener("hashchange", safeOnNavigate);
+            originalHistoryRef.current = null;
+            historyPatchedRef.current = false;
+        };
+    }, []);
+    // Change locale
+    const setLocale = useCallback((newLocale) => {
+        void (async () => {
+            if (!allLocales.includes(newLocale))
+                return;
+            const previousLocale = locale; // Capture current locale before switching
+            // Save to localStorage
+            try {
+                localStorage.setItem(LOCALE_STORAGE_KEY, newLocale);
+            }
+            catch (e) {
+                warnDebug('Failed to save locale to localStorage:', e);
+            }
+            isInternalNavigationRef.current = true;
+            // Prevent MutationObserver work during the switch to avoid React conflicts
+            isNavigatingRef.current = true;
+            // Update URL based on routing strategy
+            if (routing === 'path') {
+                const stripped = stripLocalePrefix(window.location.pathname, allLocales);
+                if (isNonLocalizedPath(stripped, routingConfig.nonLocalizedPaths)) {
+                    // Why: switching languages must not rewrite non-localized routes like "/auth" to "/de/auth".
+                    setLocaleState(newLocale);
+                    isNavigatingRef.current = false;
+                    return;
+                }
+                const pathParts = window.location.pathname.split('/').filter(Boolean);
+                // Strip existing locale
+                if (allLocales.includes(pathParts[0])) {
+                    pathParts.shift();
+                }
+                // Build new path with new locale
+                const basePath = pathParts.join('/');
+                const newPath = `/${newLocale}${basePath ? '/' + basePath : ''}${window.location.search}${window.location.hash}`;
+                // Prefer React Router navigation when available, but gracefully fallback for non-React-Router apps
+                const navigate = navigateRef?.current;
+                if (navigate) {
+                    navigate(newPath);
+                }
+                else {
+                    try {
+                        window.history.pushState({}, '', newPath);
+                    }
+                    catch {
+                        window.location.assign(newPath);
+                    }
+                }
+            }
+            else if (routing === 'query') {
+                const url = new URL(window.location.href);
+                url.searchParams.set('t', newLocale);
+                window.history.pushState({}, '', url.toString());
+            }
+            setLocaleState(newLocale);
+            await loadData(newLocale, previousLocale);
+        })().finally(() => {
+            isInternalNavigationRef.current = false;
+        });
+    }, [allLocales, defaultLocale, locale, routing, loadData, navigateRef, routingConfig.nonLocalizedPaths]);
+    // No string-level "misses" from the client: the pipeline (Browser Rendering) is source-of-truth for string discovery.
+    // Why: prevent init/load effects from re-running (and calling bootstrap/bundle again) when loadData changes due to state updates.
+    const loadDataRef = useRef(loadData);
+    useEffect(() => {
+        loadDataRef.current = loadData;
+    }, [loadData]);
+    const detectLocaleRef = useRef(detectLocale);
+    useEffect(() => {
+        detectLocaleRef.current = detectLocale;
+    }, [detectLocale]);
+    // Initialize
+    useEffect(() => {
+        const initialLocale = detectLocaleRef.current();
+        lastNormalizedPathRef.current = processPath(window.location.pathname, enhancedPathConfig);
+        // Track initial page (fallback discovery for pages not present in the routes feed).
+        trackPageviewOnce(window.location.pathname + window.location.search);
+        // Always prefetch artifacts for the initial locale (pipeline-produced translations + rules).
+        loadDataRef.current(initialLocale);
+        // Set up keyboard shortcut for edit mode
+        const handleKeyPress = (e) => {
+            if (e.code === editKey && (e.ctrlKey || e.metaKey)) {
+                e.preventDefault();
+                setEditMode(prev => !prev);
+            }
+        };
+        window.addEventListener('keydown', handleKeyPress);
+        return () => {
+            window.removeEventListener('keydown', handleKeyPress);
+        };
+    }, [editKey, enhancedPathConfig, trackPageviewOnce]);
+    useSitemapLinkTag({ enabled: sitemap, resolvedApiKey, isSeoActive });
+    useLinkAutoPrefix({
+        routing,
+        autoPrefixLinks,
+        allLocales,
+        locale,
+        navigateRef,
+        nonLocalizedPaths: routingConfig.nonLocalizedPaths,
+    });
+    useNavigationPrefetch({
+        resolvedApiKey,
+        apiBase,
+        defaultLocale,
+        locale,
+        routing,
+        allLocales,
+        enhancedPathConfig,
+    });
+    // Dynamic DOM updates are handled by the marker engine observer (React-safe in-place text/attr updates).
+    // No periodic string-miss reporting. Page discovery is tracked via pageview only.
+    const translateElement = useCallback((element) => {
+        if (mode !== "dom")
+            return;
+        applyActiveTranslations(element);
+    }, []);
+    const translateDOM = useCallback(() => {
+        if (mode !== "dom")
+            return;
+        applyActiveTranslations(document.body);
+    }, []);
+    const toggleEditMode = useCallback(() => {
+        setEditMode(prev => !prev);
+    }, []);
+    const excludeElement = useCallback(async (selector) => {
+        await apiRef.current.saveExclusion(selector, 'css');
+        const exclusions = await apiRef.current.fetchExclusions();
+        setMarkerEngineExclusions(exclusions);
+    }, []);
+    const contextValue = {
+        locale,
+        setLocale,
+        isLoading,
+        translationMap: {},
+        config,
+        translateElement,
+        translateDOM,
+        editMode,
+        toggleEditMode,
+        excludeElement,
+    };
+    return (React.createElement(LovalingoContext.Provider, { value: contextValue },
+        children,
+        (() => {
+            if (routing !== "path")
+                return true;
+            if (typeof window === "undefined")
+                return true;
+            const stripped = stripLocalePrefix(window.location.pathname, allLocales);
+            return !isNonLocalizedPath(stripped, routingConfig.nonLocalizedPaths);
+        })() && (React.createElement(LanguageSwitcher, { locales: allLocales, currentLocale: locale, onLocaleChange: setLocale, position: switcherPosition, offsetY: switcherOffsetY, theme: switcherTheme, branding: {
+                required: Boolean(entitlements?.brandingRequired),
+                enabled: brandingEnabled,
+                href: "https://lovalingo.com",
+            } }))));
+};