browserwright 0.6.2__py3-none-any.whl

browserwright/session_runtime.py

@@ -0,0 +1,133 @@
+"""Transparent reconnect-recovery for a session's tab binding.
+
+A session's durable extension anchor is its Chrome tab-group id. The ledger
+record carries a ``runtime`` cache (``current_target_id``, ``group_id``,
+``owned_tab_ids``, ``updated_at``) as a fast path — the source of truth is the
+live tab group keyed by that numeric id, recoverable via the daemon verb
+``BrowserwrightDaemon.recoverSession``.
+
+These helpers let primitives re-attach to a session's tab across daemon
+daemon restarts / extension reconnects / new ``bs run`` processes without the caller
+doing anything: ``ensure_session_target`` runs a 3-step fallback (in-process →
+ledger.runtime fast path → group-id recovery).
+"""
+from __future__ import annotations
+
+import time
+from collections import deque
+from typing import Optional
+
+from . import session_registry as reg
+from .errors import CDPError
+
+
+def _resolve_sid(sess) -> Optional[str]:
+    """Best-effort current session id from the bound record."""
+    rec = getattr(sess, "session_record", None)
+    if isinstance(rec, dict) and rec.get("id"):
+        return rec["id"]
+    return None
+
+
+def _resolve_record(sess) -> Optional[dict]:
+    """Best-effort current session record (fresh read from the ledger)."""
+    sid = _resolve_sid(sess)
+    if not sid:
+        return None
+    return reg.get(sid)
+
+
+def persist_target(target_id: str, *, group_id: Optional[int] = None,
+                   sess=None) -> None:
+    """Cache the current tab binding in the ledger record's ``runtime`` field.
+
+    Called wherever a primitive sets ``current_target_id`` so a later process
+    can fast-path re-attach without querying the tab group."""
+    if sess is None:
+        from .session import current_session
+        sess = current_session()
+    sid = _resolve_sid(sess)
+    if not sid:
+        return
+    runtime = {
+        "current_target_id": target_id,
+        "group_id": group_id,
+        "owned_tab_ids": [],
+        "updated_at": time.time(),
+    }
+    try:
+        reg.update(sid, runtime=runtime)
+    except Exception:
+        # Caching is best-effort; never let a ledger write break a primitive.
+        pass
+
+
+def register_recovered(sess, payload: dict) -> Optional[str]:
+    """Register a daemon-minted session/target in the local CDPSession tables.
+
+    Factored out of ``open_background``'s post-open registration so recovery
+    can reuse it. Returns the targetId (or None on a malformed payload)."""
+    target_id = payload.get("targetId")
+    session_id = payload.get("sessionId")
+    if not target_id or not session_id:
+        return None
+    cdp = sess.cdp
+    cdp._sessions[target_id] = session_id
+    cdp._events.setdefault(session_id, deque(maxlen=1024))
+    sess.current_target_id = target_id
+    return target_id
+
+
+def ensure_session_target(sess) -> Optional[str]:
+    """Transparent 3-step recovery of the session's attached tab.
+
+    1. ``sess.current_target_id`` already set → return it (in-process).
+    2. ledger ``runtime.current_target_id`` → try ``cdp.attach(tid)`` (FAST
+       PATH, no group query). The daemon auto-reattaches the debugger; a
+       stale/closed tab raises → fall through.
+    3. group id: ``BrowserwrightDaemon.recoverSession`` by persisted group id
+       → register + persist the new binding. On CDPError / empty group return
+       None.
+
+    Returns the targetId, or None when nothing could be recovered (brand-new
+    session with no tabs yet)."""
+    if sess.current_target_id:
+        return sess.current_target_id
+
+    rec = _resolve_record(sess)
+
+    # Step 2: ledger.runtime fast path.
+    if isinstance(rec, dict):
+        runtime = rec.get("runtime") or {}
+        tid = runtime.get("current_target_id")
+        if tid:
+            try:
+                sess.cdp.attach(tid)
+                sess.current_target_id = tid
+                return tid
+            except CDPError:
+                pass  # stale/closed tab — fall through to group recovery
+
+    # Step 3: durable group recovery by the persisted numeric groupId — NOT the
+    # title (names aren't unique; the session = the tab group, keyed by id). The
+    # groupId is cached in ledger.runtime.group_id on every open; without it
+    # there's nothing to recover (a brand-new session, or Chrome itself
+    # restarted and reassigned group ids — which needs no recovery).
+    runtime = (rec.get("runtime") or {}) if isinstance(rec, dict) else {}
+    gid = runtime.get("group_id")
+    sid = rec.get("id") if isinstance(rec, dict) else _resolve_sid(sess)
+    if not isinstance(gid, int) or gid < 0:
+        return None
+    try:
+        payload = sess.cdp.send(
+            "BrowserwrightDaemon.recoverSession", groupId=gid, bsSession=sid,
+        )
+    except CDPError:
+        return None
+    if not payload:
+        return None
+    target_id = register_recovered(sess, payload)
+    if target_id is None:
+        return None
+    persist_target(target_id, group_id=payload.get("groupId"), sess=sess)
+    return target_id

