npm - @lovalingo/lovalingo - Versions diffs - 0.5.0 → 0.5.2 - Mend

@lovalingo/lovalingo 0.5.0 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md +11 -0
package/dist/components/AixsterProvider.js +85 -11
package/dist/components/LangLink.js +0 -6
package/dist/components/LangRouter.js +1 -7
package/dist/hooks/useLangNavigate.js +0 -6
package/dist/types.d.ts +1 -0
package/dist/utils/api.d.ts +4 -1
package/dist/utils/api.js +14 -2
package/dist/utils/markerEngine.d.ts +9 -0
package/dist/utils/markerEngine.js +93 -0
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -205,6 +205,7 @@ Lovalingo includes a floating language switcher.
   publicAnonKey="aix_xxx"
   defaultLocale="en"
   locales={["en", "de", "fr"]}
+  overlayBgColor="#ffffff" // optional: background during the no-flash prehide phase (default: #ffffff)
   switcherPosition="bottom-right"
   switcherOffsetY={20}
   switcherTheme="light" // "dark" | "light" (default: "dark")
@@ -213,6 +214,16 @@ Lovalingo includes a floating language switcher.
 </LovalingoProvider>
 ```
+## Overlay Background (No-Flash UX)
+Lovalingo may briefly hide the page while it loads translations to avoid a visible EN→DE flash.
+Set `overlayBgColor` to match your app background so the fallback looks seamless:
+```tsx
+<LovalingoProvider overlayBgColor="#0b0b0b" ... />
+```
 ## SEO (Canonical + hreflang)
 Lovalingo can keep `<head>` SEO signals in sync with the active locale:

package/dist/components/AixsterProvider.js CHANGED Viewed

@@ -3,7 +3,7 @@ import { LovalingoContext } from '../context/LovalingoContext';
 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 { processPath } from '../utils/pathNormalizer';
 import { LanguageSwitcher } from './LanguageSwitcher';
@@ -11,8 +11,10 @@ const LOCALE_STORAGE_KEY = 'Lovalingo_locale';
 const LOADING_BG_STORAGE_PREFIX = "Lovalingo_loading_bg_color";
 const BRANDING_STORAGE_PREFIX = "Lovalingo_branding_enabled";
 const CRITICAL_CACHE_PREFIX = "Lovalingo_critical_v0_3";
+// Why: avoid long blank screens on blocked/untranslated routes by always revealing the original page quickly.
+const PREHIDE_FAILSAFE_MS = 1700;
 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, autoApplyRules = true, switcherPosition = 'bottom-right', switcherOffsetY = 20, switcherTheme = 'dark', editMode: initialEditMode = false, editKey = 'KeyE', pathNormalization = { enabled: true }, // Enable by default
+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
@@ -75,12 +77,18 @@ navigateRef, // For path mode routing
     }, [apiBase, enhancedPathConfig, resolvedApiKey]);
     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);
     const onNavigateRef = useRef(() => undefined);
     const retryTimeoutRef = useRef(null);
+    const loadingFailsafeTimeoutRef = useRef(null);
     const isNavigatingRef = useRef(false);
     const isInternalNavigationRef = useRef(false);
+    const inFlightLoadKeyRef = useRef(null);
     const translationCacheRef = useRef(new Map());
     const exclusionsCacheRef = useRef(null);
     const domRulesCacheRef = useRef(new Map());
@@ -109,6 +117,9 @@ navigateRef, // For path mode routing
         prevBodyBg: "",
     });
     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()))
@@ -118,7 +129,7 @@ navigateRef, // For path mode routing
             // ignore
         }
         return "#ffffff";
-    }, [loadingBgStorageKey]);
+    }, [loadingBgStorageKey, overlayBgColor]);
     const setCachedLoadingBgColor = useCallback((color) => {
         const next = (color || "").toString().trim();
         if (!/^#[0-9a-fA-F]{6}$/.test(next))
@@ -130,6 +141,13 @@ navigateRef, // For path mode routing
             // 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");
@@ -144,6 +162,7 @@ navigateRef, // For path mode routing
     }, [brandingStorageKey]);
     useEffect(() => {
         lastPageviewRef.current = "";
+        lastPageviewFingerprintRef.current = "";
     }, [resolvedApiKey]);
     const trackPageviewOnce = useCallback((path) => {
         const next = (path || "").toString();
@@ -153,6 +172,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")
@@ -176,12 +217,10 @@ navigateRef, // For path mode routing
             body.style.backgroundColor = bgColor;
         }
         if (state.timeoutId != null) {
-            window.clearTimeout(state.timeoutId);
+            return;
         }
-        // Why: avoid leaving the page hidden forever if the network is blocked or the project has no translations yet.
-        state.timeoutId = window.setTimeout(() => {
-            disablePrehide();
-        }, 2500);
+        // Why: avoid a "perma-hide" when navigation events repeatedly re-trigger prehide and keep extending the timeout.
+        state.timeoutId = window.setTimeout(() => disablePrehide(), PREHIDE_FAILSAFE_MS);
     }, []);
     const disablePrehide = useCallback(() => {
         if (typeof document === "undefined")
@@ -266,6 +305,7 @@ navigateRef, // For path mode routing
         apiBase,
         routing,
         autoPrefixLinks,
+        overlayBgColor,
         switcherPosition,
         switcherOffsetY,
         switcherTheme,
@@ -501,6 +541,10 @@ navigateRef, // For path mode routing
             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) {
@@ -513,6 +557,10 @@ navigateRef, // For path mode routing
         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;
@@ -553,12 +601,20 @@ navigateRef, // For path mode routing
             }, 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}`);
