@vexralabs/zerodom 0.0.1

package/dist/parser.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Core DOM-to-Interaction-Graph engine.
+ *
+ * Built on linkedom rather than jsdom: it implements the same DOM API (querySelector,
+ * getElementById, standard traversal) with a much smaller footprint. Like lxml on the
+ * Python side, it treats `<template>` as an ordinary element for traversal purposes
+ * rather than splitting its children into a separate content fragment — verified
+ * empirically, since that's exactly the behavior the shadow-DOM logic below depends on.
+ * Direct port of zerodom/parser.py.
+ */
+export { LabelLinker, textOf, getLabel } from "./labelLinker.js";
+/**
+ * A declarative shadow root: `<template shadowrootmode="open">`.
+ *
+ * Inert `<template>` content is pruned, but this one is a live subtree the browser
+ * renders — Chromium serializes open shadow roots back into exactly this form.
+ */
+export declare function isShadowRoot(el: Element): boolean;
+/** `#id` when that is legal CSS, otherwise an equivalent attribute selector. */
+export declare function cssId(value: string): string;
+/**
+ * Escape a value for a single-quoted CSS attribute selector.
+ *
+ * `name="it's"` must not produce `input[name='it's']`, which is a parse error.
+ */
+export declare function cssString(value: string): string;
+/**
+ * A `.class` token when the name is legal CSS, else an exact-word attribute
+ * selector. `class="a.b"` must not become `div.a.b` — that reads as two classes and
+ * matches a *different* element — and `class="1x"` must not become `.1x`, which is
+ * a parse error.
+ */
+export declare function classToken(value: string): string;
+export interface GraphNode {
+    id: string;
+    type: string;
+    role: string;
+    label: string;
+    selector: string;
+    input_type?: string;
+    placeholder?: string;
+    href?: string;
+    required?: boolean;
+    disabled?: boolean;
+    value?: string;
+    action: "click" | "fill";
+    frame?: string[];
+    frame_url?: string;
+}
+export interface GraphMetadata {
+    page_title: string;
+    url: string;
+    total_interactive_nodes: number;
+    parsing_latency_ms: number;
+    warning?: string;
+    frames_read?: number;
+    frames_skipped?: number;
+}
+/** One node as the compact DSL renders it. Shared so partial views — a search
+ * result, a diff — never drift from the format the full graph prints. */
+export declare function compactLine(node: GraphNode, selectors?: boolean, hrefs?: boolean): string;
+/**
+ * Nodes whose type or label contains every whitespace-separated term.
+ *
+ * Deliberately dumb: substring, case-folded, no stemming or synonyms.
+ */
+export declare function findNodes(nodes: GraphNode[], query: string): GraphNode[];
+export declare class InteractionGraph {
+    nodes: GraphNode[];
+    metadata: GraphMetadata;
+    constructor(nodes: GraphNode[], metadata: GraphMetadata);
+    toJson(indent?: number): string;
+    /** `node_id -> css selector`, so callers can act on ids alone. */
+    selectorMap(): Record<string, string>;
+    /**
+     * Token-dense line format for model context.
+     *
+     * JSON spends most of its tokens on repeated keys, quotes and braces. This drops
+     * them, and by default drops the CSS selector too: a caller holding
+     * `selectorMap()` can resolve `[03]` back to a selector itself, so the model
+     * never needs to see it. Enable `selectors`/`hrefs` when the reader has no
+     * session to resolve ids against.
+     *
+     * `*` marks required, `!` marks disabled.
+     */
+    toCompactText(options?: {
+        selectors?: boolean;
+        hrefs?: boolean;
+    }): string;
+}
+export declare class ZeroDOMParser {
+    private readonly url;
+    private readonly rawHtml;
+    private readonly document;
+    private readonly root;
+    private readonly nodes;
+    private occ;
+    private siblings;
+    private paths;
+    private shadow;
+    constructor(html: string, url?: string);
+    /**
+     * Hidden by an inline style, an ARIA attribute, or a boolean attribute.
+     *
+     * `data-zerodom-hidden` is set by the browser-side serializer, the only place a
+     * stylesheet rule can actually be resolved — parsing HTML text alone cannot see
+     * the cascade.
+     */
+    private static isHidden;
+    /** Is this something an agent can act on? */
+    private static isInteractive;
+    private static role;
+    /**
+     * Occurrences per id / tag+name / tag+class, counted once per document.
+     *
+     * Uniqueness is only claimed against what the document actually has. A selector
+     * like `input[name='color']` looks unique to the author but matches every radio
+     * in the group — so `name` and `id` selectors are only emitted when their key
+     * occurs exactly once.
+     */
+    private counts;
+    /** Cheapest CSS selector that uniquely targets this element. */
+    private selector;
+    private hasShadow;
+    /** The ancestor-or-self that is a direct child of a shadow root, if any. */
+    private static shadowBoundary;
+    /**
+     * Resolve light/shadow collisions that plain CSS cannot express.
+     *
+     * Playwright's CSS engine pierces open shadow roots, so `#host > button` matches
+     * a shadow button as well as a light one — the selector looks unique in the HTML
+     * and hits two elements at click time. Pages with no shadow root (nearly all of
+     * them) return here untouched and pay nothing.
+     */
+    private disambiguate;
+    /**
+     * CSS path anchored at the nearest ancestor `#id`, else at the root.
+     *
+     * Memoized so shared ancestors are walked once, and anchoring on an id keeps the
+     * selector short — a full root path on a deeply nested page costs more tokens
+     * than the node it describes.
+     */
+    private path;
+    /**
+     * `:nth-of-type(n)` for a child, or "" when its tag is unique among siblings.
+     *
+     * Positions are indexed per parent, not rescanned per node — rescanning is O(n^2)
+     * on flat pages with thousands of same-tag siblings.
+     */
+    private nthOfType;
+    /**
+     * Single depth-first pass: prune, collect interactive nodes and labels.
+     *
+     * Skipping a pruned or hidden subtree outright is both the pruning rule and the
+     * fast path — nothing below it is ever visited.
+     */
+    private walk;
+    parse(): InteractionGraph;
+    /**
+     * Say *why* the graph looks empty, when it does.
+     *
+     * A bot wall, an open modal and a genuinely bare page all return almost nothing,
+     * and the caller cannot tell them apart from the node list.
+     */
+    private emptyPageWarning;
+}
+/** Convenience one-shot parse. */
+export declare function parseHtml(html: string, url?: string): InteractionGraph;

