@lovalingo/lovalingo 0.5.5 → 0.5.7

package/dist/hooks/provider/useBundleLoading.d.ts

@@ -0,0 +1,32 @@
+import type React from "react";
+import type { LovalingoAPI, ProjectEntitlements } from "../../utils/api";
+import type { NonLocalizedPathRule } from "../../utils/nonLocalizedPaths";
+import type { PathNormalizationConfig } from "../../utils/pathNormalizer";
+type UseBundleLoadingOptions = {
+    apiRef: React.MutableRefObject<LovalingoAPI>;
+    resolvedApiKey: string;
+    defaultLocale: string;
+    routing: "path" | "query";
+    allLocales: string[];
+    nonLocalizedPaths: NonLocalizedPathRule[];
+    enhancedPathConfig: PathNormalizationConfig;
+    mode: "dom" | undefined;
+    autoApplyRules: boolean;
+    isSeoActive: () => boolean;
+    applySeoBundle: (bundle: {
+        seo?: Record<string, unknown>;
+        alternates?: any;
+        jsonld?: any;
+    } | null, hreflangEnabled: boolean) => void;
+    setEntitlements: React.Dispatch<React.SetStateAction<ProjectEntitlements | null>>;
+    setBrandingEnabled: React.Dispatch<React.SetStateAction<boolean>>;
+    setCachedBrandingEnabled: (enabled: boolean | null | undefined) => void;
+    setCachedLoadingBgColor: (color: string | null | undefined) => void;
+    getCachedLoadingBgColor: () => string;
+};
+export declare function useBundleLoading({ apiRef, resolvedApiKey, defaultLocale, routing, allLocales, nonLocalizedPaths, enhancedPathConfig, mode, autoApplyRules, isSeoActive, applySeoBundle, setEntitlements, setBrandingEnabled, setCachedBrandingEnabled, setCachedLoadingBgColor, getCachedLoadingBgColor, }: UseBundleLoadingOptions): {
+    isLoading: boolean;
+    isNavigatingRef: React.MutableRefObject<boolean>;
+    loadData: (targetLocale: string, previousLocale?: string) => Promise<void>;
+};
+export {};

package/dist/hooks/provider/useBundleLoading.js

