nat-engine 1__py3-none-any.whl

mannf/core/browser/dom_snapshot.py

@@ -0,0 +1,349 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""DOM snapshot data model and capture utility.
+
+This module provides a lightweight, Playwright-agnostic data model for
+representing page DOM state, plus an async helper that populates a
+:class:`DOMSnapshot` from a live Playwright ``Page`` object.
+
+Import note: Playwright is **not** imported at module level — it is only
+referenced inside ``capture_dom_snapshot``, so this module can be imported
+and used for pure data-modelling work without Playwright installed.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Interactive HTML tags / selectors that accept user input or navigation.
+_INTERACTIVE_TAGS = frozenset({"button", "input", "select", "textarea"})
+
+# JavaScript that extracts element data from the live DOM.
+_DOM_EXTRACTOR_JS = """
+() => {
+    const ATTRS = ['name', 'type', 'href', 'placeholder',
+                   'aria-label', 'role', 'data-testid'];
+    const INTERACTIVE_TAGS = new Set(['button','input','select','textarea']);
+    const results = [];
+    const allElements = document.querySelectorAll('*');
+    allElements.forEach(el => {
+        const tag = el.tagName.toLowerCase();
+        const elementId = el.id || '';
+        const classes = Array.from(el.classList);
+        const rawText = (el.innerText || el.textContent || '').trim();
+        const text = rawText.length > 200 ? rawText.slice(0, 200) : rawText;
+        const attrs = {};
+        ATTRS.forEach(a => {
+            const v = el.getAttribute(a);
+            if (v !== null) attrs[a] = v;
+        });
+        const isInteractive = INTERACTIVE_TAGS.has(tag) ||
+            (tag === 'a' && el.hasAttribute('href'));
+        let bbox = null;
+        try {
+            const r = el.getBoundingClientRect();
+            if (r.width > 0 || r.height > 0) {
+                bbox = {x: r.x, y: r.y, width: r.width, height: r.height};
+            }
+        } catch(_) {}
+        results.push({tag, elementId, classes, text, attrs, isInteractive, bbox});
+    });
+    return results;
+}
+"""
+
+# JavaScript that extracts <form> structures.
+_FORM_EXTRACTOR_JS = """
+() => {
+    const forms = [];
+    document.querySelectorAll('form').forEach(form => {
+        const fields = [];
+        form.querySelectorAll('input, select, textarea').forEach(el => {
+            fields.push({
+                tag: el.tagName.toLowerCase(),
+                name: el.getAttribute('name') || '',
+                type: el.getAttribute('type') || '',
+                placeholder: el.getAttribute('placeholder') || '',
+            });
+        });
+        forms.push({
+            action: form.getAttribute('action') || '',
+            method: (form.getAttribute('method') || 'get').toLowerCase(),
+            fields,
+        });
+    });
+    return forms;
+}
+"""
+
+
+# JavaScript that extracts <form> structures with enhanced field metadata
+# (required flag, associated label text, HTML5 validation pattern, and
+# per-form submit button selector).  Used by WebCrawlerAgent.
+_ENHANCED_FORM_EXTRACTOR_JS = """
+() => {
+    function buildSelector(el) {
+        if (el.id) return '#' + el.id;
+        const testid = el.getAttribute('data-testid');
+        if (testid) return '[data-testid="' + testid + '"]';
+        const name = el.getAttribute('name');
+        if (name) return el.tagName.toLowerCase() + '[name="' + name + '"]';
+        const classes = Array.from(el.classList);
+        if (classes.length) return el.tagName.toLowerCase() + '.' + classes.join('.');
+        return el.tagName.toLowerCase();
+    }
+
+    function findLabel(el) {
+        // 1. <label for="id">
+        if (el.id) {
+            const lbl = document.querySelector('label[for="' + el.id + '"]');
+            if (lbl) return (lbl.innerText || lbl.textContent || '').trim();
+        }
+        // 2. Ancestor <label>
+        let node = el.parentElement;
+        while (node) {
+            if (node.tagName && node.tagName.toLowerCase() === 'label') {
+                return (node.innerText || node.textContent || '').trim();
+            }
+            node = node.parentElement;
+        }
+        // 3. aria-label attribute
+        return el.getAttribute('aria-label') || '';
+    }
+
+    const forms = [];
+    document.querySelectorAll('form').forEach(form => {
+        const fields = [];
+        form.querySelectorAll('input, select, textarea').forEach(el => {
+            fields.push({
+                tag: el.tagName.toLowerCase(),
+                name: el.getAttribute('name') || '',
+                type: (el.getAttribute('type') || el.tagName.toLowerCase() === 'select'
+                    ? (el.tagName.toLowerCase() === 'select' ? 'select'
+                        : (el.tagName.toLowerCase() === 'textarea' ? 'textarea'
+                            : (el.getAttribute('type') || 'text')))
+                    : 'text'),
+                placeholder: el.getAttribute('placeholder') || '',
+                required: !!(el.required || el.hasAttribute('required')),
+                label: findLabel(el),
+                pattern: el.getAttribute('pattern') || '',
+                selector: buildSelector(el),
+            });
+        });
+
+        // Identify submit selector: prefer button[type=submit], then
+        // input[type=submit], then the last button in the form.
+        let submitSel = '';
+        const submitBtn = form.querySelector('button[type="submit"]');
+        if (submitBtn) {
+            submitSel = buildSelector(submitBtn);
+        } else {
+            const submitInput = form.querySelector('input[type="submit"]');
+            if (submitInput) {
+                submitSel = buildSelector(submitInput);
+            } else {
+                const buttons = form.querySelectorAll('button');
+                if (buttons.length) {
+                    submitSel = buildSelector(buttons[buttons.length - 1]);
+                }
+            }
+        }
+
+        forms.push({
+            action: form.getAttribute('action') || '',
+            method: (form.getAttribute('method') || 'get').toUpperCase(),
+            fields,
+            submit_selector: submitSel,
+        });
+    });
+    return forms;
+}
+"""
+
+
+# ---------------------------------------------------------------------------
+# Helper
+# ---------------------------------------------------------------------------
+
+def build_selector(
+    tag: str,
+    element_id: str,
+    classes: list[str],
+    attributes: dict[str, str],
+) -> str:
+    """Generate a CSS selector with priority: id > data-testid > name > class > tag.
+
+    Parameters
+    ----------
+    tag:
+        HTML element tag name (lower-cased).
+    element_id:
+        Value of the element's ``id`` attribute (empty string if absent).
+    classes:
+        List of CSS class names on the element.
+    attributes:
+        Dict of key HTML attributes (name, type, href, placeholder, etc.).
+
+    Returns
+    -------
+    str
+        A CSS selector string that can be used to locate the element.
+    """
+    if element_id:
+        return f"#{element_id}"
+
+    data_testid = attributes.get("data-testid", "")
+    if data_testid:
+        return f'[data-testid="{data_testid}"]'
+
+    name = attributes.get("name", "")
+    if name:
+        return f'{tag}[name="{name}"]'
+
+    if classes:
+        class_part = ".".join(classes)
+        return f"{tag}.{class_part}"
+
+    return tag
+
+
+# ---------------------------------------------------------------------------
+# Data model
+# ---------------------------------------------------------------------------
+
+@dataclass
+class DOMElement:
+    """Represents a single DOM element extracted from a browser page.
+
+    Parameters
+    ----------
+    tag:
+        Lower-cased HTML tag name (e.g. ``"input"``, ``"button"``).
+    element_id:
+        Value of the ``id`` attribute; empty string if absent.
+    classes:
+        List of CSS class names present on the element.
+    text:
+        Visible text content, truncated to 200 characters.
+    attributes:
+        Dict of key HTML attributes (name, type, href, placeholder,
+        aria-label, role, data-testid).
+    selector:
+        A generated CSS selector for this element.
+    is_interactive:
+        ``True`` if the element is clickable or fillable.
+    bounding_box:
+        ``{x, y, width, height}`` in pixels, or ``None`` if unavailable.
+    """
+
+    tag: str
+    element_id: str
+    classes: list[str]
+    text: str
+    attributes: dict[str, str]
+    selector: str
+    is_interactive: bool
+    bounding_box: dict[str, float] | None = None
+
+
+@dataclass
+class DOMSnapshot:
+    """Represents a full-page DOM snapshot captured from a browser.
+
+    Parameters
+    ----------
+    url:
+        The page URL at capture time.
+    title:
+        The page ``<title>`` text.
+    timestamp:
+        ISO 8601 UTC timestamp of when the snapshot was taken.
+    elements:
+        All DOM elements discovered on the page.
+    forms:
+        Extracted form structures (action, method, fields).
+    """
+
+    url: str
+    title: str
+    timestamp: str
+    elements: list[DOMElement]
+    forms: list[dict[str, Any]] = field(default_factory=list)
+
+    @property
+    def interactive_elements(self) -> list[DOMElement]:
+        """Return only the elements marked as interactive."""
+        return [el for el in self.elements if el.is_interactive]
+
+
+# ---------------------------------------------------------------------------
+# Capture
+# ---------------------------------------------------------------------------
+
+async def capture_dom_snapshot(page: Any) -> DOMSnapshot:
+    """Capture a :class:`DOMSnapshot` from a live Playwright ``Page``.
+
+    Parameters
+    ----------
+    page:
+        A Playwright ``Page`` object (typed as ``Any`` to avoid a hard
+        import-time dependency on ``playwright``).
+
+    Returns
+    -------
+    DOMSnapshot
+        The full DOM state of the page at call time.
+    """
+    url: str = page.url
+    title: str = await page.title()
+    timestamp: str = datetime.now(timezone.utc).isoformat()
+
+    raw_elements: list[dict[str, Any]] = await page.evaluate(_DOM_EXTRACTOR_JS)
+
+    elements: list[DOMElement] = []
+    for raw in raw_elements:
+        tag = raw.get("tag", "")
+        element_id = raw.get("elementId", "")
+        classes = raw.get("classes", [])
+        text = raw.get("text", "")
+        attrs = raw.get("attrs", {})
+        is_interactive = raw.get("isInteractive", False)
+        bbox = raw.get("bbox")
+
+        selector = build_selector(tag, element_id, classes, attrs)
+
+        elements.append(
+            DOMElement(
+                tag=tag,
+                element_id=element_id,
+                classes=classes,
+                text=text,
+                attributes=attrs,
+                selector=selector,
+                is_interactive=is_interactive,
+                bounding_box=bbox,
+            )
+        )
+
+    forms: list[dict[str, Any]] = await page.evaluate(_FORM_EXTRACTOR_JS)
+
+    logger.debug(
+        "capture_dom_snapshot: url=%r elements=%d forms=%d",
+        url, len(elements), len(forms),
+    )
+
+    return DOMSnapshot(
+        url=url,
+        title=title,
+        timestamp=timestamp,
+        elements=elements,
+        forms=forms,
+    )