webskrap 3.2.3__tar.gz → 3.2.4__tar.gz

{webskrap-3.2.3 → webskrap-3.2.4}/CHANGELOG.md

@@ -9,6 +9,27 @@ history, so they summarize each release rather than list every change.
 
 ## [Unreleased]
 
+## [3.2.4] - 2026-11-01
+
+### Added
+
+- Python 3.15 is a supported version. CI runs the test suite on it, and the
+  package metadata lists it.
+
+### Changed
+
+- The source distribution no longer contains the agent skill folders and the
+  test that checks them. They stay in the Git repository. Before, the sdist
+  held only one of the linked skill reference paths, and its test failed.
+
+### Fixed
+
+- The CLI guide lists the exit status for each error code. It said before that
+  every browser command failure exits with 1.
+- The MCP guide and the agent reference now describe `browser_wait_for`.
+- `SECURITY.md` names the supported release line without an old version
+  number.
+
 ## [3.2.3] - 2026-10-30
 
 ### Security
@@ -980,7 +1001,8 @@ entries below.
 
 Earlier releases (0.1.0 - 0.4.9) are recorded in the git history and tags only.
 
-[Unreleased]: https://github.com/kacigaya/webskrap/compare/v3.2.3...HEAD
+[Unreleased]: https://github.com/kacigaya/webskrap/compare/v3.2.4...HEAD
+[3.2.4]: https://github.com/kacigaya/webskrap/compare/v3.2.3...v3.2.4
 [3.2.3]: https://github.com/kacigaya/webskrap/compare/v3.2.2...v3.2.3
 [3.2.2]: https://github.com/kacigaya/webskrap/compare/v3.2.1...v3.2.2
 [3.2.1]: https://github.com/kacigaya/webskrap/compare/v3.2.0...v3.2.1

{webskrap-3.2.3 → webskrap-3.2.4}/CONTRIBUTING.md

@@ -5,7 +5,7 @@ what a reviewable pull request looks like.
 
 ## Requirements
 