@@ -0,0 +1,354 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { hashContent } from "../../utils/hash";
+import { errorDebug, logDebug } from "../../utils/logger";
+import { isNonLocalizedPath, stripLocalePrefix } from "../../utils/nonLocalizedPaths";
+import { processPath } from "../../utils/pathNormalizer";
+import { applyActiveTranslations, restoreDom, setActiveTranslations, setMarkerEngineExclusions } from "../../utils/markerEngine";
+import { useDomRules } from "./useDomRules";
+import { PREHIDE_FAILSAFE_MS, usePrehide } from "./usePrehide";
+const CRITICAL_CACHE_PREFIX = "Lovalingo_critical_v0_3";
+export function useBundleLoading({ apiRef, resolvedApiKey, defaultLocale, routing, allLocales, nonLocalizedPaths, enhancedPathConfig, mode, autoApplyRules, isSeoActive, applySeoBundle, setEntitlements, setBrandingEnabled, setCachedBrandingEnabled, setCachedLoadingBgColor, getCachedLoadingBgColor, }) {
+    const [isLoading, setIsLoading] = useState(false);
+    const retryTimeoutRef = useRef(null);
+    const loadingFailsafeTimeoutRef = useRef(null);
+    const isNavigatingRef = useRef(false);
+    const inFlightLoadKeyRef = useRef(null);
+    const translationCacheRef = useRef(new Map());
+    const exclusionsCacheRef = useRef(null);
+    const { enablePrehide, disablePrehide } = usePrehide();
+    const { applyCachedDomRules, fetchAndApplyDomRules, getCachedDomRules, setAndApplyDomRules } = useDomRules({
+        apiRef,
+        autoApplyRules,
+    });
+    const buildCriticalCacheKey = useCallback((targetLocale, normalizedPath) => {
+        const key = `${resolvedApiKey || "anonymous"}:${targetLocale}:${normalizedPath || "/"}`;
+        return `${CRITICAL_CACHE_PREFIX}:${hashContent(key)}`;
+    }, [resolvedApiKey]);
+    const readCriticalCache = useCallback((targetLocale, normalizedPath) => {
+        const key = buildCriticalCacheKey(targetLocale, normalizedPath);
+        try {
+            const raw = localStorage.getItem(key);
+            if (!raw)
+                return null;
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== "object")
+                return null;
+            const record = parsed;
+            const map = record.map && typeof record.map === "object" && !Array.isArray(record.map) ? record.map : null;
+            const exclusionsRaw = Array.isArray(record.exclusions) ? record.exclusions : [];
+            const exclusions = exclusionsRaw
+                .map((row) => {
+                if (!row || typeof row !== "object")
+                    return null;
+                const r = row;
+                const selector = typeof r.selector === "string" ? r.selector.trim() : "";
+                const type = typeof r.type === "string" ? r.type.trim() : "";
+                if (!selector)
+                    return null;
+                if (type !== "css" && type !== "xpath")
+                    return null;
+                return { selector, type: type };
+            })
+                .filter(Boolean);
+            const bg = typeof record.loading_bg_color === "string" ? record.loading_bg_color.trim() : "";
+            return {
+                map: map || {},
+                exclusions,
+                loading_bg_color: /^#[0-9a-fA-F]{6}$/.test(bg) ? bg : null,
+            };
+        }
+        catch {
+            return null;
+        }
+    }, [buildCriticalCacheKey]);
+    const writeCriticalCache = useCallback((targetLocale, normalizedPath, entry) => {
+        const key = buildCriticalCacheKey(targetLocale, normalizedPath);
+        try {
+            localStorage.setItem(key, JSON.stringify({
+                stored_at: Date.now(),
+                map: entry.map || {},
+                exclusions: entry.exclusions || [],
+                loading_bg_color: entry.loading_bg_color,
+            }));
+        }
+        catch {
+            // ignore
+        }
+    }, [buildCriticalCacheKey]);
+    const toTranslations = useCallback((map, targetLocale) => {
+        const out = [];
+        for (const [source_text, translated_text] of Object.entries(map || {})) {
+            if (!source_text || !translated_text)
+                continue;
+            out.push({
+                source_text,
+                translated_text,
+                source_locale: defaultLocale,
+                target_locale: targetLocale,
+            });
+        }
+        return out;
+    }, [defaultLocale]);
+    const loadData = useCallback(async (targetLocale, previousLocale) => {
+        // Cancel any pending retry scan to prevent race conditions
+        if (retryTimeoutRef.current) {
+            clearTimeout(retryTimeoutRef.current);
+            retryTimeoutRef.current = null;
+        }
+        if (loadingFailsafeTimeoutRef.current != null) {
+            window.clearTimeout(loadingFailsafeTimeoutRef.current);
+            loadingFailsafeTimeoutRef.current = null;
+        }
+        // If switching to default locale, clear translations and translate with empty map
+        // This will show original text using stored data-Lovalingo-original-html
+        if (targetLocale === defaultLocale) {
+            disablePrehide();
+            setActiveTranslations(null);
+            restoreDom(document.body); // React-safe: only text/attrs, no DOM structure mutation
+            isNavigatingRef.current = false;
+            return;
+        }
+        if (routing === "path") {
+            const stripped = stripLocalePrefix(window.location.pathname, allLocales);
+            if (isNonLocalizedPath(stripped, nonLocalizedPaths)) {
+                // Why: auth/admin (non-localized) routes must never be blocked or mutated by the translation runtime.
+                disablePrehide();
+                setActiveTranslations(null);
+                restoreDom(document.body);
+                isNavigatingRef.current = false;
+                return;
+            }
+        }
+        const currentPath = window.location.pathname + window.location.search;
+        const normalizedPath = processPath(window.location.pathname, enhancedPathConfig);
+        const cacheKey = `${targetLocale}:${normalizedPath}`;
+        if (inFlightLoadKeyRef.current === cacheKey) {
+            return;
+        }
+        inFlightLoadKeyRef.current = cacheKey;
+        // Check if we have cached translations for this locale + path
+        const cachedEntry = translationCacheRef.current.get(cacheKey);
+        const cachedExclusions = exclusionsCacheRef.current;
+        const cachedDomRules = getCachedDomRules(cacheKey);
+        if (cachedEntry && cachedExclusions) {
+            // CACHE HIT - Use cached data immediately (FAST!)
+            logDebug(`[Lovalingo] Using cached translations for ${targetLocale} on ${normalizedPath}`);
+            enablePrehide(getCachedLoadingBgColor());
+            setActiveTranslations(cachedEntry.translations);
+            setMarkerEngineExclusions(cachedExclusions);
+            if (mode === "dom") {
+                applyActiveTranslations(document.body);
+            }
+            if (autoApplyRules) {
+                applyCachedDomRules(cacheKey, cachedDomRules);
+                void fetchAndApplyDomRules(cacheKey, targetLocale);
+            }
+            // Delayed retry scan to catch late-rendering content
+            retryTimeoutRef.current = setTimeout(() => {
+                // Don't scan if we're navigating (prevents React conflicts)
+                if (isNavigatingRef.current) {
+                    return;
+                }
+                logDebug(`[Lovalingo] 🔄 Retry scan for late-rendering content`);
+                if (mode === "dom") {
+                    applyActiveTranslations(document.body);
+                }
+                if (autoApplyRules) {
+                    applyCachedDomRules(cacheKey, cachedDomRules);
+                }
+            }, 500);
+            disablePrehide();
+            isNavigatingRef.current = false;
+            if (inFlightLoadKeyRef.current === cacheKey) {
+                inFlightLoadKeyRef.current = null;
+            }
+            return;
+        }
+        // CACHE MISS - Fetch from API
+        logDebug(`[Lovalingo] Fetching translations for ${targetLocale} on ${normalizedPath}`);
+        setIsLoading(true);
+        enablePrehide(getCachedLoadingBgColor());
+        // Why: never keep the app hidden/blocked for longer than the UX budget; show the original content if translations aren't ready fast.
+        loadingFailsafeTimeoutRef.current = window.setTimeout(() => {
+            disablePrehide();
+            setIsLoading(false);
+        }, PREHIDE_FAILSAFE_MS);
+        try {
+            if (previousLocale && previousLocale !== defaultLocale) {
+                logDebug(`[Lovalingo] Switching from ${previousLocale} to ${targetLocale}`);
+            }
+            let revealedViaCachedCritical = false;
+            const cachedCritical = readCriticalCache(targetLocale, normalizedPath);
+            if (cachedCritical?.loading_bg_color) {
+                setCachedLoadingBgColor(cachedCritical.loading_bg_color);
+                enablePrehide(cachedCritical.loading_bg_color);
+            }
+            if (cachedCritical?.exclusions && cachedCritical.exclusions.length > 0) {
+                exclusionsCacheRef.current = cachedCritical.exclusions;
+                setMarkerEngineExclusions(cachedCritical.exclusions);
+            }
+            if (cachedCritical?.map && Object.keys(cachedCritical.map).length > 0) {
+                setActiveTranslations(toTranslations(cachedCritical.map, targetLocale));
+                if (mode === "dom") {
+                    applyActiveTranslations(document.body);
+                }
+                disablePrehide();
+                revealedViaCachedCritical = true;
+            }
+            const bootstrap = await apiRef.current.fetchBootstrap(targetLocale, currentPath);
+            const nextEntitlements = bootstrap?.entitlements || apiRef.current.getEntitlements();
+            if (nextEntitlements)
+                setEntitlements(nextEntitlements);
+            if (bootstrap?.loading_bg_color) {
+                setCachedLoadingBgColor(bootstrap.loading_bg_color);
+                enablePrehide(bootstrap.loading_bg_color);
+            }
+            if ((bootstrap?.entitlements || nextEntitlements)?.brandingRequired) {
+                setBrandingEnabled(true);
+                setCachedBrandingEnabled(true);
+            }
+            else if (typeof bootstrap?.branding_enabled === "boolean") {
+                setBrandingEnabled(bootstrap.branding_enabled);
+                setCachedBrandingEnabled(bootstrap.branding_enabled);
+            }
+            const exclusions = Array.isArray(bootstrap?.exclusions)
+                ? bootstrap.exclusions
+                    .map((row) => {
+                    if (!row || typeof row !== "object")
+                        return null;
+                    const r = row;
+                    const selector = typeof r.selector === "string" ? r.selector.trim() : "";
+                    const type = typeof r.type === "string" ? r.type.trim() : "";
+                    if (!selector)
+                        return null;
+                    if (type !== "css" && type !== "xpath")
+                        return null;
+                    return { selector, type: type };
+                })
+                    .filter(Boolean)
+                : await apiRef.current.fetchExclusions();
+            exclusionsCacheRef.current = exclusions;
+            setMarkerEngineExclusions(exclusions);
+            const criticalMap = bootstrap?.critical?.map && typeof bootstrap.critical.map === "object" && !Array.isArray(bootstrap.critical.map)
+                ? bootstrap.critical.map
+                : {};
+            const hasBootstrapCritical = Object.keys(criticalMap).length > 0;
+            if (Object.keys(criticalMap).length > 0) {
+                setActiveTranslations(toTranslations(criticalMap, targetLocale));
+                if (mode === "dom") {
+                    applyActiveTranslations(document.body);
+                }
+            }
+            if (autoApplyRules) {
+                const bootstrapDomRules = bootstrap?.dom_rules;
+                const domRules = Array.isArray(bootstrapDomRules)
+                    ? bootstrapDomRules
+                    : await apiRef.current.fetchDomRules(targetLocale);
+                setAndApplyDomRules(cacheKey, domRules);
+            }
+            if (isSeoActive() && bootstrap) {
+                const hreflangEnabled = Boolean((bootstrap.entitlements || nextEntitlements)?.hreflangEnabled);
+                applySeoBundle({ seo: bootstrap.seo, alternates: bootstrap.alternates, jsonld: bootstrap.jsonld }, hreflangEnabled);
+            }
+            writeCriticalCache(targetLocale, normalizedPath, {
+                map: criticalMap,
+                exclusions,
+                loading_bg_color: bootstrap?.loading_bg_color && /^#[0-9a-fA-F]{6}$/.test(bootstrap.loading_bg_color) ? bootstrap.loading_bg_color : null,
+            });
+            const shouldWaitForBundle = !revealedViaCachedCritical && !hasBootstrapCritical;
+            if (shouldWaitForBundle) {
+                // Why: if there's no critical slice for first paint, wait for the bundle (within the prehide failsafe) to avoid a visible flash.
+                const bundle = await apiRef.current.fetchBundle(targetLocale, currentPath);
+                if (bundle?.map && typeof bundle.map === "object") {
+                    const translations = toTranslations(bundle.map, targetLocale);
+                    if (translations.length > 0) {
+                        translationCacheRef.current.set(cacheKey, { translations });
+                        setActiveTranslations(translations);
+                        if (mode === "dom") {
+                            applyActiveTranslations(document.body);
+                        }
+                    }
+                }
+            }
+            else {
+                // Lazy-load the full page bundle after first paint.
+                void (async () => {
+                    const bundle = await apiRef.current.fetchBundle(targetLocale, currentPath);
+                    if (!bundle || !bundle.map)
+                        return;
+                    const translations = toTranslations(bundle.map, targetLocale);
+                    if (translations.length === 0)
+                        return;
+                    translationCacheRef.current.set(cacheKey, { translations });
+                    setActiveTranslations(translations);
+                    if (mode === "dom") {
+                        applyActiveTranslations(document.body);
+                    }
+                })();
+            }
+            disablePrehide();
+            // Delayed retry scan to catch late-rendering content
+            retryTimeoutRef.current = setTimeout(() => {
+                // Don't scan if we're navigating (prevents React conflicts)
+                if (isNavigatingRef.current) {
+                    return;
+                }
+                logDebug(`[Lovalingo] 🔄 Retry scan for late-rendering content`);
+                if (mode === "dom") {
+                    applyActiveTranslations(document.body);
+                }
+                if (autoApplyRules) {
+                    applyCachedDomRules(cacheKey);
+                }
+            }, 500);
+        }
+        catch (error) {
+            errorDebug("Error loading translations:", error);
+            disablePrehide();
+        }
+        finally {
+            setIsLoading(false);
+            if (loadingFailsafeTimeoutRef.current != null) {
+                window.clearTimeout(loadingFailsafeTimeoutRef.current);
+                loadingFailsafeTimeoutRef.current = null;
+            }
+            isNavigatingRef.current = false;
+            if (inFlightLoadKeyRef.current === cacheKey) {
+                inFlightLoadKeyRef.current = null;
+            }
+        }
+    }, [
+        allLocales,
+        applyCachedDomRules,
+        applySeoBundle,
+        autoApplyRules,
+        defaultLocale,
+        disablePrehide,
+        enablePrehide,
+        enhancedPathConfig,
+        fetchAndApplyDomRules,
+        getCachedDomRules,
+        getCachedLoadingBgColor,
+        isSeoActive,
+        mode,
+        nonLocalizedPaths,
+        readCriticalCache,
+        routing,
+        setAndApplyDomRules,
+        setBrandingEnabled,
+        setCachedBrandingEnabled,
+        setCachedLoadingBgColor,
+        setEntitlements,
+        toTranslations,
+        writeCriticalCache,
+    ]);
+    useEffect(() => {
+        return () => {
+            if (retryTimeoutRef.current)
+                clearTimeout(retryTimeoutRef.current);
+            if (loadingFailsafeTimeoutRef.current != null)
+                window.clearTimeout(loadingFailsafeTimeoutRef.current);
+        };
+    }, []);
+    return { isLoading, isNavigatingRef, loadData };
+}

