@lovalingo/lovalingo 0.5.25 → 0.5.28

package/dist/utils/markerEngineApply.d.ts

@@ -0,0 +1,3 @@
+export declare function applyTranslationMap(bundle: Record<string, string>, root: ParentNode | null): number;
+export declare function applyActiveTranslations(root?: ParentNode | null): number;
+export declare function restoreDom(root?: ParentNode | null): void;

package/dist/utils/markerEngineApply.js

@@ -0,0 +1,136 @@
+import { ATTRIBUTE_MARKS } from "./markerEngineConstants";
+import { findUnsafeContainer, isExcludedElement } from "./markerEngineFilters";
+import { isTranslatableText, normalizeWhitespace } from "./markerEngineDomUtils";
+import { getOrInitAttrOriginal, getOrInitTextOriginal, originalAttrByEl, originalTextByNode } from "./markerEngineOriginals";
+import { getActiveTranslationMap, setActiveTranslationMap } from "./markerEngineState";
+export function applyTranslationMap(bundle, root) {
+    if (!root)
+        return 0;
+    const map = new Map();
+    for (const [k, v] of Object.entries(bundle || {})) {
+        const source = normalizeWhitespace((k || "").toString());
+        const translated = (v ?? "").toString();
+        if (!source || !translated)
+            continue;
+        map.set(source, translated);
+    }
+    setActiveTranslationMap(map);
+    return applyActiveTranslations(root);
+}
+export function applyActiveTranslations(root = document.body) {
+    const map = getActiveTranslationMap();
+    if (!root || !map || map.size === 0)
+        return 0;
+    let applied = 0;
+    const walk = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+    const nodes = [];
+    let node = walk.nextNode();
+    while (node) {
+        if (node.nodeType === Node.TEXT_NODE)
+            nodes.push(node);
+        node = walk.nextNode();
+    }
+    for (const textNode of nodes) {
+        const parent = textNode.parentElement;
+        if (!parent)
+            continue;
+        const raw = textNode.nodeValue || "";
+        const trimmed = raw.trim();
+        if (!trimmed)
+            continue;
+        if (isExcludedElement(parent))
+            continue;
+        if (findUnsafeContainer(parent))
+            continue;
+        if (!isTranslatableText(trimmed))
+            continue;
+        const original = getOrInitTextOriginal(textNode, parent);
+        const key = normalizeWhitespace(original.trimmed);
+        const translation = map.get(key);
+        if (!translation)
+            continue;
+        const next = `${original.leading}${translation}${original.trailing}`;
+        if (textNode.nodeValue === next)
+            continue;
+        try {
+            textNode.nodeValue = next;
+            applied += 1;
+        }
+        catch {
+            // ignore
+        }
+    }
+    if (root instanceof HTMLElement) {
+        const elements = root.querySelectorAll("[title],[aria-label],[placeholder]");
+        elements.forEach((el) => {
+            if (isExcludedElement(el))
+                return;
+            if (findUnsafeContainer(el))
+                return;
+            for (const { attr } of ATTRIBUTE_MARKS) {
+                const current = el.getAttribute(attr);
+                if (!current)
+                    continue;
+                const trimmed = current.trim();
+                if (!trimmed || !isTranslatableText(trimmed))
+                    continue;
+                const original = normalizeWhitespace(getOrInitAttrOriginal(el, attr));
+                const translation = map.get(original);
+                if (!translation)
+                    continue;
+                if (el.getAttribute(attr) === translation)
+                    continue;
+                try {
+                    el.setAttribute(attr, translation);
+                    applied += 1;
+                }
+                catch {
+                    // ignore
+                }
+            }
+        });
+    }
+    return applied;
+}
+export function restoreDom(root = document.body) {
+    if (!root)
+        return;
+    const walk = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+    let node = walk.nextNode();
+    while (node) {
+        if (node.nodeType === Node.TEXT_NODE) {
+            const textNode = node;
+            const original = originalTextByNode.get(textNode);
+            if (original && textNode.nodeValue !== original.raw) {
+                try {
+                    textNode.nodeValue = original.raw;
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+        node = walk.nextNode();
+    }
+    if (root instanceof HTMLElement) {
+        const elements = root.querySelectorAll("[title],[aria-label],[placeholder]");
+        elements.forEach((el) => {
+            const originals = originalAttrByEl.get(el);
+            if (!originals)
+                return;
+            for (const { attr } of ATTRIBUTE_MARKS) {
+                const original = originals.get(attr);
+                if (original == null)
+                    continue;
+                if (el.getAttribute(attr) === original)
+                    continue;
+                try {
+                    el.setAttribute(attr, original);
+                }
+                catch {
+                    // ignore
+                }
+            }
+        });
+    }
+}

package/dist/utils/markerEngineConstants.d.ts

@@ -0,0 +1,10 @@
+export declare const DEFAULT_THROTTLE_MS = 150;
+export declare const DEFAULT_CRITICAL_BUFFER_PX = 200;
+export declare const DEFAULT_CRITICAL_MAX = 800;
+export declare const EXCLUDE_SELECTOR = "[data-lovalingo-exclude],[data-notranslate],[translate-no],[data-no-translate]";
+export declare const UNSAFE_CONTAINER_TAGS: Set<string>;
+export declare const ATTRIBUTE_MARKS: {
+    attr: string;
+    marker: string;
+}[];
+export declare const unsafeSelector: string;

package/dist/utils/markerEngineConstants.js

@@ -0,0 +1,12 @@
+// Why: keep marker scans cheap while still capturing a small above-the-fold "critical slice" for first paint.
+export const DEFAULT_THROTTLE_MS = 150;
+export const DEFAULT_CRITICAL_BUFFER_PX = 200;
+export const DEFAULT_CRITICAL_MAX = 800;
+export const EXCLUDE_SELECTOR = "[data-lovalingo-exclude],[data-notranslate],[translate-no],[data-no-translate]";
+export const UNSAFE_CONTAINER_TAGS = new Set(["script", "style", "noscript", "template", "svg", "canvas"]);
+export const ATTRIBUTE_MARKS = [
+    { attr: "title", marker: "data-lovalingo-title-original" },
+    { attr: "aria-label", marker: "data-lovalingo-aria-label-original" },
+    { attr: "placeholder", marker: "data-lovalingo-placeholder-original" },
+];
+export const unsafeSelector = Array.from(UNSAFE_CONTAINER_TAGS).join(",");

package/dist/utils/markerEngineCritical.d.ts

@@ -0,0 +1,2 @@
+import type { CriticalFingerprint } from "./markerEngineTypes";
+export declare function getCriticalFingerprint(): CriticalFingerprint;

package/dist/utils/markerEngineCritical.js

@@ -0,0 +1,98 @@
+import { hashContent } from "./hash";
+import { ATTRIBUTE_MARKS, DEFAULT_CRITICAL_BUFFER_PX, DEFAULT_CRITICAL_MAX } from "./markerEngineConstants";
+import { isExcludedElement, findUnsafeContainer } from "./markerEngineFilters";
+import { isTranslatableText, normalizeWhitespace } from "./markerEngineDomUtils";
+import { getOrInitAttrOriginal, getOrInitTextOriginal } from "./markerEngineOriginals";
+import { getTextNodeRect, isInViewport } from "./markerEngineViewport";
+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,
+    };
+}

package/dist/utils/markerEngineDomUtils.d.ts

@@ -0,0 +1,8 @@
+export declare function getStableKey(el: Element): string;
+export declare function getElementIndex(el: Element): number;
+export declare function getTextNodeIndex(node: Text): number;
+export declare function buildElementPath(el: Element): string;
+export declare function normalizeWhitespace(value: string): string;
+export declare function isTranslatableText(text: string): boolean;
+export declare function buildStableId(el: Element, text: string, textIndex: number): string;
+export declare function buildSelector(el: Element): string | null;

package/dist/utils/markerEngineDomUtils.js

@@ -0,0 +1,74 @@
+import { hashContent } from "./hash";
+export function getStableKey(el) {
+    const owner = el.closest("[data-lovalingo-key]");
+    const key = owner?.getAttribute("data-lovalingo-key") || "";
+    return key.trim();
+}
+export function getElementIndex(el) {
+    const parent = el.parentElement;
+    if (!parent)
+        return 0;
+    const children = Array.from(parent.children);
+    const idx = children.indexOf(el);
+    return idx >= 0 ? idx : 0;
+}
+export function getTextNodeIndex(node) {
+    let index = 0;
+    let prev = node.previousSibling;
+    while (prev) {
+        if (prev.nodeType === Node.TEXT_NODE)
+            index += 1;
+        prev = prev.previousSibling;
+    }
+    return index;
+}
+export function buildElementPath(el) {
+    const parts = [];
+    let current = el;
+    while (current && current.tagName && current !== document.body) {
+        const tag = current.tagName.toLowerCase();
+        const idx = getElementIndex(current);
+        parts.push(`${tag}[${idx}]`);
+        current = current.parentElement;
+    }
+    parts.push("body");
+    return parts.reverse().join("/");
+}
+export function normalizeWhitespace(value) {
+    return (value || "").toString().replace(/\s+/g, " ").trim();
+}
+export function isTranslatableText(text) {
+    if (!text || text.trim().length < 2)
+        return false;
+    if (/^(__[A-Z0-9_]+__\s*)+$/.test(text))
+        return false;
+    if (/^\d+(\.\d+)?$/.test(text))
+        return false;
+    if (!/[a-zA-Z\u00C0-\u024F\u1E00-\u1EFF]/.test(text))
+        return false;
+    return true;
+}
+export function buildStableId(el, text, textIndex) {
+    const key = getStableKey(el);
+    const path = buildElementPath(el);
+    const raw = `${path}#text[${textIndex}]|${text.trim()}|${key}`;
+    return hashContent(raw);
+}
+export function buildSelector(el) {
+    const id = el.id;
+    if (id)
+        return `#${id.replace(/[^a-zA-Z0-9_-]/g, "\\$&")}`;
+    const className = el.className;
+    if (typeof className === "string" && className.trim()) {
+        const classes = className
+            .split(/\s+/)
+            .map((c) => c.trim())
+            .filter(Boolean)
+            .slice(0, 3)
+            .map((c) => `.${c.replace(/[^a-zA-Z0-9_-]/g, "\\$&")}`)
+            .join("");
+        if (classes)
+            return classes;
+    }
+    return null;
+}

package/dist/utils/markerEngineFilters.d.ts

@@ -0,0 +1,2 @@
+export declare function isExcludedElement(el: Element | null): boolean;
+export declare function findUnsafeContainer(el: Element | null): Element | null;

package/dist/utils/markerEngineFilters.js

@@ -0,0 +1,26 @@
+import { EXCLUDE_SELECTOR, unsafeSelector } from "./markerEngineConstants";
+import { getCustomExcludeSelector } from "./markerEngineState";
+export function isExcludedElement(el) {
+    if (!el)
+        return false;
+    if (el.closest(EXCLUDE_SELECTOR))
+        return true;
+    const customExcludeSelector = getCustomExcludeSelector();
+    if (customExcludeSelector) {
+        try {
+            if (el.closest(customExcludeSelector))
+                return true;
+        }
+        catch {
+            // ignore invalid selector strings
+        }
+    }
+    return false;
+}
+export function findUnsafeContainer(el) {
+    if (!el)
+        return null;
+    if (!unsafeSelector)
+        return null;
+    return el.closest(unsafeSelector);
+}

package/dist/utils/markerEngineMisses.d.ts

@@ -0,0 +1,5 @@
+import type { DomMissScanResult } from "./markerEngineTypes";
+export declare function scanDomForMisses(opts: {
+    max: number;
+    ignore?: Set<string>;
+}): DomMissScanResult;

package/dist/utils/markerEngineMisses.js

@@ -0,0 +1,81 @@
+import { ATTRIBUTE_MARKS } from "./markerEngineConstants";
+import { findUnsafeContainer, isExcludedElement } from "./markerEngineFilters";
+import { getActiveTranslationMap } from "./markerEngineState";
+import { isTranslatableText, normalizeWhitespace } from "./markerEngineDomUtils";
+import { getOrInitAttrOriginal, getOrInitTextOriginal } from "./markerEngineOriginals";
+export function scanDomForMisses(opts) {
+    const root = document.body;
+    const misses = [];
+    if (!root) {
+        return { misses };
+    }
+    // Why: allow live miss scans even when bundles are empty so first-time pages still report.
+    const translationMap = getActiveTranslationMap();
+    const hasTranslations = Boolean(translationMap && translationMap.size > 0);
+    const max = Math.max(0, Math.floor(opts.max || 0));
+    if (max <= 0)
+        return { misses };
+    const ignore = opts.ignore || new Set();
+    const seen = new Set();
+    const recordMiss = (text, context) => {
+        if (!text || seen.has(text) || ignore.has(text))
+            return;
+        if (hasTranslations && translationMap.has(text))
+            return;
+        if (misses.length >= max)
+            return;
+        seen.add(text);
+        misses.push({ source_text: text, semantic_context: context });
+    };
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+    let node = walker.nextNode();
+    while (node && misses.length < max) {
+        if (node.nodeType !== Node.TEXT_NODE) {
+            node = walker.nextNode();
+            continue;
+        }
+        const textNode = node;
+        const parent = textNode.parentElement;
+        if (!parent || isExcludedElement(parent) || findUnsafeContainer(parent)) {
+            node = walker.nextNode();
+            continue;
+        }
+        const raw = textNode.nodeValue || "";
+        const trimmed = raw.trim();
+        if (!trimmed || !isTranslatableText(trimmed)) {
+            node = walker.nextNode();
+            continue;
+        }
+        const original = getOrInitTextOriginal(textNode, parent);
+        const key = normalizeWhitespace(original.trimmed);
+        if (key) {
+            recordMiss(key, "text");
+        }
+        node = walker.nextNode();
+    }
+    if (misses.length < max) {
+        const nodes = root.querySelectorAll("[title],[aria-label],[placeholder]");
+        nodes.forEach((el) => {
+            if (misses.length >= max)
+                return;
+            if (isExcludedElement(el) || findUnsafeContainer(el))
+                return;
+            for (const { attr } of ATTRIBUTE_MARKS) {
+                if (misses.length >= 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)
+                    continue;
+                const context = attr === "title" ? "attr:title" : attr === "aria-label" ? "attr:aria-label" : "attr:placeholder";
+                recordMiss(original, context);
+            }
+        });
+    }
+    return { misses };
+}

package/dist/utils/markerEngineOriginals.d.ts

@@ -0,0 +1,5 @@
+import type { TextOriginal } from "./markerEngineTypes";
+export declare const originalTextByNode: WeakMap<Text, TextOriginal>;
+export declare const originalAttrByEl: WeakMap<HTMLElement, Map<string, string>>;
+export declare function getOrInitTextOriginal(node: Text, parent: Element): TextOriginal;
+export declare function getOrInitAttrOriginal(el: HTMLElement, attr: string): string;

package/dist/utils/markerEngineOriginals.js

@@ -0,0 +1,29 @@
+import { buildStableId, getTextNodeIndex } from "./markerEngineDomUtils";
+export const originalTextByNode = new WeakMap();
+export const originalAttrByEl = new WeakMap();
+export function getOrInitTextOriginal(node, parent) {
+    const existing = originalTextByNode.get(node);
+    if (existing)
+        return existing;
+    const raw = node.nodeValue || "";
+    const leading = raw.match(/^\s*/)?.[0] ?? "";
+    const trailing = raw.match(/\s*$/)?.[0] ?? "";
+    const trimmed = raw.trim();
+    const id = buildStableId(parent, trimmed, getTextNodeIndex(node));
+    const created = { raw, trimmed, leading, trailing, id };
+    originalTextByNode.set(node, created);
+    return created;
+}
+export function getOrInitAttrOriginal(el, attr) {
+    let map = originalAttrByEl.get(el);
+    if (!map) {
+        map = new Map();
+        originalAttrByEl.set(el, map);
+    }
+    const existing = map.get(attr);
+    if (existing != null)
+        return existing;
+    const value = (el.getAttribute(attr) || "").toString();
+    map.set(attr, value);
+    return value;
+}

package/dist/utils/markerEngineScan.d.ts

@@ -0,0 +1,5 @@
+import type { DomScanResult } from "./markerEngineTypes";
+export declare function scanDom(opts: {
+    maxSegments: number;
+    includeCritical?: boolean;
+}): DomScanResult;

package/dist/utils/markerEngineScan.js

@@ -0,0 +1,162 @@
+import { ATTRIBUTE_MARKS, DEFAULT_CRITICAL_BUFFER_PX, DEFAULT_CRITICAL_MAX, } from "./markerEngineConstants";
+import { isExcludedElement, findUnsafeContainer } from "./markerEngineFilters";
+import { buildSelector, isTranslatableText, normalizeWhitespace } from "./markerEngineDomUtils";
+import { getOrInitAttrOriginal, getOrInitTextOriginal } from "./markerEngineOriginals";
+import { buildEmptyStats, finalizeStats } from "./markerEngineStats";
+import { getTextNodeRect, isInViewport } from "./markerEngineViewport";
+function considerTextNode(node, stats, segments, occurrences, seen, maxSegments, critical) {
+    const raw = node.nodeValue || "";
+    if (!raw)
+        return;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return;
+    stats.totalTextNodes += 1;
+    stats.totalChars += raw.length;
+    const parent = node.parentElement;
+    if (!parent)
+        return;
+    if (isExcludedElement(parent)) {
+        stats.skippedExcludedNodes += 1;
+        stats.skippedExcludedChars += raw.length;
+        return;
+    }
+    const unsafe = findUnsafeContainer(parent);
+    if (unsafe) {
+        stats.skippedUnsafeNodes += 1;
+        stats.skippedUnsafeChars += raw.length;
+        return;
+    }
+    if (!isTranslatableText(trimmed)) {
+        stats.skippedNonTranslatableNodes += 1;
+        stats.skippedNonTranslatableChars += raw.length;
+        return;
+    }
+    const original = getOrInitTextOriginal(node, parent);
+    stats.markedNodes += 1;
+    stats.markedChars += raw.length;
+    if (segments.length < maxSegments) {
+        const originalText = normalizeWhitespace(original.trimmed) || null;
+        const currentText = normalizeWhitespace(node.nodeValue || "") || null;
+        segments.push({
+            kind: "text",
+            selector: buildSelector(parent),
+            original: originalText,
+            current: currentText,
+            html: null,
+        });
+        if (originalText && !seen.has(originalText)) {
+            seen.add(originalText);
+            occurrences.push({ source_text: originalText, semantic_context: "text" });
+        }
+        if (critical?.enabled && originalText && !critical.seen.has(originalText)) {
+            const rect = getTextNodeRect(node);
+            if (isInViewport(rect, critical.viewportHeight, critical.bufferPx)) {
+                critical.seen.add(originalText);
+                critical.occurrences.push({ source_text: originalText, semantic_context: "critical:text" });
+            }
+        }
+    }
+}
+function considerAttributes(root, segments, occurrences, seen, maxSegments, critical) {
+    const nodes = root.querySelectorAll("[title],[aria-label],[placeholder]");
+    nodes.forEach((el) => {
+        if (isExcludedElement(el))
+            return;
+        if (findUnsafeContainer(el))
+            return;
+        for (const { attr } of ATTRIBUTE_MARKS) {
+            const value = el.getAttribute(attr);
+            if (!value)
+                continue;
+            const trimmed = value.trim();
+            if (!trimmed || !isTranslatableText(trimmed))
+                continue;
+            const original = normalizeWhitespace(getOrInitAttrOriginal(el, attr)) || null;
+            const current = normalizeWhitespace(el.getAttribute(attr) || "") || null;
+            const kind = (attr === "title" ? "title" : attr === "aria-label" ? "aria-label" : "placeholder");
+            if (segments.length < maxSegments) {
+                segments.push({
+                    kind,
+                    selector: buildSelector(el),
+                    original,
+                    current,
+                    html: null,
+                });
+            }
+            if (original && !seen.has(original)) {
+                seen.add(original);
+                occurrences.push({ source_text: original, semantic_context: `attr:${attr}` });
+            }
+            if (critical?.enabled && original && !critical.seen.has(original)) {
+                let rect = null;
+                try {
+                    rect = el.getBoundingClientRect();
+                }
+                catch {
+                    rect = null;
+                }
+                if (isInViewport(rect, critical.viewportHeight, critical.bufferPx)) {
+                    critical.seen.add(original);
+                    critical.occurrences.push({ source_text: original, semantic_context: `critical:attr:${attr}` });
+                }
+            }
+        }
+    });
+}
+export function scanDom(opts) {
+    const root = document.body;
+    if (!root) {
+        const empty = buildEmptyStats();
+        return { version: 1, stats: empty, segments: [], occurrences: [], truncated: false };
+    }
+    const stats = buildEmptyStats();
+    const maxSegments = Math.max(0, Math.floor(opts.maxSegments || 0)) || 20000;
+    const includeCritical = opts.includeCritical === true;
+    const viewportHeight = includeCritical ? Math.max(0, Math.floor(window.innerHeight || 0)) : 0;
+    const viewportWidth = includeCritical ? Math.max(0, Math.floor(window.innerWidth || 0)) : 0;
+    // Why: include a small buffer so "near the fold" text is ready without delaying first paint.
+    const critical = includeCritical
+        ? {
+            enabled: true,
+            viewportHeight,
+            bufferPx: DEFAULT_CRITICAL_BUFFER_PX,
+            max: DEFAULT_CRITICAL_MAX,
+            seen: new Set(),
+            occurrences: [],
+        }
+        : null;
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+    const nodes = [];
+    const segments = [];
+    const occurrences = [];
+    const seen = new Set();
+    let node = walker.nextNode();
+    while (node) {
+        if (node.nodeType === Node.TEXT_NODE)
+            nodes.push(node);
+        node = walker.nextNode();
+    }
+    nodes.forEach((textNode) => {
+        if (critical?.enabled && critical.occurrences.length >= critical.max) {
+            critical.enabled = false;
+        }
+        considerTextNode(textNode, stats, segments, occurrences, seen, maxSegments, critical);
+    });
+    considerAttributes(root, segments, occurrences, seen, maxSegments, critical);
+    finalizeStats(stats);
+    const truncated = segments.length >= maxSegments;
+    return {
+        version: 1,
+        stats,
+        segments,
+        occurrences,
+        ...(includeCritical
+            ? {
+                critical_occurrences: critical?.occurrences ?? [],
+                viewport: { width: viewportWidth, height: viewportHeight },
+            }
+            : {}),
+        truncated,
+    };
+}