helixwright 0.1.0__py3-none-any.whl

helixwright/__init__.py

@@ -0,0 +1,58 @@
+"""Helixwright automation SDK.
+
+The SDK talks to Helix Browser through the desktop Local API. It does not spawn
+Chrome, generate fingerprints, or manage browser profile directories by itself.
+"""
+
+from .client import Client, Profile, discover_base_url
+from .errors import (
+    AutomationEndpointUnavailable,
+    AutomationSessionNotFound,
+    DesktopNotLoggedIn,
+    ElementNotFoundError,
+    HelixwrightError,
+    LocalApiError,
+    LocalApiUnavailable,
+    LoginRejected,
+    ProfileNotFound,
+    ReachabilityError,
+    TransportError,
+    WaitTimeoutError,
+)
+from ._impl._network import Response, Route
+from ._impl._operator import El, NoneEl, Op
+from .launcher import HelixBrowser, attach, launch
+from .models import AutomationRpc, AutomationSession, Fingerprint, LaunchConfig, Proxy
+
+__all__ = [
+    "launch",
+    "attach",
+    "Client",
+    "Profile",
+    "Fingerprint",
+    "Proxy",
+    "LaunchConfig",
+    "AutomationRpc",
+    "AutomationSession",
+    "HelixBrowser",
+    "Op",
+    "El",
+    "NoneEl",
+    "Response",
+    "Route",
+    "discover_base_url",
+    "HelixwrightError",
+    "LocalApiError",
+    "LocalApiUnavailable",
+    "DesktopNotLoggedIn",
+    "ProfileNotFound",
+    "AutomationSessionNotFound",
+    "AutomationEndpointUnavailable",
+    "TransportError",
+    "ReachabilityError",
+    "ElementNotFoundError",
+    "WaitTimeoutError",
+    "LoginRejected",
+]
+
+__version__ = "0.1.0"

helixwright/_impl/__init__.py

@@ -0,0 +1 @@
+"""Private implementation package (unstable internals). Import the public API from `helixwright`, not from here."""