browserwright/site_skills_starter/github.com/SKILL.md

@@ -0,0 +1,14 @@
+# github.com
+
+Browse public GitHub issues + repos without login.
+
+## Conventions
+
+- Public issue / PR listings render fully without login — no auth wall.
+- Use `https://github.com/<owner>/<repo>/issues?q=...` and parse the
+  list view; the API would be more polite but Skill is fundamentally
+  browser-first.
+
+## Tasks
+
+- `list_issues` — owner/repo (+ optional state filter) → list of issues.

browserwright/site_skills_starter/github.com/memory.md

@@ -0,0 +1,29 @@
+---
+site: github
+host_patterns: ["github.com", "www.github.com"]
+aliases: ["github", "pull request", "issue tracker", "代码仓库"]
+last_updated: 2026-05-18
+---
+
+# github.com site memory
+
+## 顶层 URL 结构
+
+- repo home: https://github.com/<owner>/<repo>
+- issue list: https://github.com/<owner>/<repo>/issues?state=open
+- PR list: https://github.com/<owner>/<repo>/pulls?state=open
+
+## 稳定 selectors
+
+- 列表项: `div[aria-label="Issues"] [data-testid="issue-pr-title-link"]` 或经典 `a.js-navigation-open`
+- 标题文字: `[data-testid="issue-pr-title-link"]`
+- 状态徽标: `[data-testid="issue-state"]`
+- 数字编号: `a[id^=issue_]`
+
+## Known traps
+
+- React-rendered "new issues UI" 在某些仓库上替代了 classic — 选择器要双路。
+- 私有仓库会重定向到 login → AuthWall。
+- `https://github.com/issues` 在未登录态下也会跳 login。
+
+## Notes

browserwright/site_skills_starter/github.com/tasks/list_issues.py

