pi-lean-dimension 0.2.4 → 0.3.0

package/node_modules/pi-lean-portal/contributed/README.md

@@ -16,8 +16,8 @@ documented in `playwright_base.py`.
 > **You need the git repo, not just `npm install pi-lean-portal`.**
 > The template bridge and this README live under
 > `packages/pi-lean-portal/contributed/` in the source
-> repository. `docs/` is excluded from the portal `package.json`
-> `files`, so the templates are not in the published tarball. Clone the
+> repository. `contributed/` is not included in the portal `package.json`
+> `files` allow-list, so the templates are not in the published tarball. Clone the
 > repo (or obtain a copy of these files) before starting.
 
 For *whether* you should reach for a stealth backend at all, see
@@ -26,6 +26,52 @@ discovery, `browser.init` RPC, `PYTHONPATH` injection), see the
 "Stealth backends (user-managed)" section of
 [`packages/pi-lean-portal/AGENTS.md`](../../AGENTS.md).
 
+## Pinned CI stack
+
+The `contributed` GitHub Actions job pins both pieces of the Camoufox
+stack for reproducibility — the patched-Firefox **binary** and the
+**`cloverlabs-camoufox`** PyPI package. The canonical pin values live in
+the sidecar manifest `contributed/camoufox-py/pin.json` (the CI workflow
+reads them from there via `jq`). Unpinned, `camoufox fetch` pulls the
+latest stable binary on every run, and a new release silently changed
+wheel-scroll and humanized-click semantics — the quirks in
+`playwright_base.py` were written against the older binary and the
+`contributed` job went red.
+
+| Pin | Value | Pinned since | Source |
+|-----|-------|--------------|--------|
+| PyPI package | `cloverlabs-camoufox==0.6.0` | Jul 14 2026 | `pin.json` `.package` |
+| Patched binary | `official/152.0.4-beta.28` | Jul 16 2026 | `pin.json` `.binary` |
+
+`152.0.4-beta.27` shipped on Jul 16 2026 and broke the unpinned job:
+`page.mouse.wheel` became a no-op and `humanize=True`'s bezier motion
+made `locator.click(timeout=5s)` flake/timeout and blew MiniWoB task
+budgets. The quirks were adapted to the new binary —
+`_scroll_via_wheel` flipped off (eval `window.scrollBy` works again)
+and the contributed test suites force `launch.humanize=false` (they
+exercise the backend contract, not human-emulation stealth). The pin
+now tracks `152.0.4-beta.28`.
+
+### Upgrade procedure
+
+1. Reproduce the failure locally with `BROWSER_DEBUG=1` against the
+   **latest** Camoufox stack (bump both pins or drop them temporarily):
+   `npm run setup:miniwob` then
+   `CONTRIB_RUN=1 npx vitest run packages/pi-lean-portal/__tests__/run-contributed-suites.test.ts bench/miniwob/suites/miniwob-user-backends.test.ts`.
+2. Adapt the affected quirks in
+   `contributed/camoufox-py/bridge.py` and/or
+   `backends/python-base/pi_browser_bridge/playwright_base.py`. Keep the
+   `ponytail:` ceiling-notes on each quirk accurate to the new binary.
+3. Update `pin.json` to the newest passing version and re-run the
+   `contributed` job via `workflow_dispatch` to confirm green.
+4. The `pin.json` file drives both CI and the per-backend binary drift
+   check (see below), so bumping it here is the single source of truth
+   — no separate CI edit is needed.
+
+The `camoufox fetch` version format is `<repo>/<version>` (e.g.
+`official/152.0.4-beta.28`); run `camoufox sync` then `camoufox list` to
+discover available versions.
+
 ## Where things live
 
 ```
@@ -35,6 +81,8 @@ discovery, `browser.init` RPC, `PYTHONPATH` injection), see the
 └── user-backends/           ← stealth backends go here
     └── camoufox-py/
         ├── bridge.py        ← you copy this from the source repo
+        ├── pin.json         ← pinned versions this bridge was tested
+        │                      against; copy alongside bridge.py
         └── .venv/           ← you create this (engine pip pkg + playwright)
 ```
 
@@ -56,7 +104,7 @@ The convention is `<name>-py/` (mirrors the shipped `chromium-py` /
 `firefox-py` naming). The directory name is the plugin `name` you will
 register in `settings.json`.
 