helixwright/_impl/_assertions.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+import json
+import time
+from ._errors import HelixwrightError
+
+# The accessibility matchers now read via NATIVE RPC helpers on the Locator (_aria_role /
+# _accessible_name / _accessible_description over get_attribute + element_property('tagName')),
+# so NO JS runs. They remain APPROXIMATE (heuristic, not Chromium's computed accessibility tree).
+
+
+class _AssertionsBase:
+    """Polling assertion base: shared timeout, negation (not_/is_not), and the poll loop."""
+
+    def __init__(self, target, timeout_ms=5000, is_not=False):
+        self._t = target
+        self._to = timeout_ms
+        self._not = is_not
+
+    @property
+    def not_(self):
+        return type(self)(self._t, self._to, not self._not)
+
+    is_not = not_
+
+    def _poll(self, pred, desc):
+        deadline = time.time() + self._to / 1000.0
+        last = None
+        while True:
+            try:
+                last = bool(pred())
+            except (HelixwrightError, TypeError, AttributeError):
+                # transient (element gone / null evaluate) -> failed-but-retryable, never crash
+                last = False
+            if last != self._not:
+                return
+            if time.time() >= deadline:
+                raise AssertionError("expect %s%s failed (last=%r)"
+                                     % ("not_." if self._not else "", desc, last))
+            time.sleep(0.08)
+
+
+class LocatorAssertions(_AssertionsBase):
+    """Assertions about a Locator — visibility, text, value, count, state."""
+
+    def to_be_visible(self):
+        self._poll(self._t.is_visible, "to_be_visible")
+
+    def to_be_hidden(self):
+        self._poll(lambda: not self._t.is_visible(), "to_be_hidden")
+
+    def to_be_enabled(self):
+        self._poll(self._t.is_enabled, "to_be_enabled")
+
+    def to_be_disabled(self):
+        self._poll(lambda: not self._t.is_enabled(), "to_be_disabled")
+
+    def to_have_text(self, txt):
+        self._poll(lambda: self._t.text().strip() == txt, "to_have_text(%r)" % txt)
+
+    def to_contain_text(self, txt):
+        self._poll(lambda: txt in self._t.text(), "to_contain_text(%r)" % txt)
+
+    def to_have_value(self, v):
+        self._poll(lambda: self._t.input_value() == v, "to_have_value(%r)" % v)
+
+    def to_have_count(self, n):
+        self._poll(lambda: self._t.count() == n, "to_have_count(%d)" % n)
+
+    def to_be_checked(self):
+        self._poll(self._t.is_checked, "to_be_checked")
+
+    def to_be_editable(self):
+        self._poll(self._t.is_editable, "to_be_editable")
+
+    def to_be_focused(self):
+        self._poll(self._t.is_focused, "to_be_focused")
+
+    def to_have_attribute(self, name, value=None):
+        def _p():
+            v = self._t.get_attribute(name)
+            return (v is not None) if value is None else (v == value)
+        self._poll(_p, "to_have_attribute(%r,%r)" % (name, value))
+
+    # --- Playwright-parity matchers (pure-Python over Locator.evaluate/get_attribute/count) ----
+    def to_have_class(self, value):
+        """The full class attribute equals |value| (Playwright string form)."""
+        self._poll(lambda: (self._t.get_attribute("class") or "") == value, "to_have_class(%r)" % value)
+
+    def to_contain_class(self, value):
+        """The class token list contains |value|."""
+        self._poll(lambda: value in (self._t.get_attribute("class") or "").split(),
+                   "to_contain_class(%r)" % value)
+
+    def to_have_id(self, id_):
+        self._poll(lambda: (self._t.get_attribute("id") or "") == id_, "to_have_id(%r)" % id_)
+
+    def to_have_css(self, name, value):
+        # [no-JS] native WebElement::GetComputedValue via Locator.computed_style.
+        self._poll(lambda: self._t.computed_style(name) == value, "to_have_css(%r,%r)" % (name, value))
+
+    def to_have_js_property(self, name, value):
+        self._poll(lambda: self._t.evaluate("el[%s]" % json.dumps(name)) == value,
+                   "to_have_js_property(%r,%r)" % (name, value))
+
+    def to_have_values(self, values):
+        """The selected <option> values of a multi-select equal |values| (list)."""
+        want = list(values)
+        self._poll(lambda: self._t.evaluate(
+            "Array.prototype.map.call(el.selectedOptions||[],function(o){return o.value;})") == want,
+            "to_have_values(%r)" % (want,))
+
+    def to_be_empty(self):
+        """No child elements and no text (Playwright to_be_empty). [no-JS] native InnerHTML()=="" check."""
+        self._poll(lambda: (self._t.inner_html() or "").strip() == "", "to_be_empty")
+
+    def to_be_attached(self):
+        self._poll(lambda: self._t.count() > 0, "to_be_attached")
+
+    def to_be_in_viewport(self):
+        # [no-JS] VisibleBoundsInWidget() is viewport-clipped, so IsVisible() == visible-in-viewport.
+        self._poll(self._t.is_visible, "to_be_in_viewport")
+
+    def to_have_role(self, role):
+        """APPROXIMATE computed ARIA role (explicit role attr or a tag heuristic — not the engine AOM).
+        [no-JS] via Locator._aria_role (get_attribute + element_property('tagName'))."""
+        self._poll(lambda: self._t._aria_role() == role, "to_have_role(%r)" % role)
+
+    def to_have_accessible_name(self, name):
+        """APPROXIMATE accessible name (aria-label/text/alt/title heuristic). [no-JS] via native RPCs."""
+        self._poll(lambda: (self._t._accessible_name() or "").strip() == name,
+                   "to_have_accessible_name(%r)" % name)
+
+    def to_have_accessible_description(self, desc):
+        """APPROXIMATE accessible description (title heuristic). [no-JS] via native RPC."""
+        self._poll(lambda: (self._t._accessible_description() or "").strip() == desc,
+                   "to_have_accessible_description(%r)" % desc)
+
+
+class PageAssertions(_AssertionsBase):
+    """Assertions about a Page — url, title."""
+
+    def _page(self):
+        # target is normally the Page; tolerate a Locator (resolve its page) for the
+        # combined Expect's back-compat.
+        t = self._t
+        return t if hasattr(t, "goto") else getattr(t, "_page", t)
+
+    def to_have_url(self, url):
+        self._poll(lambda: url in self._page().evaluate("location.href"),
+                   "to_have_url(%r)" % url)
+
+    def to_have_title(self, title):
+        self._poll(lambda: title in self._page().evaluate("document.title"),
+                   "to_have_title(%r)" % title)
+
+
+class Expect(LocatorAssertions, PageAssertions):
+    """Back-compat combined assertions (the public ``Expect`` export). Prefer ``expect()``,
+    which returns the precise LocatorAssertions / PageAssertions for the target."""
+
+
+def expect(target, timeout_ms=5000):
+    """Polling assertion proxy for |target|: a Page -> PageAssertions (url/title), a
+    Locator -> LocatorAssertions (visibility/text/value/state). Async facade objects
+    (AsyncPage/AsyncLocator) are unwrapped to their sync object (assertions are
+    synchronous). For a bare Element use page.locator(css) instead."""
+    inner = getattr(target, "_p", None)      # AsyncPage wraps the sync Page as _p
+    if inner is None:
+        inner = getattr(target, "_l", None)  # AsyncLocator wraps the sync Locator as _l
+    if inner is not None:
+        target = inner
+    if hasattr(target, "goto"):              # a Page
+        return PageAssertions(target, timeout_ms)
+    # Locator OR Element -> BOTH expose _as_locator() (Locator returns self; Element re-resolves to a
+    # Locator from its originating selector, or raises clearly for a selector-less Element). Resolve to
+    # a Locator so assertions POLL across re-render/detach (a fixed node_id snapshot can't survive one).
+    # We no longer inspect the .text descriptor to tell Element from Locator: that property-vs-method
+    # hack breaks once the two unify, and an instance .text read would fire a get_text RPC on a
+    # navigating page. _as_locator() is a plain method (no RPC) present on both.
+    loc_fn = getattr(target, "_as_locator", None)
+    if callable(loc_fn):
+        return LocatorAssertions(loc_fn(), timeout_ms)
+    raise HelixwrightError(
+        "expect() needs a Page, Locator, or selector-based Element; got %r" % type(target).__name__)