package/dist/hooks/provider/useDomRules.d.ts

@@ -0,0 +1,15 @@
+import type React from "react";
+import type { DomRule } from "../../types";
+import type { LovalingoAPI } from "../../utils/api";
+type UseDomRulesOptions = {
+    apiRef: React.MutableRefObject<LovalingoAPI>;
+    autoApplyRules: boolean;
+};
+export declare function useDomRules({ apiRef, autoApplyRules }: UseDomRulesOptions): {
+    applyCachedDomRules: (cacheKey: string, fallbackRules?: DomRule[] | null) => number;
+    fetchAndApplyDomRules: (cacheKey: string, targetLocale: string) => Promise<DomRule[]>;
+    getCachedDomRules: (cacheKey: string) => DomRule[] | undefined;
+    setAndApplyDomRules: (cacheKey: string, rules: DomRule[]) => number;
+    setCachedDomRules: (cacheKey: string, rules: DomRule[]) => void;
+};
+export {};

package/dist/hooks/provider/useDomRules.js

@@ -0,0 +1,38 @@
+import { useCallback, useRef } from "react";
+import { applyDomRules } from "../../utils/domRules";
+export function useDomRules({ apiRef, autoApplyRules }) {
+    const domRulesCacheRef = useRef(new Map());
+    const getCachedDomRules = useCallback((cacheKey) => {
+        return domRulesCacheRef.current.get(cacheKey);
+    }, []);
+    const applyCachedDomRules = useCallback((cacheKey, fallbackRules) => {
+        if (!autoApplyRules)
+            return 0;
+        const rules = domRulesCacheRef.current.get(cacheKey) || fallbackRules || [];
+        return applyDomRules(rules);
+    }, [autoApplyRules]);
+    const setCachedDomRules = useCallback((cacheKey, rules) => {
+        domRulesCacheRef.current.set(cacheKey, rules);
+    }, []);
+    const setAndApplyDomRules = useCallback((cacheKey, rules) => {
+        domRulesCacheRef.current.set(cacheKey, rules);
+        if (!autoApplyRules)
+            return 0;
+        return applyDomRules(rules);
+    }, [autoApplyRules]);
+    const fetchAndApplyDomRules = useCallback(async (cacheKey, targetLocale) => {
+        if (!autoApplyRules)
+            return [];
+        const rules = await apiRef.current.fetchDomRules(targetLocale);
+        domRulesCacheRef.current.set(cacheKey, rules);
+        applyDomRules(rules);
+        return rules;
+    }, [apiRef, autoApplyRules]);
+    return {
+        applyCachedDomRules,
+        fetchAndApplyDomRules,
+        getCachedDomRules,
+        setAndApplyDomRules,
+        setCachedDomRules,
+    };
+}