-### 2. Copy the template bridge
+### 2. Copy the template bridge and pin manifest
 
 Copy the source-repo template into your user-backends tree:
 
@@ -64,11 +112,19 @@ Copy the source-repo template into your user-backends tree:
 mkdir -p ~/.pi/agent/pi-lean-portal/user-backends/camoufox-py
 cp packages/pi-lean-portal/contributed/camoufox-py/bridge.py \
    ~/.pi/agent/pi-lean-portal/user-backends/camoufox-py/bridge.py
+cp packages/pi-lean-portal/contributed/camoufox-py/pin.json \
+   ~/.pi/agent/pi-lean-portal/user-backends/camoufox-py/pin.json
 ```
 
+The `pin.json` sidecar is what the CI reads and what the bridge's
+built-in drift check uses at launch. Copying it alongside the bridge
+lets the binary self-verify that the locally installed package
+matches the tested pin — a warning is emitted to stderr if the
+versions diverge.
+
 You need the **git repo** for this step — the template is not in the
-`npm install pi-lean-portal` tarball (`docs/` is excluded from
-`package.json` `files` by design). Alternatively, write your own
+`npm install pi-lean-portal` tarball (`contributed/` is not included in the
+`package.json` `files` allow-list by design). Alternatively, write your own
 subclass using the [quirks schema](#quirks-schema-reference) documented
 in `backends/python-base/pi_browser_bridge/playwright_base.py`. Either
 way, audit what you copy — this is trusted user code that the extension
@@ -226,10 +282,13 @@ as class attributes on your subclass:
 |------|---------|-----------------|
 | `_fingerprint_managed_context` | `False` | `create_browser_context()` skips hardcoded `viewport`/`user_agent`; lets the fingerprint package set them. |
 | `_eval_prefix` | `""` | Prepended to every `page.evaluate` expression in `do_evaluate` (e.g. Camoufox's `"mw:"` routes writes to the main world). |
-| `_scroll_via_wheel` | `False` | `do_scroll` uses `page.mouse.wheel` instead of `page.evaluate("window.scrollBy")` (avoids eval-write under isolated-world stealth). |
+| `_scroll_via_wheel` | `False` | `do_scroll` uses `page.mouse.wheel` instead of `page.evaluate("window.scrollBy")`. Legacy Camoufox (``135.0.1-beta.24``) needed this — eval-write scrollBy no-op'd under the isolated world. Current binary (``152.0.4-beta.28``) is the reverse: wheel no-ops, eval scrollBy works, so Camoufox now leaves the default `False`. |
 | `_skip_default_viewport` | `False` | Skips Playwright's `Browser.setDefaultViewport` CDP call (Camoufox binary rejects its `isMobile` prop). |
 | `_skip_networkidle` | `False` | Nav-settle uses `load` instead of `networkidle` (patched binaries don't fire `networkidle` reliably). |
 | `_wrap_mw_eval_in_eval` | `False` | `do_evaluate` rewrites the expression as `eval(<JSON-string of expression>)` before prepending `_eval_prefix`, so multi-statement scripts survive Camoufox's `let _s = (${script})` main-world wrapper (which only accepts a single expression). Camoufox-only; flip back to `False` when a future driver fixes the wrapper. |
+| `_settle_budget_ms` | `400` | Poll budget (ms) for `_wait_for_navigation_settle` when no `framenavigated` event fires. Stealth backends whose patched Juggler fires events with higher latency (e.g. Camoufox) set a larger value (2000) to avoid settling before the navigation commit is observable. |
+| `_url_stability_settle` | `False` | When True, the no-nav poll waits for the URL to stabilise at a new value for 150 ms before exiting, instead of a fixed budget. Complements a wider `_settle_budget_ms` by confirming the URL has finished changing. |
+| `_csp_safe_readonly_via_init_script` | `False` | `create_browser_context` registers an init script (isolated world, CSP-free) that wraps the EXTRACTOR_SCRIPT in a `DOMContentLoaded`-deferred IIFE writing JSON to `<meta id="__pi-extract">`. `do_evaluate(read_only=True)` reads from that meta via `query_selector` + `get_attribute` instead of `page.evaluate` (which is CSP-blocked on some patched-Firefox stealth binaries). |
 
 All flags default off, so the shipped `chromium-py` / `firefox-py`
 behavior is bit-identical to a pre-stealth install. For the two

package/node_modules/pi-lean-portal/contributed/camoufox-py/bridge.py

@@ -6,6 +6,7 @@ User-installed backend for fingerprint-managed browsing via cloverlabs-camoufox.
 
 import json
 import sys
+from pathlib import Path
 
 # Lazy-patch Playwright's coreBundle.js if needed. The patcher is idempotent
 # and guarded: it only runs once per file (marker comment), warns on pattern
@@ -34,7 +35,7 @@ class CamoufoxPyBridge(PlaywrightBridge):
     """Stealth bridge using Camoufox (Firefox-based).
 
     The base's quirks dispatch handles eval-world routing (``mw:`` prefix)
-    and wheel-based scrolling (``_scroll_via_wheel``).  This subclass sets
+    and eval-based scrolling (``window.scrollBy``).  This subclass sets
     the quirk flags and overrides ``_launch_browser`` to call
     ``camoufox.NewBrowser`` with the plugin config's launch options.
 
@@ -60,7 +61,13 @@ class CamoufoxPyBridge(PlaywrightBridge):
     # crashes on this binary (same ``isMobile`` rejection).  Keep using
     # the standard ``browser.new_context()``.
     _eval_prefix: str = "mw:"
-    _scroll_via_wheel: bool = True
+    # Camoufox ``152.0.4-beta.27+`` no-ops ``page.mouse.wheel`` (the ``wheel``
+    # listener never fires), so the base's eval-based ``window.scrollBy`` is
+    # the only path that moves the page on the current binary.  Leave the
+    # base default (``_scroll_via_wheel = False``).  The legacy
+    # ``135.0.1-beta.24`` binary needed ``True`` (eval-write scrollBy
+    # no-op'd under the isolated world); flipped off when the CI pin moved
+    # to ``152.0.4-beta.28``.  See ``playwright_base._scroll_via_wheel``.
     # The Camoufox patched Firefox binary rejects the ``isMobile`` property that
     # Playwright includes in ``Browser.setDefaultViewport``.  Skip the call.
     _skip_default_viewport: bool = True
@@ -75,6 +82,15 @@ class CamoufoxPyBridge(PlaywrightBridge):
     # `mw:eval(<json>)` so it is a single expression that `eval` runs
     # verbatim.  See the `_wrap_mw_eval_in_eval` quirk docstring.
     _wrap_mw_eval_in_eval: bool = True
+    # The patched Camoufox Juggler fires ``framenavigated`` events and
+    # updates ``page.url`` with higher latency than a standard Playwright
+    # browser.  Widen the settle poll budget so a ``setTimeout``-delayed
+    # redirect (e.g. ``location.href`` after 280 ms) is still captured
+    # under CI load.  URL stability mode confirms the URL has finished
+    # changing before declaring "no navigation" — the 150 ms hold is
+    # negligible against the wider budget.
+    _settle_budget_ms: int = 2000
+    _url_stability_settle: bool = True
     _install_hint: str = (
         "Camoufox browser not installed.\n"
         "Run the following commands in your camoufox-py virtual environment:\n"
@@ -82,6 +98,80 @@ class CamoufoxPyBridge(PlaywrightBridge):
         "  python -m camoufox fetch"
     )
 
+    def _check_pinned_version(self) -> None:
+        """Best-effort runtime check that the installed Camoufox stack matches pin.json.
+
+        Reads ``pin.json`` (same directory as this module) and
+        compares the pinned ``cloverlabs-camoufox`` package version
+        against what's actually installed via pip metadata.
+        Warns to stderr on any mismatch or if the check cannot be
+        performed.  Never raises — this is advisory only.
+        """
+        try:
+            pin_path = Path(__file__).parent / "pin.json"
+            if not pin_path.exists():
+                return
+            pinned = json.loads(pin_path.read_text())
+        except Exception:
+            return
+
+        expected_pkg = pinned.get("package", "")
+        if expected_pkg:
+            try:
+                from importlib.metadata import version as _get_version
+
+                installed = _get_version("cloverlabs-camoufox")
+                expected_ver = expected_pkg.split("==")[-1].split("[")[0]
+                if installed != expected_ver:
+                    print(
+                        "pi-bridge camoufox-py: pin.json pins "
+                        f"cloverlabs-camoufox=={expected_ver} but "
+                        f"{installed} is installed — browser binary "
+                        "drift risk.",
+                        file=sys.stderr,
+                    )
+            except Exception:
+                pass  # package not installed or metadata unavailable
+
+        expected_binary = pinned.get("binary", "")
+        if expected_binary:
+            try:
+                import camoufox  # type: ignore[import-unresolved]
+                _binary_version = None
+                for _attr in (
+                    "__binary_version__",
+                    "_binary_version",
+                    "binary_version",
+                ):
+                    _candidate = getattr(camoufox, _attr, None)
+                    if _candidate is not None:
+                        _binary_version = _candidate
+                        break
+                if _binary_version is None:
+                    _sync = getattr(camoufox, "sync", None)
+                    if _sync is not None:
+                        for _attr in (
+                            "__binary_version__",
+                            "_binary_version",
+                            "binary_version",
+                        ):
+                            _candidate = getattr(_sync, _attr, None)
+                            if _candidate is not None:
+                                _binary_version = _candidate
+                                break
+                if _binary_version is None:
+                    return
+                expected_ref = expected_binary.split("/")[-1]
+                if _binary_version != expected_ref:
+                    print(
+                        "pi-bridge camoufox-py: pin.json expects binary "
+                        f"{expected_ref} but {_binary_version} is "
+                        "installed — binary drift risk.",
+                        file=sys.stderr,
+                    )
+            except Exception:
+                pass  # camoufox not importable yet — skip silently
+
     def _launch_browser(self):  # type: ignore[override]
         """Launch Camoufox via ``camoufox.NewBrowser``.
 
@@ -103,6 +193,8 @@ class CamoufoxPyBridge(PlaywrightBridge):
 
         Returns a standard Playwright ``Browser`` patched by Camoufox.
         """
+        self._check_pinned_version()
+
         # Lazy-import so non-Camoufox bridges don't pay the import cost
         # and to give a clear error when the package is missing.
         try:
@@ -196,18 +288,20 @@ if __name__ == "__main__":
         import camoufox  # type: ignore[import-unresolved] # noqa: F401
     except ImportError:
         print(
-            json.dumps({
-                "jsonrpc": "2.0",
-                "id": None,
-                "error": {
-                    "code": -32000,
-                    "message": (
-                        "cloverlabs-camoufox is not installed.\n"
-                        "Run: pip install cloverlabs-camoufox[geoip] && "
-                        "python -m camoufox fetch"
-                    ),
-                },
-            })
+            json.dumps(
+                {
+                    "jsonrpc": "2.0",
+                    "id": None,
+                    "error": {
+                        "code": -32000,
+                        "message": (
+                            "cloverlabs-camoufox is not installed.\n"
+                            "Run: pip install cloverlabs-camoufox[geoip] && "
+                            "python -m camoufox fetch"
+                        ),
+                    },
+                }
+            )
         )
         sys.stdout.flush()
         sys.exit(1)

package/node_modules/pi-lean-portal/contributed/camoufox-py/pin.json

@@ -0,0 +1,4 @@
+{
+  "package": "cloverlabs-camoufox[geoip]==0.6.0",
+  "binary": "official/152.0.4-beta.28"
+}

package/node_modules/pi-lean-portal/core/fetch-backend.ts

@@ -6,7 +6,6 @@
  * No JavaScript execution — fastest path for static content.
  *
  * When called directly via the `webFetch()` entry point, this backend:
- * - Validates the URL (blocks localhost, private IPs, dangerous schemes)
  * - Fetches and converts HTML → Markdown
  * - Runs JS-shell detection inline
  * - Runs bot-detection heuristics inline
@@ -20,10 +19,10 @@ import {
 	BROWSER_TEMP_DIR,
 	safeTaskId,
 	ensureBrowserTempDir,
+	formatBytes,
 } from "./shared/paths.js";
 import TurndownService from "turndown";
 import { parse as parseHtml } from "node-html-parser";
-import { validateUrl } from "./shared/url-safety.js";
 import { checkPage } from "./shared/bot-detection.js";
 
 const DEFAULT_USER_AGENT =
@@ -194,7 +193,7 @@ function htmlToMarkdown(root: ReturnType<typeof parseHtml>): string {
 
 // ─── Decoupled entry point: webFetch() ────────────────────────────────
 
-export interface WebFetchOptions {
+interface WebFetchOptions {
 	url: string;
 	timeout?: number; // seconds, default 30, max 120
 	signal?: AbortSignal;
@@ -202,7 +201,7 @@ export interface WebFetchOptions {
 	taskId?: string;
 }
 
-export interface WebFetchResult {
+interface WebFetchResult {
 	success: boolean;
 	url: string;
 	title: string;
@@ -231,12 +230,6 @@ const activeFetchFiles = new Map<string, string[]>();
 
 // ─── Temp file management ──────────────────────────────────────────────
 
-function formatBytes(bytes: number): string {
-	if (bytes < 1024) return `${bytes}B`;
-	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)}KB`;
-	return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
-}
-
 function writeFetchTempFile(content: string, taskId: string): string {
 	ensureBrowserTempDir();
 
@@ -312,7 +305,7 @@ export function cleanupFetchTempFiles(taskId?: string): void {
 /**
  * Decoupled web fetch entry point.
  *
- * Pipeline: URL safety → fetch → JS detection → bot detection → content capping
+ * Pipeline: fetch → JS detection → bot detection → content capping
  *
  * This function is the new recommended way to perform a stateless HTTP fetch.
  * It replaces the router-level fetch dispatch that used to live in `router.ts navigate()`.
@@ -322,7 +315,7 @@ export async function webFetch(
 ): Promise<WebFetchResult> {
 	const timeout = (options.timeout ?? 30) * 1000;
 
-	// Step 1: URL safety validation
+	// Parse URL
 	let url: string;
 	try {
 		url = new URL(options.url).href;
@@ -337,19 +330,7 @@ export async function webFetch(
 		};
 	}
 
-	const safety = validateUrl(url);
-	if (!safety.safe) {
-		return {
-			success: false,
-			url,
-			title: "",
-			content: safety.reason || "URL blocked",
-			backendUsed: "fetch",
-			error: `URL blocked: ${safety.reason}`,
-		};
-	}
-
-	// Step 2: Perform fetch
+	// Step 1: Perform fetch
 	let result: {
 		html: string;
 		title: string;
@@ -401,21 +382,20 @@ export async function webFetch(
 		};
 	}
 
-	// Step 3: Bot detection via shared utility (uses un-mutated parsed root)
+	// Step 2: Bot detection via shared utility (uses un-mutated parsed root)
 	let botDetected: boolean | undefined;
 	try {
 		const bodyText = result.root.textContent?.trim() || "";
-		const detection = checkPage(result.title, bodyText);
-		if (detection.isBlocked) botDetected = true;
+		if (checkPage(result.title, bodyText)) botDetected = true;
 	} catch {
 		/* best-effort — don't fail on bot detection errors */
 	}
 
-	// Step 4: Convert to Markdown (uses pre-parsed root from performFetch)
+	// Step 3: Convert to Markdown (uses pre-parsed root from performFetch)
 	// NOTE: htmlToMarkdown mutates the tree — run after bot detection
 	const markdown = htmlToMarkdown(result.root);
 
-	// Step 5: Cap content
+	// Step 4: Cap content
 	const tid = options.taskId ?? "web-fetch-default";
 	const { inline, filePath, totalChars } = capFetchContent(markdown, tid);
 

package/node_modules/pi-lean-portal/core/guides.ts

@@ -280,37 +280,31 @@ export function loadUserGuides(): Record<string, Guide> {
 	return result;
 }
 
-// ── Merged Guide Content (lazy) ────────────────────────────────
+// ── Merged Guide Content (always fresh) ──────────────────────
 
-let _guideContentCache: Record<string, Guide> | null = null;
+let _testGuideOverrides: Record<string, Guide> | null = null;
 
 /**
  * Get the merged guide content (builtin + user-authored).
- * Lazily built on first call; invalidate via invalidateGuideContent().
+ * Always reads user guides from disk — no stale cache.
  * User-authored guides override builtin guides on name collision.
  */
 export function getGuideContent(): Record<string, Guide> {
-	if (!_guideContentCache) {
-		_guideContentCache = {
-			...BUILTIN_GUIDES,
-			...loadUserGuides(),
-		};
+	const base = { ...BUILTIN_GUIDES, ...loadUserGuides() };
+	if (_testGuideOverrides) {
+		return { ...base, ..._testGuideOverrides };
 	}
-	return _guideContentCache;
-}
-
-/** Invalidate the guide content cache so the next getGuideContent() call rescans guides/. */
-export function invalidateGuideContent(): void {
-	_guideContentCache = null;
+	return base;
 }
 
 /**
- * Override the guide content cache for testing.
- * Pass undefined/null to reset to default (same as invalidateGuideContent).
+ * Inject test-only guide overrides.
+ * Pass undefined/null to clear. These are layered on top of the real
+ * builtin+user guides — no filesystem writes needed in tests.
  * @internal
  */
 export function _setGuideContentForTest(content?: Record<string, Guide>): void {
-	_guideContentCache = content ?? null;
+	_testGuideOverrides = content ?? null;
 }
 
 /** Format guide listing grouped by category, with icon/shortName and trigger info. */
@@ -434,7 +428,9 @@ export function formatGuideFooter(guides: ApplicableGuide[]): string {
 			lines.push("  Site:");
 			addedSiteHeader = true;
 		}
-		lines.push(`  • ${g.icon} ${g.shortName} — ${g.reason}`);
+		lines.push(
+			`  • ${g.icon} ${g.shortName} — ${g.reason} (web-guide guide="${g.name}")`,
+		);
 	}
 
 	return lines.join("\n");

package/node_modules/pi-lean-portal/core/router.ts

@@ -1,6 +1,6 @@
 /**
  * Plugin Router — registry-based dispatch for interactive browser operations.
- * Handles snapshot truncation, URL safety, session lifecycle, and crash recovery.
+ * Handles snapshot truncation, session lifecycle, and crash recovery.
  */
 
 import { writeFileSync } from "node:fs";
@@ -8,7 +8,6 @@ import { BROWSER_TEMP_DIR, ensureBrowserTempDir } from "./shared/paths.js";
 import { pluginRegistry } from "./plugin-registry.js";
 import { sessionManager } from "./shared/session-manager.js";
 import type { BrowserSession } from "./shared/session-manager.js";
-import { validateUrl } from "./shared/url-safety.js";
 import { snapshotFingerprint } from "./shared/accessibility-tree.js";
 import {
 	cacheSnapshot,
@@ -425,23 +424,6 @@ export async function navigate(
 		};
 	}
 
-	// URL safety check
-	const safety = validateUrl(normalizedUrl);
-	if (!safety.safe) {
-		return {
-			success: false,
-			url: normalizedUrl,
-			title: "",
-			snapshot: "",
-			elementCount: 0,
-			error: `URL blocked: ${safety.reason}`,
-			backendUsed: plugin.name,
-		} as NavigateResult & {
-			backendUsed: string;
-			botDetectionWarning?: boolean;
-		};
-	}
-
 	// ── Resolve profile mode ───────────────────────────────────
 	let resolvedProfileName: string | undefined;
 	let profileMode: "none" | "session" | "named" | undefined;
@@ -866,7 +848,7 @@ export async function clearConsole(
 
 // ─── browser-inspect public types ──────────────────────────────────
 
-export interface InspectParams {
+interface InspectParams {
 	role?: string;
 	name?: string;
 	ref?: string;

package/node_modules/pi-lean-portal/core/shared/bot-detection.ts

@@ -13,11 +13,6 @@
 
 import { BOT_SIGNALS } from "./browser-data.js";
 
-export interface BotDetectionResult {
-	/** True if the page appears to be a bot block/challenge page */
-	isBlocked: boolean;
-}
-
 /**
  * Content patterns that indicate a bot block — loaded from shared data.
  */
@@ -43,17 +38,17 @@ const HTML_SIGNALS = BOT_SIGNALS.htmlSignals;
 /**
  * Check if page text content suggests a bot block.
  */
-function checkBodyText(bodyText: string): BotDetectionResult {
-	if (!bodyText) return { isBlocked: false };
+function checkBodyText(bodyText: string): boolean {
+	if (!bodyText) return false;
 
 	const lower = bodyText.toLowerCase();
 	for (const signal of BLOCK_SIGNALS) {
 		if (lower.includes(signal)) {
-			return { isBlocked: true };
+			return true;
 		}
 	}
 
-	return { isBlocked: false };
+	return false;
 }
 
 /**
@@ -62,15 +57,15 @@ function checkBodyText(bodyText: string): BotDetectionResult {
  * inclusion (for CDN domains, generic 403 messages) and regex patterns
  * (for Akamai reference codes, etc.).
  */
-function checkBodyOnlyText(bodyText: string): BotDetectionResult {
-	if (!bodyText) return { isBlocked: false };
+function checkBodyOnlyText(bodyText: string): boolean {
+	if (!bodyText) return false;
 
 	const lower = bodyText.toLowerCase();
 
 	// Check string signals first
 	for (const signal of BODY_ONLY_SIGNALS) {
 		if (lower.includes(signal)) {
-			return { isBlocked: true };
+			return true;
 		}
 	}
 
@@ -78,11 +73,11 @@ function checkBodyOnlyText(bodyText: string): BotDetectionResult {
 	for (const pattern of BODY_ONLY_PATTERNS) {
 		const match = bodyText.match(pattern);
 		if (match) {
-			return { isBlocked: true };
+			return true;
 		}
 	}
 
-	return { isBlocked: false };
+	return false;
 }
 
 /**
@@ -93,17 +88,17 @@ function checkBodyOnlyText(bodyText: string): BotDetectionResult {
  * loaded from the shared ``browser-data.json`` so TypeScript and Python
  * bridge implementations share a single source of truth.
  */
-function checkHtmlContent(html: string): BotDetectionResult {
-	if (!html) return { isBlocked: false };
+function checkHtmlContent(html: string): boolean {
+	if (!html) return false;
 
 	const lower = html.toLowerCase();
 	for (const signal of HTML_SIGNALS) {
 		if (lower.includes(signal)) {
-			return { isBlocked: true };
+			return true;
 		}
 	}
 
-	return { isBlocked: false };
+	return false;
 }
 
 /**
@@ -118,24 +113,18 @@ export function checkPage(
 	title: string,
 	bodyText: string,
 	html?: string,
-): BotDetectionResult {
+): boolean {
 	// Check title first (often contains "Attention Required!" etc.)
-	const titleResult = checkBodyText(title);
-	if (titleResult.isBlocked) return titleResult;
+	if (checkBodyText(title)) return true;
 
 	// Check body against challenge phrases
-	const bodyResult = checkBodyText(bodyText);
-	if (bodyResult.isBlocked) return bodyResult;
+	if (checkBodyText(bodyText)) return true;
 
 	// Check body against CDN-specific patterns (reference #, etc.)
-	const bodyOnlyResult = checkBodyOnlyText(bodyText);
-	if (bodyOnlyResult.isBlocked) return bodyOnlyResult;
+	if (checkBodyOnlyText(bodyText)) return true;
 
 	// Check HTML source for CAPTCHA widget embed codes
-	if (html !== undefined) {
-		const htmlResult = checkHtmlContent(html);
-		if (htmlResult.isBlocked) return htmlResult;
-	}
+	if (html !== undefined && checkHtmlContent(html)) return true;
 
-	return { isBlocked: false };
+	return false;
 }

package/node_modules/pi-lean-portal/core/shared/browser-data.ts

@@ -14,27 +14,27 @@ import _raw from "./browser-data.json" with { type: "json" };
 
 // ─── Types ─────────────────────────────────────────────────────────────
 
-export interface BotSignals {
+interface BotSignals {
 	blockSignals: string[];
 	bodyOnlySignals: string[];
 	bodyOnlyPatterns: string[];
 	htmlSignals: string[];
 }
 
-export interface AccessibilityData {
+interface AccessibilityData {
 	interactiveRoles: string[];
 	informationalRoles: string[];
 	roleIcons: Record<string, string>;
 }
 
-export interface NavSettleData {
+interface NavSettleData {
 	navTimeoutMs: number;
 	settleTimeoutMs: number;
 	settleRaceMs: number;
 	domStabilizationJs: string;
 }
 
-export interface BrowserDataFile {
+interface BrowserDataFile {
 	version: number;
 	botSignals: BotSignals;
 	accessibility: AccessibilityData;