@lovalingo/lovalingo 0.1.0 → 0.1.2

package/README.md

@@ -14,6 +14,16 @@ It does **not** generate translations in the browser.
 
 All artifacts are produced server-side by the pipeline (render → audit → deterministic translate → optional fix loop).
 
+## Marker engine (v0.1+)
+
+The runtime now marks translatable text nodes deterministically and exposes marker stats to the pipeline.
+
+- The pipeline waits for `window.__lovalingoMarkersReady` before capturing HTML.
+- Coverage is enforced server-side (jobs fail if marker coverage is below the threshold).
+- This is a breaking change: older runtimes will be rejected by the pipeline.
+
+Debug (runtime logs): set `window.__lovalingoDebug = true` before initializing `LovalingoProvider`.
+
 ## Installation
 
 ```bash
@@ -163,6 +173,7 @@ function MyComponent() {
 - ✅ Zero-flash translations (rendered before browser paint)
 - ✅ Automatic route change detection
 - ✅ MutationObserver for dynamic content
+- ✅ Deterministic marker engine + pipeline coverage gate (v0.1+)
 - ✅ SEO: automatic `canonical` + `hreflang` (can be disabled via `seo={false}`)
 - ✅ Customizable language switcher
 - ✅ TypeScript support

package/dist/components/AixsterProvider.js

@@ -4,6 +4,7 @@ import { LovalingoAPI } from '../utils/api';
 import { Translator } from '../utils/translator';
 import { applyDomRules } from '../utils/domRules';
 import { startMarkerEngine } from '../utils/markerEngine';
+import { logDebug, warnDebug, errorDebug } from '../utils/logger';
 import { LanguageSwitcher } from './LanguageSwitcher';
 import { NavigationOverlay } from './NavigationOverlay';
 const LOCALE_STORAGE_KEY = 'Lovalingo_locale';
@@ -206,7 +207,7 @@ navigateRef, // For path mode routing
             }
         }
         catch (e) {
-            console.warn("[Lovalingo] updateSeoLinks() failed:", e);
+            warnDebug("[Lovalingo] updateSeoLinks() failed:", e);
         }
     }, [isSeoActive]);
     // Marker engine: always mark full DOM content for deterministic pipeline extraction.
@@ -241,7 +242,7 @@ navigateRef, // For path mode routing
         }
         catch (e) {
             // localStorage might be unavailable (SSR, private browsing)
-            console.warn('localStorage not available:', e);
+            warnDebug('localStorage not available:', e);
         }
         // 3. Default locale
         return defaultLocale;
@@ -289,7 +290,7 @@ navigateRef, // For path mode routing
         const cachedDomRules = domRulesCacheRef.current.get(cacheKey);
         if (cachedEntry && cachedExclusions) {
             // CACHE HIT - Use cached data immediately (FAST!)
-            console.log(`[Lovalingo] Using cached translations for ${targetLocale} on ${currentPath}`);
+            logDebug(`[Lovalingo] Using cached translations for ${targetLocale} on ${currentPath}`);
             translatorRef.current.setTranslations(cachedEntry.translations);
             translatorRef.current.setExclusions(cachedExclusions);
             if (mode === 'dom') {
@@ -311,7 +312,7 @@ navigateRef, // For path mode routing
                 if (isNavigatingRef.current) {
                     return;
                 }
-                console.log(`[Lovalingo] 🔄 Retry scan for late-rendering content`);
+                logDebug(`[Lovalingo] 🔄 Retry scan for late-rendering content`);
                 if (mode === 'dom') {
                     translatorRef.current.translateDOM();
                 }
@@ -327,11 +328,11 @@ navigateRef, // For path mode routing
             return;
         }
         // CACHE MISS - Fetch from API
-        console.log(`[Lovalingo] Fetching translations for ${targetLocale} on ${currentPath}`);
+        logDebug(`[Lovalingo] Fetching translations for ${targetLocale} on ${currentPath}`);
         setIsLoading(true);
         try {
             if (previousLocale && previousLocale !== defaultLocale) {
-                console.log(`[Lovalingo] Switching from ${previousLocale} to ${targetLocale}`);
+                logDebug(`[Lovalingo] Switching from ${previousLocale} to ${targetLocale}`);
             }
             const [bundle, exclusions, domRules] = await Promise.all([
                 apiRef.current.fetchBundle(targetLocale),
@@ -369,7 +370,7 @@ navigateRef, // For path mode routing
                 if (isNavigatingRef.current) {
                     return;
                 }
-                console.log(`[Lovalingo] 🔄 Retry scan for late-rendering content`);
+                logDebug(`[Lovalingo] 🔄 Retry scan for late-rendering content`);
                 if (mode === "dom") {
                     translatorRef.current.translateDOM();
                 }
@@ -383,7 +384,7 @@ navigateRef, // For path mode routing
             }
         }
         catch (error) {
-            console.error('Error loading translations:', error);
+            errorDebug('Error loading translations:', error);
             if (showOverlay)
                 setIsNavigationLoading(false);
         }
@@ -403,7 +404,7 @@ navigateRef, // For path mode routing
                 localStorage.setItem(LOCALE_STORAGE_KEY, newLocale);
             }
             catch (e) {
-                console.warn('Failed to save locale to localStorage:', e);
+                warnDebug('Failed to save locale to localStorage:', e);
             }
             isInternalNavigationRef.current = true;
             // Show navigation overlay immediately (only when a non-default locale is involved)

package/dist/utils/api.js

@@ -1,4 +1,5 @@
 import { processPath } from './pathNormalizer';
+import { warnDebug, errorDebug } from './logger';
 export class LovalingoAPI {
     constructor(apiKey, apiBase, pathConfig) {
         this.entitlements = null;
@@ -11,10 +12,10 @@ export class LovalingoAPI {
     }
     warnMissingApiKey(action) {
         // Avoid hard-crashing apps; make the failure mode obvious.
-        console.warn(`[Lovalingo] Missing public project key: ${action} was skipped. Pass publicAnonKey to <LovalingoProvider ...> (or set VITE_LOVALINGO_PUBLIC_ANON_KEY).`);
+        warnDebug(`[Lovalingo] Missing public project key: ${action} was skipped. Pass publicAnonKey to <LovalingoProvider ...> (or set VITE_LOVALINGO_PUBLIC_ANON_KEY).`);
     }
     logActivationRequired(context, response) {
-        console.error(`[Lovalingo] ${context} blocked (HTTP ${response.status}). ` +
+        errorDebug(`[Lovalingo] ${context} blocked (HTTP ${response.status}). ` +
             `This project is not activated yet. ` +
             `Publish a public manifest at "/.well-known/lovalingo.json" on your domain, ` +
             `then verify it in the Lovalingo dashboard to activate translations + SEO.`);
@@ -129,7 +130,7 @@ export class LovalingoAPI {
             }));
         }
         catch (error) {
-            console.error('Error fetching translations:', error);
+            errorDebug('Error fetching translations:', error);
             return [];
         }
     }
@@ -184,7 +185,7 @@ export class LovalingoAPI {
             return Array.isArray(data.exclusions) ? data.exclusions : [];
         }
         catch (error) {
-            console.error('Error fetching exclusions:', error);
+            errorDebug('Error fetching exclusions:', error);
             return [];
         }
     }
@@ -210,7 +211,7 @@ export class LovalingoAPI {
             return Array.isArray(data?.rules) ? data.rules : [];
         }
         catch (error) {
-            console.error('Error fetching DOM rules:', error);
+            errorDebug('Error fetching DOM rules:', error);
             return [];
         }
     }
@@ -230,7 +231,7 @@ export class LovalingoAPI {
             }
         }
         catch (error) {
-            console.error('Error saving exclusion:', error);
+            errorDebug('Error saving exclusion:', error);
             throw error;
         }
     }

package/dist/utils/logger.d.ts

@@ -0,0 +1,3 @@
+export declare function logDebug(...args: unknown[]): void;
+export declare function warnDebug(...args: unknown[]): void;
+export declare function errorDebug(...args: unknown[]): void;

package/dist/utils/logger.js

@@ -0,0 +1,23 @@
+function isDebugEnabled() {
+    if (typeof globalThis === "undefined")
+        return false;
+    const value = globalThis.__lovalingoDebug;
+    if (value === true || value === "true" || value === 1)
+        return true;
+    return false;
+}
+export function logDebug(...args) {
+    if (!isDebugEnabled())
+        return;
+    console.log(...args);
+}
+export function warnDebug(...args) {
+    if (!isDebugEnabled())
+        return;
+    console.warn(...args);
+}
+export function errorDebug(...args) {
+    if (!isDebugEnabled())
+        return;
+    console.error(...args);
+}

package/dist/utils/pathNormalizer.js

@@ -8,6 +8,7 @@
  *   /dashboard/projects/4458eb10-608c-4622-a92e-ec3ed2eeb524/setup
  *   → /dashboard/projects/:id/setup
  */
+import { warnDebug } from "./logger";
 // Common patterns for dynamic segments
 const UUID_PATTERN = /[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}/gi;
 const NUMERIC_ID_PATTERN = /\/\d+(?=\/|$)/g;
@@ -40,7 +41,7 @@ export function normalizePath(path, config) {
                 }
             }
             catch (error) {
-                console.warn('[PathNormalizer] Invalid pattern:', rule.pattern, error);
+                warnDebug('[PathNormalizer] Invalid pattern:', rule.pattern, error);
             }
         }
     }

package/dist/utils/translator.js

@@ -1,3 +1,4 @@
+import { logDebug, warnDebug, errorDebug } from './logger';
 export class Translator {
     constructor() {
         this.translationMap = new Map();
@@ -113,7 +114,7 @@ export class Translator {
     setTranslations(translations) {
         this.translationMap.clear();
         if (!Array.isArray(translations)) {
-            console.error('[Lovalingo] setTranslations expected array, got:', typeof translations);
+            errorDebug('[Lovalingo] setTranslations expected array, got:', typeof translations);
             return;
         }
         translations.forEach(t => {
@@ -122,7 +123,7 @@ export class Translator {
                 this.translationMap.set(t.source_text.trim(), t.translated_text);
             }
         });
-        console.log(`[Lovalingo] ✅ Loaded ${this.translationMap.size} translations`);
+        logDebug(`[Lovalingo] ✅ Loaded ${this.translationMap.size} translations`);
     }
     setExclusions(exclusions) {
         this.exclusions = exclusions || [];
@@ -334,7 +335,7 @@ export class Translator {
             const hadLettersInRaw = /[a-zA-Z\u00C0-\u024F\u1E00-\u1EFF]/.test(rawHTML);
             const hadPlaceholders = Object.keys(placeholderMap).length > 0;
             if (hadLettersInRaw || hadPlaceholders) {
-                console.warn('[Lovalingo] ⚠️ Non-translatable content after extraction:', semanticElement.outerHTML.substring(0, 140));
+                warnDebug('[Lovalingo] ⚠️ Non-translatable content after extraction:', semanticElement.outerHTML.substring(0, 140));
             }
             return {
                 rawHTML,
@@ -343,7 +344,7 @@ export class Translator {
                 semanticContext
             };
         }
-        console.log(`[Lovalingo] 📝 Extracted: "${processedText.substring(0, 80)}..." with ${Object.keys(placeholderMap).length} placeholders`);
+        logDebug(`[Lovalingo] 📝 Extracted: "${processedText.substring(0, 80)}..." with ${Object.keys(placeholderMap).length} placeholders`);
         return {
             rawHTML,
             processedText,
@@ -394,7 +395,7 @@ export class Translator {
         if (SEMANTIC_BOUNDARIES.has(element.tagName)) {
             const originalHTML = element.getAttribute('data-Lovalingo-original-html');
             if (originalHTML) {
-                console.log(`[Lovalingo] 🔄 Restoring: "${element.textContent?.substring(0, 50)}..."`);
+                logDebug(`[Lovalingo] 🔄 Restoring: "${element.textContent?.substring(0, 50)}..."`);
                 // Mark current live elements before restoring
                 const markedElements = this.markElements(element);
                 // Use safe update that preserves live elements
@@ -422,11 +423,11 @@ export class Translator {
      * Restore all elements to original state
      */
     restoreDOM() {
-        console.log('[Lovalingo] 🔄 Restoring DOM to original state...');
+        logDebug('[Lovalingo] 🔄 Restoring DOM to original state...');
         const startTime = performance.now();
         this.restoreElement(document.body);
         const elapsed = performance.now() - startTime;
-        console.log(`[Lovalingo] 🏁 DOM restoration complete in ${elapsed.toFixed(2)}ms`);
+        logDebug(`[Lovalingo] 🏁 DOM restoration complete in ${elapsed.toFixed(2)}ms`);
     }
     /**
      * Mark all descendant elements with unique IDs before translation
@@ -481,7 +482,7 @@ export class Translator {
     updateElementChildren(parent, newHTML, markedElements) {
         // Safety check: Ensure parent is still in the DOM
         if (!parent.isConnected || !document.body.contains(parent)) {
-            console.warn('[Lovalingo] Parent element not in DOM, skipping translation');
+            warnDebug('[Lovalingo] Parent element not in DOM, skipping translation');
             return;
         }
         try {
@@ -498,7 +499,7 @@ export class Translator {
                 }
                 catch (e) {
                     // Node might have been removed by React already, skip
-                    console.warn('[Lovalingo] Could not remove child, likely already removed by framework');
+                    warnDebug('[Lovalingo] Could not remove child, likely already removed by framework');
                     break;
                 }
             }
@@ -508,13 +509,13 @@ export class Translator {
                     parent.appendChild(temp.firstChild);
                 }
                 catch (e) {
-                    console.warn('[Lovalingo] Could not append child:', e);
+                    warnDebug('[Lovalingo] Could not append child:', e);
                     break;
                 }
             }
         }
         catch (error) {
-            console.error('[Lovalingo] Error updating element children:', error);
+            errorDebug('[Lovalingo] Error updating element children:', error);
         }
     }
     /**
@@ -595,7 +596,7 @@ export class Translator {
                 const sourceText = originalTextAttr || content.processedText;
                 // If boundary isn't translatable, recurse to children.
                 if (!this.isTranslatableText(sourceText)) {
-                    console.log('[Lovalingo] ⏭️ Skipping non-translatable content:', sourceText.substring(0, 50));
+                    logDebug('[Lovalingo] ⏭️ Skipping non-translatable content:', sourceText.substring(0, 50));
                     Array.from(element.children).forEach((child) => {
                         if (child instanceof HTMLElement)
                             this.translateElement(child);
@@ -604,10 +605,10 @@ export class Translator {
                 }
                 const translated = this.translationMap.get(sourceText);
                 if (translated) {
-                    console.log(`[Lovalingo] ✅ Translating: "${sourceText.substring(0, 50)}..." → "${translated.substring(0, 50)}..."`);
+                    logDebug(`[Lovalingo] ✅ Translating: "${sourceText.substring(0, 50)}..." → "${translated.substring(0, 50)}..."`);
                     let reconstructedHTML = this.reconstructHTML(translated, content.placeholderMap);
                     if (/__[A-Z0-9_]+__/.test(reconstructedHTML)) {
-                        console.warn('[Lovalingo] ⚠️ Tokens remain after reconstruction, using original HTML');
+                        warnDebug('[Lovalingo] ⚠️ Tokens remain after reconstruction, using original HTML');
                         reconstructedHTML = content.rawHTML;
                     }
                     // Mark for MutationObserver suppression (prevents feedback loops on DOM updates).
@@ -625,7 +626,7 @@ export class Translator {
                     });
                 }
                 else {
-                    console.log(`[Lovalingo] ❌ Miss: "${sourceText.substring(0, 80)}..."`);
+                    logDebug(`[Lovalingo] ❌ Miss: "${sourceText.substring(0, 80)}..."`);
                 }
             }
             finally {
@@ -661,15 +662,15 @@ export class Translator {
                 // Use stored original text
                 const sourceText = originalTextAttr || content.processedText;
                 if (!this.isTranslatableText(sourceText)) {
-                    console.log('[Lovalingo] ⏭️ Skipping non-translatable content (generic):', sourceText.substring(0, 50));
+                    logDebug('[Lovalingo] ⏭️ Skipping non-translatable content (generic):', sourceText.substring(0, 50));
                     return;
                 }
                 const translated = this.translationMap.get(sourceText);
                 if (translated) {
-                    console.log(`[Lovalingo] ✅ Generic semantic: "${sourceText.substring(0, 50)}..." → "${translated.substring(0, 50)}..."`);
+                    logDebug(`[Lovalingo] ✅ Generic semantic: "${sourceText.substring(0, 50)}..." → "${translated.substring(0, 50)}..."`);
                     let reconstructedHTML = this.reconstructHTML(translated, content.placeholderMap);
                     if (/__[A-Z0-9_]+__/.test(reconstructedHTML)) {
-                        console.warn('[Lovalingo] ⚠️ Tokens remain (generic), using original HTML');
+                        warnDebug('[Lovalingo] ⚠️ Tokens remain (generic), using original HTML');
                         reconstructedHTML = content.rawHTML;
                     }
                     this.updateElementChildren(element, reconstructedHTML, markedElements);
@@ -681,7 +682,7 @@ export class Translator {
                     });
                 }
                 else {
-                    console.log(`[Lovalingo] ❌ Miss (generic): "${sourceText.substring(0, 80)}..."`);
+                    logDebug(`[Lovalingo] ❌ Miss (generic): "${sourceText.substring(0, 80)}..."`);
                 }
             }
             finally {
@@ -792,10 +793,10 @@ export class Translator {
         }
     }
     translateDOM() {
-        console.log(`[Lovalingo] 🔄 translateDOM() called with ${this.translationMap.size} translations`);
+        logDebug(`[Lovalingo] 🔄 translateDOM() called with ${this.translationMap.size} translations`);
         const startTime = performance.now();
         this.translateElement(document.body);
         const elapsed = performance.now() - startTime;
-        console.log(`[Lovalingo] 🏁 translateDOM() complete in ${elapsed.toFixed(2)}ms.`);
+        logDebug(`[Lovalingo] 🏁 translateDOM() complete in ${elapsed.toFixed(2)}ms.`);
     }
 }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.1.2";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.1.0";
+export const VERSION = "0.1.2";

package/package.json

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