sela-core 0.1.0-alpha.39 → 0.1.0-alpha.41

package/dist/services/SmartDOMPruner.js

@@ -0,0 +1,678 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SmartDOMPruner = exports.DEFAULT_PRUNER_OPTIONS = void 0;
+exports.DEFAULT_PRUNER_OPTIONS = {
+    candidateCount: 5,
+    baselineK: 30,
+    scoreFloor: 0.45,
+    repeatCollapseThreshold: 8,
+    exemplarsPerRun: 2,
+    tokenBudget: 6000,
+    // variant prefixes (hover:, md:), numeric scales (px-4, w-1/2, z-50),
+    // single-purpose atoms (flex, grid, block), color scales (text-red-500).
+    utilityClassDenyRegex: /^(?:[a-z-]+:)|^-?[a-z]+-\d/i,
+    exposeCandidatesToPrompt: true,
+};
+// ---------------------------------------------------------------------------
+class SmartDOMPruner {
+    /**
+     * Build a candidate-focused, repeat-collapsed snapshot for a FAILED selector.
+     * Runs the whole in-browser pipeline (Stages 1–6) in one evaluate pass and
+     * assembles the manifest (Stage 7) on the Node side.
+     */
+    static async prune(page, target, opts = {}) {
+        const resolved = { ...exports.DEFAULT_PRUNER_OPTIONS, ...opts };
+        // --- Stage 0: decomposition / normalization (Node-side) ----------------
+        const normalized = SmartDOMPruner.normalizeTarget(target);
+        const browserOpts = {
+            candidateCount: resolved.candidateCount,
+            baselineK: resolved.baselineK,
+            scoreFloor: resolved.scoreFloor,
+            repeatCollapseThreshold: resolved.repeatCollapseThreshold,
+            exemplarsPerRun: resolved.exemplarsPerRun,
+            tokenBudget: resolved.tokenBudget,
+            utilityClassDenySource: resolved.utilityClassDenyRegex.source,
+            utilityClassDenyFlags: resolved.utilityClassDenyRegex.flags,
+        };
+        // --- Stages 1–6 run in the browser; result is fully serializable -------
+        const browserResult = await page.evaluate(SmartDOMPruner.browserPipeline, { target: normalized, opts: browserOpts });
+        // --- Stage 7: manifest assembly (Node-side) — STUB ---------------------
+        return browserResult;
+    }
+    /**
+     * Stage 0 — fold the failed selector + DNA into a clean feature vector.
+     * Derives the leaf class when absent and trims/normalizes text fields.
+     */
+    static normalizeTarget(target) {
+        const classes = (target.classes ?? []).filter(Boolean);
+        const leafClass = target.leafClass ?? (classes.length ? classes[classes.length - 1] : undefined);
+        const norm = (s) => (s == null ? s : s.replace(/\s+/g, " ").trim());
+        return {
+            ...target,
+            classes,
+            leafClass,
+            text: norm(target.text),
+            closestLabel: norm(target.closestLabel),
+            rowAnchor: norm(target.rowAnchor),
+        };
+    }
+    /**
+     * The in-browser pipeline. MUST be self-contained — under real Playwright it
+     * is serialized and executed in the page, so it may not close over Node-side
+     * scope. Stage 1 is implemented; Stages 2–6 are stubs.
+     */
+    static browserPipeline(arg) {
+        const { opts } = arg;
+        // ---- Stage 1: lightweight, layout-free deep traversal + flat index ----
+        // HARD RULE: no getComputedStyle / getBoundingClientRect / rect reads in
+        // this pass — on a 50k-node page that thrashes layout and freezes the
+        // browser thread. Only string-cheap attribute/property reads here.
+        const SKIP = new Set([
+            "script", "style", "svg", "path", "g", "defs", "template",
+            "link", "meta", "noscript", "head", "base", "title",
+        ]);
+        const cheapHidden = (el) => {
+            if (el.getAttribute("aria-hidden") === "true")
+                return true;
+            if (el.hasAttribute("hidden"))
+                return true;
+            if (el.tagName === "INPUT" && el.getAttribute("type") === "hidden")
+                return true;
+            const st = el.getAttribute("style");
+            if (st && /(?:^|;)\s*display\s*:\s*none/i.test(st))
+                return true;
+            if (st && /(?:^|;)\s*visibility\s*:\s*hidden/i.test(st))
+                return true;
+            return false;
+        };
+        // Light DOM + OPEN shadow root + same-origin iframe body. Closed shadow
+        // roots return null (inaccessible) — Stage 5 marks them as blind spots.
+        const childrenOf = (node) => {
+            const out = [];
+            const el = node;
+            if (el.shadowRoot)
+                out.push(...Array.from(el.shadowRoot.childNodes));
+            out.push(...Array.from(node.childNodes));
+            if (node.tagName === "IFRAME") {
+                try {
+                    const d = node.contentDocument;
+                    if (d && d.body)
+                        out.push(...Array.from(d.body.childNodes));
+                }
+                catch {
+                    /* cross-origin frame — handled by the >> drill instead */
+                }
+            }
+            return out;
+        };
+        const featuresOf = (el, docOrder) => ({
+            el,
+            docOrder,
+            tag: el.tagName.toLowerCase(),
+            id: el.getAttribute("id"),
+            testid: el.getAttribute("data-testid"),
+            name: el.getAttribute("name"),
+            role: el.getAttribute("role"),
+            type: el.getAttribute("type"),
+            placeholder: el.getAttribute("placeholder"),
+            classes: Array.from(el.classList || []),
+            ariaLabel: el.getAttribute("aria-label"),
+            // Own text only (direct text-node children) — cheap, no layout.
+            text: Array.from(el.childNodes)
+                .filter((n) => n.nodeType === 3 /* TEXT_NODE */)
+                .map((n) => (n.textContent || "").trim())
+                .filter(Boolean)
+                .join(" "),
+        });
+        const index = [];
+        let rawChars = 0;
+        const ELEMENT_NODE = 1;
+        const walk = (node) => {
+            if (node.nodeType !== ELEMENT_NODE)
+                return;
+            const el = node;
+            const tag = el.tagName.toLowerCase();
+            if (SKIP.has(tag))
+                return;
+            if (cheapHidden(el))
+                return;
+            const entry = featuresOf(el, index.length);
+            index.push(entry);
+            // Shadow-inclusive raw-size estimate. innerHTML excludes shadow content,
+            // which would skew reduction% for shadow-hosted UIs (card grids etc.).
+            rawChars += tag.length * 2 + 5 + entry.text.length;
+            for (const child of childrenOf(el))
+                walk(child);
+        };
+        const root = document.body || document.documentElement;
+        if (root)
+            walk(root);
+        const originalChars = rawChars;
+        // =====================================================================
+        // Stage 2 — Candidate scoring (2a cheap baseline → 2b heavy refine)
+        // =====================================================================
+        const tt = arg.target;
+        const norm = (s) => (s || "").toLowerCase().replace(/\s+/g, " ").trim();
+        const targetName = norm(tt.text || tt.closestLabel);
+        const targetClasses = new Set((tt.classes || []).filter(Boolean));
+        const targetAncestry = new Set((tt.ancestryFingerprints || []).filter(Boolean));
+        // Minimal implicit-ARIA-role map (layout-free; no accessibility tree).
+        const IMPLICIT_ROLE = {
+            button: "button", a: "link", input: "textbox", textarea: "textbox",
+            select: "combobox", nav: "navigation", main: "main",
+            h1: "heading", h2: "heading", h3: "heading",
+            h4: "heading", h5: "heading", h6: "heading",
+        };
+        const roleOf = (e) => e.role || IMPLICIT_ROLE[e.tag] || "";
+        const fingerprintOf = (el) => {
+            const tag = el.tagName.toLowerCase();
+            const id = el.getAttribute("id");
+            const cls = Array.from(el.classList || []).sort();
+            return (tag + (id ? `#${id}` : "") + (cls.length ? `.${cls.join(".")}` : ""));
+        };
+        // Climb one logical parent, crossing shadow boundaries (host hop).
+        const parentOf = (node) => {
+            const p = node.parentNode;
+            if (!p)
+                return null;
+            return p.nodeType === 11
+                ? p.host
+                : p;
+        };
+        const ancestorFingerprints = (el, max = 15) => {
+            const out = new Set();
+            let cur = parentOf(el);
+            let depth = 0;
+            while (cur && depth < max) {
+                if (cur.tagName)
+                    out.add(fingerprintOf(cur));
+                cur = parentOf(cur);
+                depth++;
+            }
+            return out;
+        };
+        // Repeater containers: any element with ≥ threshold element children.
+        // children.length is O(1), so precomputing the set once keeps membership
+        // checks below from re-introducing the O(nodes × siblings) blow-up.
+        const repeaterContainers = new Set();
+        for (const e of index) {
+            if (e.el.children && e.el.children.length >= opts.repeatCollapseThreshold)
+                repeaterContainers.add(e.el);
+        }
+        // Nearest ancestor that is a direct child of a repeater container — the
+        // generalized "row"/member. Works for <tr>, <li>, card grids, virtual rows.
+        const repeaterMemberOf = (el) => {
+            let cur = el;
+            let depth = 0;
+            while (cur && depth < 25) {
+                const p = parentOf(cur);
+                if (p && p.tagName && repeaterContainers.has(p))
+                    return cur;
+                cur = p;
+                depth++;
+            }
+            return null;
+        };
+        // Shadow-piercing text of a member subtree (cached, bounded) — element
+        // .textContent does NOT cross shadow boundaries, so row identity for a
+        // shadow-hosted card needs an explicit deep walk.
+        const deepTextCache = new Map();
+        const deepText = (el) => {
+            const cached = deepTextCache.get(el);
+            if (cached !== undefined)
+                return cached;
+            let out = "";
+            const stack = [el];
+            let n = 0;
+            while (stack.length && out.length < 500 && n < 2000) {
+                const node = stack.pop();
+                n++;
+                if (node.nodeType === 3)
+                    out += " " + (node.textContent || "");
+                else if (node.nodeType === 1)
+                    for (const k of childrenOf(node))
+                        stack.push(k);
+            }
+            out = out.replace(/\s+/g, " ").trim();
+            deepTextCache.set(el, out);
+            return out;
+        };
+        const scoreEntry = (e) => {
+            let score = 0;
+            const signals = [];
+            // Identity (dominant).
+            if (tt.testid && e.testid && e.testid === tt.testid) {
+                score += 0.45;
+                signals.push("testid");
+            }
+            if (tt.id && e.id && e.id === tt.id) {
+                score += 0.45;
+                signals.push("id");
+            }
+            if (tt.name && e.name && e.name === tt.name) {
+                score += 0.15;
+                signals.push("name");
+            }
+            // Role + accessible name (semantics over geometry).
+            const roleMatch = !!tt.role && roleOf(e) === tt.role;
+            const nameText = norm(e.text || e.ariaLabel);
+            const nameMatch = !!targetName && !!nameText &&
+                (nameText === targetName ||
+                    nameText.includes(targetName) ||
+                    targetName.includes(nameText));
+            if (roleMatch && nameMatch) {
+                score += 0.3;
+                signals.push("role+name");
+            }
+            else if (roleMatch) {
+                score += 0.08;
+                signals.push("role");
+            }
+            else if (nameMatch) {
+                score += 0.22;
+                signals.push("text");
+            }
+            // Structural continuity.
+            if (targetAncestry.size) {
+                const anc = ancestorFingerprints(e.el);
+                let hit = 0;
+                targetAncestry.forEach((f) => { if (anc.has(f))
+                    hit++; });
+                if (hit) {
+                    score += (hit / targetAncestry.size) * 0.15;
+                    signals.push("ancestry");
+                }
+            }
+            // Row identity (the 50-buttons / virtual-scroll lever) — generalized to
+            // any repeater member, with shadow-piercing text.
+            const rowEl = repeaterMemberOf(e.el);
+            const rowMatchesIdentity = !!tt.rowAnchor && !!rowEl && deepText(rowEl).includes(tt.rowAnchor);
+            if (rowMatchesIdentity) {
+                score += 0.2;
+                signals.push("rowAnchor");
+            }
+            // Class token overlap (exact Jaccard; fuzzy typo handling lands in Stage 5).
+            if (targetClasses.size && e.classes.length) {
+                const ecls = new Set(e.classes);
+                let inter = 0;
+                targetClasses.forEach((c) => { if (ecls.has(c))
+                    inter++; });
+                const union = new Set([...targetClasses, ...e.classes]).size;
+                const j = union ? inter / union : 0;
+                if (inter) {
+                    score += j * 0.1;
+                    signals.push("class");
+                }
+            }
+            if (tt.tag && e.tag === tt.tag) {
+                score += 0.05;
+                signals.push("tag");
+            }
+            if (tt.placeholder && e.placeholder && e.placeholder === tt.placeholder) {
+                score += 0.1;
+                signals.push("placeholder");
+            }
+            if (score > 1)
+                score = 1;
+            return {
+                entry: e, score, signals, rowEl,
+                inRepeater: !!rowEl, rowMatchesIdentity,
+            };
+        };
+        // 2a — cheap baseline over the whole index, filtered by floor.
+        const baseline = index
+            .map(scoreEntry)
+            .filter((s) => s.score >= opts.scoreFloor)
+            .sort((a, b) => b.score - a.score);
+        // 2b — heavy refine STRICTLY gated to the top-K (perf invariant). Layout
+        // reads (getBoundingClientRect) happen here and ONLY here, ≤ baselineK.
+        let heavyChecks = 0;
+        const topK = baseline.slice(0, opts.baselineK);
+        const rectDeltaOf = new Map();
+        if (tt.rect) {
+            const rect = tt.rect;
+            for (const s of topK) {
+                const r = s.entry.el.getBoundingClientRect();
+                const dx = r.x - rect.x;
+                const dy = r.y - rect.y;
+                rectDeltaOf.set(s.entry, Math.round(Math.hypot(dx, dy)));
+                heavyChecks++;
+            }
+        }
+        // =====================================================================
+        // Stage 3 — Selection / multi-anchor pivot set / Trust-Engine back-off
+        // =====================================================================
+        const virtualization = (() => {
+            const grids = Array.from(document.querySelectorAll("[aria-rowcount],[aria-setsize]"));
+            for (const g of grids) {
+                const declared = Math.max(parseInt(g.getAttribute("aria-rowcount") || "", 10) || 0, parseInt(g.getAttribute("aria-setsize") || "", 10) || 0);
+                if (!declared)
+                    continue;
+                const rendered = g.querySelectorAll('[role="row"], tr, li').length;
+                if (declared - rendered >= opts.repeatCollapseThreshold)
+                    return true;
+            }
+            return false;
+        })();
+        // Identity gate: a candidate INSIDE a repeater must prove it is the
+        // target's row (rowAnchor match). Non-repeater candidates are not gated.
+        const gated = topK.filter((s) => !tt.rowAnchor || !s.inRepeater || s.rowMatchesIdentity);
+        const backoff = (reason) => ({
+            dom: "",
+            candidates: [],
+            reason,
+            stats: {
+                originalChars,
+                prunedChars: 0,
+                reductionPct: 0,
+                nodesIndexed: index.length,
+                heavyChecks,
+                estTokens: 0,
+            },
+        });
+        if (gated.length === 0) {
+            // Windowed grid + a repeater target whose row never mounted → the
+            // visible rows are NOT the target. Refuse rather than hallucinate one.
+            if (virtualization && tt.rowAnchor && topK.some((s) => s.inRepeater)) {
+                return backoff("virtualized:target-out-of-viewport");
+            }
+            // Nothing cleared the floor → element genuinely gone (real app bug).
+            return backoff("not-found");
+        }
+        // ---- Stage 7 (partial): manifest assembly ----------------------------
+        const LANDMARKS = new Set([
+            "dialog", "nav", "main", "section", "aside", "header", "footer", "form",
+        ]);
+        const landmarkPathOf = (el) => {
+            let cur = parentOf(el);
+            let depth = 0;
+            while (cur && depth < 20) {
+                const c = cur;
+                if (c.tagName) {
+                    const tag = c.tagName.toLowerCase();
+                    const role = c.getAttribute("role");
+                    if (tag === "dialog" || role === "dialog" || LANDMARKS.has(tag) || role) {
+                        const label = c.getAttribute("aria-label") || c.getAttribute("aria-labelledby");
+                        const kind = tag === "dialog" || role === "dialog" ? "dialog" : role || tag;
+                        return `${kind}${label ? `:"${label}"` : ""}`;
+                    }
+                }
+                cur = parentOf(cur);
+                depth++;
+            }
+            return null;
+        };
+        // Count preceding same-tag siblings via O(1)-step pointers. NEVER iterate
+        // `parent.children` (a jsdom HTMLCollection is O(n)-indexed → O(n²)).
+        const nthInRepeaterOf = (rowEl) => {
+            if (!rowEl)
+                return null;
+            const tag = rowEl.tagName;
+            let i = 0;
+            let c = rowEl.previousElementSibling;
+            while (c) {
+                if (c.tagName === tag)
+                    i++;
+                c = c.previousElementSibling;
+            }
+            return i;
+        };
+        const chosen = gated.slice(0, opts.candidateCount);
+        const candidates = chosen.map((s, i) => ({
+            selaCand: i,
+            rank: i + 1,
+            score: Math.round(s.score * 100) / 100,
+            matchedSignals: s.signals,
+            disambiguators: {
+                rowAnchor: s.rowMatchesIdentity ? tt.rowAnchor ?? null : null,
+                closestLabel: tt.closestLabel ?? null,
+                landmarkPath: landmarkPathOf(s.entry.el),
+                nthInRepeater: nthInRepeaterOf(s.rowEl),
+                rectDelta: rectDeltaOf.has(s.entry)
+                    ? rectDeltaOf.get(s.entry)
+                    : null,
+            },
+            semanticFlip: false,
+        }));
+        // =====================================================================
+        // Stage 4 + 5 — Repeat-collapse + serialization + class classifier
+        // =====================================================================
+        const utilityRe = new RegExp(opts.utilityClassDenySource, opts.utilityClassDenyFlags);
+        const PRESERVED = [
+            "id", "data-testid", "role", "name", "type", "placeholder",
+            "href", "alt", "title", "for", "value",
+            "aria-label", "aria-labelledby", "aria-describedby",
+        ];
+        const MAXTEXT = 200;
+        const truncate = (s) => s.length > MAXTEXT ? s.slice(0, MAXTEXT) + "…" : s;
+        // Candidate markers + survival spine (each candidate + all its ancestors).
+        const candIdOf = new Map();
+        chosen.forEach((s, i) => candIdOf.set(s.entry.el, i));
+        const spine = new Set();
+        for (const s of chosen) {
+            let cur = s.entry.el;
+            while (cur) {
+                if (cur.tagName)
+                    spine.add(cur);
+                cur = parentOf(cur);
+            }
+        }
+        // Stage 6 state: elements whose subtree the budget drops, with their token
+        // cost. Populated AFTER the first full render, then re-rendered.
+        const budgetDrop = new Set();
+        const branchTokens = new Map();
+        // Merge consecutive per-node elision markers into one (keeps output tidy
+        // and the marker overhead bounded).
+        const coalesceElided = (s) => s.replace(/(?:<!-- sela:budget-elided \d+ tokens -->)+/g, (m) => {
+            const parts = m.match(/budget-elided (\d+) tokens/g) || [];
+            let sum = 0;
+            for (const p of parts)
+                sum += parseInt(p.replace(/\D+/g, ""), 10) || 0;
+            return `<!-- sela:budget-elided ${parts.length} nodes, ~${sum} tokens -->`;
+        });
+        const semanticClasses = (el) => Array.from(el.classList || []).filter((c) => !utilityRe.test(c));
+        // Volatile-data-blind structural signature: tag + semantic classes +
+        // shallow child-tag shape (incl. open shadow). Ignores text/ids/indices so
+        // 500 data rows hash identically and collapse into one run.
+        const signatureOf = (el) => {
+            const tag = el.tagName.toLowerCase();
+            const cls = semanticClasses(el).sort().join(".");
+            const shape = childrenOf(el)
+                .filter((n) => n.nodeType === 1)
+                .map((n) => n.tagName.toLowerCase())
+                .join(",");
+            return `${tag}.${cls}|${shape}`;
+        };
+        const containsHeader = (el) => el.tagName === "TH" || !!el.querySelector?.("th");
+        // Closed shadow roots are invisible to page script. Probe via attachShadow:
+        // it THROWS when a (closed) shadow already exists → blind-spot marker. Only
+        // probed for light-empty RENDERED nodes (post-collapse), so it can never
+        // mass-mutate the page.
+        const hasClosedShadow = (el) => {
+            if (el.shadowRoot || el.childNodes.length > 0)
+                return false;
+            try {
+                el.attachShadow({ mode: "open" });
+                return false;
+            }
+            catch {
+                return true;
+            }
+        };
+        const renderAttrs = (el) => {
+            let a = "";
+            const cid = candIdOf.get(el);
+            if (cid !== undefined)
+                a += ` sela-cand="${cid}"`;
+            for (const name of PRESERVED) {
+                const v = el.getAttribute(name);
+                if (v)
+                    a += ` ${name}="${v}"`;
+            }
+            const cls = semanticClasses(el);
+            if (cls.length)
+                a += ` class="${cls.join(" ")}"`;
+            return a;
+        };
+        // Mutually recursive — function declarations so order/TDZ is a non-issue.
+        function renderNode(node) {
+            if (node.nodeType === 3) {
+                const t = (node.textContent || "").trim();
+                return t ? truncate(t) : "";
+            }
+            if (node.nodeType !== 1)
+                return "";
+            const el = node;
+            const tag = el.tagName.toLowerCase();
+            if (SKIP.has(tag) || cheapHidden(el))
+                return "";
+            if (budgetDrop.has(el)) {
+                const t = branchTokens.get(el) ?? 0;
+                return `<!-- sela:budget-elided ${t} tokens -->`;
+            }
+            const closed = hasClosedShadow(el) ? "<!-- shadow:closed -->" : "";
+            return `<${tag}${renderAttrs(el)}>${closed}${renderChildren(el)}</${tag}>`;
+        }
+        function renderChildren(el) {
+            const kids = childrenOf(el);
+            if (!repeaterContainers.has(el))
+                return kids.map(renderNode).join("");
+            // Collapse consecutive same-signature runs of element children.
+            const elemKids = kids.filter((n) => n.nodeType === 1 &&
+                !SKIP.has(n.tagName.toLowerCase()) &&
+                !cheapHidden(n));
+            const sigs = elemKids.map(signatureOf);
+            let out = "";
+            let i = 0;
+            while (i < elemKids.length) {
+                let j = i;
+                while (j < elemKids.length && sigs[j] === sigs[i])
+                    j++;
+                const run = elemKids.slice(i, j);
+                if (run.length >= opts.repeatCollapseThreshold) {
+                    // Keep: spine members (target/candidates) + header rows + a couple of
+                    // exemplars. The target row is pinned BEFORE collapse can see it, so
+                    // it is structurally impossible to drop.
+                    let shown = 0;
+                    let collapsed = 0;
+                    let exemplars = 0;
+                    for (const m of run) {
+                        if (spine.has(m) || containsHeader(m)) {
+                            out += renderNode(m);
+                            shown++;
+                        }
+                        else if (exemplars < opts.exemplarsPerRun) {
+                            out += renderNode(m);
+                            shown++;
+                            exemplars++;
+                        }
+                        else
+                            collapsed++;
+                    }
+                    if (collapsed > 0) {
+                        const sig = sigs[i].split("|")[0];
+                        out += `<!-- sela:collapsed ${collapsed} of ${run.length} «${sig}» (${shown} shown) -->`;
+                    }
+                }
+                else {
+                    for (const m of run)
+                        out += renderNode(m);
+                }
+                i = j;
+            }
+            return out;
+        }
+        let dom = root ? renderNode(root) : "";
+        // =====================================================================
+        // Stage 6 — Candidate-aware budgeting (priority elision)
+        // =====================================================================
+        if (root && Math.ceil(dom.length / 4) > opts.tokenBudget) {
+            const orderOf = new Map();
+            for (const e of index)
+                orderOf.set(e.el, e.docOrder);
+            const candOrders = chosen
+                .map((s) => orderOf.get(s.entry.el))
+                .filter((n) => n !== undefined);
+            const spineDepthOf = (el) => {
+                let d = 0;
+                let cur = el;
+                while (cur) {
+                    d++;
+                    cur = parentOf(cur);
+                }
+                return d;
+            };
+            // Elidable branches: element subtrees hanging off the spine that are
+            // neither on the spine nor inside a candidate (candidate neighborhoods
+            // are reserved). Priority = closeness to a candidate: deeper spine
+            // attachment first, then nearer in document order.
+            const branches = [];
+            for (const p of spine) {
+                if (candIdOf.has(p))
+                    continue; // never elide under a candidate
+                for (const c of childrenOf(p)) {
+                    if (c.nodeType !== 1)
+                        continue;
+                    const ce = c;
+                    if (spine.has(ce) || candIdOf.has(ce))
+                        continue;
+                    if (SKIP.has(ce.tagName.toLowerCase()) || cheapHidden(ce))
+                        continue;
+                    const ord = orderOf.get(ce) ?? 0;
+                    const dist = candOrders.length
+                        ? Math.min(...candOrders.map((o) => Math.abs(o - ord)))
+                        : 0;
+                    branches.push({
+                        el: ce,
+                        tokens: Math.ceil(renderNode(ce).length / 4),
+                        depth: spineDepthOf(p),
+                        dist,
+                    });
+                }
+            }
+            branches.sort((a, b) => b.depth - a.depth || a.dist - b.dist);
+            const branchTotal = branches.reduce((s, b) => s + b.tokens, 0);
+            const RESERVE = 40; // headroom for the coalesced elision markers
+            let used = Math.ceil(dom.length / 4) - branchTotal; // trunk cost
+            let dropping = false;
+            for (const b of branches) {
+                if (!dropping && used + b.tokens <= opts.tokenBudget - RESERVE) {
+                    used += b.tokens; // keep — closest first
+                }
+                else {
+                    dropping = true; // once over, drop this and every farther branch
+                    budgetDrop.add(b.el);
+                    branchTokens.set(b.el, b.tokens);
+                }
+            }
+            dom = coalesceElided(renderNode(root));
+            // Safety net: if marker overhead still tipped us over, drop the current
+            // farthest-kept branch and re-render, until we fit (bounded).
+            let guard = branches.length;
+            while (Math.ceil(dom.length / 4) > opts.tokenBudget && guard-- > 0) {
+                const victim = branches.filter((b) => !budgetDrop.has(b.el)).pop();
+                if (!victim)
+                    break;
+                budgetDrop.add(victim.el);
+                branchTokens.set(victim.el, victim.tokens);
+                dom = coalesceElided(renderNode(root));
+            }
+        }
+        const reductionPct = originalChars > 0
+            ? Math.round((1 - dom.length / originalChars) * 1000) / 10
+            : 0;
+        return {
+            dom,
+            candidates,
+            stats: {
+                originalChars,
+                prunedChars: dom.length,
+                reductionPct,
+                nodesIndexed: index.length,
+                heavyChecks,
+                estTokens: Math.ceil(dom.length / 4),
+            },
+        };
+    }
+}
+exports.SmartDOMPruner = SmartDOMPruner;