@@ -673,7 +729,14 @@ navigateRef, // For path mode routing
         }
         finally {
             setIsLoading(false);
+            if (loadingFailsafeTimeoutRef.current != null) {
+                window.clearTimeout(loadingFailsafeTimeoutRef.current);
+                loadingFailsafeTimeoutRef.current = null;
+            }
             isNavigatingRef.current = false;
+            if (inFlightLoadKeyRef.current === cacheKey) {
+                inFlightLoadKeyRef.current = null;
+            }
         }
     }, [
         applySeoBundle,
@@ -694,15 +757,25 @@ navigateRef, // For path mode routing
         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);
-                void loadData(nextLocale, locale);
+                if (!isInternalNavigationRef.current) {
+                    void loadData(nextLocale, locale);
+                }
             }
             else if (mode === "dom" && nextLocale !== defaultLocale) {
                 applyActiveTranslations(document.body);
             }
         };
-    }, [defaultLocale, detectLocale, loadData, locale, mode, trackPageviewOnce]);
+    }, [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")
@@ -801,6 +874,7 @@ navigateRef, // For path mode routing
     // Initialize
     useEffect(() => {
         const initialLocale = detectLocale();
+        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).
@@ -820,7 +894,7 @@ navigateRef, // For path mode routing
                 clearTimeout(retryTimeoutRef.current);
             }
         };
-    }, [detectLocale, loadData, editKey, trackPageviewOnce]);
+    }, [detectLocale, enhancedPathConfig, loadData, editKey, trackPageviewOnce]);
     // Auto-inject sitemap link tag
     useEffect(() => {
         if (sitemap && resolvedApiKey && isSeoActive()) {

package/dist/components/LangLink.js CHANGED Viewed

@@ -2,12 +2,6 @@ import React from 'react';
 import { Link } from 'react-router-dom';
 import { useLang } from '../hooks/useLang';
 const NON_LOCALIZED_APP_PATHS = new Set([
-    'auth',
-    'login',
-    'signup',
-    'sign-in',
-    'sign-up',
-    'register',
     'robots.txt',
     'sitemap.xml',
 ]);

package/dist/components/LangRouter.js CHANGED Viewed

@@ -2,12 +2,6 @@ import React, { useEffect } from 'react';
 import { BrowserRouter, Routes, Route, Navigate, Outlet, useLocation, useNavigate } from 'react-router-dom';
 import { LangContext } from '../context/LangContext';
 const NON_LOCALIZED_APP_PATHS = new Set([
-    '/auth',
-    '/login',
-    '/signup',
-    '/sign-in',
-    '/sign-up',
-    '/register',
     '/robots.txt',
     '/sitemap.xml',
 ]);
@@ -35,7 +29,7 @@ function NavigateExporter({ navigateRef }) {
  */
 function LangGuard({ defaultLang, lang }) {
     const location = useLocation();
-    // If the URL is language-prefixed but the underlying route is non-localized (auth/login/signup),
+    // 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;

package/dist/hooks/useLangNavigate.js CHANGED Viewed

@@ -3,12 +3,6 @@ import { useCallback } from 'react';
 import { useLang } from './useLang';
 //Globally excluded paths.
 const NON_LOCALIZED_APP_PATHS = new Set([
-    'auth',
-    'login',
-    'signup',
-    'sign-in',
-    'sign-up',
-    'register',
     'robots.txt',
     'sitemap.xml',
 ]);

package/dist/types.d.ts CHANGED Viewed

@@ -10,6 +10,7 @@ export interface LovalingoConfig {
     apiBase?: string;
     routing?: 'query' | 'path';
     autoPrefixLinks?: boolean;
+    overlayBgColor?: string;
     switcherPosition?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
     switcherOffsetY?: number;
     switcherTheme?: 'dark' | 'light';

package/dist/utils/api.d.ts CHANGED Viewed

@@ -65,7 +65,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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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/package.json CHANGED Viewed

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