pi-lean-dimension 0.1.0 → 0.2.1

package/node_modules/pi-lean-portal/backends/python-base/tests/test_py_bridges.py

@@ -0,0 +1,198 @@
+"""
+Tests for Python bridge backends (chromium-py, firefox-py).
+
+Pure-logic unit tests parametrized over both backends.  Engine-specific
+assertions live in top-level test functions (not parametrized).
+"""
+
+from conftest import METHOD_NAMES, _MockConsolePage, _load_bridge_class
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  Engine-specific construction tests
+# ═══════════════════════════════════════════════════════════════════════
+
+
+class TestChromiumPyBridgeConstruction:
+    def test_constructs_without_playwright_browser(self):
+        """ChromiumPyBridge can be instantiated without a Playwright browser."""
+        Cls = _load_bridge_class("chromium-py")
+        bridge = Cls()
+        assert bridge.sessions == {}
+        assert bridge.element_caches == {}
+
+
+class TestFirefoxPyBridgeConstruction:
+    def test_constructs_without_playwright_browser(self):
+        """FirefoxPyBridge has engine-specific name, UA hint, and install hint."""
+        Cls = _load_bridge_class("firefox-py")
+        bridge = Cls()
+        assert bridge._plugin_name == "firefox-py"
+        assert bridge._user_agent is not None
+        assert bridge._install_hint is not None
+        assert "playwright install firefox" in bridge._install_hint
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  Test: Dispatch layer (all methods routed correctly)
+# ═══════════════════════════════════════════════════════════════════════
+
+
+class TestDispatch:
+    """Verify that all methods are routed correctly in handle_command."""
+
+    def test_all_methods_have_dispatch_entries(self, bridge_factory):
+        """Every method gets routed (even if it returns a session error)."""
+        _, bridge = bridge_factory
+        no_session_ok = {
+            "browser.getConsoleMessages",
+            "browser.clearConsole",
+            "browser.cleanup",
+        }
+        for method in METHOD_NAMES:
+            params = {"taskId": "no-session-test"}
+            result = bridge.handle_command(method, params, 99)
+            if method in no_session_ok:
+                assert "result" in result, f"{method} should return a result"
+                continue
+            assert "error" in result, f"{method} did not produce an error"
+            code = result["error"]["code"]
+            _valid = {-32002, -32602, -32601, -32000}
+            _msg = f"{method}: unexpected error code {code}: {result['error']['message'][:60]}"
+            assert code in _valid, _msg
+
+    def test_navigate_missing_url(self, bridge_factory):
+        """navigate without url returns an error mentioning url."""
+        _, bridge = bridge_factory
+        result = bridge.handle_command("browser.navigate", {"taskId": "t"}, 1)
+        assert "error" in result
+        assert "url" in result["error"]["message"]
+
+    def test_navigate_missing_task_id(self, bridge_factory):
+        """navigate without taskId returns an error mentioning taskId."""
+        _, bridge = bridge_factory
+        result = bridge.handle_command(
+            "browser.navigate", {"url": "https://example.com"}, 2
+        )
+        assert "error" in result
+        assert "taskId" in result["error"]["message"]
+
+    def test_click_missing_ref(self, bridge_factory):
+        """click without ref returns INVALID_PARAMS."""
+        _, bridge = bridge_factory
+        result = bridge.handle_command("browser.click", {"taskId": "t"}, 3)
+        assert "error" in result
+        assert "ref" in result["error"]["message"]
+
+    def test_type_missing_text(self, bridge_factory):
+        """type without text returns INVALID_PARAMS."""
+        _, bridge = bridge_factory
+        result = bridge.handle_command(
+            "browser.type", {"taskId": "t", "ref": "e1"}, 4
+        )
+        assert "error" in result
+        assert "text" in result["error"]["message"]
+
+    def test_evaluate_missing_expression(self, bridge_factory):
+        """evaluate without expression returns INVALID_PARAMS."""
+        _, bridge = bridge_factory
+        result = bridge.handle_command("browser.evaluate", {"taskId": "t"}, 5)
+        assert "error" in result
+        assert "expression" in result["error"]["message"]
+
+    def test_shutdown_command(self, bridge_factory):
+        """shutdown returns success and sets _running to False."""
+        _, bridge = bridge_factory
+        result = bridge.handle_command("shutdown", {}, 6)
+        assert result["result"] == "shutting_down"
+        assert not bridge._running
+
+    def test_cleanup_missing_task_id(self, bridge_factory):
+        """cleanup without taskId returns INVALID_PARAMS."""
+        _, bridge = bridge_factory
+        result = bridge.handle_command("browser.cleanup", {}, 7)
+        assert "error" in result
+        assert "taskId" in result["error"]["message"]
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  Test: Console capture ring-buffer cap
+# ═══════════════════════════════════════════════════════════════════════
+
+
+class TestConsoleCap:
+    """Verify the 500-entry ring buffer on console capture."""
+
+    def test_console_capped_at_500(self, bridge_factory):
+        """After 501 events, only the last 500 are retained."""
+        _, bridge = bridge_factory
+        page = _MockConsolePage()
+        session = bridge._setup_page_session(page)
+        messages: list[dict[str, str]] = session["console_messages"]
+
+        for i in range(501):
+            page.fire_console(f"msg-{i}")
+
+        assert len(messages) == 500, f"Expected 500, got {len(messages)}"
+        assert (
+            messages[0]["text"] == "msg-1"
+        ), "First entry should be msg-1 (msg-0 popped)"
+        assert messages[-1]["text"] == "msg-500", "Last entry should be msg-500"
+
+    def test_console_under_cap_retains_all(self, bridge_factory):
+        """Fewer than 501 events are all retained."""
+        _, bridge = bridge_factory
+        page = _MockConsolePage()
+        session = bridge._setup_page_session(page)
+        messages: list[dict[str, str]] = session["console_messages"]
+
+        for i in range(10):
+            page.fire_console(f"msg-{i}")
+
+        assert len(messages) == 10, f"Expected 10, got {len(messages)}"
+        assert messages[0]["text"] == "msg-0"
+        assert messages[-1]["text"] == "msg-9"
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  Test: browser.evaluate RPC dispatch with readOnly
+# ═══════════════════════════════════════════════════════════════════════
+
+
+class TestEvaluateReadOnly:
+    """Verify ``browser.evaluate`` reads the ``readOnly`` param
+    and forwards it to ``do_evaluate`` as ``read_only``."""
+
+    def test_readonly_true_reaches_do_evaluate(self, bridge_factory):
+        """readOnly: True in params reaches do_evaluate as read_only=True."""
+        _, bridge = bridge_factory
+        recorded: list[bool] = []
+
+        def spy(task_id, expression, *, read_only=False):
+            recorded.append(read_only)
+            return {"success": True, "result": None}
+
+        bridge.do_evaluate = spy  # type: ignore[assignment]
+        bridge.handle_command(
+            "browser.evaluate",
+            {"taskId": "t", "expression": "1+1", "readOnly": True},
+            999,
+        )
+        assert recorded == [True]
+
+    def test_readonly_omitted_defaults_false(self, bridge_factory):
+        """No readOnly param: defaults to False."""
+        _, bridge = bridge_factory
+        recorded: list[bool] = []
+
+        def spy(task_id, expression, *, read_only=False):
+            recorded.append(read_only)
+            return {"success": True, "result": None}
+
+        bridge.do_evaluate = spy  # type: ignore[assignment]
+        bridge.handle_command(
+            "browser.evaluate",
+            {"taskId": "t", "expression": "1+1"},
+            1000,
+        )
+        assert recorded == [False]