@@ -0,0 +1,55 @@
+"""List public GitHub issues for owner/repo without login.
+
+Phase C surface: drives the injected Playwright ``page`` (reused, navigated in
+place); reads the issue list with ``page.evaluate``.
+"""
+
+ARGS = {
+    "owner": {"type": "str", "required": True, "desc": "github owner / org name"},
+    "repo": {"type": "str", "required": True, "desc": "repo name"},
+    "state": {"type": "str", "required": False, "default": "open",
+              "desc": "open / closed / all"},
+    "limit": {"type": "int", "required": False, "default": 20},
+}
+
+OUTPUT = "list[{number: int, title: str, url: str, state: str}]"
+TAGS = ["github", "issues", "list"]
+REQUIRES_LOGIN = False
+ESTIMATED_DURATION_SEC = 10
+LAST_VERIFIED = "2026-05-25"
+
+
+def selftest():
+    page.goto("https://github.com/")
+    return page.url.startswith("https://github.com")
+
+
+def run(args, ctx=None):
+    pg = ctx.page if ctx is not None and getattr(ctx, "page", None) else page
+
+    owner, repo = args["owner"], args["repo"]
+    state = args.get("state", "open")
+    limit = int(args.get("limit", 20))
+    url = f"https://github.com/{owner}/{repo}/issues?q=is%3Aissue+state%3A{state}"
+    pg.goto(url)
+    results = pg.evaluate(
+        """
+        (limit) => {
+          const cards = Array.from(document.querySelectorAll(
+            '[data-testid="issue-pr-title-link"], a.js-navigation-open'
+          )).filter(a => /\\/issues\\/\\d+$/.test(a.getAttribute('href') || ''));
+          return cards.slice(0, limit).map(a => {
+            const m = a.getAttribute('href').match(/\\/issues\\/(\\d+)$/);
+            const stateBadge = a.closest('li, div')?.querySelector('[data-testid="issue-state"]');
+            return {
+              number: m ? parseInt(m[1], 10) : null,
+              title: a.innerText.trim(),
+              url: new URL(a.getAttribute('href'), location.origin).toString(),
+              state: stateBadge ? stateBadge.innerText.trim().toLowerCase() : '',
+            };
+          });
+        }
+        """,
+        limit,
+    )
+    return results or []

browserwright/site_skills_starter/google.com/SKILL.md

@@ -0,0 +1,16 @@
+# google.com
+
+Search Google and extract the top organic results.
+
+## Conventions
+
+- Navigate the bound `page` in place with `page.goto(...)` — reuse the working
+  tab, don't open a new one per query.
+- The result selector `div.g h3` is stable across the consumer SERP. The mobile
+  layout uses `div[data-hveid] h3` — `tasks/search.py` falls back if needed.
+- Don't try to login. Google's bot detection is aggressive; skill stays
+  unauthenticated and reads public SERP only.
+
+## Tasks
+
+- `search` — query → `list[{title, url, snippet}]`

browserwright/site_skills_starter/google.com/memory.md

@@ -0,0 +1,27 @@
+---
+site: google
+host_patterns: ["google.com", "www.google.com"]
+aliases: ["谷歌", "google search", "search the web"]
+last_updated: 2026-05-18
+---
+
+# google.com site memory
+
+## 顶层 URL 结构
+
+- 搜索: https://www.google.com/search?q=<query>&hl=en
+- 图片搜索: https://www.google.com/search?tbm=isch&q=<query>
+
+## 稳定 selectors
+
+- 结果块: `div.g`
+- 结果标题: `div.g h3` / `div[data-hveid] h3`
+- 结果链接: `div.g a[href^=http]`
+- 结果摘要: `div.g div[data-content-feature="1"]`
+
+## Known traps
+
+- 偶尔 SERP 被 "before you continue" cookie consent 拦截：先 dismiss `button#L2AGLb` 或 `form[action*="consent"]`。
+- 中文 query 在某些区域返回 "did you mean…" 重定向，结果数为 0；要识别并提示 user。
+
+## Notes

browserwright/site_skills_starter/google.com/tasks/search.py

@@ -0,0 +1,53 @@
+"""Search Google for `query` and return the top N organic results.
+
+Phase C surface: drives the injected Playwright ``page`` (reused, navigated in
+place) and reads results via ``page.evaluate``.
+"""
+
+ARGS = {
+    "query": {"type": "str", "required": True, "desc": "search query"},
+    "limit": {"type": "int", "required": False, "default": 10},
+    "hl": {"type": "str", "required": False, "default": "en", "desc": "interface language"},
+}
+
+OUTPUT = "list[{title: str, url: str, snippet: str}]"
+TAGS = ["search", "general"]
+REQUIRES_LOGIN = False
+ESTIMATED_DURATION_SEC = 8
+LAST_VERIFIED = "2026-05-25"
+
+
+def selftest():
+    page.goto("https://www.google.com/?hl=en")
+    return "google.com" in page.url
+
+
+def run(args, ctx=None):
+    from urllib.parse import quote_plus
+
+    pg = ctx.page if ctx is not None and getattr(ctx, "page", None) else page
+
+    q = args["query"]
+    limit = int(args.get("limit", 10))
+    hl = args.get("hl", "en")
+    pg.goto(f"https://www.google.com/search?q={quote_plus(q)}&hl={hl}")
+    results = pg.evaluate(
+        """
+        (limit) => Array.from(document.querySelectorAll('div.g, div[data-hveid]'))
+          .map(div => {
+            const a = div.querySelector('a[href^="http"]');
+            const h = div.querySelector('h3');
+            const sn = div.querySelector('div[data-content-feature="1"], div[role="link"] + div');
+            if (!a || !h) return null;
+            return {
+              title: h.innerText.trim(),
+              url: a.href,
+              snippet: (sn && sn.innerText.trim()) || '',
+            };
+          })
+          .filter(Boolean)
+          .slice(0, limit)
+        """,
+        limit,
+    )
+    return results or []