helixwright/_impl/_consent.py

@@ -0,0 +1,80 @@
+"""Declarative cookie-consent rules (plan F7 / G3 accept_cookies).
+
+Our advantage over autoconsent extensions: we execute these with our OWN isTrusted cross-frame
+(+ shadow-piercing) click engine — no extension, no injected JS. Each entry is a Helixwright
+selector (CMP-specific id/class first — fast + precise — then aria-label, then visible text as a
+multilingual fallback). page.accept_cookies() tries them in order via find_anywhere (so a CMP
+inside an OOPIF / shadow root is reached) and isTrusted-clicks the first match. Opt-in by
+calling it; default action is 'accept'."""
+from __future__ import annotations
+
+
+# Ordered most-specific -> most-general. CMP id/class are unique enough to be safe;
+# text fallbacks are intentionally conservative (exact, common labels) to avoid mis-clicks.
+_ACCEPT = [
+    # OneTrust
+    "#onetrust-accept-btn-handler",
+    "#accept-recommended-btn-handler",
+    ".onetrust-close-btn-handler.accept",
+    # Cookiebot
+    "#CybotCookiebotDialogBodyLevelButtonLevelOptinAllowAll",
+    "#CybotCookiebotDialogBodyButtonAccept",
+    "#CybotCookiebotDialogBodyLevelButtonAccept",
+    # Usercentrics
+    'button[data-testid="uc-accept-all-button"]',
+    'button[data-testid="uc-accept-button"]',
+    # Didomi
+    "#didomi-notice-agree-button",
+    "button.didomi-button-highlight",
+    # Quantcast
+    '.qc-cmp2-summary-buttons button[mode="primary"]',
+    # Osano / TrustArc / Cookie-script / cookieconsent
+    ".osano-cm-accept-all",
+    "#truste-consent-button",
+    "#cookiescript_accept",
+    ".cc-allow",
+    ".cc-btn.cc-allow",
+    # Google Funding Choices / IAB generic
+    ".fc-cta-consent",
+    # aria-label fallbacks
+    '[aria-label="Accept all"]',
+    '[aria-label="Accept all cookies"]',
+    '[aria-label="Accept cookies"]',
+    # visible-text fallbacks (role=button restricts to actual buttons/links; @@name:
+    # filters by aria-label/text/value — the role grammar's supported text predicate).
+    'role=button@@name:Accept all',
+    'role=button@@name:Accept All Cookies',
+    'role=button@@name:Allow all',
+    'role=button@@name:I accept',
+    'role=button@@name:Agree',
+    'role=button@@name:Got it',
+    'role=button@@name:Accept',
+    'role=button@@name:Alle akzeptieren',     # de
+    'role=button@@name:Tout accepter',        # fr
+    'role=button@@name:Aceptar todo',         # es
+    'role=button@@name:接受全部',              # zh
+    'role=button@@name:同意',                  # zh/ja
+]
+
+_REJECT = [
+    "#onetrust-reject-all-handler",
+    ".ot-pc-refuse-all-handler",
+    "#CybotCookiebotDialogBodyButtonDecline",
+    "#CybotCookiebotDialogBodyLevelButtonLevelOptinDeclineAll",
+    'button[data-testid="uc-deny-all-button"]',
+    "#didomi-notice-disagree-button",
+    ".qc-cmp2-summary-buttons button[mode=\"secondary\"]",
+    ".osano-cm-deny-all",
+    ".cc-deny",
+    '[aria-label="Reject all"]',
+    '[aria-label="Decline all"]',
+    'role=button@@name:Reject all',
+    'role=button@@name:Decline all',
+    'role=button@@name:Necessary only',
+    'role=button@@name:Reject',
+    'role=button@@name:Decline',
+    'role=button@@name:Alle ablehnen',        # de
+    'role=button@@name:Tout refuser',         # fr
+]
+
+_CONSENT_SELECTORS = {"accept": _ACCEPT, "reject": _REJECT}