package/node_modules/pi-lean-portal/browser-toggle.ts

@@ -1,5 +1,6 @@
 import type {
 	ExtensionAPI,
+	ExtensionCommandContext,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 // fs functions used by profile/cookies handlers are in their respective modules
@@ -60,6 +61,21 @@ const LEARN_TOOL_NAMES = new Set(["web-learn"]);
  */
 const SIBLING_TOOL_NAMES = new Set<string>(["web-search"]);
 
+/**
+ * Update the search status bar glyph if sibling tools are installed.
+ * Used by ``/web on|learn|off`` to keep the ``search`` slot in sync.
+ */
+function setSearchSlot(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	glyph: string,
+): void {
+	const hasSiblingTools = getRegisteredIn(pi, SIBLING_TOOL_NAMES).length > 0;
+	if (hasSiblingTools) {
+		ctx.ui.setStatus("search", glyph);
+	}
+}
+
 /** Persisted state shape — two independent booleans plus conversation-scoped default profile. */
 interface BrowserToggleState {
 	browserToolsEnabled: boolean;
@@ -88,25 +104,19 @@ export function getConversationDefaultProfile(): string | undefined {
 
 // ---- Helpers ---------------------------------------------------
 
-/**
- * Return the subset of BROWSER_TOOL_NAMES that are actually registered.
- * (With the toggle integrated into pi-lean-portal, this is always non-empty
- *  when pi-lean-portal is loaded, but the helper remains for robustness.)
- */
-function getRegisteredBrowserTools(pi: ExtensionAPI): string[] {
+/** Return the subset of a tool-name set that is actually registered. */
+function getRegisteredIn(pi: ExtensionAPI, names: Set<string>): string[] {
 	return pi
 		.getAllTools()
 		.map((t) => t.name)
-		.filter((n) => BROWSER_TOOL_NAMES.has(n));
+		.filter((n) => names.has(n));
 }
 
 /**
  * Check whether browser tools are currently active in the system prompt.
- * Returns true when no browser tools exist (nothing to toggle).
  */
 function isBrowserEnabled(pi: ExtensionAPI): boolean {
-	const registered = getRegisteredBrowserTools(pi);
-	if (registered.length === 0) return true; // nothing registered → vacuously "enabled"
+	const registered = getRegisteredIn(pi, BROWSER_TOOL_NAMES);
 
 	const active = new Set(pi.getActiveTools());
 	return registered.some((name) => active.has(name));
@@ -121,8 +131,8 @@ function applyBrowserState(pi: ExtensionAPI, enable: boolean): void {
 	// Combine browser tools + sibling tools into one toggle set.
 	// (/web on enables both; /web off disables both.)
 	const registered = new Set([
-		...getRegisteredBrowserTools(pi),
-		...getRegisteredSiblingTools(pi),
+		...getRegisteredIn(pi, BROWSER_TOOL_NAMES),
+		...getRegisteredIn(pi, SIBLING_TOOL_NAMES),
 	]);
 	if (registered.size === 0) return;
 	_lastToggleState = enable;
@@ -149,7 +159,7 @@ function persistState(pi: ExtensionAPI, state: BrowserToggleState): void {
 // ---- Branch-aware restoration ----------------------------------
 
 function restoreFromBranch(pi: ExtensionAPI, ctx: ExtensionContext): boolean {
-	const registered = getRegisteredBrowserTools(pi);
+	const registered = getRegisteredIn(pi, BROWSER_TOOL_NAMES);
 	if (registered.length === 0) return false;
 
 	let savedState: BrowserToggleState | undefined;
@@ -261,34 +271,11 @@ function readBrowserToggleConfig(): boolean {
 	return true; // default: enabled
 }
 
-/**
- * Return the subset of LEARN_TOOL_NAMES that are actually registered.
- */
-function getRegisteredLearnTools(pi: ExtensionAPI): string[] {
-	return pi
-		.getAllTools()
-		.map((t) => t.name)
-		.filter((n) => LEARN_TOOL_NAMES.has(n));
-}
-
-/**
- * Return the subset of SIBLING_TOOL_NAMES that are actually registered.
- * Used by applyBrowserState to include sibling tools in toggle operations.
- */
-function getRegisteredSiblingTools(pi: ExtensionAPI): string[] {
-	return pi
-		.getAllTools()
-		.map((t) => t.name)
-		.filter((n) => SIBLING_TOOL_NAMES.has(n));
-}
-
 /**
  * Check whether learn tools are currently active.
- * Returns true when no learn tools exist (vacuously enabled).
  */
 function isLearnEnabled(pi: ExtensionAPI): boolean {
-	const registered = getRegisteredLearnTools(pi);
-	if (registered.length === 0) return true;
+	const registered = getRegisteredIn(pi, LEARN_TOOL_NAMES);
 	const active = new Set(pi.getActiveTools());
 	return registered.some((name) => active.has(name));
 }
@@ -300,7 +287,7 @@ function isLearnEnabled(pi: ExtensionAPI): boolean {
  */
 function applyLearnState(pi: ExtensionAPI, enable: boolean): void {
 	_lastLearnState = enable;
-	const registered = new Set(getRegisteredLearnTools(pi));
+	const registered = new Set(getRegisteredIn(pi, LEARN_TOOL_NAMES));
 	if (registered.size === 0) return;
 	if (enable) {
 		const current = pi.getActiveTools();
@@ -313,20 +300,17 @@ function applyLearnState(pi: ExtensionAPI, enable: boolean): void {
 }
 
 // ── Test-only exports ──────────────────────────────────
-// These are exported solely for unit testing via
-// __tests__/helpers/toggle-test-utils.ts. Do not import
-// them directly from production code.
+// These are exported solely for unit testing.
+// Do not import them directly from production code.
 /** @internal */
 export {
-	getRegisteredBrowserTools,
+	getRegisteredIn,
 	isBrowserEnabled,
 	applyBrowserState,
 	persistState,
 	restoreFromBranch,
 	readBrowserToggleConfig,
 	applyConfigDefault,
-	getRegisteredLearnTools,
-	getRegisteredSiblingTools,
 	isLearnEnabled,
 	applyLearnState,
 	_resetToggleStateForTest,
@@ -389,7 +373,7 @@ export default function initBrowserToggle(pi: ExtensionAPI) {
 			"Usage: /web on | off | learn | status",
 		handler: async (args, ctx) => {
 			const cmd = args.trim().toLowerCase();
-			const hasBrowserTools = getRegisteredBrowserTools(pi).length > 0;
+			const hasBrowserTools = getRegisteredIn(pi, BROWSER_TOOL_NAMES).length > 0;
 
 			if (!hasBrowserTools) {
 				ctx.ui.notify(
@@ -409,14 +393,7 @@ export default function initBrowserToggle(pi: ExtensionAPI) {
 				});
 				ctx.ui.setStatus("browser", ctx.ui.theme.fg("accent", "●") + " idle");
 
-				// Clear any stale search off-glyph — sibling tools are now enabled.
-				const hasSiblingTools = getRegisteredSiblingTools(pi).length > 0;
-				if (hasSiblingTools) {
-					ctx.ui.setStatus(
-						"search",
-						ctx.ui.theme.fg("accent", "●") + " searxng",
-					);
-				}
+				setSearchSlot(pi, ctx, ctx.ui.theme.fg("accent", "●") + " searxng");
 
 				ctx.ui.notify(
 					"🌐 Browser tools enabled. /web learn to make web-learn available.",
@@ -432,14 +409,7 @@ export default function initBrowserToggle(pi: ExtensionAPI) {
 				});
 				ctx.ui.setStatus("browser", ctx.ui.theme.fg("success", "●") + " idle");
 
-				// Clear any stale search off-glyph — sibling tools are now enabled.
-				const hasSiblingTools = getRegisteredSiblingTools(pi).length > 0;
-				if (hasSiblingTools) {
-					ctx.ui.setStatus(
-						"search",
-						ctx.ui.theme.fg("accent", "●") + " searxng",
-					);
-				}
+				setSearchSlot(pi, ctx, ctx.ui.theme.fg("accent", "●") + " searxng");
 
 				ctx.ui.notify(
 					"📖 web-learn tool is now available. Agent will save/update guides when asked.",
@@ -455,13 +425,7 @@ export default function initBrowserToggle(pi: ExtensionAPI) {
 				});
 				ctx.ui.setStatus("browser", "○ web off");
 
-				// Set the search tool status to off if sibling apps are present.
-				// Search owns the colored glyph for on states; portal only writes
-				// the off state when tools are explicitly disabled.
-				const hasSiblingTools = getRegisteredSiblingTools(pi).length > 0;
-				if (hasSiblingTools) {
-					ctx.ui.setStatus("search", "○ searxng");
-				}
+				setSearchSlot(pi, ctx, "○ searxng");
 
 				ctx.ui.notify(
 					"🌐 Browser tools disabled. /web on to re-enable.",
@@ -515,7 +479,7 @@ export default function initBrowserToggle(pi: ExtensionAPI) {
 		// toggle state.  Without this, a race between portal's session_start
 		// (async — restores/applies state) and search's session_start (probes
 		// health) can leave the search glyph showing blue when tools are off.
-		const hasSiblingTools = getRegisteredSiblingTools(pi).length > 0;
+		const hasSiblingTools = getRegisteredIn(pi, SIBLING_TOOL_NAMES).length > 0;
 		if (hasSiblingTools && !isBrowserEnabled(pi)) {
 			ctx.ui.setStatus("search", "○ searxng");
 		}

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

@@ -0,0 +1,126 @@
+# Choosing a Backend
+
+A short decision doc: when to reach for a stealth backend at all, when
+to use the shipped Camoufox template specifically, and what the
+contract looks like if you implement your own. For the install flow,
+see [`README.md`](./README.md). For the architecture, see the
+"Stealth backends (user-managed)" section of
+[`packages/pi-lean-portal/AGENTS.md`](../../AGENTS.md).
+
+## When to use a stealth backend at all
+
+**Usually: don't.** The four shipped backends (`chromium`, `firefox`,
+`chromium-py`, `firefox-py`) are faster, have better ARIA-tree parity,
+need no per-engine venv, and need no binary fetch. Reach for a stealth
+backend only when:
+
+- The target site runs bot detection that blocks the shipped
+  Chromium/Firefox (Cloudflare Turnstile, Datadome, PerimeterX, etc.
+  that fingerprint the browser binary), **and**
+- The `bot-detection` guide + a real User-Agent + cookie persistence
+  (named profiles) are not enough to get past the challenge.
+
+Most sites do not need it. The cost is real: a ~100 MB binary fetch, a
+dedicated venv, slower humanized input, and more moving parts to keep
+working across engine version bumps. Treat stealth as a last resort,
+not a default.
+
+## When to use Camoufox specifically
+
+[Camoufox](https://github.com/daijro/camoufox) is the **shipped,
+tested template** — there is a reference `bridge.py` under
+[`camoufox-py/`](./camoufox-py/), and a generic discovery runner at
+`__tests__/run-contributed-suites.test.ts` auto-discovers any
+installed user backend and runs the shared contract + persistence +
+parity + quirks introspection suites against it. Properties:
+
+- **Firefox-based** — a patched Firefox binary, so it shares Firefox's
+  ARIA-tree shape with the shipped `firefox` / `firefox-py` backends.
+- **Fingerprint injected at browser launch** — via
+  `camoufox.NewBrowser(playwright, ...)`, not at context creation. This
+  is why Camoufox sets `_fingerprint_managed_context = True` and uses
+  standard `browser.new_context()` rather than a custom context factory.
+- **`mw:`-prefix main-world eval** — `_eval_prefix = "mw:"` routes
+  `page.evaluate` writes to the main world (Camoufox's isolated-world
+  stealth otherwise blocks them). The bridge also sets
+  `main_world_eval=True` in the `NewBrowser` kwargs.
+- **Wheel-based scroll** — `_scroll_via_wheel = True` uses
+  `page.mouse.wheel` instead of `window.scrollBy` eval (avoids
+  eval-write under isolated-world stealth).
+
+If you want a stealth backend and you do not have a strong reason to
+pick something else, use Camoufox via the template in
+[`camoufox-py/bridge.py`](./camoufox-py/bridge.py). The install flow is
+in [`README.md`](./README.md).
+
+## Implementing your own stealth backend
+
+The contract is the **quirks schema** — the set of class attributes on
+`PlaywrightBridge` documented in
+`backends/python-base/pi_browser_bridge/playwright_base.py` (and
+reproduced in [`README.md`](./README.md#quirks-schema-reference)). Set
+the flags your engine needs as class attributes on a subclass, and
+override the launch hook that matches how your engine owns Playwright.
+There are two lifecycle patterns:
+
+### Pattern 1 — Engine accepts an external Playwright instance
+
+The engine exposes a constructor like `NewBrowser(playwright, ...)`
+that takes an already-running Playwright and returns a browser. **Do
+not** override `_ensure_playwright` — let the base class own the
+Playwright lifecycle. Override **`_launch_browser` only**, handing the
+base-supplied `playwright` to the engine. (Camoufox is the example of
+this pattern; see `camoufox-py/bridge.py`.)
+
+### Pattern 2 — Engine owns its own Playwright instance
+
+The engine brings its own Playwright (e.g. it wraps a context manager
+that starts Playwright internally). Override **`_ensure_playwright`**
+and **`_maybe_stop_playwright`** to delegate to the engine's context
+manager, and **do not call super** in those overrides — the base
+implementation would start a redundant Playwright. The base class's
+`_newBrowserContext` still drives the page through the standard
+`BrowserContext` / `Page` path, so navigation, snapshot, click, etc.
+keep working unchanged.
+
+In both patterns, read user launch options from
+`self.plugin_config.get("launch", {})` (forwarded via the `browser.init`
+RPC from `settings.json` `config.launch`), and surface a helpful
+`_install_hint` string so a missing binary tells the user what to run
+rather than failing opaquely.
+
+## Trade-offs
+
+- **~100 MB binary fetch** per engine, plus the engine's pip package.
+- **Per-engine venv** at `user-backends/<name>-py/.venv/` — each
+  stealth backend maintains its own dependencies.
+- **Slower humanized input** — `humanize=True` (Camoufox default) uses
+  bezier-curved mouse motion; fine for bot-detection sites, slower for
+  bulk automation.
+- **`xvfb` on Linux** for `headless='virtual'` modes; true headless
+  (`headless=True`) works without it.
+- **Back-navigation may be limited on patched binaries.** Camoufox
+  needs `enable_cache=True` (the template's default) to restore session
+  history so `do_go_back()` works. Some patched Firefox binaries have a
+  binary-level back-navigation bug that requires a `document.referrer`
+  workaround; Camoufox does not need it with `enable_cache=True`. If
+  your engine disables the bfcache and `do_go_back` misbehaves, fall
+  back to navigating to the `document.referrer`.
+- **Version drift** — patched binaries are pinned to specific engine
+  releases. A binary version bump can change which quirks are needed
+  (e.g. an `isMobile` rejection gets fixed, or a `NewContext` path
+  starts working). Re-validate your bridge on engine releases; the
+  quirks flags degrade gracefully (default off).
+
+## What this is not
+
+- **Not a plugin marketplace.** The extension never downloads or
+  executes stealth backends automatically. `user-backends/` is trusted
+  user code — you wrote or audited it.
+- **Not shipped in the npm tarball.** The templates live in the source
+  repo under `contributed/`; `docs/` is excluded from
+  `package.json` `files`. You need the git repo (or a copy of the
+  files) to install a stealth backend.
+- **Not in the default fallback list.** Stealth backends are loaded
+  only when explicitly listed in `browser.plugins`. A fresh install
+  never validates plugins the user never asked for.