browserwright/site_skills_starter/producthunt.com/SKILL.md

@@ -0,0 +1,7 @@
+# producthunt.com
+
+Today's Product Hunt front page.
+
+## Tasks
+
+- `today` — `limit?` → list of today's products with vote counts and tagline.

browserwright/site_skills_starter/producthunt.com/memory.md

@@ -0,0 +1,26 @@
+---
+site: producthunt
+host_patterns: ["producthunt.com", "www.producthunt.com"]
+aliases: ["product hunt", "ph", "产品猎手", "今日新品"]
+last_updated: 2026-05-18
+---
+
+# producthunt.com site memory
+
+## 顶层 URL 结构
+
+- 今日榜: https://www.producthunt.com/
+
+## Known traps
+
+- Cookie consent 横幅可能挡住第一屏；如果选择器返回空，先 dismiss 一次再重试。
+- ProductHunt 偶尔 A/B 切 React tree，hard-coded selector 会变；当 selector
+  miss 时改用 anchor `a[href^="/posts/"]` 兜底。
+
+## 稳定 selectors
+
+- 卡片: `[data-test^="post-item"]` 或 `a[href^="/posts/"]`
+- 名称: 卡片内 `a[href^="/posts/"]` 的 innerText
+- vote 数: 卡片内 `[data-test="vote-button"]` 的 innerText
+
+## Notes

browserwright/site_skills_starter/producthunt.com/tasks/today.py

@@ -0,0 +1,64 @@
+"""Today's top products on Product Hunt.
+
+Phase C surface: drives the injected Playwright ``page`` (reused, navigated in
+place); scrapes the feed with ``page.evaluate``.
+"""
+
+ARGS = {
+    "limit": {"type": "int", "required": False, "default": 20},
+}
+
+OUTPUT = "list[{name: str, url: str, tagline: str, votes: int}]"
+TAGS = ["producthunt", "feed", "launches"]
+REQUIRES_LOGIN = False
+ESTIMATED_DURATION_SEC = 10
+LAST_VERIFIED = "2026-05-25"
+
+
+def selftest():
+    page.goto("https://www.producthunt.com/")
+    return "producthunt" in page.url
+
+
+def run(args, ctx=None):
+    pg = ctx.page if ctx is not None and getattr(ctx, "page", None) else page
+
+    limit = int(args.get("limit", 20))
+    pg.goto("https://www.producthunt.com/")
+    products = pg.evaluate(
+        """
+        () => {
+          // Hand-rolled scrape: walk every /posts/<slug> anchor on the page
+          // and grab a sibling vote count if we can find one.
+          const seen = new Set();
+          const out = [];
+          const anchors = document.querySelectorAll('a[href^="/posts/"]');
+          anchors.forEach(a => {
+            const slug = a.getAttribute('href').replace(/^\\/posts\\//, '').split(/[?#]/)[0];
+            if (!slug || seen.has(slug)) return;
+            const card = a.closest('[data-test^="post-item"], li, article, div');
+            if (!card) return;
+            const name = a.innerText.trim();
+            if (!name) return;
+            let votes = 0;
+            const numberEl = card.querySelector('[data-test="vote-button"], button');
+            if (numberEl) {
+              const m = (numberEl.innerText || '').replace(/,/g, '').match(/\\d+/);
+              if (m) votes = parseInt(m[0], 10);
+            }
+            let tagline = '';
+            const para = card.querySelector('p, [class*="tagline"], [class*="description"]');
+            if (para && para.innerText) tagline = para.innerText.trim();
+            out.push({
+              name,
+              url: 'https://www.producthunt.com/posts/' + slug,
+              tagline,
+              votes,
+            });
+            seen.add(slug);
+          });
+          return out;
+        }
+        """
+    )
+    return (products or [])[:limit]

