@lovalingo/lovalingo 0.5.1 → 0.5.3

package/README.md

@@ -55,7 +55,7 @@ export function App() {
   const navigateRef = useRef();
 
   return (
-    <LangRouter defaultLang="en" langs={["en", "de", "fr"]} navigateRef={navigateRef}>
+    <LangRouter publicAnonKey="aix_your_public_anon_key" defaultLang="en" langs={["en", "de", "fr"]} navigateRef={navigateRef}>
       <LovalingoProvider
         publicAnonKey="aix_your_public_anon_key"
         defaultLocale="en"

package/dist/components/AixsterProvider.js

@@ -1,10 +1,12 @@
-import React, { useMemo, useState, useEffect, useCallback, useRef } from 'react';
+import React, { useMemo, useState, useEffect, useCallback, useRef, useContext } from 'react';
 import { LovalingoContext } from '../context/LovalingoContext';
+import { LangRoutingContext } from '../context/LangRoutingContext';
 import { LovalingoAPI } from '../utils/api';
 import { applyDomRules } from '../utils/domRules';
 import { hashContent } from '../utils/hash';
-import { applyActiveTranslations, restoreDom, setActiveTranslations, setMarkerEngineExclusions, startMarkerEngine } from '../utils/markerEngine';
+import { applyActiveTranslations, getCriticalFingerprint, restoreDom, setActiveTranslations, setMarkerEngineExclusions, startMarkerEngine } from '../utils/markerEngine';
 import { logDebug, warnDebug, errorDebug } from '../utils/logger';
+import { isNonLocalizedPath, stripLocalePrefix } from '../utils/nonLocalizedPaths';
 import { processPath } from '../utils/pathNormalizer';
 import { LanguageSwitcher } from './LanguageSwitcher';
 const LOCALE_STORAGE_KEY = 'Lovalingo_locale';
@@ -75,8 +77,12 @@ navigateRef, // For path mode routing
     useEffect(() => {
         apiRef.current = new LovalingoAPI(resolvedApiKey, apiBase, enhancedPathConfig);
     }, [apiBase, enhancedPathConfig, resolvedApiKey]);
+    const routingConfig = useContext(LangRoutingContext);
     const [entitlements, setEntitlements] = useState(() => apiRef.current.getEntitlements());
     const lastPageviewRef = useRef("");
+    const lastPageviewFingerprintRef = useRef("");
+    const pageviewFingerprintTimeoutRef = useRef(null);
+    const pageviewFingerprintRetryTimeoutRef = useRef(null);
     const lastNormalizedPathRef = useRef("");
     const historyPatchedRef = useRef(false);
     const originalHistoryRef = useRef(null);
@@ -159,6 +165,7 @@ navigateRef, // For path mode routing
     }, [brandingStorageKey]);
     useEffect(() => {
         lastPageviewRef.current = "";
+        lastPageviewFingerprintRef.current = "";
     }, [resolvedApiKey]);
     const trackPageviewOnce = useCallback((path) => {
         const next = (path || "").toString();
@@ -168,6 +175,28 @@ navigateRef, // For path mode routing
             return;
         lastPageviewRef.current = next;
         apiRef.current.trackPageview(next);
+        const trySendFingerprint = () => {
+            if (typeof window === "undefined")
+                return;
+            const markersReady = window.__lovalingoMarkersReady === true;
+            if (!markersReady)
+                return;
+            const fp = getCriticalFingerprint();
+            if (!fp || fp.critical_count <= 0)
+                return;
+            const signature = `${next}|${fp.critical_hash}|${fp.critical_count}`;
+            if (lastPageviewFingerprintRef.current === signature)
+                return;
+            lastPageviewFingerprintRef.current = signature;
+            apiRef.current.trackPageview(next, fp);
+        };
+        if (pageviewFingerprintTimeoutRef.current != null)
+            window.clearTimeout(pageviewFingerprintTimeoutRef.current);
+        if (pageviewFingerprintRetryTimeoutRef.current != null)
+            window.clearTimeout(pageviewFingerprintRetryTimeoutRef.current);
+        // Why: wait briefly for markers/content to settle before computing a critical fingerprint for change detection.
+        pageviewFingerprintTimeoutRef.current = window.setTimeout(trySendFingerprint, 800);
+        pageviewFingerprintRetryTimeoutRef.current = window.setTimeout(trySendFingerprint, 2000);
     }, []);
     const enablePrehide = useCallback((bgColor) => {
         if (typeof document === "undefined")
@@ -528,6 +557,17 @@ navigateRef, // For path mode routing
             isNavigatingRef.current = false;
             return;
         }
+        if (routing === "path") {
+            const stripped = stripLocalePrefix(window.location.pathname, allLocales);
+            if (isNonLocalizedPath(stripped, routingConfig.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}`;
@@ -811,6 +851,13 @@ navigateRef, // For path mode routing
             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])) {
@@ -843,7 +890,7 @@ navigateRef, // For path mode routing
         })().finally(() => {
             isInternalNavigationRef.current = false;
         });
-    }, [allLocales, locale, routing, loadData, navigateRef]);
+    }, [allLocales, locale, routing, loadData, navigateRef, routingConfig.nonLocalizedPaths]);
     // No string-level "misses" from the client: the pipeline (Browser Rendering) is source-of-truth for string discovery.
     // Initialize
     useEffect(() => {
@@ -903,13 +950,6 @@ navigateRef, // For path mode routing
         if (!autoPrefixLinks)
             return;
         const supportedLocales = allLocales;
-        const isAssetPath = (pathname) => {
-            if (pathname === '/robots.txt' || pathname === '/sitemap.xml')
-                return true;
-            if (pathname.startsWith('/.well-known/'))
-                return true;
-            return /\.(?:png|jpg|jpeg|gif|svg|webp|avif|ico|css|js|map|json|xml|txt|pdf|zip|gz|br|woff2?|ttf|eot)$/i.test(pathname);
-        };
         const shouldProcessCurrentPath = () => {
             const parts = window.location.pathname.split('/').filter(Boolean);
             return parts.length > 0 && supportedLocales.includes(parts[0]);
@@ -937,7 +977,7 @@ navigateRef, // For path mode routing
             }
             if (url.origin !== window.location.origin)
                 return null;
-            if (isAssetPath(url.pathname))
+            if (isNonLocalizedPath(url.pathname, routingConfig.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")
@@ -1044,7 +1084,7 @@ navigateRef, // For path mode routing
             mo.disconnect();
             document.removeEventListener('click', onClickCapture, true);
         };
-    }, [routing, autoPrefixLinks, allLocales, locale, navigateRef]);
+    }, [routing, autoPrefixLinks, allLocales, locale, navigateRef, routingConfig.nonLocalizedPaths]);
     // Navigation prefetch: warm the HTTP cache for bootstrap + page bundle before the user clicks (reduces EN→FR flash on SPA route changes).
     useEffect(() => {
         if (!resolvedApiKey)
@@ -1156,9 +1196,16 @@ navigateRef, // For path mode routing
     };
     return (React.createElement(LovalingoContext.Provider, { value: contextValue },
         children,
-        React.createElement(LanguageSwitcher, { locales: allLocales, currentLocale: locale, onLocaleChange: setLocale, position: switcherPosition, offsetY: switcherOffsetY, theme: switcherTheme, branding: {
+        (() => {
+            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",
-            } })));
+            } }))));
 };

package/dist/components/LangLink.js

@@ -1,10 +1,9 @@
 import React from 'react';
 import { Link } from 'react-router-dom';
 import { useLang } from '../hooks/useLang';
-const NON_LOCALIZED_APP_PATHS = new Set([
-    'robots.txt',
-    'sitemap.xml',
-]);
+import { useContext } from 'react';
+import { LangRoutingContext } from '../context/LangRoutingContext';
+import { isNonLocalizedPath } from '../utils/nonLocalizedPaths';
 /**
  * LangLink - Language-aware Link component
  *
@@ -24,12 +23,13 @@ const NON_LOCALIZED_APP_PATHS = new Set([
  */
 export function LangLink({ to, ...props }) {
     const lang = useLang();
+    const routing = useContext(LangRoutingContext);
     // If 'to' is a string, prepend language
     const langTo = typeof to === 'string'
         ? (() => {
-            const trimmed = to.replace(/^\//, '');
-            const firstSegment = trimmed.split('/')[0] || '';
-            return NON_LOCALIZED_APP_PATHS.has(firstSegment) ? `/${trimmed}` : `/${lang}/${trimmed}`;
+            const trimmed = (to || '').toString().trim();
+            const normalized = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+            return isNonLocalizedPath(normalized, routing.nonLocalizedPaths) ? normalized : `/${lang}${normalized}`;
         })()
         : to;
     return React.createElement(Link, { ...props, to: langTo });

package/dist/components/LangRouter.d.ts

@@ -4,6 +4,9 @@ interface LangRouterProps {
     defaultLang: string;
     langs: string[];
     navigateRef?: React.MutableRefObject<((path: string) => void) | undefined>;
+    apiBase?: string;
+    apiKey?: string;
+    publicAnonKey?: string;
 }
 /**
  * LangRouter - Drop-in replacement for BrowserRouter that automatically handles language routing
@@ -30,5 +33,5 @@ interface LangRouterProps {
  * - /fr/pricing
  * - etc.
  */
-export declare function LangRouter({ children, defaultLang, langs, navigateRef }: LangRouterProps): React.JSX.Element;
+export declare function LangRouter({ children, defaultLang, langs, navigateRef, apiBase, apiKey, publicAnonKey }: LangRouterProps): React.JSX.Element;
 export {};

package/dist/components/LangRouter.js

@@ -1,17 +1,9 @@
-import React, { useEffect } from 'react';
-import { BrowserRouter, Routes, Route, Navigate, Outlet, useLocation, useNavigate } from 'react-router-dom';
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import { BrowserRouter, Routes, Route, Outlet, useLocation, useNavigate } from 'react-router-dom';
 import { LangContext } from '../context/LangContext';
-const NON_LOCALIZED_APP_PATHS = new Set([
-    '/robots.txt',
-    '/sitemap.xml',
-]);
-function isNonLocalizedPath(pathname) {
-    if (NON_LOCALIZED_APP_PATHS.has(pathname))
-        return true;
-    if (pathname.startsWith('/.well-known/'))
-        return true;
-    return /\.(?:png|jpg|jpeg|gif|svg|webp|avif|ico|css|js|map|json|xml|txt|pdf|zip|gz|br|woff2?|ttf|eot)$/i.test(pathname);
-}
+import { LangRoutingContext } from '../context/LangRoutingContext';
+import { isNonLocalizedPath, parseBootstrapNonLocalizedPaths } from '../utils/nonLocalizedPaths';
+import { logDebug } from '../utils/logger';
 /**
  * NavigateExporter - Internal component that exports navigate function via ref
  */
@@ -27,29 +19,42 @@ function NavigateExporter({ navigateRef }) {
 /**
  * LangGuard - Internal component that validates language and provides it to children
  */
-function LangGuard({ defaultLang, lang }) {
+function LangGuard({ lang, nonLocalizedPaths, }) {
     const location = useLocation();
+    const navigate = useNavigate();
     // If the URL is language-prefixed but the underlying route is non-localized (e.g. robots/sitemap),
     // redirect to the canonical non-localized path.
     const prefix = `/${lang}`;
     const restPath = location.pathname.startsWith(prefix) ? location.pathname.slice(prefix.length) || '/' : location.pathname;
-    if (isNonLocalizedPath(restPath)) {
+    const shouldDePrefix = isNonLocalizedPath(restPath, nonLocalizedPaths);
+    useEffect(() => {
+        if (!shouldDePrefix)
+            return;
         const nextPath = `${restPath}${location.search}${location.hash}`;
-        return React.createElement(Navigate, { to: nextPath, replace: true });
-    }
+        navigate(nextPath, { replace: true });
+    }, [location.hash, location.search, navigate, restPath, shouldDePrefix]);
     // Valid language - render children (user's routes)
     return (React.createElement(LangContext.Provider, { value: lang },
         React.createElement(Outlet, { context: { lang } })));
 }
-function RedirectToDefaultLang({ defaultLang, children }) {
+function RedirectToDefaultLang({ defaultLang, children, nonLocalizedPaths, routingStatus, }) {
     const location = useLocation();
-    if (isNonLocalizedPath(location.pathname)) {
-        return React.createElement(React.Fragment, null, children);
-    }
-    const nextPath = location.pathname === '/' || location.pathname === ''
-        ? `/${defaultLang}${location.search}${location.hash}`
-        : `/${defaultLang}${location.pathname}${location.search}${location.hash}`;
-    return React.createElement(Navigate, { to: nextPath, replace: true });
+    const navigate = useNavigate();
+    const shouldSkip = isNonLocalizedPath(location.pathname, nonLocalizedPaths);
+    useEffect(() => {
+        if (shouldSkip)
+            return;
+        if (routingStatus === "loading")
+            return;
+        const nextPath = location.pathname === "/" || location.pathname === ""
+            ? `/${defaultLang}${location.search}${location.hash}`
+            : `/${defaultLang}${location.pathname}${location.search}${location.hash}`;
+        const current = `${location.pathname}${location.search}${location.hash}`;
+        if (nextPath === current)
+            return;
+        navigate(nextPath, { replace: true });
+    }, [defaultLang, location.hash, location.pathname, location.search, navigate, routingStatus, shouldSkip]);
+    return React.createElement(React.Fragment, null, children);
 }
 /**
  * LangRouter - Drop-in replacement for BrowserRouter that automatically handles language routing
@@ -76,12 +81,92 @@ function RedirectToDefaultLang({ defaultLang, children }) {
  * - /fr/pricing
  * - etc.
  */
-export function LangRouter({ children, defaultLang, langs, navigateRef }) {
+export function LangRouter({ children, defaultLang, langs, navigateRef, apiBase, apiKey, publicAnonKey }) {
+    const metaKey = typeof document !== "undefined"
+        ? document.querySelector('meta[name="lovalingo-public-anon-key"]')?.content?.trim() || ""
+        : "";
+    const globals = globalThis;
+    const resolvedApiKey = (typeof apiKey === "string" && apiKey.trim().length > 0
+        ? apiKey
+        : typeof publicAnonKey === "string" && publicAnonKey.trim().length > 0
+            ? publicAnonKey
+            : globals.__LOVALINGO_PUBLIC_ANON_KEY__ || globals.__LOVALINGO_API_KEY__ || metaKey || "").trim();
+    const resolvedApiBase = (typeof apiBase === "string" && apiBase.trim().length > 0
+        ? apiBase.trim()
+        : "https://cdn.lovalingo.com");
+    const nonLocalizedStorageKey = useMemo(() => `Lovalingo_non_localized_paths:${resolvedApiKey || "anonymous"}`, [resolvedApiKey]);
+    const [nonLocalizedPaths, setNonLocalizedPaths] = useState(() => {
+        if (typeof window === "undefined")
+            return [];
+        if (!resolvedApiKey)
+            return [];
+        try {
+            const raw = localStorage.getItem(nonLocalizedStorageKey);
+            if (!raw)
+                return [];
+            const parsed = JSON.parse(raw);
+            return parseBootstrapNonLocalizedPaths(parsed);
+        }
+        catch {
+            return [];
+        }
+    });
+    const [routingStatus, setRoutingStatus] = useState(() => {
+        if (!resolvedApiKey)
+            return "unknown";
+        return nonLocalizedPaths.length > 0 ? "ready" : "loading";
+    });
+    const fetchNonLocalizedPaths = useCallback(async () => {
+        if (typeof window === "undefined")
+            return;
+        if (!resolvedApiKey)
+            return;
+        const pathParam = window.location.pathname + window.location.search;
+        const requestUrl = `${resolvedApiBase}/functions/v1/bootstrap?key=${encodeURIComponent(resolvedApiKey)}&locale=${encodeURIComponent(defaultLang)}&path=${encodeURIComponent(pathParam)}`;
+        const response = await fetch(requestUrl);
+        const resolvedResponse = response.status === 304 ? await fetch(requestUrl, { cache: "force-cache" }) : response;
+        if (!resolvedResponse.ok)
+            throw new Error(`bootstrap HTTP ${resolvedResponse.status}`);
+        const data = (await resolvedResponse.json());
+        const record = (data || {});
+        return parseBootstrapNonLocalizedPaths(record["non_localized_paths"]);
+    }, [defaultLang, resolvedApiBase, resolvedApiKey]);
+    useEffect(() => {
+        let cancelled = false;
+        void (async () => {
+            if (!resolvedApiKey)
+                return;
+            setRoutingStatus((prev) => (prev === "ready" ? prev : "loading"));
+            try {
+                const next = await fetchNonLocalizedPaths();
+                if (cancelled || !next)
+                    return;
+                setNonLocalizedPaths(next);
+                setRoutingStatus("ready");
+                try {
+                    localStorage.setItem(nonLocalizedStorageKey, JSON.stringify(next));
+                }
+                catch {
+                    // ignore
+                }
+            }
+            catch (err) {
+                if (cancelled)
+                    return;
+                setRoutingStatus("error");
+                logDebug("[Lovalingo] Failed to fetch non-localized paths:", err);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [fetchNonLocalizedPaths, nonLocalizedStorageKey, resolvedApiKey]);
     return (React.createElement(BrowserRouter, null,
         React.createElement(NavigateExporter, { navigateRef: navigateRef }),
-        React.createElement(Routes, null,
-            langs.map((lang) => (React.createElement(Route, { key: lang, path: `${lang}/*`, element: React.createElement(LangGuard, { defaultLang: defaultLang, lang: lang }) },
-                React.createElement(Route, { index: true, element: React.createElement(React.Fragment, null, children) }),
-                React.createElement(Route, { path: "*", element: React.createElement(React.Fragment, null, children) })))),
-            React.createElement(Route, { path: "*", element: React.createElement(RedirectToDefaultLang, { defaultLang: defaultLang }, children) }))));
+        React.createElement(LangRoutingContext.Provider, { value: { nonLocalizedPaths, status: routingStatus } },
+            React.createElement(Routes, null,
+                langs.map((lang) => (React.createElement(Route, { key: lang, path: `${lang}/*`, element: React.createElement(LangGuard, { lang: lang, nonLocalizedPaths: nonLocalizedPaths }) },
+                    React.createElement(Route, { index: true, element: React.createElement(React.Fragment, null, children) }),
+                    React.createElement(Route, { path: "*", element: React.createElement(React.Fragment, null, children) })))),
+                React.createElement(Route, { path: "*", element: React.createElement(RedirectToDefaultLang, { defaultLang: defaultLang, nonLocalizedPaths: nonLocalizedPaths, routingStatus: routingStatus }, children) })))));
 }

package/dist/context/LangRoutingContext.d.ts

@@ -0,0 +1,6 @@
+import type { NonLocalizedPathRule } from "../utils/nonLocalizedPaths";
+export type LangRoutingContextValue = {
+    nonLocalizedPaths: NonLocalizedPathRule[];
+    status: "unknown" | "loading" | "ready" | "error";
+};
+export declare const LangRoutingContext: import("react").Context<LangRoutingContextValue>;

package/dist/context/LangRoutingContext.js

@@ -0,0 +1,5 @@
+import { createContext } from "react";
+export const LangRoutingContext = createContext({
+    nonLocalizedPaths: [],
+    status: "unknown",
+});

package/dist/hooks/useLangNavigate.js

@@ -1,11 +1,8 @@
 import { useNavigate } from 'react-router-dom';
-import { useCallback } from 'react';
+import { useCallback, useContext } from 'react';
 import { useLang } from './useLang';
-//Globally excluded paths.
-const NON_LOCALIZED_APP_PATHS = new Set([
-    'robots.txt',
-    'sitemap.xml',
-]);
+import { LangRoutingContext } from '../context/LangRoutingContext';
+import { isNonLocalizedPath } from '../utils/nonLocalizedPaths';
 /**
  * useLangNavigate - Get a language-aware navigate function
  *
@@ -29,12 +26,13 @@ const NON_LOCALIZED_APP_PATHS = new Set([
 export function useLangNavigate() {
     const navigate = useNavigate();
     const lang = useLang();
+    const routing = useContext(LangRoutingContext);
     return useCallback((path, options) => {
-        const trimmed = path.replace(/^\//, '');
-        const firstSegment = trimmed.split('/')[0] || '';
-        const fullPath = NON_LOCALIZED_APP_PATHS.has(firstSegment)
-            ? `/${trimmed}`
-            : `/${lang}/${trimmed}`;
+        const trimmed = (path || "").toString().trim();
+        if (!trimmed)
+            return;
+        const normalized = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+        const fullPath = isNonLocalizedPath(normalized, routing.nonLocalizedPaths) ? normalized : `/${lang}${normalized}`;
         navigate(fullPath, options);
-    }, [lang, navigate]);
+    }, [lang, navigate, routing.nonLocalizedPaths]);
 }

package/dist/utils/api.d.ts

@@ -25,6 +25,11 @@ export type BootstrapResponse = {
     locale?: string;
     normalized_path?: string;
     routing_strategy?: string;
+    non_localized_paths?: Array<{
+        pattern?: string;
+        match_type?: string;
+        updated_at?: string | null;
+    }>;
     loading_bg_color?: string | null;
     branding_enabled?: boolean;
     seoEnabled?: boolean;
@@ -65,7 +70,10 @@ export declare class LovalingoAPI {
     getEntitlements(): ProjectEntitlements | null;
     fetchEntitlements(localeHint: string): Promise<ProjectEntitlements | null>;
     fetchSeoBundle(localeHint: string): Promise<SeoBundleResponse | null>;
-    trackPageview(pathOrUrl: string): Promise<void>;
+    trackPageview(pathOrUrl: string, opts?: {
+        critical_count?: number;
+        critical_hash?: string;
+    }): Promise<void>;
     fetchTranslations(sourceLocale: string, targetLocale: string): Promise<Translation[]>;
     fetchBundle(localeHint: string, pathOrUrl?: string): Promise<{
         map: Record<string, string>;

package/dist/utils/api.js

@@ -117,11 +117,23 @@ export class LovalingoAPI {
             return null;
         }
     }
-    async trackPageview(pathOrUrl) {
+    async trackPageview(pathOrUrl, opts) {
         try {
             if (!this.hasApiKey())
                 return;
-            const response = await fetch(`${this.apiBase}/functions/v1/pageview?key=${encodeURIComponent(this.apiKey)}&path=${encodeURIComponent(pathOrUrl)}`, { method: "GET", keepalive: true });
+            const params = new URLSearchParams();
+            params.set("key", this.apiKey);
+            params.set("path", pathOrUrl);
+            const count = opts?.critical_count;
+            const hash = (opts?.critical_hash || "").toString().trim().toLowerCase();
+            if (typeof count === "number" && Number.isFinite(count) && count > 0 && count <= 5000 && /^[a-z0-9]{1,40}$/.test(hash)) {
+                params.set("critical_count", String(Math.floor(count)));
+                params.set("critical_hash", hash);
+            }
+            const response = await fetch(`${this.apiBase}/functions/v1/pageview?${params.toString()}`, {
+                method: "GET",
+                keepalive: true,
+            });
             if (response.status === 403) {
                 // Tracking should never block app behavior; keep logging consistent.
                 this.logActivationRequired("trackPageview", response);

package/dist/utils/markerEngine.d.ts

@@ -39,6 +39,15 @@ export type DomScanResult = {
     };
     truncated: boolean;
 };
+export type CriticalFingerprint = {
+    critical_count: number;
+    critical_hash: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+};
+export declare function getCriticalFingerprint(): CriticalFingerprint;
 export declare function startMarkerEngine(options?: MarkerEngineOptions): typeof stopMarkerEngine;
 export declare function stopMarkerEngine(): void;
 export declare function getMarkerStats(): MarkerStats;

package/dist/utils/markerEngine.js

@@ -50,6 +50,7 @@ function setGlobalStats(stats) {
         g.__lovalingo.dom = {};
     g.__lovalingo.dom.getStats = () => lastStats;
     g.__lovalingo.dom.scan = () => scanDom({ maxSegments: 20000, includeCritical: true });
+    g.__lovalingo.dom.getCriticalFingerprint = () => getCriticalFingerprint();
     g.__lovalingo.dom.apply = (bundle) => ({ applied: applyTranslationMap(bundle, document.body) });
     g.__lovalingo.dom.restore = () => restoreDom(document.body);
 }
@@ -314,6 +315,98 @@ function finalizeStats(stats) {
     stats.coverageRatio = eligibleNodes > 0 ? stats.markedNodes / eligibleNodes : 1;
     stats.coverageRatioChars = eligibleChars > 0 ? stats.markedChars / eligibleChars : 1;
 }
+function scanCriticalTexts() {
+    const root = document.body;
+    const viewportHeight = Math.max(0, Math.floor(window.innerHeight || 0));
+    const viewportWidth = Math.max(0, Math.floor(window.innerWidth || 0));
+    const viewport = { width: viewportWidth, height: viewportHeight };
+    if (!root || viewportHeight <= 0)
+        return { texts: [], viewport };
+    const seen = new Set();
+    const texts = [];
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+    let node = walker.nextNode();
+    while (node && texts.length < DEFAULT_CRITICAL_MAX) {
+        if (node.nodeType !== Node.TEXT_NODE) {
+            node = walker.nextNode();
+            continue;
+        }
+        const textNode = node;
+        const raw = textNode.nodeValue || "";
+        const trimmed = raw.trim();
+        if (!trimmed || !isTranslatableText(trimmed)) {
+            node = walker.nextNode();
+            continue;
+        }
+        const parent = textNode.parentElement;
+        if (!parent || isExcludedElement(parent) || findUnsafeContainer(parent)) {
+            node = walker.nextNode();
+            continue;
+        }
+        const original = getOrInitTextOriginal(textNode, parent);
+        const originalText = normalizeWhitespace(original.trimmed);
+        if (!originalText || seen.has(originalText)) {
+            node = walker.nextNode();
+            continue;
+        }
+        const rect = getTextNodeRect(textNode);
+        if (!isInViewport(rect, viewportHeight, DEFAULT_CRITICAL_BUFFER_PX)) {
+            node = walker.nextNode();
+            continue;
+        }
+        seen.add(originalText);
+        texts.push(originalText);
+        node = walker.nextNode();
+    }
+    if (texts.length < DEFAULT_CRITICAL_MAX) {
+        const nodes = root.querySelectorAll("[title],[aria-label],[placeholder]");
+        nodes.forEach((el) => {
+            if (texts.length >= DEFAULT_CRITICAL_MAX)
+                return;
+            if (isExcludedElement(el) || findUnsafeContainer(el))
+                return;
+            let rect = null;
+            try {
+                rect = el.getBoundingClientRect();
+            }
+            catch {
+                rect = null;
+            }
+            if (!isInViewport(rect, viewportHeight, DEFAULT_CRITICAL_BUFFER_PX))
+                return;
+            for (const { attr } of ATTRIBUTE_MARKS) {
+                if (texts.length >= DEFAULT_CRITICAL_MAX)
+                    break;
+                const value = el.getAttribute(attr);
+                if (!value)
+                    continue;
+                const trimmed = value.trim();
+                if (!trimmed || !isTranslatableText(trimmed))
+                    continue;
+                const original = normalizeWhitespace(getOrInitAttrOriginal(el, attr));
+                if (!original || seen.has(original))
+                    continue;
+                seen.add(original);
+                texts.push(original);
+            }
+        });
+    }
+    return { texts, viewport };
+}
+export function getCriticalFingerprint() {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+        return { critical_count: 0, critical_hash: "0", viewport: { width: 0, height: 0 } };
+    }
+    const { texts, viewport } = scanCriticalTexts();
+    const normalized = texts.map((t) => normalizeWhitespace(t)).filter(Boolean);
+    // Why: sort to stay stable across minor DOM reordering without affecting the set of critical strings.
+    normalized.sort((a, b) => a.localeCompare(b));
+    return {
+        critical_count: normalized.length,
+        critical_hash: hashContent(normalized.join("\n")),
+        viewport,
+    };
+}
 function scanDom(opts) {
     const root = document.body;
     if (!root) {

package/dist/utils/nonLocalizedPaths.d.ts

@@ -0,0 +1,9 @@
+export type NonLocalizedPathRule = {
+    pattern: string;
+    match_type: "exact" | "prefix" | "regex";
+};
+export declare function isGlobalNonLocalizedPath(pathname: string): boolean;
+export declare function matchesNonLocalizedRules(pathname: string, rules: NonLocalizedPathRule[]): boolean;
+export declare function isNonLocalizedPath(pathname: string, rules: NonLocalizedPathRule[]): boolean;
+export declare function stripLocalePrefix(pathname: string, locales: string[]): string;
+export declare function parseBootstrapNonLocalizedPaths(value: unknown): NonLocalizedPathRule[];

package/dist/utils/nonLocalizedPaths.js

@@ -0,0 +1,78 @@
+const GLOBAL_NON_LOCALIZED_APP_PATHS = new Set(["/robots.txt", "/sitemap.xml"]);
+export function isGlobalNonLocalizedPath(pathname) {
+    const input = (pathname || "").toString();
+    if (!input.startsWith("/"))
+        return false;
+    if (GLOBAL_NON_LOCALIZED_APP_PATHS.has(input))
+        return true;
+    if (input.startsWith("/.well-known/"))
+        return true;
+    return /\.(?:png|jpg|jpeg|gif|svg|webp|avif|ico|css|js|map|json|xml|txt|pdf|zip|gz|br|woff2?|ttf|eot)$/i.test(input);
+}
+export function matchesNonLocalizedRules(pathname, rules) {
+    const input = (pathname || "").toString();
+    if (!input.startsWith("/"))
+        return false;
+    if (!Array.isArray(rules) || rules.length === 0)
+        return false;
+    for (const rule of rules) {
+        const pattern = typeof rule?.pattern === "string" ? rule.pattern : "";
+        const matchType = rule?.match_type;
+        if (!pattern)
+            continue;
+        if (matchType === "exact") {
+            if (input === pattern)
+                return true;
+            continue;
+        }
+        if (matchType === "prefix") {
+            if (input.startsWith(pattern))
+                return true;
+            continue;
+        }
+        if (matchType === "regex") {
+            try {
+                if (new RegExp(pattern).test(input))
+                    return true;
+            }
+            catch {
+                // ignore invalid regex rules
+            }
+        }
+    }
+    return false;
+}
+export function isNonLocalizedPath(pathname, rules) {
+    return isGlobalNonLocalizedPath(pathname) || matchesNonLocalizedRules(pathname, rules);
+}
+export function stripLocalePrefix(pathname, locales) {
+    const input = (pathname || "").toString();
+    if (!input.startsWith("/"))
+        return input;
+    const parts = input.split("/").filter(Boolean);
+    if (parts.length === 0)
+        return "/";
+    const first = parts[0] || "";
+    if (!first || !Array.isArray(locales) || !locales.includes(first))
+        return input;
+    const rest = `/${parts.slice(1).join("/")}`;
+    return rest === "" ? "/" : rest;
+}
+export function parseBootstrapNonLocalizedPaths(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const row of value) {
+        if (!row || typeof row !== "object")
+            continue;
+        const record = row;
+        const pattern = typeof record.pattern === "string" ? record.pattern.trim() : "";
+        const match_type = typeof record.match_type === "string" ? record.match_type.trim() : "";
+        if (!pattern)
+            continue;
+        if (match_type !== "exact" && match_type !== "prefix" && match_type !== "regex")
+            continue;
+        out.push({ pattern, match_type: match_type });
+    }
+    return out;
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.3.2";
+export declare const VERSION = "0.5.3";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.3.2";
+export const VERSION = "0.5.3";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovalingo/lovalingo",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "React translation runtime with i18n routing, deterministic bundles + DOM rules, and zero-flash rendering.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",