@lovalingo/lovalingo 0.5.25 → 0.5.28

package/dist/utils/translator.js

@@ -1,802 +0,0 @@
-import { logDebug, warnDebug, errorDebug } from './logger';
-export class Translator {
-    constructor() {
-        this.translationMap = new Map();
-        this.exclusions = [];
-        // Brand names that should NEVER be translated
-        this.nonTranslatableTerms = new Set([
-            'Lovalingo',
-            'Lovable', 'v0', 'Claude Code', 'Bolt', 'Base44',
-            'Replit', 'GitHub', 'Supabase', 'OpenAI', 'Anthropic'
-        ]);
-    }
-    /**
-     * Check if element is interactive (should be preserved as island)
-     */
-    isInteractive(el) {
-        const tag = el.tagName.toLowerCase();
-        if (['button', 'a', 'label', 'input', 'textarea', 'select'].includes(tag))
-            return true;
-        if (el.hasAttribute('contenteditable'))
-            return true;
-        const role = el.getAttribute('role');
-        if (role === 'button' || role === 'link' || role === 'tab')
-            return true;
-        if (el.tabIndex >= 0)
-            return true;
-        if (el.hasAttribute('onclick'))
-            return true;
-        return false;
-    }
-    /**
-     * Check if text contains actual translatable content
-     */
-    isTranslatableText(text) {
-        if (!text || text.trim().length < 2)
-            return false;
-        // Check if it's only placeholder tokens
-        if (/^(__[A-Z0-9_]+__\s*)+$/.test(text))
-            return false;
-        // Check if it's numeric only
-        if (/^\d+(\.\d+)?$/.test(text))
-            return false;
-        // Check if contains at least one letter
-        if (!/[a-zA-Z\u00C0-\u024F\u1E00-\u1EFF]/.test(text))
-            return false;
-        return true;
-    }
-    /**
-     * Check if element should be treated as semantic boundary
-     * even though it's not in the predefined SEMANTIC_BOUNDARIES set
-     *
-     * Phase 1: Conservative approach - only leaf elements (no element children)
-     * This catches cases like: <span>text</span>, <div>text</div>, etc.
-     */
-    shouldTreatAsSemantic(element) {
-        // Skip interactive elements, they have dedicated handling
-        if (this.isInteractive(element))
-            return false;
-        // New rule: treat elements that have direct translatable text nodes
-        const hasDirectTranslatableText = Array.from(element.childNodes).some((n) => n.nodeType === Node.TEXT_NODE && this.isTranslatableText((n.textContent || '').trim()));
-        if (hasDirectTranslatableText) {
-            return true;
-        }
-        // Fallback: legacy conservative rule for true leaf nodes
-        if (element.children.length > 0) {
-            return false;
-        }
-        const textContent = (element.textContent || '').trim();
-        if (!textContent)
-            return false;
-        return this.isTranslatableText(textContent);
-    }
-    isLargeInteractiveContainer(element) {
-        const textLen = (element.textContent || '').trim().length;
-        if (textLen > 200)
-            return true;
-        const descendantCount = element.querySelectorAll('*').length;
-        if (descendantCount > 12)
-            return true;
-        const hasBlockDescendant = Boolean(element.querySelector('div,p,h1,h2,h3,h4,h5,h6,section,article,header,footer,main,nav,aside,ul,ol,li,table,tr,td,th,form,fieldset'));
-        if (hasBlockDescendant)
-            return true;
-        const hasNestedInteractive = Boolean(element.querySelector('button,a,input,textarea,select,[role="button"],[role="link"],[contenteditable]'));
-        if (hasNestedInteractive)
-            return true;
-        return false;
-    }
-    sanitizePlaceholderMap(placeholderMap) {
-        const out = {};
-        if (!placeholderMap || typeof placeholderMap !== 'object')
-            return out;
-        const stripPreserveIds = (html) => (html || '').replace(/\sdata-lovalingo-preserve-id=("[^"]*"|'[^']*')/gi, '');
-        for (const [token, data] of Object.entries(placeholderMap)) {
-            if (!data)
-                continue;
-            const next = {
-                ...data,
-                originalHTML: stripPreserveIds(data.originalHTML || ''),
-                attributes: data.attributes ? { ...data.attributes } : {},
-            };
-            for (const key of Object.keys(next.attributes || {})) {
-                if (key.toLowerCase() === 'data-lovalingo-preserve-id') {
-                    delete next.attributes[key];
-                }
-            }
-            out[token] = next;
-        }
-        return out;
-    }
-    cleanupPreserveIds(element, markedElements) {
-        markedElements?.forEach((el) => el.removeAttribute('data-Lovalingo-preserve-id'));
-        element.querySelectorAll('[data-Lovalingo-preserve-id]').forEach((el) => el.removeAttribute('data-Lovalingo-preserve-id'));
-    }
-    setTranslations(translations) {
-        this.translationMap.clear();
-        if (!Array.isArray(translations)) {
-            errorDebug('[Lovalingo] setTranslations expected array, got:', typeof translations);
-            return;
-        }
-        translations.forEach(t => {
-            if (t?.source_text && t?.translated_text) {
-                // Key is the TOKENIZED text, not the original
-                this.translationMap.set(t.source_text.trim(), t.translated_text);
-            }
-        });
-        logDebug(`[Lovalingo] ✅ Loaded ${this.translationMap.size} translations`);
-    }
-    setExclusions(exclusions) {
-        this.exclusions = exclusions || [];
-    }
-    isExcluded(element) {
-        // Check CSS selectors
-        for (const exclusion of this.exclusions) {
-            if (exclusion.type === 'css') {
-                try {
-                    if (element.matches(exclusion.selector))
-                        return true;
-                }
-                catch (e) {
-                    // Invalid selector, skip
-                }
-            }
-            else if (exclusion.type === 'xpath') {
-                try {
-                    const result = document.evaluate(exclusion.selector, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
-                    if (result.singleNodeValue === element)
-                        return true;
-                }
-                catch (e) {
-                    // Invalid xpath, skip
-                }
-            }
-        }
-        // Check data attributes
-        if (element.hasAttribute('data-notranslate') ||
-            element.hasAttribute('translate-no') ||
-            element.hasAttribute('data-no-translate')) {
-            return true;
-        }
-        // Check if inside excluded parent
-        let parent = element.parentElement;
-        while (parent) {
-            if (parent.hasAttribute('data-notranslate') ||
-                parent.hasAttribute('translate-no') ||
-                parent.hasAttribute('data-no-translate')) {
-                return true;
-            }
-            parent = parent.parentElement;
-        }
-        return false;
-    }
-    /**
-     * DOM-BASED EXTRACTION
-     * Uses DOM APIs to reliably parse and tokenize HTML
-     */
-    extractTranslatableContent(semanticElement) {
-        // Prefer a stable snapshot without temporary preserve markers.
-        const rawHTML = semanticElement.getAttribute('data-Lovalingo-original-html') || semanticElement.innerHTML;
-        const semanticContext = semanticElement.tagName.toLowerCase();
-        // Clone element to avoid modifying original DOM
-        const clone = semanticElement.cloneNode(true);
-        let placeholderCounter = 0;
-        const placeholderMap = {};
-        // Inline elements that should be tokenized
-        const INLINE_TAGS = new Set([
-            'span', 'strong', 'em', 'b', 'i', 'u', 'mark', 'small',
-            'sub', 'sup', 'code', 'kbd', 'samp', 'var', 'abbr',
-            'a', 'time', 'data'
-        ]);
-        // Elements to completely remove (keep as tokens but don't translate)
-        const SKIP_TAGS = new Set([
-            'script', 'style', 'noscript', 'svg', 'canvas',
-            'img', 'video', 'audio', 'iframe', 'object', 'embed',
-            'code', 'pre'
-        ]);
-        const WRAP_INTERACTIVE_TAGS = new Set(['button', 'label', 'summary']);
-        const WRAP_INTERACTIVE_ROLES = new Set(['button', 'link', 'tab']);
-        const getOuterHTML = (el) => {
-            try {
-                return el.outerHTML || '';
-            }
-            catch {
-                return '';
-            }
-        };
-        const getOpenTag = (outerHTML) => {
-            const idx = outerHTML.indexOf('>');
-            if (idx === -1)
-                return '';
-            return outerHTML.slice(0, idx + 1);
-        };
-        /**
-         * Recursively process DOM nodes
-         * Returns true if node was replaced with token
-         */
-        const processNode = (node) => {
-            if (node.nodeType === Node.ELEMENT_NODE) {
-                const element = node;
-                const tagName = element.tagName.toLowerCase();
-                // Remove skip tags entirely
-                if (SKIP_TAGS.has(tagName)) {
-                    const token = `__PRESERVE_${placeholderCounter}__`;
-                    placeholderMap[token] = {
-                        type: 'non-translatable',
-                        originalHTML: getOuterHTML(element),
-                        textContent: '',
-                        tag: tagName,
-                        attributes: {}
-                    };
-                    placeholderCounter++;
-                    const textNode = document.createTextNode(token); // Use token, not space
-                    element.replaceWith(textNode);
-                    return true;
-                }
-                // Process children first (depth-first)
-                const children = Array.from(element.childNodes);
-                children.forEach(child => processNode(child));
-                const textContent = element.textContent || '';
-                const trimmedContent = textContent.trim();
-                // Skip wrapping/preserving when there's nothing meaningful inside.
-                if (!trimmedContent || trimmedContent.length < 2) {
-                    return false;
-                }
-                // Skip icon elements (or icon-like wrappers).
-                const isIcon = tagName === 'svg' ||
-                    tagName === 'i' ||
-                    element.hasAttribute('aria-hidden') ||
-                    element.classList.contains('icon') ||
-                    element.classList.contains('lucide');
-                if (isIcon) {
-                    return false;
-                }
-                // Preserve explicit non-translatable inline nodes as a single token, so surrounding text can still translate.
-                const isNonTranslatable = this.nonTranslatableTerms.has(trimmedContent) ||
-                    element.hasAttribute('data-no-translate') ||
-                    element.hasAttribute('translate-no') ||
-                    element.hasAttribute('data-no-translate');
-                if (isNonTranslatable && element !== clone) {
-                    const token = `__PRESERVE_${placeholderCounter}__`;
-                    placeholderMap[token] = {
-                        type: 'non-translatable',
-                        originalHTML: getOuterHTML(element),
-                        textContent,
-                        tag: tagName,
-                        attributes: {},
-                    };
-                    placeholderCounter++;
-                    const textNode = document.createTextNode(token);
-                    element.replaceWith(textNode);
-                    return true;
-                }
-                const role = (element.getAttribute('role') || '').toLowerCase();
-                const shouldWrapInteractive = element !== clone &&
-                    this.isInteractive(element) &&
-                    !['input', 'textarea', 'select'].includes(tagName) &&
-                    (WRAP_INTERACTIVE_TAGS.has(tagName) || WRAP_INTERACTIVE_ROLES.has(role));
-                const shouldWrapInline = element !== clone && INLINE_TAGS.has(tagName);
-                if (shouldWrapInline || shouldWrapInteractive) {
-                    // Wrap with OPEN/CLOSE tokens so the model can translate inner text and still preserve markup.
-                    const openToken = `__OPEN_${placeholderCounter}__`;
-                    const closeToken = `__CLOSE_${placeholderCounter}__`;
-                    placeholderCounter++;
-                    const outer = getOuterHTML(element);
-                    const openTag = getOpenTag(outer);
-                    const closeTag = `</${tagName}>`;
-                    const attributes = {};
-                    Array.from(element.attributes).forEach(attr => {
-                        attributes[attr.name] = attr.value;
-                    });
-                    placeholderMap[openToken] = {
-                        type: 'inline-formatting',
-                        originalHTML: openTag,
-                        textContent,
-                        tag: tagName,
-                        attributes,
-                    };
-                    placeholderMap[closeToken] = {
-                        type: 'inline-formatting',
-                        originalHTML: closeTag,
-                        textContent: '',
-                        tag: tagName,
-                        attributes: {},
-                    };
-                    const fragment = document.createDocumentFragment();
-                    fragment.appendChild(document.createTextNode(openToken));
-                    while (element.firstChild) {
-                        fragment.appendChild(element.firstChild);
-                    }
-                    fragment.appendChild(document.createTextNode(closeToken));
-                    element.replaceWith(fragment);
-                    return true;
-                }
-            }
-            return false;
-        };
-        // Process all nodes in the cloned tree
-        const walker = document.createTreeWalker(clone, NodeFilter.SHOW_ELEMENT, null);
-        const nodesToProcess = [];
-        let node = walker.nextNode();
-        while (node) {
-            nodesToProcess.push(node);
-            node = walker.nextNode();
-        }
-        // Process from deepest to shallowest to handle nesting
-        nodesToProcess.reverse().forEach(processNode);
-        // Extract final text
-        let processedText = clone.textContent || '';
-        // Normalize whitespace
-        processedText = processedText
-            .replace(/\s+/g, ' ') // Multiple spaces → single space
-            .trim();
-        // LAYER 2: Validate content using isTranslatableText
-        if (!this.isTranslatableText(processedText)) {
-            // This is expected for icons/flags/short labels; only warn when it looks like we actually had meaningful text.
-            const hadLettersInRaw = /[a-zA-Z\u00C0-\u024F\u1E00-\u1EFF]/.test(rawHTML);
-            const hadPlaceholders = Object.keys(placeholderMap).length > 0;
-            if (hadLettersInRaw || hadPlaceholders) {
-                warnDebug('[Lovalingo] ⚠️ Non-translatable content after extraction:', semanticElement.outerHTML.substring(0, 140));
-            }
-            return {
-                rawHTML,
-                processedText: '',
-                placeholderMap: {},
-                semanticContext
-            };
-        }
-        logDebug(`[Lovalingo] 📝 Extracted: "${processedText.substring(0, 80)}..." with ${Object.keys(placeholderMap).length} placeholders`);
-        return {
-            rawHTML,
-            processedText,
-            placeholderMap,
-            semanticContext
-        };
-    }
-    /**
-     * RECONSTRUCTION: Replace tokens with original HTML
-     */
-    reconstructHTML(translatedText, placeholderMap) {
-        let result = translatedText;
-        // Replace each token with its original HTML
-        // Sort by token number to ensure correct order
-        const tokens = Object.keys(placeholderMap).sort((a, b) => {
-            const numA = parseInt(a.match(/\d+/)?.[0] || '0');
-            const numB = parseInt(b.match(/\d+/)?.[0] || '0');
-            if (numA !== numB)
-                return numA - numB;
-            return a.localeCompare(b);
-        });
-        for (const token of tokens) {
-            const data = placeholderMap[token];
-            if (data?.originalHTML) {
-                // Escape special regex characters in token
-                const escapedToken = token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-                const regex = new RegExp(escapedToken, 'g');
-                result = result.replace(regex, data.originalHTML);
-            }
-        }
-        return result;
-    }
-    /**
-     * Restore element to original HTML while preserving event listeners
-     */
-    restoreElement(element) {
-        if (this.isExcluded(element))
-            return;
-        // Skip non-translatable elements
-        const SKIP_TAGS = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'IFRAME', 'CODE', 'PRE']);
-        if (SKIP_TAGS.has(element.tagName))
-            return;
-        const SEMANTIC_BOUNDARIES = new Set([
-            'P', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6',
-            'LI', 'TD', 'TH', 'BUTTON', 'LABEL', 'A',
-            'BLOCKQUOTE', 'FIGCAPTION', 'SUMMARY', 'CAPTION'
-        ]);
-        if (SEMANTIC_BOUNDARIES.has(element.tagName)) {
-            const originalHTML = element.getAttribute('data-Lovalingo-original-html');
-            if (originalHTML) {
-                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
-                this.updateElementChildren(element, originalHTML, markedElements);
-                // Clean up preserve IDs
-                element.querySelectorAll('[data-Lovalingo-preserve-id]').forEach(el => {
-                    el.removeAttribute('data-Lovalingo-preserve-id');
-                });
-                // Keep the original HTML attribute for future switches
-            }
-            return;
-        }
-        // For non-semantic boundaries, recurse to children
-        Array.from(element.children).forEach(child => {
-            if (child instanceof HTMLElement) {
-                this.restoreElement(child);
-            }
-        });
-        // Restore attributes
-        this.restoreAttribute(element, 'placeholder');
-        this.restoreAttribute(element, 'title');
-        this.restoreAttribute(element, 'alt');
-    }
-    /**
-     * Restore all elements to original state
-     */
-    restoreDOM() {
-        logDebug('[Lovalingo] 🔄 Restoring DOM to original state...');
-        const startTime = performance.now();
-        this.restoreElement(document.body);
-        const elapsed = performance.now() - startTime;
-        logDebug(`[Lovalingo] 🏁 DOM restoration complete in ${elapsed.toFixed(2)}ms`);
-    }
-    /**
-     * Mark all descendant elements with unique IDs before translation
-     * This allows us to reuse original DOM nodes (preserving event listeners)
-     */
-    markElements(element) {
-        const markedElements = new Map();
-        const descendants = element.querySelectorAll('*');
-        descendants.forEach((child, index) => {
-            if (child instanceof HTMLElement) {
-                const id = `Lovalingo-preserve-${Date.now()}-${index}`;
-                child.setAttribute('data-Lovalingo-preserve-id', id);
-                markedElements.set(id, child);
-            }
-        });
-        return markedElements;
-    }
-    /**
-     * After reconstruction, transplant original LIVE elements into new structure
-     * This preserves event listeners and framework connections
-     */
-    transplantOriginalElements(tempContainer, markedElements) {
-        if (markedElements.size === 0) {
-            return;
-        }
-        // Find all elements with preserve IDs in the temp structure
-        const preserveElements = tempContainer.querySelectorAll('[data-Lovalingo-preserve-id]');
-        preserveElements.forEach((tempElement) => {
-            if (!(tempElement instanceof HTMLElement))
-                return;
-            const id = tempElement.getAttribute('data-Lovalingo-preserve-id');
-            if (id && markedElements.has(id)) {
-                // Get the LIVE original element from the DOM
-                const originalElement = markedElements.get(id);
-                // Update text content if different
-                const tempText = tempElement.textContent;
-                const originalText = originalElement.textContent;
-                if (tempText !== originalText) {
-                    // Update only text nodes within the original element
-                    this.updateTextNodesOnly(originalElement, tempElement);
-                }
-                // Replace temp element with the LIVE original (not a clone!)
-                // This moves the original element into the temp structure
-                tempElement.replaceWith(originalElement);
-            }
-        });
-    }
-    /**
-     * Directly update the parent element's children by transplanting from temp
-     * This avoids using innerHTML which would destroy event listeners
-     */
-    updateElementChildren(parent, newHTML, markedElements) {
-        // Safety check: Ensure parent is still in the DOM
-        if (!parent.isConnected || !document.body.contains(parent)) {
-            warnDebug('[Lovalingo] Parent element not in DOM, skipping translation');
-            return;
-        }
-        try {
-            // Parse new structure
-            const temp = document.createElement('div');
-            temp.innerHTML = newHTML;
-            // Transplant original live elements into temp structure
-            this.transplantOriginalElements(temp, markedElements);
-            // Now replace parent's children with temp's children
-            // Use try-catch for each removeChild to handle React conflicts gracefully
-            while (parent.firstChild) {
-                try {
-                    parent.removeChild(parent.firstChild);
-                }
-                catch (e) {
-                    // Node might have been removed by React already, skip
-                    warnDebug('[Lovalingo] Could not remove child, likely already removed by framework');
-                    break;
-                }
-            }
-            // Move all nodes from temp to parent
-            while (temp.firstChild) {
-                try {
-                    parent.appendChild(temp.firstChild);
-                }
-                catch (e) {
-                    warnDebug('[Lovalingo] Could not append child:', e);
-                    break;
-                }
-            }
-        }
-        catch (error) {
-            errorDebug('[Lovalingo] Error updating element children:', error);
-        }
-    }
-    /**
-     * Update only text nodes within an element, preserving child elements
-     * Enhanced to handle nested structures recursively
-     */
-    updateTextNodesOnly(original, translated) {
-        const updateTextRecursively = (origNode, transNode) => {
-            if (origNode.nodeType === Node.TEXT_NODE && transNode.nodeType === Node.TEXT_NODE) {
-                // Update text content in place
-                origNode.textContent = transNode.textContent;
-                return;
-            }
-            if (origNode.nodeType === Node.ELEMENT_NODE && transNode.nodeType === Node.ELEMENT_NODE) {
-                const origChildren = Array.from(origNode.childNodes);
-                const transChildren = Array.from(transNode.childNodes);
-                // Match children by node type and tag name
-                origChildren.forEach((origChild, i) => {
-                    if (transChildren[i]) {
-                        updateTextRecursively(origChild, transChildren[i]);
-                    }
-                });
-            }
-        };
-        updateTextRecursively(original, translated);
-    }
-    translateElement(element) {
-        if (this.isExcluded(element))
-            return;
-        // Skip non-translatable elements
-        const SKIP_TAGS = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'IFRAME', 'CODE', 'PRE']);
-        if (SKIP_TAGS.has(element.tagName))
-            return;
-        if (this.isInteractive(element)) {
-            const tag = element.tagName.toLowerCase();
-            const role = (element.getAttribute('role') || '').toLowerCase();
-            const isKnownLeafControl = ['button', 'label', 'summary', 'input', 'textarea', 'select'].includes(tag);
-            const isRoleLeaf = role === 'button' || role === 'tab';
-            const isLink = tag === 'a' || role === 'link';
-            // For leaf controls and simple interactive labels: translate safely in-place and stop.
-            // For interactive containers (cards, composite widgets): translate attributes and recurse to children.
-            const shouldRecurse = (!isKnownLeafControl && !isRoleLeaf && !isLink) ||
-                ((isLink || isRoleLeaf) && this.isLargeInteractiveContainer(element));
-            this.translateInteractive(element);
-            if (!shouldRecurse)
-                return;
-        }
-        // Semantic boundaries - translate these as complete units
-        const SEMANTIC_BOUNDARIES = new Set([
-            'P', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6',
-            'LI', 'TD', 'TH',
-            'BLOCKQUOTE', 'FIGCAPTION', 'SUMMARY', 'CAPTION'
-        ]);
-        if (SEMANTIC_BOUNDARIES.has(element.tagName)) {
-            // Store original HTML on first translation
-            const originalHTMLAttr = element.getAttribute('data-Lovalingo-original-html');
-            if (!originalHTMLAttr) {
-                element.setAttribute('data-Lovalingo-original-html', element.innerHTML);
-            }
-            // STEP 1: Mark all child elements before extraction
-            const markedElements = this.markElements(element);
-            try {
-                const content = this.extractTranslatableContent(element);
-                // If there's no meaningful boundary content, recurse to children.
-                if (!content.processedText || content.processedText.length <= 1) {
-                    Array.from(element.children).forEach((child) => {
-                        if (child instanceof HTMLElement)
-                            this.translateElement(child);
-                    });
-                    return;
-                }
-                // Store original processed text for comparison
-                const originalTextAttr = element.getAttribute('data-Lovalingo-original');
-                if (!originalTextAttr) {
-                    element.setAttribute('data-Lovalingo-original', content.processedText);
-                }
-                // Always use stored original text, not current DOM state
-                const sourceText = originalTextAttr || content.processedText;
-                // If boundary isn't translatable, recurse to children.
-                if (!this.isTranslatableText(sourceText)) {
-                    logDebug('[Lovalingo] ⏭️ Skipping non-translatable content:', sourceText.substring(0, 50));
-                    Array.from(element.children).forEach((child) => {
-                        if (child instanceof HTMLElement)
-                            this.translateElement(child);
-                    });
-                    return;
-                }
-                const translated = this.translationMap.get(sourceText);
-                if (translated) {
-                    logDebug(`[Lovalingo] ✅ Translating: "${sourceText.substring(0, 50)}..." → "${translated.substring(0, 50)}..."`);
-                    let reconstructedHTML = this.reconstructHTML(translated, content.placeholderMap);
-                    if (/__[A-Z0-9_]+__/.test(reconstructedHTML)) {
-                        warnDebug('[Lovalingo] ⚠️ Tokens remain after reconstruction, using original HTML');
-                        reconstructedHTML = content.rawHTML;
-                    }
-                    // Mark for MutationObserver suppression (prevents feedback loops on DOM updates).
-                    element.setAttribute('data-Lovalingo-translating', '1');
-                    setTimeout(() => {
-                        element.removeAttribute('data-Lovalingo-translating');
-                    }, 50);
-                    // Full reconstruction + live-node transplant.
-                    this.updateElementChildren(element, reconstructedHTML, markedElements);
-                    // Translate interactive descendants safely (preserves event handlers)
-                    const interactiveSelector = 'button, a, label, input, textarea, select, [role="button"], [role="link"], [contenteditable], [contenteditable="true"], [tabindex]';
-                    element.querySelectorAll(interactiveSelector).forEach(el => {
-                        if (el instanceof HTMLElement)
-                            this.translateInteractive(el);
-                    });
-                }
-                else {
-                    logDebug(`[Lovalingo] ❌ Miss: "${sourceText.substring(0, 80)}..."`);
-                }
-            }
-            finally {
-                this.cleanupPreserveIds(element, markedElements);
-            }
-            return; // Don't process children if we handled the boundary
-        }
-        // ============================================================
-        // CASE 2: Generic semantic boundaries (leaf text containers)
-        // ============================================================
-        // Check if this element should be treated as semantic boundary
-        // even though it's not in the predefined SEMANTIC_BOUNDARIES set
-        if (this.shouldTreatAsSemantic(element)) {
-            // Reuse EXACT same logic as Case 1 (SEMANTIC_BOUNDARIES)
-            // Store original HTML on first translation
-            const originalHTMLAttr = element.getAttribute('data-Lovalingo-original-html');
-            if (!originalHTMLAttr) {
-                element.setAttribute('data-Lovalingo-original-html', element.innerHTML);
-            }
-            // Mark all child elements before extraction
-            const markedElements = this.markElements(element);
-            try {
-                const content = this.extractTranslatableContent(element);
-                // Skip if no valid content
-                if (!content.processedText || content.processedText.length <= 1) {
-                    return;
-                }
-                // Store original processed text
-                const originalTextAttr = element.getAttribute('data-Lovalingo-original');
-                if (!originalTextAttr) {
-                    element.setAttribute('data-Lovalingo-original', content.processedText);
-                }
-                // Use stored original text
-                const sourceText = originalTextAttr || content.processedText;
-                if (!this.isTranslatableText(sourceText)) {
-                    logDebug('[Lovalingo] ⏭️ Skipping non-translatable content (generic):', sourceText.substring(0, 50));
-                    return;
-                }
-                const translated = this.translationMap.get(sourceText);
-                if (translated) {
-                    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)) {
-                        warnDebug('[Lovalingo] ⚠️ Tokens remain (generic), using original HTML');
-                        reconstructedHTML = content.rawHTML;
-                    }
-                    this.updateElementChildren(element, reconstructedHTML, markedElements);
-                    // Translate interactive descendants
-                    const interactiveSelector = 'button, a, label, input, textarea, select, [role="button"], [role="link"], [contenteditable], [contenteditable="true"], [tabindex]';
-                    element.querySelectorAll(interactiveSelector).forEach(el => {
-                        if (el instanceof HTMLElement)
-                            this.translateInteractive(el);
-                    });
-                }
-                else {
-                    logDebug(`[Lovalingo] ❌ Miss (generic): "${sourceText.substring(0, 80)}..."`);
-                }
-            }
-            finally {
-                this.cleanupPreserveIds(element, markedElements);
-            }
-            return; // Don't recurse to children
-        }
-        // ============================================================
-        // CASE 3: Structural containers - recurse to children
-        // ============================================================
-        // For non-semantic boundaries, recurse to children
-        Array.from(element.children).forEach(child => {
-            if (child instanceof HTMLElement) {
-                this.translateElement(child);
-            }
-        });
-        // Translate input placeholders
-        if (element.tagName === 'INPUT' || element.tagName === 'TEXTAREA') {
-            this.translateAttribute(element, 'placeholder', 'placeholder');
-        }
-        // Translate title and alt attributes
-        this.translateAttribute(element, 'title', 'title');
-        this.translateAttribute(element, 'alt', 'alt');
-    }
-    /**
-     * Restore attribute to original value
-     */
-    restoreAttribute(element, attr) {
-        const originalAttrKey = `data-Lovalingo-${attr}-original`;
-        const originalValue = element.getAttribute(originalAttrKey);
-        if (originalValue) {
-            element.setAttribute(attr, originalValue);
-        }
-    }
-    /**
-     * Translate interactive element safely (preserves event handlers)
-     */
-    translateInteractive(el) {
-        const tag = el.tagName;
-        const role = (el.getAttribute('role') || '').toLowerCase();
-        // Always translate common interactive attributes.
-        this.translateAttribute(el, 'title', 'title');
-        this.translateAttribute(el, 'aria-label', 'aria-label');
-        if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') {
-            this.translateAttribute(el, 'placeholder', 'placeholder');
-            return;
-        }
-        // For large interactive containers, let nested semantic nodes handle visible text.
-        if ((tag === 'A' || role === 'link' || role === 'button' || role === 'tab') && el.children.length > 0 && this.isLargeInteractiveContainer(el)) {
-            return;
-        }
-        // Idempotently store original plain text once
-        const plainOriginalKey = 'data-Lovalingo-original';
-        if (!el.getAttribute(plainOriginalKey)) {
-            el.setAttribute(plainOriginalKey, (el.textContent || '').trim());
-        }
-        // Translate text nodes for label-like elements (only safe for simple/leaf controls)
-        if (tag === 'BUTTON' || tag === 'A' || tag === 'LABEL' || tag === 'SUMMARY' || role === 'button' || role === 'link') {
-            const content = this.extractTranslatableContent(el);
-            const tokenizedKeyAttr = 'data-Lovalingo-original-tokenized';
-            const tokenized = (el.getAttribute(tokenizedKeyAttr) || content.processedText || '').trim();
-            if (!el.getAttribute(tokenizedKeyAttr) && content.processedText) {
-                el.setAttribute(tokenizedKeyAttr, content.processedText);
-            }
-            const plainOriginal = el.getAttribute(plainOriginalKey) || (el.textContent || '').trim();
-            const source = (tokenized && this.isTranslatableText(tokenized)) ? tokenized : plainOriginal;
-            if (this.isTranslatableText(source)) {
-                const translated = this.translationMap.get(source);
-                if (translated) {
-                    // Ensure restoreDOM can revert translated controls.
-                    const nearestOriginalHtml = el.closest?.('[data-Lovalingo-original-html]');
-                    if ((!nearestOriginalHtml || nearestOriginalHtml === el) && !el.getAttribute('data-Lovalingo-original-html')) {
-                        el.setAttribute('data-Lovalingo-original-html', el.innerHTML);
-                    }
-                    const temp = document.createElement('div');
-                    temp.innerHTML = this.reconstructHTML(translated, content.placeholderMap);
-                    this.updateTextNodesOnly(el, temp);
-                }
-            }
-        }
-    }
-    /**
-     * Translate individual attributes
-     */
-    translateAttribute(element, attr, context) {
-        if (this.isExcluded(element))
-            return;
-        const originalAttrKey = `data-Lovalingo-${attr}-original`;
-        // Get or store original
-        let sourceValue = element.getAttribute(originalAttrKey);
-        if (!sourceValue) {
-            const value = element.getAttribute(attr);
-            if (value) {
-                sourceValue = value.trim();
-                element.setAttribute(originalAttrKey, sourceValue);
-            }
-        }
-        if (!sourceValue || sourceValue.length <= 1)
-            return;
-        // LAYER 5: Validate attribute value is translatable
-        if (!this.isTranslatableText(sourceValue)) {
-            return; // Skip non-translatable attributes
-        }
-        // Try to translate
-        const translated = this.translationMap.get(sourceValue);
-        if (translated) {
-            element.setAttribute(attr, translated);
-        }
-    }
-    translateDOM() {
-        logDebug(`[Lovalingo] 🔄 translateDOM() called with ${this.translationMap.size} translations`);
-        const startTime = performance.now();
-        this.translateElement(document.body);
-        const elapsed = performance.now() - startTime;
-        logDebug(`[Lovalingo] 🏁 translateDOM() complete in ${elapsed.toFixed(2)}ms.`);
-    }
-}