browserwright/site_skills_starter/wikipedia.org/SKILL.md

@@ -0,0 +1,7 @@
+# wikipedia.org
+
+Quick lookup of Wikipedia articles by title.
+
+## Tasks
+
+- `lookup` — title (+ optional `lang`) → `{title, summary, url, sections}`

browserwright/site_skills_starter/wikipedia.org/memory.md

@@ -0,0 +1,22 @@
+---
+site: wikipedia
+host_patterns: ["wikipedia.org", "en.wikipedia.org"]
+aliases: ["wikipedia", "wiki", "维基百科"]
+last_updated: 2026-05-18
+---
+
+# wikipedia.org site memory
+
+## 顶层 URL 结构
+
+- 英文: https://en.wikipedia.org/wiki/<Title_With_Underscores>
+- 中文: https://zh.wikipedia.org/wiki/<Title>
+- 检索: https://<lang>.wikipedia.org/w/index.php?search=<query>&fulltext=1
+
+## 稳定 selectors
+
+- 摘要段: `div.mw-parser-output > p:not(.mw-empty-elt)`
+- 章节标题: `h2 > span.mw-headline`
+- 第一段: `div.mw-parser-output > p:not(.mw-empty-elt):first-of-type`
+
+## Notes

browserwright/site_skills_starter/wikipedia.org/tasks/lookup.py

@@ -0,0 +1,55 @@
+"""Lookup a Wikipedia article and return its first-paragraph summary + section TOC.
+
+Phase C surface: drives the injected Playwright ``page`` (bound to the session's
+current tab — reused, navigated in place). No ``new_tab`` / ``js`` primitives.
+"""
+
+ARGS = {
+    "title": {"type": "str", "required": True, "desc": "article title (free text)"},
+    "lang": {"type": "str", "required": False, "default": "en",
+             "desc": "wikipedia language subdomain (en/zh/ja/...)"},
+}
+
+OUTPUT = "{title: str, url: str, summary: str, sections: list[str]}"
+TAGS = ["wikipedia", "lookup", "reference"]
+REQUIRES_LOGIN = False
+ESTIMATED_DURATION_SEC = 6
+LAST_VERIFIED = "2026-05-25"
+
+
+def selftest():
+    page.goto("https://en.wikipedia.org/wiki/Wikipedia")
+    return "Wikipedia" in page.title()
+
+
+def run(args, ctx=None):
+    from urllib.parse import quote
+
+    # `page` / `context` / `snapshot` are injected by the task runner (Phase C),
+    # mirroring the heredoc namespace. Prefer ctx if a caller passed one.
+    pg = ctx.page if ctx is not None and getattr(ctx, "page", None) else page
+
+    title = args["title"]
+    lang = args.get("lang", "en")
+    underscore_title = title.strip().replace(" ", "_")
+    url = f"https://{lang}.wikipedia.org/wiki/{quote(underscore_title)}"
+    pg.goto(url)
+    info = pg.evaluate(
+        """
+        () => {
+          const summary_p = document.querySelector(
+            'div.mw-parser-output > p:not(.mw-empty-elt)'
+          );
+          const sections = Array.from(
+            document.querySelectorAll('h2 > span.mw-headline, h2 .mw-headline')
+          ).map(el => el.innerText.trim());
+          return {
+            title: document.title.replace(' - Wikipedia', '').trim(),
+            url: location.href,
+            summary: summary_p ? summary_p.innerText.trim() : '',
+            sections,
+          };
+        }
+        """
+    )
+    return info or {"title": title, "url": url, "summary": "", "sections": []}