helixwright/_impl/_errors.py

@@ -0,0 +1,44 @@
+
+class HelixwrightError(Exception):
+    """Base for all Helixwright errors. Public API: callers can `except HelixwrightError`
+    to catch everything; the subtypes below let internal code (and callers) discriminate
+    failure CLASSES without inspecting the error message string. [B3]"""
+    pass
+
+
+class TransportError(HelixwrightError):
+    """The local RPC transport failed (socket/HTTP/JSON, or the host process died). This is a
+    SESSION-level failure -- distinct from a per-element miss -- and must NOT be swallowed by the
+    best-effort `except` sites that mean 'element not present in this frame' (a browser crash
+    mid frame-walk used to surface as a confusing 'element not found')."""
+    pass
+
+
+class ElementNotFoundError(HelixwrightError):
+    """A query resolved to no element (the host's 'not found' reply). Frame-walk / non-strict
+    lookups suppress exactly this class; everything else (incl. TransportError) propagates."""
+    pass
+
+
+class WaitTimeoutError(HelixwrightError):
+    """A wait/poll exceeded its deadline. (Named WaitTimeoutError, not TimeoutError, to avoid
+    shadowing the builtin OSError-derived TimeoutError.)"""
+    pass
+
+
+class ReachabilityError(HelixwrightError):
+    """[3.0] A pre-launch connectivity check FAILED -- the proxy is dead/unreachable or there is no
+    internet -- so the browser is NOT opened (fail BEFORE spending a launch on a dead exit). This is
+    CONNECTIVITY only, not IP-reputation vetting (the framework does not vet proxy reputation)."""
+    pass
+
+
+class LoginRejected(HelixwrightError):
+    """[Tier-1A] A submitted form/login was REJECTED by the site -- raised by fill_form/login with
+    confirm=True when an unambiguous blocking inline error (aria-invalid / [role=alert] / a known
+    error class, with non-empty text) renders after submit. `.message` carries the site's VERBATIM
+    text so the failure surfaces at the cause ('Invalid password') instead of three steps later."""
+
+    def __init__(self, message):
+        self.message = message
+        super().__init__("login/form rejected: %s" % (message,))

helixwright/_impl/_forensics.py

