browserwright 0.8.2__tar.gz → 0.9.0__tar.gz

{browserwright-0.8.2/src/browserwright.egg-info → browserwright-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: browserwright
-Version: 0.8.2
+Version: 0.9.0
 Summary: Browserwright — let AI/code agents drive a real or isolated browser and author userscripts. Single package: the agent-facing REPL/site-skills/memory layer plus the bundled browser-resolving daemon (CDP proxy + extension/cloud backends).
 License-Expression: AGPL-3.0-only
 Requires-Python: >=3.11
@@ -10,6 +10,7 @@ Requires-Dist: pillow==12.2.0
 Requires-Dist: httpx>=0.27
 Requires-Dist: playwright>=1.60.0
 Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: html-to-markdown<4,>=3.10.6
 Provides-Extra: ux
 Requires-Dist: rich>=13; extra == "ux"
 Dynamic: license-file

{browserwright-0.8.2 → browserwright-0.9.0}/pyproject.toml

@@ -15,7 +15,7 @@ name = "browserwright"
 # stamping regex is `^(version\s*=\s*)["'][^"']+["']\s*$` and CI aborts unless
 # it matches exactly once. `tests/skill/test_release_versioning.py` enforces all
 # of that before a tag is ever pushed. See RELEASING.md.
-version = "0.8.2"
+version = "0.9.0"
 description = "Browserwright — let AI/code agents drive a real or isolated browser and author userscripts. Single package: the agent-facing REPL/site-skills/memory layer plus the bundled browser-resolving daemon (CDP proxy + extension/cloud backends)."
 requires-python = ">=3.11"
 license = "AGPL-3.0-only"
@@ -30,6 +30,26 @@ dependencies = [
     # daemon-resolved Chrome and does not need Playwright's bundled browser.
     "playwright>=1.60.0",
     "pyyaml>=6.0.3",
+    # HTML -> Markdown for the `read_markdown()` content view (ADR-0006/0007).
+    # Rust core + PyO3, and it pulls in NOTHING transitively — which is why it
+    # beat `markdownify` (bs4 + soupsieve) and `trafilatura` (lxml + a 32 MB
+    # babel locale tree) here. It is also the only converter measured that
+    # carries `class="language-*"` into a fenced ```lang block and keeps
+    # `rowspan` cells, both of which matter on the documentation pages this
+    # view exists to read.
+    #
+    # We deliberately track upstream rather than freeze: the project is running
+    # a systematic markdown-fidelity campaign (its own "Phase Z..HH" feat
+    # series) that keeps improving exactly what we depend on. The safety net for
+    # that is `tests/skill/test_markdown_golden.py` — golden files turn an
+    # upstream byte-level output change into a CI failure instead of a silent
+    # shift in what every agent reads. ADR-0007 makes those tests a precondition
+    # of this `>=`, not an optional extra.
+    #
+    # The `<4` cap is not conservatism about features: 3.0.0 removed the v1
+    # `convert_to_markdown()` entry point outright, so a major bump can break us
+    # at import time. Raise it deliberately, with the golden files as the diff.
+    "html-to-markdown>=3.10.6,<4",
 ]
 
 [project.optional-dependencies]
@@ -58,6 +78,11 @@ browserwright = [
     "site_skills_starter/**/*.md",
     "site_skills_starter/**/*.py",
     "skill_runtime.md",
+    # Vendored Mozilla Readability, injected as SOURCE TEXT via page.evaluate
+    # (add_script_tag is blocked by page CSP; page.evaluate is not). It has to
+    # ship as a real file for that reason — see repl/vendor/README.md.
+    "repl/vendor/*.js",
+    "repl/vendor/*.md",
 ]
 
 [tool.setuptools.exclude-package-data]

{browserwright-0.8.2 → browserwright-0.9.0}/src/browserwright/__init__.py

@@ -42,6 +42,7 @@ from .errors import (  # noqa: F401
     NeedsUserConfirm,
     NetworkError,
     PageLoadFailed,
+    UnsupportedContentType,
 )
 from .primitives.discovery_api import (  # noqa: F401
     list_site_skills,
@@ -69,7 +70,7 @@ EXPORTS = [
     # errors
     "BrowserwrightError", "PageLoadFailed", "ElementNotFound", "AuthWall",
     "Captcha", "NetworkError", "DaemonUnavailable", "CDPError",
-    "NeedsUserConfirm",
+    "NeedsUserConfirm", "UnsupportedContentType",
 ]
 
 __all__ = EXPORTS

{browserwright-0.8.2 → browserwright-0.9.0}/src/browserwright/cli.py

@@ -38,6 +38,11 @@ Usage:
   browserwright whoami --session=ID
   browserwright userscript {push|list|remove|toggle|logs} ...
 
+  browserwright markdown <url> [--mode=auto|article|full] [--backend=extension|cdp]
+                               [--out=PATH] [--max-chars=N]
+      One page as Markdown. Creates and tears down its own session, so it takes
+      no -s. Absolute links, shadow DOM flattened in, HTML only.
+
   browserwright -s <session-id> task <site>/<name> [--key=value ...] [--isolated]
   browserwright list-tasks [--site SITE] [--query Q] [--json]
 
@@ -418,6 +423,149 @@ def _cmd_task(args: list[str], *, session_id: Optional[str] = None) -> int:
     return 0
 
 
+MARKDOWN_HELP = """Usage:
+  browserwright markdown <url> [--mode=auto|article|full] [--backend=extension|cdp]
+                              [--out=PATH] [--max-chars=N] [--name=LABEL]
+
+Fetch one page and print it as Markdown. Owns its whole lifecycle: it creates a
+throwaway session, navigates, converts, and tears the session down again — so
+unlike every other browser-driving command it takes no -s/--session.
+
+Links come out absolute, open shadow roots are flattened in, and same-origin
+iframes are inlined. Only HTML is converted; anything else is refused with its
+Content-Type rather than silently returning an empty-looking result.
+
+Flags:
+  --mode=auto      (default) extract the main content; if extraction collapses,
+                   fall back to the page with nav/aside/footer/forms removed
+  --mode=article   force extraction
+  --mode=full      the page verbatim — use it when you want the navigation,
+                   a form, or every link
+  --backend        extension (default, the user's real Chrome) | cdp
+  --out=PATH       write the full Markdown here instead of a temp file
+  --max-chars=N    cap what is printed (default 8000; 0 prints everything).
+                   The FULL text is always written to the file either way.
+  --name=LABEL     session label; shows as the Chrome tab group title
+"""
+
+# Runs inside the session's executor, which is the only place a live `page`
+# exists. Values arrive through the request environment (names only cross the
+# CLI boundary, never values — same discipline as `--env`), and the markdown
+# rides back on disk rather than through the executor's 10000-char console cap.
+_MARKDOWN_CODE = """
+import os
+from browserwright.repl.markdown import render_page_markdown
+
+page.goto(os.environ["BW_MD_URL"])
+_r = render_page_markdown(page, mode=os.environ["BW_MD_MODE"])
+with open(os.environ["BW_MD_OUT"], "w", encoding="utf-8") as _f:
+    _f.write(_r.markdown)
+_bw_warn("markdown: rendered as %s (%d chars)" % (_r.mode_used, len(_r.markdown)))
+for _n in _r.notes:
+    _bw_warn("markdown: " + _n)
+"""
+
+
+def _cmd_markdown(args: list[str]) -> int:
+    """``browserwright markdown <url>`` — one page, as Markdown (ADR-0006).
+
+    The one browser-driving command with no session argument: it mints a
+    throwaway one, uses it, and ends it. Teardown runs in a `finally` because a
+    leaked session leaves a tab group behind in the user's real Chrome (see
+    issue #53 for why that path is worth watching).
+    """
+    if not args or args[0] in {"-h", "--help"}:
+        sys.stdout.write(MARKDOWN_HELP)
+        return 0 if args else 1
+
+    url = args[0]
+    if url.startswith("-"):
+        print(f"usage error: expected a URL, got {url!r}", file=sys.stderr)
+        print(MARKDOWN_HELP, file=sys.stderr)
+        return 1
+    kw = _parse_kv_args(args[1:])
+
+    mode = str(kw.get("mode", "auto"))
+    from .repl.markdown import DEFAULT_MAX_CHARS, MODES, spill_path
+
+    if mode not in MODES:
+        print(f"usage error: --mode must be one of {'|'.join(MODES)}, "
+              f"got {mode!r}", file=sys.stderr)
+        return 1
+    backend = str(kw.get("backend", "extension"))
+    if backend not in ("extension", "cdp"):
+        print(f"usage error: --backend must be extension or cdp, got "
+              f"{backend!r}", file=sys.stderr)
+        return 1
+    try:
+        max_chars = int(kw.get("max-chars", DEFAULT_MAX_CHARS))
+    except (TypeError, ValueError):
+        print("usage error: --max-chars must be an integer (0 = no cap)",
+              file=sys.stderr)
+        return 1
+
+    out = kw.get("out")
+    keep_file = out is not None
+    out_path = str(out) if keep_file else spill_path(url)
+
+    import contextlib
+
+    from . import session_create
+    from .errors import BrowserwrightError
+    from .repl import inline
+    from .session_ctx import resolve_session_or_env
+
+    try:
+        sid = session_create.new(
+            backend=backend,
+            # `cdp` has no meaning without an owner: it must either launch a
+            # browser or attach to one, and a throwaway session has nobody to
+            # attach to. NOTE this launches a real Chrome, which on macOS takes
+            # the active window — the default backend is `extension` precisely
+            # so the common path never does that.
+            create=(backend == "cdp"),
+            attach=None,
+            name=str(kw.get("name", "markdown")),
+        )
+    except (ValueError, BrowserwrightError) as e:
+        print(str(e), file=sys.stderr)
+        return 1
+
+    try:
+        rc = inline.run_code(
+            _MARKDOWN_CODE,
+            session_id=sid,
+            env={"BW_MD_URL": url, "BW_MD_OUT": out_path, "BW_MD_MODE": mode},
+        )
+        if rc != 0:
+            return rc
+        try:
+            text = Path(out_path).read_text(encoding="utf-8")
+        except OSError as e:
+            print(f"markdown: could not read rendered output: {e}",
+                  file=sys.stderr)
+            return 3
+        if max_chars > 0 and len(text) > max_chars:
+            from .repl.snapshot import _truncate_lines
+
+            print(f"[markdown] truncated to {max_chars} of {len(text)} chars; "
+                  f"full text: {out_path}", file=sys.stderr)
+            sys.stdout.write(_truncate_lines(text, max_chars) + "\n")
+            keep_file = True  # the caller needs it to see the rest
+        else:
+            sys.stdout.write(text if text.endswith("\n") else text + "\n")
+        return 0
+    finally:
+        if not keep_file:
+            with contextlib.suppress(OSError):
+                Path(out_path).unlink()
+        try:
+            session_create.end(resolve_session_or_env(sid))
+        except Exception as e:  # noqa: BLE001 — never mask the real result
+            print(f"[markdown] warning: could not end throwaway session {sid}: "
+                  f"{e}", file=sys.stderr)
+
+
 def _cmd_doctor(args: list[str]) -> int:
     """A4: a ``{status, message, fix}`` check table.
 
@@ -890,6 +1038,10 @@ def main(argv: Optional[list[str]] = None) -> None:
         sys.exit(_cmd_index(rest))
     if cmd == "memory":
         sys.exit(_cmd_memory(rest))
+    # Deliberately NOT under the -s branch: this is the one browser-driving
+    # command that owns its own throwaway session (ADR-0006).
+    if cmd == "markdown":
+        sys.exit(_cmd_markdown(rest))
     if cmd == "session":
         sys.exit(_cmd_session(rest, session_id=global_session))
     if cmd == "whoami":

{browserwright-0.8.2 → browserwright-0.9.0}/src/browserwright/daemon/server/extension_upstream.py

@@ -1242,6 +1242,18 @@ class ExtensionUpstream:
                                       group_id: int) -> dict:
         resolved_group_id, info = await self._resolve_session_group(
             session_id, group_id)
+        # The adapter-memory fast path returns ``(gid, None)`` — the group
+        # query is deferred to the caller. Mirror `_group_member_tabs` and
+        # re-query by the resolved id before concluding the group is empty
+        # (e2e recovery test: an in-daemon session that just opened a tab
+        # hits the memory path and would otherwise be reported "group
+        # missing" despite a live group with tabs).
+        if info is None and isinstance(resolved_group_id, int) and resolved_group_id >= 0:
+            query_generation = self._relay_generation()
+            info = await self._relay.query_group_tabs(group_id=resolved_group_id)
+            if query_generation != self._relay_generation():
+                raise RuntimeError(
+                    "extension reconnected while resolving group membership")
         if not info or not info.get("tabs"):
             raise RuntimeError(
                 f"no recoverable tabs for group id {group_id} "

{browserwright-0.8.2 → browserwright-0.9.0}/src/browserwright/errors.py

@@ -75,6 +75,34 @@ class ElementNotFound(BrowserwrightError):
         super().__init__(f"element not found: {selector!r} after {timeout}s", fix=fix)
 
 
+class UnsupportedContentType(BrowserwrightError):
+    """The page is not HTML, so there is nothing to convert to Markdown.
+
+    Raised loudly on purpose (ADR-0007). A PDF is the motivating case: Chrome's
+    built-in viewer renders a REAL DOM (an ``<embed>`` shell), so a best-effort
+    conversion would succeed and return a short, plausible-looking result that
+    contains none of the document — a silent empty answer, which is the one
+    failure mode the markdown path is built to make impossible.
+
+    browserwright deliberately does not grow a document pipeline. Route the URL
+    to whatever handles that type and keep browserwright for HTML.
+    """
+
+    exit_code = 3
+    default_fix = (
+        "this endpoint only converts HTML; route non-HTML types "
+        "(PDF, images, binaries) to a handler for that type"
+    )
+
+    def __init__(self, url: str = "", content_type: str = "", fix: str = ""):
+        self.url, self.content_type = url, content_type
+        super().__init__(
+            f"not HTML, refusing to convert: {url} (Content-Type: "
+            f"{content_type or 'unknown'})",
+            fix=fix,
+        )
+
+
 class AuthWall(BrowserwrightError):
     exit_code = 4
     default_fix = "stop and ask the user to log in; do not type credentials from a screenshot"

browserwright-0.9.0/src/browserwright/repl/_md_convert.py

@@ -0,0 +1,101 @@
+"""The one and only place HTML becomes Markdown.
+
+ADR-0007 requires this seam: we track `html-to-markdown` with a `>=` rather
+than freezing it, so the day we swap converters — or the day upstream changes a
+default out from under us — exactly one function has to change, and
+``tests/skill/test_markdown_golden.py`` is what makes the change visible.
+
+Nothing else in the tree may import ``html_to_markdown`` directly.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+# Built once per variant. `ConversionOptions` is a plain frozen options object,
+# so module singletons are safe and save rebuilding 44 fields per page.
+_OPTIONS: dict[bool, Any] = {}
+
+
+def _options(strip_chrome: bool) -> Any:
+    if strip_chrome not in _OPTIONS:
+        from html_to_markdown import ConversionOptions, PreprocessingOptions
+
+        # Two tiers of "remove things", and the difference is the whole point:
+        #
+        #   strip_chrome=False -> remove NOTHING. The verbatim page.
+        #   strip_chrome=True  -> remove KNOWN chrome by tag/class (`<nav>`,
+        #                         `<aside>`, `<footer>`, forms, `.sidebar`…).
+        #
+        # Neither one scores or guesses which block is the article — that is
+        # Readability's job, upstream of here, and the reason this second tier
+        # exists at all is that Readability's guessing can wipe a page out
+        # (a GitHub issue page: 118 links -> 0, 2866 tokens -> 92). Tag-based
+        # removal cannot do that: it deletes the elements it recognizes and
+        # keeps everything else, so it is the honest fallback when extraction
+        # collapses — the reader wanted the body text, not the site furniture.
+        #
+        # Measured on 3.10.6 with nav/header/main/aside/footer/.sidebar/form:
+        #   enabled=False      keeps all 8 markers
+        #   preset="standard"  drops only <nav> and <form>
+        #   preset="aggressive" keeps header + body text + body links; drops the
+        #                       rest of the furniture
+        pre = (
+            PreprocessingOptions(enabled=True, preset="aggressive")
+            if strip_chrome
+            else PreprocessingOptions(enabled=False)
+        )
+        _OPTIONS[strip_chrome] = ConversionOptions(
+            # Never left at its default. `preprocessing=None` is NOT "off" — it
+            # means "use the built-in default", which is
+            # `enabled=True, remove_navigation=True, remove_forms=True`:
+            #   '<nav><a href="/n">nav link</a></nav><p>body</p><form>…</form>'
+            #     default        -> 'body\n'
+            #     enabled=False  -> '[nav link](/n)\n\nbody\n\nQ\n'
+            # So out of the box this library quietly deletes navigation and
+            # forms on EVERY conversion, including the one the caller asked to
+            # be verbatim. Removal has to be our decision, driven by `mode`, and
+            # announced — never a converter default nobody chose.
+            preprocessing=pre,
+            # Default is False, and leaving it there pads every separator row
+            # out to the widest cell in the column: a wide Wikipedia table
+            # measured 984,849 chars vs 359,598 with this on. That single flag
+            # is the whole of this library's "token-hungry" reputation.
+            compact_tables=True,
+            # Default is True, which prepends a YAML front-matter block built
+            # from <title>/<meta> whenever the document has a <head>. The agent
+            # asked for page content, not for a document envelope, and every
+            # downstream consumer would have to strip it (ADR-0007: metadata
+            # goes out-of-band, never into the body).
+            extract_metadata=False,
+            # Already the upstream default today. Pinned explicitly anyway
+            # because we track upstream with `>=`: ATX (`# h1`) vs setext
+            # (`h1\n===`) changes the bytes of every heading, and a default
+            # flip should break a golden file, not silently reshape output.
+            heading_style="atx",
+        )
+    return _OPTIONS[strip_chrome]
+
+
+def convert_html(html: str, *, strip_chrome: bool = False) -> str:
+    """Convert an HTML string to Markdown. Returns "" for empty input.
+
+    ``strip_chrome=True`` additionally removes recognized page furniture
+    (nav / aside / footer / forms / sidebar-ish class names) by tag and class,
+    never by scoring. Use it for the fallback path where the reader wants body
+    text; leave it off wherever the caller asked for the page verbatim, and off
+    for a Readability fragment, which has already been stripped.
+
+    The caller owns the empty-output decision. This function does NOT guard
+    against the upstream defect where a stray ``<td>``/``<th>`` outside a table
+    silently collapses its whole subtree to ``""`` (verified against 3.10.6:
+    ``<div><td>hello</td></div>`` -> ``""``). That defect cannot fire on
+    browser-serialized HTML, which is always well-formed — only on hand-built
+    fragments, i.e. the Readability path — so the guard lives where the
+    fragment is produced, as the "empty -> fall back to the full page" rule of
+    ADR-0007.
+    """
+    if not html or not html.strip():
+        return ""
+    from html_to_markdown import convert
+
+    return convert(html, _options(strip_chrome)).content

browserwright-0.9.0/src/browserwright/repl/_md_normalize.py

@@ -0,0 +1,234 @@
+"""The in-page half of the markdown pipeline: normalize the live DOM to HTML.
+
+This exists because ``page.content()`` silently loses two things Markdown needs,
+and neither can be recovered on the Python side (ADR-0007):
+
+- **open shadow roots are not serialized at all.** Verified in this repo: a page
+  with a declarative ``<template shadowrootmode="open">`` reports ``shadowRoot``
+  present, in-page JS reads its text fine, and the string from
+  ``page.content()`` does not contain it.
+- **relative URLs stay relative.** No Python converter resolves ``<base>``. The
+  browser resolves per document — including separately inside each iframe.
+
+So this script runs where the DOM is, rebuilds a detached copy with those two
+problems fixed, and hands back plain HTML strings.
+
+Why ``page.evaluate`` and not ``add_script_tag``
+------------------------------------------------
+Verified in this repo against ``default-src 'none'; script-src 'none'`` with
+``bypass_csp=False``: the page's own inline ``<script>`` does NOT run (CSP is
+being enforced), while ``page.evaluate("new Function('return 41+1')()")``
+returns ``42`` and ``add_script_tag`` raises. CDP's ``Runtime.evaluate`` carries
+``allowUnsafeEvalBlockedByCSP``, so protocol-driven evaluation is exempt where
+page-driven script injection is not.
+
+Three consequences the script below obeys:
+
+- **Stay synchronous.** The CSP exemption is a toggle held for the duration of
+  the protocol call; a continuation scheduled from inside it (``setTimeout``,
+  ``await``) loses it. Everything here is one synchronous pass.
+- **Never assign ``innerHTML``, never use ``DOMParser``.** Those are gated by
+  Trusted Types, which ``page.evaluate`` does NOT bypass — it runs in the main
+  world. *Reading* ``innerHTML``/``outerHTML`` and calling ``cloneNode`` /
+  ``importNode`` are unaffected, which is why the copy is built with node APIs
+  and HTML is only ever read out.
+- **Never mutate the live page.** Everything is built detached, and Readability
+  (which rewrites whatever document it is handed) only ever sees a scratch
+  document.
+
+And do not "fix" any of this by turning on ``bypass_csp``: that lets the page's
+previously-blocked inline scripts run and stops Trusted Types being enforced,
+i.e. it changes the very DOM we are here to capture.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+_VENDOR = Path(__file__).resolve().parent / "vendor"
+
+
+@lru_cache(maxsize=1)
+def _readability_source() -> str:
+    """Mozilla Readability 0.6.0, vendored. See ``vendor/README.md``."""
+    return (_VENDOR / "readability.js").read_text(encoding="utf-8")
+
+
+# The body of the injected function. Assembled with the Readability source in
+# `build_script()` below, because the extraction pass needs it in scope.
+_NORMALIZE_BODY = r"""
+  // Elements dropped wholesale: no readable content, pure token cost.
+  // `svg`/`canvas` are decorative here - when they carry an accessible name it
+  // lives on an ancestor, which survives. `template` is author-declared inert
+  // content; declarative shadow DOM is consumed by the parser long before this
+  // runs and surfaces as a real shadowRoot, handled below.
+  const DROP = new Set([
+    "SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE", "SVG", "CANVAS",
+    "LINK", "META", "BASE",
+  ]);
+  // Attributes whose value is a URL we want absolute in the output.
+  const URL_ATTRS = { A: "href", AREA: "href", IMG: "src", SOURCE: "src" };
+  const MAX_DEPTH = 128;
+
+  const stats = {
+    shadowRoots: 0,
+    sameOriginFrames: 0,
+    crossOriginFrames: 0,
+    linksTotal: 0,
+  };
+
+  const isHidden = (el) => {
+    if (el.hasAttribute("hidden")) return true;
+    if (el.getAttribute("aria-hidden") === "true") return true;
+    return false;
+  };
+
+  // Resolve against the *owning* document's base URI, which differs per frame.
+  // Reading the IDL property (`a.href`) would resolve nodes imported from an
+  // iframe against the top document instead, so resolve explicitly.
+  const absolutize = (src, clone, baseURI) => {
+    const attr = URL_ATTRS[src.nodeName.toUpperCase()];
+    if (!attr) return;
+    const raw = src.getAttribute(attr);
+    if (!raw) return;
+    if (attr === "href") stats.linksTotal += 1;
+    try {
+      clone.setAttribute(attr, new URL(raw, baseURI).href);
+    } catch (e) {
+      /* mailto:, javascript:, malformed - keep the author's value */
+    }
+  };
+
+  // Build a detached copy of `node`. Returns null when the node is dropped.
+  const build = (node, baseURI, depth) => {
+    if (depth > MAX_DEPTH) return null;
+
+    if (node.nodeType === Node.TEXT_NODE) {
+      return node.data.trim() ? node.cloneNode(false) : null;
+    }
+    if (node.nodeType !== Node.ELEMENT_NODE) return null;
+
+    const name = node.nodeName.toUpperCase();
+    if (DROP.has(name)) return null;
+    if (isHidden(node)) return null;
+
+    if (name === "IFRAME") {
+      // A null contentDocument IS the same-origin test. Sandboxed frames can
+      // throw rather than return null, hence the guard.
+      let doc = null;
+      try { doc = node.contentDocument; } catch (e) { doc = null; }
+      if (!doc || !doc.body) {
+        stats.crossOriginFrames += 1;
+        return null;
+      }
+      stats.sameOriginFrames += 1;
+      // Inline the frame body at the iframe's position, wrapped so the
+      // converter sees a block boundary instead of splicing the frame's
+      // paragraphs into the parent's.
+      const holder = document.createElement("div");
+      for (const child of Array.from(doc.body.childNodes)) {
+        const built = build(child, doc.baseURI, depth + 1);
+        if (built) holder.appendChild(built);
+      }
+      return holder.childNodes.length ? holder : null;
+    }
+
+    // Shallow clone keeps attributes; children are rebuilt so we control
+    // shadow/slot/iframe expansion.
+    const clone = node.cloneNode(false);
+    absolutize(node, clone, baseURI);
+
+    // A SLOT renders its assigned nodes. Expanding it here is what makes a
+    // flattened shadow tree come out in composed-tree order rather than
+    // shadow-then-light.
+    if (name === "SLOT" && typeof node.assignedNodes === "function") {
+      const holder = document.createElement("div");
+      for (const child of node.assignedNodes({ flatten: true })) {
+        const built = build(child, baseURI, depth + 1);
+        if (built) holder.appendChild(built);
+      }
+      return holder.childNodes.length ? holder : null;
+    }
+
+    // Open shadow root: its content is what the user actually sees, and the
+    // light children are reached through the slots inside it. A CLOSED root is
+    // indistinguishable from no root here - `shadowRoot` is null either way -
+    // so closed roots are invisible to every approach, ours included, and we
+    // cannot even report their number. See ADR-0007.
+    const root = node.shadowRoot;
+    if (root) {
+      stats.shadowRoots += 1;
+      for (const child of Array.from(root.childNodes)) {
+        const built = build(child, baseURI, depth + 1);
+        if (built) clone.appendChild(built);
+      }
+      return clone;
+    }
+
+    for (const child of Array.from(node.childNodes)) {
+      const built = build(child, baseURI, depth + 1);
+      if (built) clone.appendChild(built);
+    }
+    return clone;
+  };
+
+  // A scratch document, so Readability has something it is allowed to destroy
+  // and so the normalized tree is a real document rather than a loose node.
+  const scratch = document.implementation.createHTMLDocument(document.title || "");
+  const normalized = document.body ? build(document.body, document.baseURI, 0) : null;
+  if (normalized) {
+    for (const child of Array.from(normalized.childNodes)) {
+      scratch.body.appendChild(scratch.importNode(child, true));
+    }
+  }
+
+  const result = {
+    fullHtml: scratch.body.innerHTML,
+    articleHtml: null,
+    articleLinks: 0,
+    title: document.title || "",
+    url: location.href,
+    contentType: document.contentType || "",
+    stats: stats,
+  };
+
+  if (opts && opts.extract) {
+    // Readability rewrites the document it is given, so hand it a copy of the
+    // scratch document - never `scratch` itself, which we still need above.
+    try {
+      const forReader = scratch.cloneNode(true);
+      const article = new Readability(forReader).parse();
+      if (article && article.content) {
+        result.articleHtml = article.content;
+        // Counted here rather than in Python: the caller's collapse test is
+        // about the DOM that came out, and re-parsing markdown to count links
+        // would measure the converter instead.
+        const probe = document.implementation.createHTMLDocument("");
+        probe.body.appendChild(probe.importNode(forReader.body, true));
+        result.articleLinks = probe.querySelectorAll("a[href]").length;
+      }
+    } catch (e) {
+      result.articleHtml = null;   // treated as a collapse by the caller
+    }
+  }
+
+  return result;
+"""
+
+
+def build_script(*, extract: bool) -> str:
+    """Assemble the full ``page.evaluate`` payload.
+
+    Returns the source of a single arrow function taking one options object.
+    The Readability source is inlined only when extraction is requested — it is
+    ~91 KB, and shipping it across the CDP boundary on every full-page read
+    would be pure overhead.
+    """
+    prelude = ""
+    if extract:
+        # Readability ends with `if (typeof module === "object") module.exports
+        # = Readability;`. In a page that leaked a bundler's `module` global
+        # (webpack/browserify do), that assignment would mutate the page. A
+        # local binding shadows it so the branch is never taken.
+        prelude = "  var module = void 0;\n" + _readability_source() + "\n"
+    return "(opts) => {\n" + prelude + _NORMALIZE_BODY + "\n}"

{browserwright-0.8.2 → browserwright-0.9.0}/src/browserwright/repl/_namespace.py

@@ -101,6 +101,15 @@ def build_globals() -> dict[str, Any]:
     # to override.
     from .snapshot import make_snapshot
     g["snapshot"] = make_snapshot(handle)
+    # The second view (ADR-0006): `snapshot()` is the action view, this is the
+    # content view. Same rules — injected per heredoc, read-only, never in
+    # EXPORTS (a view needs the live `page`, which a module-level function
+    # cannot have). `g` is passed so the closure can find the executor's
+    # `_bw_warn` channel, which is injected into this same dict *after* we
+    # return; its notes (extraction path taken, iframes excluded, spill file
+    # path) go out-of-band and never into the markdown body.
+    from .markdown import make_read_markdown
+    g["read_markdown"] = make_read_markdown(handle, g)
     # Agent-editable layer last, so helpers can call core primitives.
     _load_agent_helpers(g)
     return g