@lovalingo/lovalingo 0.5.1 → 0.5.2

package/dist/components/AixsterProvider.js

@@ -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';
@@ -77,6 +77,9 @@ 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);
@@ -159,6 +162,7 @@ navigateRef, // For path mode routing
     }, [brandingStorageKey]);
     useEffect(() => {
         lastPageviewRef.current = "";
+        lastPageviewFingerprintRef.current = "";
     }, [resolvedApiKey]);
     const trackPageviewOnce = useCallback((path) => {
         const next = (path || "").toString();
@@ -168,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")

package/dist/utils/api.d.ts

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

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

@@ -1,6 +1,6 @@
 {
   "name": "@lovalingo/lovalingo",
-  "version": "0.5.1",
+  "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",