package/dist/hooks/provider/useLinkAutoPrefix.d.ts

@@ -0,0 +1,12 @@
+import type React from "react";
+import type { NonLocalizedPathRule } from "../../utils/nonLocalizedPaths";
+type UseLinkAutoPrefixOptions = {
+    routing: "path" | "query";
+    autoPrefixLinks: boolean;
+    allLocales: string[];
+    locale: string;
+    navigateRef?: React.MutableRefObject<((path: string) => void) | undefined>;
+    nonLocalizedPaths: NonLocalizedPathRule[];
+};
+export declare function useLinkAutoPrefix({ routing, autoPrefixLinks, allLocales, locale, navigateRef, nonLocalizedPaths, }: UseLinkAutoPrefixOptions): void;
+export {};

package/dist/hooks/provider/useLinkAutoPrefix.js

@@ -0,0 +1,146 @@
+import { useEffect } from "react";
+import { isNonLocalizedPath } from "../../utils/nonLocalizedPaths";
+export function useLinkAutoPrefix({ routing, autoPrefixLinks, allLocales, locale, navigateRef, nonLocalizedPaths, }) {
+    // PATH mode: auto-prefix internal links that are missing a locale segment.
+    // This prevents "losing" the current locale when the app renders absolute links like "/projects/slug"
+    // while the user is on "/de/...".
+    useEffect(() => {
+        if (routing !== "path")
+            return;
+        if (!autoPrefixLinks)
+            return;
+        const supportedLocales = allLocales;
+        const shouldProcessCurrentPath = () => {
+            const parts = window.location.pathname.split("/").filter(Boolean);
+            return parts.length > 0 && supportedLocales.includes(parts[0]);
+        };
+        const buildLocalePrefixedPath = (rawHref) => {
+            if (!rawHref)
+                return null;
+            const trimmed = rawHref.trim();
+            if (!trimmed)
+                return null;
+            // Only rewrite absolute-path or same-origin absolute URLs.
+            const isAbsolutePath = trimmed.startsWith("/");
+            const isAbsoluteUrl = /^https?:\/\//i.test(trimmed) || trimmed.startsWith("//");
+            if (!isAbsolutePath && !isAbsoluteUrl)
+                return null;
+            // Ignore special schemes / fragments
+            if (/^(?:#|mailto:|tel:|sms:|javascript:)/i.test(trimmed))
+                return null;
+            let url;
+            try {
+                url = new URL(trimmed, window.location.origin);
+            }
+            catch {
+                return null;
+            }
+            if (url.origin !== window.location.origin)
+                return null;
+            if (isNonLocalizedPath(url.pathname, nonLocalizedPaths))
+                return null;
+            const parts = url.pathname.split("/").filter(Boolean);
+            // Root ("/") should be locale-prefixed too (e.g. clicking a logo linking to "https://example.com")
+            // when we are currently on a locale URL like "/de/...".
+            if (parts.length === 0) {
+                return `/${locale}${url.search}${url.hash}`;
+            }
+            if (supportedLocales.includes(parts[0]))
+                return null; // already locale-prefixed
+            const pathWithoutLeadingSlashes = url.pathname.replace(/^\/+/, "");
+            const nextPathname = pathWithoutLeadingSlashes ? `/${locale}/${pathWithoutLeadingSlashes}` : `/${locale}`;
+            return `${nextPathname}${url.search}${url.hash}`;
+        };
+        const ORIGINAL_HREF_KEY = "data-Lovalingo-href-original";
+        const patchAnchor = (a) => {
+            if (!a || a.hasAttribute("data-Lovalingo-exclude"))
+                return;
+            const original = a.getAttribute(ORIGINAL_HREF_KEY) ?? a.getAttribute("href") ?? "";
+            if (!a.getAttribute(ORIGINAL_HREF_KEY) && original) {
+                a.setAttribute(ORIGINAL_HREF_KEY, original);
+            }
+            const fixed = buildLocalePrefixedPath(original);
+            if (fixed) {
+                if (a.getAttribute("href") !== fixed)
+                    a.setAttribute("href", fixed);
+            }
+            else if (original) {
+                // If we previously rewrote it, restore the original when it no longer applies.
+                if (a.getAttribute("href") !== original)
+                    a.setAttribute("href", original);
+            }
+        };
+        const patchAllAnchors = () => {
+            if (!shouldProcessCurrentPath())
+                return;
+            document.querySelectorAll("a[href]").forEach((node) => {
+                if (node instanceof HTMLAnchorElement)
+                    patchAnchor(node);
+            });
+        };
+        // Patch existing anchors (also updates when locale changes)
+        patchAllAnchors();
+        // Patch new anchors when the DOM changes
+        const mo = new MutationObserver((mutations) => {
+            if (!shouldProcessCurrentPath())
+                return;
+            for (const mutation of mutations) {
+                mutation.addedNodes.forEach((node) => {
+                    if (!(node instanceof HTMLElement))
+                        return;
+                    if (node instanceof HTMLAnchorElement) {
+                        patchAnchor(node);
+                        return;
+                    }
+                    node.querySelectorAll?.("a[href]").forEach((a) => {
+                        if (a instanceof HTMLAnchorElement)
+                            patchAnchor(a);
+                    });
+                });
+            }
+        });
+        mo.observe(document.body, { childList: true, subtree: true });
+        // Click interception (capture) to handle cases where frameworks (e.g. React Router <Link>)
+        // navigate based on their "to" prop rather than the DOM href attribute.
+        const onClickCapture = (event) => {
+            if (!shouldProcessCurrentPath())
+                return;
+            if (event.defaultPrevented)
+                return;
+            if (event.button !== 0)
+                return;
+            if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+                return;
+            const target = event.target;
+            const a = target?.closest?.("a[href]");
+            if (!a)
+                return;
+            // Let the browser handle new tabs/downloads/etc.
+            if (a.target && a.target !== "_self")
+                return;
+            if (a.hasAttribute("download"))
+                return;
+            if (a.getAttribute("rel")?.includes("external"))
+                return;
+            const original = a.getAttribute(ORIGINAL_HREF_KEY) ?? a.getAttribute("href") ?? "";
+            const fixed = buildLocalePrefixedPath(original);
+            if (!fixed)
+                return;
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            event.stopPropagation();
+            const navigate = navigateRef?.current;
+            if (navigate) {
+                navigate(fixed);
+            }
+            else {
+                window.location.assign(fixed);
+            }
+        };
+        document.addEventListener("click", onClickCapture, true);
+        return () => {
+            mo.disconnect();
+            document.removeEventListener("click", onClickCapture, true);
+        };
+    }, [routing, autoPrefixLinks, allLocales, locale, navigateRef, nonLocalizedPaths]);
+}

package/dist/hooks/provider/useNavigationPrefetch.d.ts

@@ -0,0 +1,12 @@
+import type { PathNormalizationConfig } from "../../utils/pathNormalizer";
+type UseNavigationPrefetchOptions = {
+    resolvedApiKey: string;
+    apiBase: string;
+    defaultLocale: string;
+    locale: string;
+    routing: "path" | "query";
+    allLocales: string[];
+    enhancedPathConfig: PathNormalizationConfig;
+};
+export declare function useNavigationPrefetch({ resolvedApiKey, apiBase, defaultLocale, locale, routing, allLocales, enhancedPathConfig, }: UseNavigationPrefetchOptions): void;
+export {};