package/dist/parser.js

@@ -0,0 +1,501 @@
+/**
+ * Core DOM-to-Interaction-Graph engine.
+ *
+ * Built on linkedom rather than jsdom: it implements the same DOM API (querySelector,
+ * getElementById, standard traversal) with a much smaller footprint. Like lxml on the
+ * Python side, it treats `<template>` as an ordinary element for traversal purposes
+ * rather than splitting its children into a separate content fragment — verified
+ * empirically, since that's exactly the behavior the shadow-DOM logic below depends on.
+ * Direct port of zerodom/parser.py.
+ */
+import { parseHTML } from "linkedom";
+import { LabelLinker, textOf } from "./labelLinker.js";
+export { LabelLinker, textOf, getLabel } from "./labelLinker.js";
+// `head` is deliberately absent: everything bloated inside it is pruned by name
+// anyway, and a parser that mis-files stray body content into head would lose those
+// nodes if head were skipped wholesale.
+const PRUNE_TAGS = new Set(["script", "style", "link", "svg", "meta", "noscript", "template"]);
+/**
+ * A declarative shadow root: `<template shadowrootmode="open">`.
+ *
+ * Inert `<template>` content is pruned, but this one is a live subtree the browser
+ * renders — Chromium serializes open shadow roots back into exactly this form.
+ */
+export function isShadowRoot(el) {
+    return el.localName === "template" && el.hasAttribute("shadowrootmode");
+}
+const INTERACTIVE_TAGS = new Set(["a", "button", "input", "select", "textarea"]);
+const INTERACTIVE_ROLES = new Set([
+    "button", "link", "textbox", "checkbox", "radio", "combobox",
+    "searchbox", "switch", "menuitem", "tab", "option", "slider",
+]);
+// input[type] -> ARIA role. Anything unlisted (text, email, password, ...) is a textbox.
+const INPUT_ROLES = {
+    checkbox: "checkbox",
+    radio: "radio",
+    submit: "button",
+    button: "button",
+    reset: "button",
+    image: "button",
+    file: "button", // ARIA: opens a chooser — clickable, not fillable
+    search: "searchbox",
+    range: "slider",
+};
+const TAG_ROLES = { a: "link", button: "button", select: "combobox", textarea: "textbox" };
+// Roles driven by typing text rather than clicking.
+const FILLABLE_ROLES = new Set(["textbox", "searchbox", "slider"]);
+// A CSS identifier cannot start with a digit, so `#49151933` is a parse error, not a
+// miss — querySelector throws on it. Hacker News numbers every row that way.
+const CSS_IDENT = /^-?[_a-zA-Z][_a-zA-Z0-9-]*$/;
+const DOCUMENT_START = /^\s*(<!doctype\s+html|<html[\s>])/i;
+/**
+ * Unlike lxml.html.document_fromstring (or a real browser), linkedom's parser does
+ * not normalize a bare fragment into a full document — it takes the first top-level
+ * tag as `documentElement` and silently drops any siblings after it. `page.content()`
+ * always returns a full document, so this only matters for hand-fed HTML, but it has
+ * to be handled once, here, rather than requiring every caller to know about it.
+ */
+function normalizeDocument(html) {
+    const trimmed = html.trim();
+    if (!trimmed)
+        return "<html><body></body></html>";
+    return DOCUMENT_START.test(trimmed) ? trimmed : `<html><body>${trimmed}</body></html>`;
+}
+/** `#id` when that is legal CSS, otherwise an equivalent attribute selector. */
+export function cssId(value) {
+    if (CSS_IDENT.test(value))
+        return `#${value}`;
+    return `[id="${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"]`;
+}
+/**
+ * Escape a value for a single-quoted CSS attribute selector.
+ *
+ * `name="it's"` must not produce `input[name='it's']`, which is a parse error.
+ */
+export function cssString(value) {
+    return value
+        .replace(/\\/g, "\\\\")
+        .replace(/'/g, "\\'")
+        .replace(/\n/g, "\\a ")
+        .replace(/\r/g, "\\d ");
+}
+/**
+ * A `.class` token when the name is legal CSS, else an exact-word attribute
+ * selector. `class="a.b"` must not become `div.a.b` — that reads as two classes and
+ * matches a *different* element — and `class="1x"` must not become `.1x`, which is
+ * a parse error.
+ */
+export function classToken(value) {
+    if (CSS_IDENT.test(value))
+        return `.${value}`;
+    return `[class~='${cssString(value)}']`;
+}
+/** One node as the compact DSL renders it. Shared so partial views — a search
+ * result, a diff — never drift from the format the full graph prints. */
+export function compactLine(node, selectors = false, hrefs = false) {
+    let flags = node.required ? "*" : "";
+    flags += node.disabled ? "!" : "";
+    let line = `[${node.id.replace(/^node_/, "")}] ${node.type}${flags} ${JSON.stringify(node.label)}`;
+    if (node.placeholder)
+        line += ` ph=${JSON.stringify(node.placeholder)}`;
+    if (hrefs && node.href)
+        line += ` -> ${node.href}`;
+    if (selectors)
+        line += ` (${node.selector})`;
+    return line;
+}
+/**
+ * Nodes whose type or label contains every whitespace-separated term.
+ *
+ * Deliberately dumb: substring, case-folded, no stemming or synonyms.
+ */
+export function findNodes(nodes, query) {
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    return nodes.filter((node) => {
+        const haystack = `${node.type} ${node.label}`.toLowerCase();
+        return terms.every((term) => haystack.includes(term));
+    });
+}
+export class InteractionGraph {
+    nodes;
+    metadata;
+    constructor(nodes, metadata) {
+        this.nodes = nodes;
+        this.metadata = metadata;
+    }
+    toJson(indent = 2) {
+        return JSON.stringify({ nodes: this.nodes, metadata: this.metadata }, null, indent || undefined);
+    }
+    /** `node_id -> css selector`, so callers can act on ids alone. */
+    selectorMap() {
+        const map = {};
+        for (const node of this.nodes)
+            map[node.id] = node.selector;
+        return map;
+    }
+    /**
+     * Token-dense line format for model context.
+     *
+     * JSON spends most of its tokens on repeated keys, quotes and braces. This drops
+     * them, and by default drops the CSS selector too: a caller holding
+     * `selectorMap()` can resolve `[03]` back to a selector itself, so the model
+     * never needs to see it. Enable `selectors`/`hrefs` when the reader has no
+     * session to resolve ids against.
+     *
+     * `*` marks required, `!` marks disabled.
+     */
+    toCompactText(options = {}) {
+        const lines = [`PAGE: ${this.metadata.page_title} | ${this.metadata.url}`];
+        for (const node of this.nodes)
+            lines.push(compactLine(node, options.selectors, options.hrefs));
+        return lines.join("\n");
+    }
+}
+export class ZeroDOMParser {
+    url;
+    rawHtml;
+    document;
+    root;
+    nodes = [];
+    // (kind:key) -> occurrences, one pass over the tree, keyed so each kind of
+    // uniqueness claim — id, tag|name, tag|class — is counted separately.
+    occ = null;
+    // parent element -> (child -> nth-of-type position, tag -> sibling count)
+    siblings = new Map();
+    paths = new Map();
+    shadow = null;
+    constructor(html, url = "about:blank") {
+        this.url = url;
+        this.rawHtml = html;
+        const { document } = parseHTML(normalizeDocument(html));
+        this.document = document;
+        this.root = document.documentElement;
+    }
+    /**
+     * Hidden by an inline style, an ARIA attribute, or a boolean attribute.
+     *
+     * `data-zerodom-hidden` is set by the browser-side serializer, the only place a
+     * stylesheet rule can actually be resolved — parsing HTML text alone cannot see
+     * the cascade.
+     */
+    static isHidden(el) {
+        if (el.hasAttribute("data-zerodom-hidden"))
+            return true;
+        const style = (el.getAttribute("style") ?? "").toLowerCase().replace(/\s+/g, "");
+        if (style.includes("display:none") || style.includes("visibility:hidden"))
+            return true;
+        if (el.getAttribute("aria-hidden") === "true" || el.hasAttribute("hidden"))
+            return true;
+        return el.localName === "input" && el.getAttribute("type") === "hidden";
+    }
+    /** Is this something an agent can act on? */
+    static isInteractive(el) {
+        if (INTERACTIVE_TAGS.has(el.localName)) {
+            // A bare <a> with no href is a named anchor, not something to click.
+            if (el.localName === "a" && !(el.hasAttribute("href") || el.hasAttribute("onclick")))
+                return false;
+            // Nor is `<a href="#section" id="section"></a>` — the empty fragment anchors
+            // GitHub-rendered markdown scatters through a page are link *destinations*.
+            // Clicking one does nothing.
+            if (el.localName === "a" &&
+                (el.getAttribute("href") ?? "").startsWith("#") &&
+                el.children.length === 0 &&
+                !(el.textContent ?? "").trim()) {
+                return false;
+            }
+            return true;
+        }
+        const role = el.getAttribute("role");
+        if (role && INTERACTIVE_ROLES.has(role))
+            return true;
+        return el.hasAttribute("onclick") || el.hasAttribute("tabindex");
+    }
+    static role(el) {
+        const role = el.getAttribute("role");
+        if (role)
+            return role;
+        if (el.localName === "input")
+            return INPUT_ROLES[el.getAttribute("type") ?? "text"] ?? "textbox";
+        return TAG_ROLES[el.localName] ?? "button";
+    }
+    /**
+     * Occurrences per id / tag+name / tag+class, counted once per document.
+     *
+     * Uniqueness is only claimed against what the document actually has. A selector
+     * like `input[name='color']` looks unique to the author but matches every radio
+     * in the group — so `name` and `id` selectors are only emitted when their key
+     * occurs exactly once.
+     */
+    counts() {
+        if (this.occ === null) {
+            const counts = new Map();
+            const bump = (key) => counts.set(key, (counts.get(key) ?? 0) + 1);
+            for (const el of [this.root, ...Array.from(this.root.querySelectorAll("*"))]) {
+                const id = el.getAttribute("id");
+                if (id)
+                    bump(`i:${id}`);
+                const name = el.getAttribute("name");
+                if (name)
+                    bump(`n:${el.localName}:${name}`);
+                for (const cls of (el.getAttribute("class") ?? "").split(/\s+/).filter(Boolean)) {
+                    bump(`c:${el.localName}:${cls}`);
+                }
+            }
+            this.occ = counts;
+        }
+        return this.occ;
+    }
+    /** Cheapest CSS selector that uniquely targets this element. */
+    selector(el) {
+        const id = el.getAttribute("id");
+        if (id && this.counts().get(`i:${id}`) === 1)
+            return cssId(id);
+        const name = el.getAttribute("name");
+        if (name && this.counts().get(`n:${el.localName}:${name}`) === 1) {
+            return `${el.localName}[name='${cssString(name)}']`;
+        }
+        // Only claim uniqueness when a single class already pins the element down; a
+        // pair that is jointly unique is possible but not worth an xpath-equivalent per node.
+        const classes = (el.getAttribute("class") ?? "").split(/\s+/).filter((c) => c && c.length < 30 && !c.includes(":"));
+        for (const cls of classes) {
+            if (this.counts().get(`c:${el.localName}:${cls}`) === 1)
+                return `${el.localName}${classToken(cls)}`;
+        }
+        // Structural fallback: a full ancestor path is verbose but always unique, unlike
+        // a bare `tag:nth-of-type(n)` which matches under every parent.
+        return this.disambiguate(el, this.path(el) || el.localName);
+    }
+    hasShadow() {
+        if (this.shadow === null) {
+            this.shadow = Array.from(this.root.querySelectorAll("template")).some(isShadowRoot);
+        }
+        return this.shadow;
+    }
+    /** The ancestor-or-self that is a direct child of a shadow root, if any. */
+    static shadowBoundary(el) {
+        let node = el;
+        let parent = el.parentElement;
+        while (parent !== null) {
+            if (isShadowRoot(parent))
+                return node;
+            node = parent;
+            parent = parent.parentElement;
+        }
+        return null;
+    }
+    /**
+     * Resolve light/shadow collisions that plain CSS cannot express.
+     *
+     * Playwright's CSS engine pierces open shadow roots, so `#host > button` matches
+     * a shadow button as well as a light one — the selector looks unique in the HTML
+     * and hits two elements at click time. Pages with no shadow root (nearly all of
+     * them) return here untouched and pay nothing.
+     */
+    disambiguate(el, path) {
+        if (!this.hasShadow())
+            return path;
+        const boundary = ZeroDOMParser.shadowBoundary(el);
+        if (boundary === null) {
+            // `:light()` is Playwright's non-piercing matcher: scope the whole path,
+            // every hop, to the light tree the HTML actually described.
+            return `:light(${path})`;
+        }
+        // A shadow child collides only at the boundary hop; above it, both trees share
+        // the same ancestors. Positions are counted per tree, so an identical tag at an
+        // identical position on the host is the one ambiguous case.
+        const shadowParent = boundary.parentElement; // the <template shadowrootmode> itself
+        const host = shadowParent?.parentElement ?? null;
+        const segment = this.nthOfType(boundary, shadowParent);
+        const twin = host !== null &&
+            Array.from(host.children).some((child) => child.localName === boundary.localName && this.nthOfType(child, host) === segment);
+        // Light matches come first in Playwright's document order, so the twin is nth=1.
+        return twin ? `${path} >> nth=1` : path;
+    }
+    /**
+     * CSS path anchored at the nearest ancestor `#id`, else at the root.
+     *
+     * Memoized so shared ancestors are walked once, and anchoring on an id keeps the
+     * selector short — a full root path on a deeply nested page costs more tokens
+     * than the node it describes.
+     */
+    path(el) {
+        const chain = [];
+        let node = el;
+        let path;
+        for (;;) {
+            const cached = this.paths.get(node);
+            if (cached !== undefined) {
+                path = cached;
+                break;
+            }
+            const parent = node.parentElement;
+            if (parent === null) {
+                // reached <html>, which we leave implicit
+                path = "";
+                break;
+            }
+            const nodeId = node.getAttribute("id");
+            if (node !== el && nodeId && this.counts().get(`i:${nodeId}`) === 1) {
+                path = cssId(nodeId);
+                this.paths.set(node, path);
+                break;
+            }
+            chain.push(node);
+            node = parent;
+        }
+        for (let i = chain.length - 1; i >= 0; i--) {
+            const n = chain[i];
+            // The shadow root itself has no live counterpart — the browser exposes its
+            // children as children of the host, and Playwright's `>` reaches them.
+            if (isShadowRoot(n)) {
+                this.paths.set(n, path);
+                continue;
+            }
+            // Child combinator, not descendant: `:nth-of-type` is omitted when a tag is
+            // unique among its *siblings*, which only pins the element down if every hop
+            // is a direct one. Under a descendant combinator `span a` also matches an <a>
+            // nested two spans deep — on Hacker News that aimed "new" at the logo.
+            const parent = n.parentElement;
+            let segment = parent === null ? n.localName : `${n.localName}${this.nthOfType(n, parent)}`;
+            // A live DOM already has the <tbody> a <table> implies; this only matters
+            // when building the path from source HTML that hasn't been through a browser
+            // yet — kept for parity with a raw-source parse.
+            //
+            // Known limitation: a table that *mixes* authored sections with bare <tr>s
+            // splits into two live <tbody> elements, and only a tbody index tells them
+            // apart. That renumbering is skipped here, so rows in such tables may share
+            // a selector.
+            if (n.localName === "tr" && parent?.localName === "table")
+                segment = `tbody > ${segment}`;
+            path = path ? `${path} > ${segment}` : segment;
+            this.paths.set(n, path);
+        }
+        return path;
+    }
+    /**
+     * `:nth-of-type(n)` for a child, or "" when its tag is unique among siblings.
+     *
+     * Positions are indexed per parent, not rescanned per node — rescanning is O(n^2)
+     * on flat pages with thousands of same-tag siblings.
+     */
+    nthOfType(node, parent) {
+        let cache = this.siblings.get(parent);
+        if (!cache) {
+            const totals = new Map();
+            const positions = new Map();
+            for (const child of Array.from(parent.children)) {
+                const n = (totals.get(child.localName) ?? 0) + 1;
+                totals.set(child.localName, n);
+                positions.set(child, n);
+            }
+            cache = [positions, totals];
+            this.siblings.set(parent, cache);
+        }
+        const [positions, totals] = cache;
+        const position = positions.get(node);
+        if (position === undefined || (totals.get(node.localName) ?? 0) < 2)
+            return "";
+        return `:nth-of-type(${position})`;
+    }
+    /**
+     * Single depth-first pass: prune, collect interactive nodes and labels.
+     *
+     * Skipping a pruned or hidden subtree outright is both the pruning rule and the
+     * fast path — nothing below it is ever visited.
+     */
+    walk() {
+        const found = [];
+        const labelsByFor = new Map();
+        // [element, nearest ancestor <label>], pushed reversed so pops stay in doc order.
+        const stack = [[this.root, null]];
+        while (stack.length) {
+            const [el, parentLabel] = stack.pop();
+            if ((PRUNE_TAGS.has(el.localName) && !isShadowRoot(el)) || ZeroDOMParser.isHidden(el))
+                continue;
+            let ancestorLabel = parentLabel;
+            if (el.localName === "label") {
+                ancestorLabel = el;
+                const forId = el.getAttribute("for");
+                if (forId && !labelsByFor.has(forId))
+                    labelsByFor.set(forId, el);
+            }
+            if (ZeroDOMParser.isInteractive(el))
+                found.push([el, ancestorLabel]);
+            const children = Array.from(el.children);
+            for (let i = children.length - 1; i >= 0; i--)
+                stack.push([children[i], ancestorLabel]);
+        }
+        return { found, labelsByFor };
+    }
+    parse() {
+        const start = performance.now();
+        const titleEl = this.document.querySelector("title");
+        const title = titleEl ? textOf(titleEl) : "";
+        const { found, labelsByFor } = this.walk();
+        const linker = new LabelLinker(this.document, labelsByFor);
+        for (const [el, ancestorLabel] of found) {
+            const role = ZeroDOMParser.role(el);
+            const node = {
+                id: `node_${String(this.nodes.length + 1).padStart(2, "0")}`,
+                type: el.localName,
+                role,
+                label: linker.label(el, ancestorLabel),
+                selector: this.selector(el),
+                action: FILLABLE_ROLES.has(role) ? "fill" : "click",
+            };
+            if (el.localName === "input")
+                node.input_type = el.getAttribute("type") ?? "text";
+            const placeholder = el.getAttribute("placeholder");
+            if (placeholder)
+                node.placeholder = placeholder;
+            const href = el.getAttribute("href");
+            if (href)
+                node.href = href;
+            if (el.hasAttribute("required"))
+                node.required = true;
+            if (el.hasAttribute("disabled"))
+                node.disabled = true;
+            if (FILLABLE_ROLES.has(role)) {
+                node.value = el.localName === "input" ? el.getAttribute("value") ?? "" : directText(el);
+            }
+            this.nodes.push(node);
+        }
+        const metadata = {
+            page_title: title || "Untitled",
+            url: this.url,
+            total_interactive_nodes: this.nodes.length,
+            parsing_latency_ms: Math.round((performance.now() - start) * 100) / 100,
+        };
+        const warning = this.emptyPageWarning(this.rawHtml.length);
+        if (warning)
+            metadata.warning = warning;
+        return new InteractionGraph(this.nodes, metadata);
+    }
+    /**
+     * Say *why* the graph looks empty, when it does.
+     *
+     * A bot wall, an open modal and a genuinely bare page all return almost nothing,
+     * and the caller cannot tell them apart from the node list.
+     */
+    emptyPageWarning(htmlBytes) {
+        if (this.nodes.length > 2)
+            return null;
+        if (htmlBytes < 4000) {
+            return "Almost no interactive nodes, and the page is tiny — this is usually a bot wall or an error page, not the site you wanted.";
+        }
+        const inert = this.root.querySelectorAll('[aria-hidden="true"] a, [inert] a');
+        if (inert.length) {
+            return `Almost no interactive nodes, but ${inert.length} links sit under aria-hidden/inert — a modal or overlay is open. Dismiss it and re-read.`;
+        }
+        return "Almost no interactive nodes on a large page — the content is probably in an iframe (not traversed), a closed shadow root, or rendered to canvas.";
+    }
+}
+/** Leading text directly inside an element, before its first child tag — not the full subtree text. */
+function directText(el) {
+    const first = el.firstChild;
+    return first && first.nodeType === 3 ? first.data : "";
+}
+/** Convenience one-shot parse. */
+export function parseHtml(html, url = "about:blank") {
+    return new ZeroDOMParser(html, url).parse();
+}