browserwright/site_skills_starter/ycombinator.com/SKILL.md

@@ -0,0 +1,8 @@
+# news.ycombinator.com
+
+Hacker News front page + ask/show variants.
+
+## Tasks
+
+- `front_page` — `(limit=30)` → top stories from /news
+- `front_page` works for `top`, `new`, `best` via a `kind` arg.

browserwright/site_skills_starter/ycombinator.com/memory.md

@@ -0,0 +1,25 @@
+---
+site: ycombinator.com
+host_patterns: ["news.ycombinator.com", "ycombinator.com"]
+aliases: ["hacker news", "hn", "黑客新闻"]
+last_updated: 2026-05-18
+---
+
+# Hacker News site memory
+
+## 顶层 URL 结构
+
+- 首页 / top: https://news.ycombinator.com/
+- newest: https://news.ycombinator.com/newest
+- best: https://news.ycombinator.com/best
+
+## 稳定 selectors
+
+- 表格行: `tr.athing` — id 属性是 story id
+- 标题链接: `tr.athing span.titleline > a`
+- 分数: 紧邻 athing 之后的 `tr` 下的 `span.score`
+- 评论数: 同上 `tr` 下面的最后一个 `a`
+
+## Notes
+
+- HN 上很少改 DOM。这里的 selector 在过去 10 年基本没变。

browserwright/site_skills_starter/ycombinator.com/tasks/front_page.py

@@ -0,0 +1,63 @@
+"""Pull top stories from Hacker News (top/new/best).
+
+Phase C surface: drives the injected Playwright ``page`` (reused, navigated in
+place); reads the story list with ``page.evaluate``.
+"""
+
+ARGS = {
+    "kind": {"type": "str", "required": False, "default": "top",
+             "desc": "top / new / best"},
+    "limit": {"type": "int", "required": False, "default": 30},
+}
+
+OUTPUT = "list[{rank: int, id: int, title: str, url: str, score: int, comments: int}]"
+TAGS = ["hn", "news", "feed"]
+REQUIRES_LOGIN = False
+ESTIMATED_DURATION_SEC = 5
+LAST_VERIFIED = "2026-05-25"
+
+_KINDS = {
+    "top": "https://news.ycombinator.com/",
+    "new": "https://news.ycombinator.com/newest",
+    "best": "https://news.ycombinator.com/best",
+}
+
+
+def selftest():
+    page.goto("https://news.ycombinator.com/")
+    return "ycombinator.com" in page.url
+
+
+def run(args, ctx=None):
+    pg = ctx.page if ctx is not None and getattr(ctx, "page", None) else page
+
+    kind = args.get("kind", "top")
+    limit = int(args.get("limit", 30))
+    url = _KINDS.get(kind, _KINDS["top"])
+    pg.goto(url)
+    rows = pg.evaluate(
+        """
+        () => {
+          const out = [];
+          const stories = document.querySelectorAll('tr.athing');
+          stories.forEach((row, i) => {
+            const a = row.querySelector('span.titleline > a');
+            if (!a) return;
+            const sub = row.nextElementSibling;
+            const score = sub ? sub.querySelector('span.score') : null;
+            const links = sub ? sub.querySelectorAll('a') : [];
+            const commentLink = links.length ? links[links.length - 1] : null;
+            out.push({
+              rank: i + 1,
+              id: parseInt(row.id, 10),
+              title: a.innerText.trim(),
+              url: a.href,
+              score: score ? parseInt(score.innerText, 10) : 0,
+              comments: commentLink ? parseInt(commentLink.innerText, 10) || 0 : 0,
+            });
+          });
+          return out;
+        }
+        """
+    )
+    return (rows or [])[:limit]