-- Python 3.11, 3.12, 3.13, or 3.14 (CI runs all four).
+- Python 3.11, 3.12, 3.13, 3.14, or 3.15 (CI runs all five).
 - [uv](https://docs.astral.sh/uv/) for environments and dependencies.
 - A Chromium build for browser tests, installed via `webskrap install`.
 

{webskrap-3.2.3 → webskrap-3.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: webskrap
-Version: 3.2.3
+Version: 3.2.4
 Summary: Async Python scraping on Chromium over its own CDP client, with coherent browser profiles and session controls.
 Project-URL: Homepage, https://github.com/kacigaya/webskrap
 Project-URL: Repository, https://github.com/kacigaya/webskrap
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: mcp<3,>=2

{webskrap-3.2.3 → webskrap-3.2.4}/SECURITY.md

@@ -5,10 +5,10 @@
 WebSkrap is developed on `main` and released from tags. Fixes land in a new
 patch release on top of the latest minor; older minors are not backported.
 
-| Version                                   | Supported |
-| ----------------------------------------- | --------- |
-| Latest minor (2.13.x as of 2026-10-01)       | Yes       |
-| Older minors                              | No        |
+| Version      | Supported |
+| ------------ | --------- |
+| Latest minor | Yes       |
+| Older minors | No        |
 
 ## Reporting a vulnerability
 

{webskrap-3.2.3 → webskrap-3.2.4}/docs/diagnostics/datadome.md

@@ -129,9 +129,9 @@ was dated March 2024. Some listed endpoints timed out or rejected authentication
 The catalog was refreshed through Gluetun's existing updater. The original
 catalog was backed up, and the VPN was restored to a healthy state.
 
-The final verified exit was `187.13.198.190` in Marseille. It still required
-verification. The refreshed catalog is in the container's writable layer;
-container recreation can replace it because there is no catalog volume mount.
+The final verified exit still required verification. The refreshed catalog is
+in the container's writable layer; container recreation can replace it because
+there is no catalog volume mount.
 
 ## CDP identity investigation
 

{webskrap-3.2.3 → webskrap-3.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "webskrap"
-version = "3.2.3"
+version = "3.2.4"
 description = "Async Python scraping on Chromium over its own CDP client, with coherent browser profiles and session controls."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -22,6 +22,7 @@ classifiers = [
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
   "Typing :: Typed",
 ]
 dependencies = [
@@ -56,8 +57,20 @@ packages = ["src/webskrap"]
 
 [tool.hatch.build.targets.sdist]
 # The web/ frontend ships only to GitHub Pages, never to PyPI. assets/ holds
-# the README logo, which no install step reads.
-exclude = ["web", ".github", "assets"]
+# the README logo, which no install step reads. The agent skill folders link
+# to one shared references/ copy, and Hatch keeps only one path to a linked
+# directory, so they stay in the Git checkout together with test_docs.py,
+# which checks them.
+exclude = [
+  "web",
+  ".github",
+  "assets",
+  ".agents",
+  ".claude",
+  ".codex",
+  "references",
+  "tests/test_docs.py",
+]
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"

{webskrap-3.2.3 → webskrap-3.2.4}/tests/test_cli.py

@@ -786,6 +786,8 @@ def test_schema_human_format_lists_commands() -> None:
 
 
 def test_fetch_stays_sandboxed_by_default(monkeypatch: Any) -> None:
+    # The host can opt out globally; this test checks the built-in default.
+    monkeypatch.delenv("WEBSKRAP_CHROMIUM_SANDBOX", raising=False)
     _fake_client(monkeypatch)
 
     result = runner.invoke(cli.app, ["fetch", "https://example.test", "--format", "json"])

{webskrap-3.2.3 → webskrap-3.2.4}/uv.lock

@@ -1163,7 +1163,7 @@ wheels = [
 
 [[package]]
 name = "webskrap"
-version = "3.2.3"
+version = "3.2.4"
 source = { editable = "." }
 dependencies = [
     { name = "mcp" },

webskrap-3.2.3/.agents/skills/webskrap/SKILL.md

@@ -1,151 +0,0 @@
----
-name: webskrap
-description: Use when writing, debugging, documenting, or reviewing Python scraping, web search, and visual browser automation with WebSkrap. Not for ordinary HTTP clients or search APIs.
----
-
-# WebSkrap
-
-WebSkrap is an async Python scraping package that drives Chromium through its
-own Chrome DevTools Protocol (CDP) client, with no Playwright. The Python API,
-`webskrap` CLI, and `webskrap-mcp` server share core behavior.
-
-WebSkrap loads known URLs. To find URLs it loads DuckDuckGo or Bing's
-results page in the same browser and parses the hits. It calls no search API
-and it does not offer Google.
-
-## Workflow
-
-1. Identify the affected public surface: Python, CLI, MCP, or more than one.
-2. Read its implementation and nearest tests. Trace calls into shared code
-   before editing.
-3. Change the shared implementation when behavior belongs to more than one
-   surface. Do not patch each wrapper independently.
-4. Update affected public contracts: models, serialization, errors, command
-   help, MCP schemas, guides, and tests.
-5. Run focused tests during development, then the full validation gate before
-   handoff when practical.
-
-## Route by task
-
-| Task | Implementation | Tests and contracts |
-| --- | --- | --- |
-| Fetching, sessions, links, or screenshots | `src/webskrap/client.py`, `src/webskrap/models.py` | `tests/test_client_unit.py`, `tests/test_models.py` |
-| Search engines, redirect unwrapping, or results parsing | `src/webskrap/search.py`, `src/webskrap/models.py` | `tests/test_search.py` and its fixtures under `tests/fixtures/search/` |
-| Parsing | `src/webskrap/parsing.py` | `tests/test_parsing.py` |
-| Errors, hints, or exit statuses | `src/webskrap/errors.py`, `src/webskrap/cli_output.py` | `tests/test_errors.py`, CLI and MCP callers |
-| Main CLI commands | `src/webskrap/cli.py` | `tests/test_cli.py`, `tests/test_diagnostics.py` |
-| Persistent browser state | `src/webskrap/browser_session.py`, `src/webskrap/paths.py` | `tests/test_browser_session_unit.py`, `tests/test_paths.py` |
-| Interactive browser commands | `src/webskrap/browser_cli.py`, `src/webskrap/mcp_server.py` | `tests/test_browser_cli.py`, `tests/test_browser_integration.py`, `tests/test_mcp.py` |
-| MCP tools, resources, or annotations | `src/webskrap/mcp_server.py` | `tests/test_mcp.py`, `src/webskrap/guide.md` |
-| Profiles or stealth defaults | `src/webskrap/profiles.py`, `src/webskrap/models.py`, `src/webskrap/client.py` | `tests/test_profiles.py`, opt-in bot-detection tests when needed |
-| Cookie rejection | `src/webskrap/consent.py` | `tests/test_consent.py`; `tests/test_consent_live.py` only for selector rot |
-| Documentation and examples | `README.md`, `src/webskrap/guide.md` | `tests/test_docs.py`, current CLI help, public Python exports |
-
-Search for every constructor, serializer, command, and schema that uses a
-changed model or field. Fetch and search behavior cross Python, CLI, and MCP.
-Persistent browser behavior crosses the browser CLI and MCP. Engine markup
-lives only in `src/webskrap/search.py`. When an engine changes its page,
-refresh that engine's fixture and fix that one extractor.
-
-## Choose the public surface
-
-| Need | Python | CLI | MCP |
-| --- | --- | --- | --- |
-| Fetch one known URL | `client.fetch()` | `webskrap fetch` | `stealth_fetch` |
-| Find URLs for a query | `client.search()` | `webskrap search` | `search` |
-| Preserve cookies or storage | `client.session()` | `webskrap browser open` | `browser_open` |
-| See a rendered page or interact with canvas | `browser_session.view()` on a session page | `webskrap browser view` and `mouse` | `browser_view` and `browser_mouse` |
-| Click, fill, wait, or run a flow | `session.new_page()` and `human_click()` | `webskrap browser` | `browser_interact` and related tools |
-| Diagnose installation | Inspect raised error | `webskrap doctor` | `doctor` |
-
-Use a one-shot fetch for one page. Use a persistent browser only when state or
-interaction must survive between operations. Do not repeatedly fetch a page to
-drive a multi-step flow.
-
-Read only the reference needed for the task:
-
-- [Python API](references/python-api.md): sessions, pages, profile modes, consent, links,
-  and fingerprint controls.
-- [CLI](references/cli.md): one-shot fetches, persistent browser commands, and
-  Linux ARM64 behavior.
-- [MCP](references/mcp.md): tool selection, confined paths, annotations, and
-  keeping tool results small.
-
-## Visual browser interaction
-
-Use `browser_view` (MCP) or `webskrap browser view --format json` (CLI) when
-layout, images, canvas, or controls missing from the accessibility tree matter.
-MCP returns an image block directly. CLI saves a PNG; open its returned `path`
-with the agent's image-viewing tool before choosing coordinates. A path or
-base64 text alone does not give a model vision. The client and model must
-support image input.
-
-The view covers the viewport at one PNG pixel per CSS pixel. Coordinates start
-at its top-left; use the original `width` and `height` if the image viewer
-resizes it. Do not add `scroll_x` or `scroll_y` to mouse coordinates. Full-page
-screenshots are for inspection or export and do not map directly to the mouse.
-
-Prefer refs/selectors when they identify a control. Use `browser_mouse` / CLI
-`mouse` for visual targets, then `browser_insert_text` / CLI `insert-text` for
-literal text in the focused control and `browser_press` / CLI `press` for keys.
-Wait for the expected change and take a fresh view after scrolling, navigation,
-or layout changes. Coordinate clicks hit whatever occupies that point.
-Run dependent actions sequentially within a session.
-
-This is the browser's rendered page, available headless without Xvfb. It does
-not show browser chrome, OS dialogs, or a desktop stream. One-shot fetch
-sessions are separate; open a persistent browser to drive a visual flow.
-Read the [CLI](references/cli.md) or [MCP](references/mcp.md) reference for examples.
-
-## Guardrails
-
-- Use public pages, local test servers, or targets the user is authorized to
-  access.
-- Do not add CAPTCHA solving, login-wall bypass, credential bypass, or
-  access-control circumvention.
-- Do not commit cookies, storage state, proxy credentials, or persistent browser
-  data such as `.webskrap/`.
-- Preserve Chromium's sandbox by default. Any opt-out must remain explicit and
-  outside page-controlled input.
-- Keep MCP file paths confined to their configured roots. Reject absolute paths,
-  traversal, and symlink escapes.
-- Prefer public `webskrap` exports. Use private helpers only in tests.
-- Keep changes typed. Add focused tests for parsing, state transitions, output
-  contracts, and tool-safety behavior.
-
-## Public contract checklist
-
-When public behavior changes, check all applicable items:
-
-- Python models and exports
-- CLI arguments, help, JSON output, and exit status
-- MCP input schema, result shape, annotations, and server instructions
-- `README.md` and `src/webskrap/guide.md`
-- unit tests for each affected surface
-
-Use the implementation as the source of truth. In particular, read
-`src/webskrap/models.py` for result fields, `src/webskrap/errors.py` for error
-codes and exits, and `src/webskrap/diagnostics.py` for environment reporting.
-Do not copy these catalogs into the skill.
-
-## Validation
-
-Run the nearest tests while editing. Before handoff, run the repository gate
-when practical:
-
-```bash
-uv run --extra dev pytest -q -m "not browser and not live"
-uv run --extra dev ruff check .
-uv run --extra dev ruff format --check .
-uvx --from pyright==1.1.411 pyright --pythonpath .venv/bin/python src/webskrap
-uv run --extra dev bandit -c pyproject.toml -q -r src/
-uv run --extra dev --with pip-audit==2.9.0 pip-audit
-uv build
-```
-
-Run browser tests when browser behavior changes and the required browsers are
-installed.
-
-Use `WEBSKRAP_LIVE=1 pytest -q -m live` only when explicitly checking public
-third-party behavior. Live tests are non-deterministic and do not replace the
-default suite.

webskrap-3.2.3/.agents/skills/webskrap/references/cli.md

@@ -1,154 +0,0 @@
-# CLI
-
-Read this reference when changing or using `webskrap` commands. Treat
-`src/webskrap/cli.py` and `src/webskrap/browser_cli.py` as the source of truth
-for arguments and help text.
-
-## One-shot commands
-
-`webskrap fetch` runs headless Chrome through WebSkrap's own CDP client. `webskrap install`
-downloads Chrome for Testing into the user cache folder
-(`WEBSKRAP_BROWSERS_PATH` overrides it); `--force` downloads it again. `doctor` reports
-readiness, browser identity, host CPU architecture, and Fontconfig family count.
-It warns when the host timezone is UTC. `fetch` and `search` try Chrome, Edge,
-then Chrome for Testing when a channel cannot launch. `schema` describes commands
-as JSON.
-
-```bash
-webskrap doctor --format json
-webskrap schema
-webskrap profiles --format json
-webskrap fetch https://example.com --profile desktop-chrome
-webskrap fetch https://example.com --format json --max-chars 4000
-webskrap fetch https://example.com --format json --links --max-links 20
-webskrap fetch https://example.com --stdout --text-only
-webskrap fetch https://example.com --quiet --output page.html
-```
-
-Use `--offset` with the previous result's next offset to continue reading a
-long page. Do not re-fetch with an ever larger limit.
-
-Pass `--ready-selector '#content'` (CSS or a snapshot ref) to wait for visible content after consent
-dismissal. `--timeout-ms` applies separately to navigation and the readiness wait.
-A missing selector exits 3 (`timeout`). A known challenge or block page
-(DataDome, Cloudflare, Akamai, AWS WAF) exits 11 (`blocked`) without retrying,
-including one served with HTTP 200.
-Ordinary HTTP error pages still return a result with `ok: false`.
-
-`webskrap search` loads a results page through the same stealth path and
-prints the organic hits. `--engine` is `bing` (default) or `ddg`.
-
-```bash
-webskrap search "example domain"
-webskrap search "example domain" --engine bing --max-results 5 --format json
-```
-
-A `blocked` failure (exit 11) means the engine served a bot challenge; switch
-engine, reuse `--user-data-dir`, or change exit IP instead of retrying.
-
-On Linux ARM64, the `chrome` channel may be unavailable. `fetch` retries a
-failed launch with Chrome for Testing. Pass `--channel chromium` to avoid the
-first attempt.
-
-`--profile-mode` sets how much of the profile pages see: `native` (default),
-`locale` or `full`. See the Python API reference.
-
-## Persistent browser
-
-`webskrap browser open` launches detached Chromium. Later commands reconnect
-over CDP, act on its current page, and exit. The browser
-gets the same automation and headless-screen flags as `fetch`; `--headed`
-also drops the `HeadlessChrome` user-agent token. `--proxy URL` routes the
-session through a proxy and defaults WebRTC to `disable_non_proxied_udp`;
-`--webrtc-ip-handling-policy` overrides it. Both are fixed at launch, and
-reopening with different values is refused. The URL never holds credentials:
-for an http or https proxy, set `WEBSKRAP_PROXY_USERNAME` and
-`WEBSKRAP_PROXY_PASSWORD`, and a helper process answers the proxy.
-
-```bash
-webskrap browser open https://example.com --decline-cookies
-webskrap browser snapshot
-webskrap browser click e15
-webskrap browser fill "input[name=q]" "chromium"
-webskrap browser press Enter
-webskrap browser wait --text "Results"
-webskrap browser screenshot page.png --full-page
-webskrap browser screenshot button.png --target e15   # one element
-webskrap browser close
-```
-
-`click`, `dblclick` and `type` use human mouse and keystroke timing (wheel
-scrolling, a curved cursor path, a human button hold, spaced keys) and refuse
-a covered target; `fill` sets a value at once.
-
-Snapshot refs become stale when the DOM changes. Take another snapshot before
-retrying. `wait` accepts one condition. Do not guess when callers provide more
-than one.
-
-Targets are snapshot refs or CSS selectors. Playwright selector engines such
-as `text=` are not supported. Snapshot refs are stable while the element exists,
-also across commands. Iframe content is listed under its `iframe` line. Refs in a frame look
-like `f12345e15`. CSS selectors match in the main frame only.
-
-Sessions default to the name `default`. Profiles live below
-`~/.webskrap/browser/<name>/`, unless `WEBSKRAP_BROWSER_DIR` changes the root.
-They contain cookies and logins and must remain mode `0700`.
-
-Keep Chromium's OS sandbox enabled. The explicit opt-outs are
-`webskrap browser open --no-sandbox` for one session,
-`webskrap fetch --no-sandbox` / `webskrap search --no-sandbox` for one-shot
-calls, and `WEBSKRAP_CHROMIUM_SANDBOX=0` for a host. Document that disabling it
-leaves a compromised renderer uncontained. Never pass `--no-sandbox` (or its
-companions) through `--launch-arg`: those flags are blocked.
-
-Commands act on the current tab. `tab-list`, `tab-new [url]`,
-`tab-select <index>` and `tab-close [index]` manage tabs; a popup or a new tab
-becomes current. Current limitations are Chrome for Testing only, no network
-mocking, tracing, or video, and history navigation that reloads.
-
-## Vision and coordinate input
-
-```bash
-webskrap browser open https://example.com -s visual
-webskrap browser view viewport.png -s visual --format json
-# Inspect the PNG with your image-viewing tool before choosing coordinates.
-webskrap browser mouse click 120 80 -s visual
-webskrap browser insert-text "hello 世界" -s visual
-webskrap browser press Enter -s visual
-webskrap browser mouse scroll 400 300 --delta-y 500 -s visual
-webskrap browser view viewport.png -s visual --format json
-# Inspect the new view before choosing the drag points.
-webskrap browser mouse drag 100 150 --end-x 250 --end-y 180 -s visual
-webskrap browser view viewport.png -s visual --format json
-webskrap browser close -s visual
-```
-
-`view` writes a viewport PNG and returns `path` (absolute), `url`, `title`,
-`width`, `height`, `scroll_x`, `scroll_y`, `mime_type`, and `coordinate_system`
-(`viewport-css-pixels`). Omitting the path generates a unique PNG in the current
-directory. JSON contains metadata, not base64 image data: the agent must open
-the file with an image-viewing tool.
-
-One image pixel equals one CSS pixel, even on high-DPI pages. `(0, 0)` is the
-viewport's top-left. Map resized previews back to the original dimensions;
-do not add document scroll offsets. `screenshot --full-page` remains available
-for export, but its coordinates cannot be used directly with `mouse`.
-
-`mouse` accepts `click`, `dblclick`, `move`, `scroll`, or `drag`, with required
-`x y`. `--button` is `left` (default), `middle`, or `right` for click/double-click/
-drag. Drag requires both `--end-x` and `--end-y`. Scroll uses `--delta-x` and
-`--delta-y` over the element under `x y`; positive vertical deltas scroll down,
-including in nested scroll areas. Non-finite, out-of-viewport, and unused
-arguments fail with `usage`. Coordinate input uses direct browser events;
-selector-based `click` and `type` retain their human timing and covered-target
-checks.
-
-`insert-text` inserts literal Unicode into the focused control with an input
-event. It does not interpret `Enter` as a key or emit per-character keydown/
-keyup events. Focus with a click or Tab; use `press` for shortcuts and keys,
-or selector-based `type` for controls that require individual keystrokes.
-
-Take a fresh view after navigation, scrolling, or layout changes. Wheel input
-may return before scrolling finishes; wait for the expected page condition.
-Prefer refs/selectors for known controls, and run dependent session actions
-sequentially. This shows the page viewport, not browser chrome or OS dialogs.

webskrap-3.2.3/.agents/skills/webskrap/references/mcp.md

@@ -1,130 +0,0 @@
-# MCP
-
-Read this reference for MCP tools, resources, schemas, annotations, and safety
-boundaries. Confirm the current contract in `src/webskrap/mcp_server.py` and
-`tests/test_mcp.py`.
-
-## Select a tool
-
-- `stealth_fetch` is the default one-shot fetch. It exposes fingerprint,
-  WebRTC, user-agent, and persistent-profile controls.
-- `fetch` is the simpler one-shot form.
-- `search` finds URLs for a query on Bing (default) or DuckDuckGo, with the
-  same stealth controls as `stealth_fetch`. Google is not offered. Follow up
-  with `stealth_fetch` on the hits worth reading.
-- `doctor` reports readiness, browser identity, CPU architecture, Fontconfig
-  family count, versions, paths, environment overrides, persistent sessions,
-  and the host timezone, with a warning when it is UTC.
-- `browser_open` and the other `browser_*` tools drive a stateful flow.
-  `browser_open` takes `webrtc_ip_handling_policy` but no proxy; open a proxied
-  session with `webskrap browser open --proxy URL` and the tools reuse it.
-- `webskrap://guide`, `webskrap://profiles`, and `webskrap://sessions` expose
-  static guidance and current state as resources.
-
-One-shot fetches do not share cookies between calls. Use a browser session when
-state must persist.
-
-All tools drive Chromium through WebSkrap's own CDP client. Selectors are
-snapshot refs or CSS. `stealth_fetch` takes `profile_mode` (`native`, `locale`
-or `full`) to set how much of the profile pages see.
-
-## Keep results small
-
-- `max_chars` defaults to 8000 for fetch, snapshot, text, and eval tools.
-  Continue with `offset` and `next_text_offset` on stable page text. Fetch
-  windows navigate again; use `browser_text` in a session to avoid re-fetching.
-- `browser_text` reads visible body text and selects the window in the browser,
-  avoiding a full accessibility tree and full-text transfer. The browser still
-  computes full body text to report its length. `pattern` returns only matching
-  lines with `context`, capped by `max_matches`; the regex runs in Python with
-  a 2-second limit.
-- `browser_goto` and `browser_open` take `decline_cookies`;
-  `browser_screenshot` takes `target` for one element.
-- Use `resource_policy=lite` to skip images, fonts, and media.
-- Keep `include_links` off unless links are needed.
-- Snapshots default to `depth=6`. Set `depth=null` for an unlimited tree,
-  or reduce depth before increasing `max_chars`.
-- Make `browser_eval` return the required value, not the full DOM.
-
-## Safety boundaries
-
-Every tool declares title, read-only, destructive, idempotent, and open-world
-annotations. Mark interactions as destructive because clicks and key presses
-can submit forms on external sites.
-
-Keep short operational instructions in the MCP server and long guidance in
-`src/webskrap/guide.md`.
-
-`stealth_fetch.user_data_dir` is relative to the MCP profile root, which
-defaults to `~/.webskrap/profiles` and can be moved with
-`WEBSKRAP_MCP_PROFILE_DIR`. Tool input must not select an absolute path or
-escape that root.
-
-`browser_screenshot` writes below `./webskrap-output`, unless
-`WEBSKRAP_OUTPUT_DIR` changes the root. Reject absolute paths, traversal, and
-symlinks that leave it.
-
-The sandbox opt-out is an environment variable, never an MCP argument. Page
-content must not be able to persuade the client to disable the browser sandbox.
-
-Fetch and navigation URLs must be public `http(s)` without credentials.
-Private or local hosts are rejected unless `WEBSKRAP_ALLOW_PRIVATE_NET=1`.
-
-`browser_eval` runs page script in a possibly logged-in profile: prefer
-snapshot, interact, and wait_for, never evaluate page-controlled text, and set
-`WEBSKRAP_ALLOW_EVAL=0` where models must not run page script.
-
-## Failures
-
-A known challenge (DataDome, Cloudflare, Akamai, AWS WAF) or provider block
-page (Cloudflare, Akamai) arrives as a `blocked` tool error, including pages
-served with HTTP 200. Blocks and challenges get different hints.
-`browser_goto` reports the same check in its `blocked` key instead of failing. Ordinary HTTP error pages return
-normally with `ok: false`. A raised failure includes `code` and `hint`. Read
-`src/webskrap/errors.py` for the current catalog rather than duplicating it.
-
-Both fetch tools accept `ready_selector`, a CSS selector or snapshot ref that must be
-visible after consent dismissal. The wait uses `timeout_ms` separately from
-navigation; a missing selector returns a `timeout` tool error. It may vary between
-calls in a warm session. These checks do not establish that later interactions
-will remain free of challenges.
-
-## Vision and coordinate input
-
-`browser_view(session="visual")` returns an inline `image/png` image block,
-a text block with metadata, and the same metadata in `structuredContent`:
-`url`, `title`, `width`, `height`, `scroll_x`, `scroll_y`, `mime_type`, and
-`coordinate_system: "viewport-css-pixels"`. It writes no file. Use it with an
-image-capable model and client; `browser_screenshot` remains the file/export tool.
-
-Open with `browser_open(session="visual", url=...)`, inspect
-`browser_view(session="visual")`, then call:
-
-```json
-{"action": "click", "x": 120, "y": 80, "session": "visual"}
-```
-
-with `browser_mouse`. Choose coordinates from the observed target. For a focused
-input, `browser_insert_text(text="hello 世界", session="visual")` inserts literal
-text; `browser_press(key="Enter", session="visual")` sends a key. Insertion emits
-an input event, not individual keydown/keyup events. Use `browser_interact` with
-`action="type"` when a control requires individual keystrokes.
-
-Mouse actions are `click`, `dblclick`, `move`, `scroll`, and `drag`. All require
-`x` and `y`. `button` is `left` (default), `middle`, or `right`, for click,
-double-click, or drag only. Drag also requires `end_x` and `end_y`. Scroll accepts
-`delta_x` and `delta_y` in CSS pixels, targeting the element under the pointer;
-positive `delta_y` scrolls down. Invalid, non-finite, unused, or out-of-viewport
-arguments return a `usage` error before mouse input is sent.
-
-Use the original PNG dimensions: each image pixel is one CSS pixel, independent
-of device scale. `(0,0)` is the viewport's top-left. Map any resized preview back
-to `width`/`height`, and do not add scroll offsets. Full-page screenshots do not
-share this mouse coordinate mapping.
-
-Prefer refs/selectors for identifiable controls. Coordinate clicks hit whatever
-is visible at the point. After an action, wait for the expected change, then take
-a fresh view before choosing more coordinates. Wheel input can finish after the
-call returns. Run dependent actions sequentially in each session. The image
-shows the page, including canvas and frames, not browser chrome, OS dialogs,
-or a live desktop stream. Headless rendering needs no Xvfb.

webskrap-3.2.3/.agents/skills/webskrap/references/python-api.md

@@ -1,147 +0,0 @@
-# Python API
-
-Read this reference for Python API work. Confirm signatures and defaults in
-`src/webskrap/client.py` and `src/webskrap/models.py` before changing code.
-
-## Fetch or session
-
-Use `WebSkrapClient` as an async context manager. `client.fetch()` handles a
-one-shot request. Use `client.session()` when cookies, storage, manual page
-work, headed debugging, or interactions must persist.
-
-```python
-import asyncio
-
-from webskrap import WebSkrapClient
-
-
-async def main() -> None:
-    async with WebSkrapClient() as client:
-        result = await client.fetch("https://example.com", include_links=True)
-    print(result.status, result.final_url, result.title)
-    print(result.text[:200])
-
-
-asyncio.run(main())
-```
-
-WebSkrap 3 drives Chromium through its own CDP client. There is no driver to
-choose. Pick the browser with `channel` (`chrome`, `msedge`, `chromium`):
-
-```python
-from pathlib import Path
-
-from webskrap import SessionConfig
-
-config = SessionConfig(
-    channel="chrome",
-    headless=True,
-    user_data_dir=Path(".webskrap/headless-profile"),
-)
-```
-
-`channel=None` or `"chromium"` uses the Chrome for Testing build from
-`webskrap install`.
-
-## Pages you drive yourself
-
-`session.new_page()` returns a `webskrap.cdp.CDPPage` with the session's
-profile and policies applied. Close it with `session.close_page(page)`.
-
-```python
-async with WebSkrapClient() as client:
-    session = await client.session("manual")
-    page = await session.new_page()
-    response = await page.goto("https://example.com", wait_until="load", timeout_s=30)
-    title = await page.evaluate("document.title")
-    await session.human_click(page, "a")
-    await session.close_page(page)
-```
-
-- `page.goto()` returns the CDP `Response` object, for example `status` and
-  `headers`.
-- `page.evaluate()` runs in an isolated world. It shares the DOM with the page
-  but not the page's JavaScript globals.
-- `session.human_click()` and `session.human_type()` take a CSS selector or a
-  snapshot ref.
-- `page.send(method, params)` sends any other CDP command to the page.
-
-## Consent and links
-
-`client.fetch()` and `session.fetch()` accept `ready_selector`, an optional
-CSS selector or snapshot ref that must become visible after consent dismissal and before
-extraction. Its wait uses `timeout_ms` or `navigation_timeout_ms` separately from
-navigation. A missing selector raises a timeout. A blank selector is a usage error.
-
-Known challenge pages (DataDome, Cloudflare, Akamai, AWS WAF) and provider block pages (Cloudflare, Akamai) raise `WebSkrapError` with
-`code=ErrorCode.BLOCKED`, even when served with HTTP 200. `error.hint`
-holds a kind-specific hint. Ordinary HTTP errors
-still return `FetchResult(ok=False)`. Detection uses active provider markers and
-headers; it does not identify every challenge or solve verification widgets.
-
-Cookie rejection is opt-in for Python callers. The CLI and MCP server enable it
-by default.
-
-```python
-config = SessionConfig(decline_cookies=True, decline_cookies_timeout_ms=2_000)
-```
-
-`FetchResult.cookie_notice_declined` reports `"cmp"`, `"text"`, or `None`.
-`session.decline_cookies(page)` applies the same handling to a page controlled
-by the caller.
-
-Link collection is opt-in with `include_links=True` and capped by `max_links`.
-Links resolve against the final URL. Duplicate and `javascript:` targets are
-dropped. `links_total` is the count before the cap. A session with
-`java_script_enabled=False` cannot collect links.
-
-## Search
-
-`client.search(query, engine=..., max_results=...)` and
-`session.search(...)` load the engine's results page through the same fetch
-path, so `SessionConfig` proxy, consent, and profile settings apply. Engines
-are `SearchEngine.BING` (default) and `SearchEngine.DDG`; Google is not
-offered.
-
-```python
-from webskrap import SearchEngine, WebSkrapClient
-
-async with WebSkrapClient() as client:
-    result = await client.search("example domain", engine=SearchEngine.BING, max_results=5)
-for hit in result.hits:
-    print(hit.title, hit.url, hit.snippet)
-```
-
-`SearchResult.hits` is capped by `max_results`; `hits_total` counts the page.
-Destinations are unwrapped from the engine's click redirects and deduplicated.
-A bot challenge raises `WebSkrapError` with code `blocked`; nothing is retried.
-
-## Detection-sensitive pages
-
-Headed Chrome is the strongest available mode for strict detection surfaces:
-
-```python
-config = SessionConfig(channel="chrome", headless=False)
-```
-
-For fingerprint-statistics or WebRTC leak-test pages, prefer native browser
-controls over JavaScript patches:
-
-```python
-config = SessionConfig(
-    channel="chrome",
-    headless=True,
-    profile_mode="locale",
-    reduce_fingerprint_surface=True,
-    virtual_display=True,
-    webrtc_ip_handling_policy="disable_non_proxied_udp",
-)
-```
-
-`profile_mode` sets how much of the `BrowserProfile` pages see:
-
-- `"native"` (default): nothing. The browser shows its own identity.
-- `"locale"`: locale, timezone, color scheme, reduced motion and extra headers.
-  On Linux, locale and timezone come from the browser environment.
-- `"full"`: also viewport, screen, device scale, touch and user agent, as
-  WebSkrap 2.x did. Each override is a surface that a page can cross-check.

webskrap-3.2.3/.claude/skills/webskrap/SKILL.md

@@ -1 +0,0 @@
-../../../.agents/skills/webskrap/SKILL.md

webskrap-3.2.3/.codex/skills/webskrap/SKILL.md

@@ -1 +0,0 @@
-../../../.agents/skills/webskrap/SKILL.md

webskrap-3.2.3/tests/test_docs.py

@@ -1,44 +0,0 @@
-"""Guard the skill's routing without duplicating generated API catalogs."""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parents[1]
-SKILL_DIR = ROOT / ".agents" / "skills" / "webskrap"
-SKILL = (SKILL_DIR / "SKILL.md").read_text(encoding="utf-8")
-
-
-def test_skill_routes_to_existing_references() -> None:
-    for relative_path in (
-        "references/python-api.md",
-        "references/cli.md",
-        "references/mcp.md",
-    ):
-        assert f"]({relative_path})" in SKILL
-        assert (SKILL_DIR / relative_path).is_file()
-
-
-def test_agent_skill_folders_share_one_copy() -> None:
-    for agent in (".claude", ".codex"):
-        folder = ROOT / agent / "skills" / "webskrap"
-        assert (folder / "SKILL.md").resolve() == (SKILL_DIR / "SKILL.md").resolve()
-        assert (folder / "references").resolve() == (ROOT / "references").resolve()
-
-
-def test_skill_routes_dynamic_contracts_to_their_sources() -> None:
-    for source in (
-        "src/webskrap/models.py",
-        "src/webskrap/errors.py",
-        "src/webskrap/diagnostics.py",
-        "src/webskrap/cli.py",
-        "src/webskrap/browser_cli.py",
-        "src/webskrap/mcp_server.py",
-    ):
-        assert f"`{source}`" in SKILL
-
-
-def test_skill_states_how_search_works_and_what_it_excludes() -> None:
-    assert "calls no search API" in SKILL
-    assert "does not offer Google" in SKILL
-    assert "`src/webskrap/search.py`" in SKILL