@@ -0,0 +1,202 @@
+"""Failure forensics (plan G2) — the anti-detection debugging moat.
+
+Competitors' debuggers (Playwright trace, DrissionPage, SeleniumBase) capture the DOM. They
+cannot answer the question that matters for a fingerprint browser: whether the page saw the
+fingerprint snapshot Helix Local API launched. capture_failure() writes that bundle locally.
+
+Defensive by construction: capturing a failure must never raise (that would mask the original
+error), so every step is individually guarded."""
+from __future__ import annotations
+
+import json
+import os
+import time
+
+
+# Compact live-fingerprint probe: the values the page really saw.
+_FP_SNAPSHOT_JS = r"""(function(){
+  function gl(){try{var c=document.createElement('canvas');
+    var x=c.getContext('webgl')||c.getContext('experimental-webgl');if(!x)return {};
+    var e=x.getExtension('WEBGL_debug_renderer_info');if(!e)return {};
+    return {renderer:x.getParameter(e.UNMASKED_RENDERER_WEBGL),
+            vendor:x.getParameter(e.UNMASKED_VENDOR_WEBGL)};}catch(_){return {};}}
+  var o={platform:navigator.platform,vendor:navigator.vendor,
+    hardwareConcurrency:navigator.hardwareConcurrency,deviceMemory:navigator.deviceMemory,
+    maxTouchPoints:navigator.maxTouchPoints,language:navigator.language,
+    languages:navigator.languages,webdriver:navigator.webdriver,userAgent:navigator.userAgent,
+    screen:[screen.width,screen.height,screen.availWidth,screen.availHeight,screen.colorDepth],
+    devicePixelRatio:window.devicePixelRatio,
+    outer:[window.outerWidth,window.outerHeight,window.screenX,window.screenY]};
+  try{o.timezone=Intl.DateTimeFormat().resolvedOptions().timeZone;}catch(_){}
+  try{var g=gl();if(g.renderer)o.webglRenderer=g.renderer;if(g.vendor)o.webglVendor=g.vendor;}catch(_){}
+  return o;})()"""
+
+
+def _safe(fn, default=None):
+    try:
+        return fn()
+    except Exception:
+        return default
+
+
+def _slug(s):
+    return "".join(c if (c.isalnum() or c in "-_") else "_" for c in str(s))[:48] or "x"
+
+
+def _live_fp_js():
+    """Return the local fingerprint snapshot probe used in failure bundles."""
+    return _FP_SNAPSHOT_JS
+
+
+def _eq(a, b):
+    if a is None or b is None:
+        return a == b
+    if str(a).strip() == str(b).strip():
+        return True
+    try:
+        return abs(float(a) - float(b)) < 1e-6
+    except (ValueError, TypeError):
+        return False
+
+
+# fingerprint snapshot key -> live JS key.
+_FINGERPRINT_TO_LIVE = [
+    ("platform", "platform"), ("hwcc", "hardwareConcurrency"), ("devmem", "deviceMemory"),
+    ("webglRenderer", "webglRenderer"), ("webglVendor", "webglVendor"),
+    ("tz", "timezone"), ("sw", "screenWidth"), ("sh", "screenHeight"),
+    ("dpr", "devicePixelRatio"), ("ua", "userAgent"), ("userAgent", "userAgent"),
+    ("vendor", "vendor"), ("maxTouch", "maxTouchPoints"),
+]
+
+
+def _delta(live, fingerprint_snapshot):
+    """Return {key: {expected, actual, live_key}} for fingerprint snapshot mismatches."""
+    if not isinstance(live, dict) or not isinstance(fingerprint_snapshot, dict):
+        return {}
+    out = {}
+    for pk, lk in _FINGERPRINT_TO_LIVE:
+        if pk not in fingerprint_snapshot:
+            continue
+        exp, act = fingerprint_snapshot.get(pk), live.get(lk)
+        if not _eq(exp, act):
+            out[pk] = {"expected": exp, "actual": act, "live_key": lk}
+    if "langs" in fingerprint_snapshot:
+        exp = fingerprint_snapshot.get("langs")
+        expl = [s.strip() for s in (exp.split(",") if isinstance(exp, str) else list(exp or []))]
+        act = live.get("languages")
+        actl = [str(s).strip() for s in (act if isinstance(act, list) else [])]
+        if expl != actl:
+            out["langs"] = {"expected": expl, "actual": actl, "live_key": "languages"}
+    return out
+
+
+# [W6.1] WAF block/challenge fingerprints for a LOCAL scan over the already-captured DOM (NO
+# network). A fingerprint that passes every readback check can still be IP/ASN-blocked; these
+# markers say WHICH WAF challenged -- turning a "delta says ok but still blocked" bundle actionable.
+_BLOCK_MARKERS = {
+    "cloudflare": ("just a moment", "checking your browser", "cf-browser-verification",
+                   "challenge-platform", "__cf_chl", "cf-turnstile", "attention required",
+                   "cf-error-details"),
+    "datadome": ("datadome", "captcha-delivery.com", "geo.captcha-delivery"),
+    "akamai": ("errors.edgesuite.net", "reference #", "access denied"),
+    "perimeterx_human": ("px-captcha", "perimeterx", "px-cdn", "press & hold", "press and hold"),
+    "imperva_incapsula": ("incapsula", "incident id", "_incap_"),
+    "generic": ("unusual traffic", "verify you are human", "are you a robot",
+                "pardon our interruption", "request blocked", "bot detection"),
+}
+
+
+def _scan_block_signals(html):
+    """[W6.1] Pure LOCAL scan of the already-captured DOM for WAF block/challenge markers (no
+    network, no navigation). Returns sorted "waf:marker" hits (empty if the page looks unblocked)."""
+    if not isinstance(html, str) or not html:
+        return []
+    low = html.lower()
+    hits = set()
+    for waf, markers in _BLOCK_MARKERS.items():
+        for m in markers:
+            if m in low:
+                hits.add("%s:%s" % (waf, m))
+    return sorted(hits)
+
+
+def capture_failure(page, label="failure", error=None):
+    """Write a forensic bundle for |page| into settings.capture_dir and return the bundle dir
+    (or None if capture is disabled / the dir can't be created). Never raises."""
+    settings = getattr(page, "settings", None)
+    base = getattr(settings, "capture_dir", None)
+    if not base:
+        return None
+    stamp = time.strftime("%Y%m%d_%H%M%S")
+    bundle = os.path.join(base, "%s_%s" % (stamp, _slug(label)))
+    if not _safe(lambda: (os.makedirs(bundle, exist_ok=True) or True), False):
+        return None
+
+    # 1) screenshot (PNG) — the visual state at failure.
+    _safe(lambda: page.screenshot(os.path.join(bundle, "screenshot.png")))
+
+    # 2) live fingerprint snapshot — what the page actually saw.
+    fp = _safe(lambda: page.evaluate(_live_fp_js()), {})
+    _safe(lambda: _write_json(os.path.join(bundle, "fingerprint.json"), fp))
+
+    # 2b) configured-vs-live delta.
+    fingerprint_snapshot = getattr(settings, "fingerprint_snapshot", None) or {}
+    delta = _safe(lambda: _delta(fp, fingerprint_snapshot), {})
+    _safe(lambda: _write_json(os.path.join(bundle, "delta.json"),
+                              {"mismatches": delta, "ok": not delta}))
+
+    # 3) action trail (G10) — the behavior leading up to the failure.
+    trail = _safe(lambda: list(getattr(page, "_trail", [])), [])
+    _safe(lambda: _write_json(os.path.join(bundle, "trail.json"), trail))
+
+    # 4) console messages (if console_listen() was active).
+    console = _safe(lambda: page.console_messages(), None)
+    if console:
+        _safe(lambda: _write_json(os.path.join(bundle, "console.json"), console))
+
+    # 5) DOM snapshot (for completeness; we already beat competitors on 1-4).
+    html = _safe(lambda: page.content(), None)
+    if isinstance(html, str):
+        _safe(lambda: _write_text(os.path.join(bundle, "page.html"), html))
+
+    # 5b) Local WAF-marker DOM scan (Cloudflare/DataDome/Akamai/PerimeterX cookie/script/global
+    #     markers in the ALREADY-captured HTML). Pure local scan — NO network/navigation (that would
+    #     destroy the captured failure state). Forensic signal only, NOT IP-reputation vetting:
+    #     IP/ASN reputation is the user's Plane B, not the framework's (no proxy pool / no preflight).
+    block_signals = _safe(lambda: _scan_block_signals(html if isinstance(html, str) else ""), [])
+    if block_signals:
+        _safe(lambda: _write_json(os.path.join(bundle, "block_signals.json"), {
+            "block_signals": block_signals,
+            "note": "local DOM WAF-marker scan of the captured page (no network)"}))
+
+    # 6) meta — url, error, fingerprint summary, think-time stats. fingerprint_summary carries the
+    #    full set the delta compares (so delta.json has complete expected values), not 7 keys.
+    _SUMMARY_KEYS = ("platform", "lang", "langs", "tz", "webglRenderer", "webglVendor",
+                     "hwcc", "devmem", "sw", "sh", "dpr", "ua", "userAgent", "vendor",
+                     "maxTouch", "webgpuArch", "voices", "color_scheme")
+    meta = {
+        "label": label,
+        "error": (str(error) if error is not None else None),
+        "url": _safe(lambda: page.url, ""),
+        "frame_depth": getattr(page, "_frame_depth", 0),
+        "humanize": getattr(settings, "humanize", None),
+        "behavior_seed": getattr(settings, "behavior_seed", 0),
+        "fingerprint_summary": {
+            k: fingerprint_snapshot.get(k) for k in _SUMMARY_KEYS if k in fingerprint_snapshot
+        },
+        "delta_ok": (not delta),
+        "block_signals": block_signals,
+        "think_time_total_s": round(getattr(getattr(page, "_hz", None), "total_slept", 0.0), 2),
+    }
+    _safe(lambda: _write_json(os.path.join(bundle, "meta.json"), meta))
+    return bundle
+
+
+def _write_json(path, obj):
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(obj, f, ensure_ascii=False, indent=2)
+
+
+def _write_text(path, text):
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(text)