feat: add benchmarks docs page and patchright focus control

- web: benchmarks page renders stealth comparison and perf tables with coss ui
- web: humanizer guide plus sessions/stealth doc updates and nav entries
- config: add patchright_focus_control (omit focus_control for older Patchright)
- bump version 0.5.6

Author: kacigaya

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "webskrap"
-version = "0.5.5"
+version = "0.5.6"
 description = "A Playwright-based Python scraping framework with coherent browser profiles and session controls."
 readme = "README.md"
 requires-python = ">=3.11"

src/webskrap/cli.py

@@ -279,6 +279,7 @@ async def _fetch(
         navigation_timeout_ms=timeout_ms,
         resource_policy=resource_policy,
         patchright_context_profile=patchright_context_profile,
+        patchright_focus_control=None,
         reduce_fingerprint_surface=reduce_fingerprint_surface,
         mask_headless_user_agent=mask_headless_user_agent,
         launch_args=launch_args,

src/webskrap/models.py

@@ -185,6 +185,9 @@ class SessionConfig(BaseModel):
     # scheme, reduced motion, and caller-provided extra headers) while still
     # avoiding viewport, user-agent, and JavaScript fingerprint patches.
     patchright_context_profile: bool = False
+    # Patchright-specific focus behavior control. Set to None to omit the option
+    # for Patchright versions that do not accept it.
+    patchright_focus_control: bool | None = False
 
     def launch_options(self) -> dict[str, Any]:
         options: dict[str, Any] = {
@@ -274,6 +277,8 @@ def context_options(self, profile: BrowserProfile) -> dict[str, Any]:
             # visible. The opt-in context profile below only applies settings
             # Chrome can expose natively through BrowserContext options.
             options: dict[str, Any] = {"no_viewport": True}
+            if self.patchright_focus_control is not None:
+                options["focus_control"] = self.patchright_focus_control
             if self.patchright_context_profile:
                 options.update(
                     {

tests/test_cli.py

@@ -69,6 +69,7 @@ def test_fetch_json_is_bounded_and_uses_headless_stealth(monkeypatch: Any) -> No
     assert config.driver == "patchright"
     assert config.headless is True
     assert config.channel == "chrome"
+    assert config.patchright_focus_control is None
 
 
 def test_fetch_stdout_prints_raw_content(monkeypatch: Any) -> None:

tests/test_models.py

@@ -61,6 +61,7 @@ def test_patchright_context_omits_profile_by_default() -> None:
     options = config.context_options(profile)
 
     assert options["no_viewport"] is True
+    assert options["focus_control"] is False
     assert "user_agent" not in options
     assert "extra_http_headers" not in options
 
@@ -83,6 +84,7 @@ def test_patchright_context_profile_applies_native_context_metadata() -> None:
     options = config.context_options(profile)
 
     assert options["no_viewport"] is True
+    assert options["focus_control"] is False
     assert options["locale"] == "en-US"
     assert options["timezone_id"] == "Europe/Paris"
     assert options["color_scheme"] == "dark"
@@ -96,6 +98,16 @@ def test_patchright_context_profile_applies_native_context_metadata() -> None:
     assert "has_touch" not in options
 
 
+def test_patchright_focus_control_can_be_omitted() -> None:
+    profile = BrowserProfile(name="test")
+    config = SessionConfig(driver="patchright", patchright_focus_control=None)
+
+    options = config.context_options(profile)
+
+    assert options["no_viewport"] is True
+    assert "focus_control" not in options
+
+
 def test_headless_chromium_gets_simulated_screen() -> None:
     config = SessionConfig(driver="patchright", channel="chrome", headless=True)
 

web/content/user-guide/humanizer.md

@@ -0,0 +1,50 @@
+# Humanizer
+
+WebSkrap's humanizer is the `human_click` session helper. It waits for a visible
+target, scrolls it into view, moves the mouse along a curved eased path, and then
+clicks near the target center instead of calling Playwright's direct
+`page.click`.
+
+```python
+async with WebSkrapClient() as client:
+    session = await client.session("default")
+    page = await session.context.new_page()
+    await page.goto("https://example.com", wait_until="domcontentloaded")
+    await session.human_click(page, "button[type='submit']")
+```
+
+Use it when a normal page interaction should look closer to a manual browser
+click. It is useful for flows with hover-sensitive controls, scroll-dependent
+layouts, or simple behavioral checks that treat instant coordinate jumps as
+synthetic.
+
+## Direct click fallback
+
+Pass `human=False` to keep the same call shape while delegating to Playwright's
+click implementation.
+
+```python
+await session.human_click(page, "button[type='submit']", human=False, timeout=5_000)
+```
+
+## Click options
+
+`human_click` accepts normal Playwright click options including `button`,
+`click_count`, `delay`, `modifiers`, `position`, `strict`, `timeout`, and
+`trial`.
+
+```python
+await session.human_click(
+    page,
+    "button[type='submit']",
+    strict=True,
+    timeout=10_000,
+    modifiers=["Shift"],
+)
+```
+
+## Boundaries
+
+Humanized clicks do not solve CAPTCHAs, bypass login walls, evade access
+controls, or grant permission to scrape restricted targets. Use them only on
+sites and workflows you are allowed to access.

web/content/user-guide/sessions.md

@@ -119,6 +119,9 @@ await session.human_click(
 )
 ```
 
+See the [Humanizer](/docs/user-guide/humanizer) guide for the focused behavior
+reference and safety boundaries.
+
 ## Common options
 
 ```python

web/content/user-guide/stealth.md

@@ -31,7 +31,9 @@ config = SessionConfig(
 Patchright works best with real Chrome and a persistent context. If
 `user_data_dir` is omitted, WebSkrap creates a temporary persistent profile for
 Patchright sessions. Patchright contexts use the browser's real viewport and
-avoid synthetic viewport overrides (`no_viewport=True`).
+disable synthetic focus control (`no_viewport=True`, `focus_control=False`).
+The CLI omits `focus_control` for compatibility with Patchright versions that do
+not accept that option.
 
 ## Context profile mode