browser-ctl 0.2.0__tar.gz → 0.2.2__tar.gz

{browser_ctl-0.2.0 → browser_ctl-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: browser-ctl
-Version: 0.2.0
+Version: 0.2.2
 Summary: Control your browser from the command line via a Chrome extension + WebSocket bridge
 Author-email: geb <853934146@qq.com>
 License-Expression: MIT
@@ -47,8 +47,9 @@ Dynamic: license-file
 pip install browser-ctl
 
 bctl go https://github.com
-bctl click "a.search-button"
-bctl type "input[name=q]" "browser-ctl"
+bctl snapshot                        # List interactive elements → e0, e1, e2, …
+bctl click e3                        # Click by ref — no CSS selector needed
+bctl type e5 "browser-ctl"          # Type into element by ref
 bctl press Enter
 bctl screenshot results.png
 ```
@@ -74,11 +75,12 @@ Tools like [browser-use](https://github.com/browser-use/browser-use), [Playwrigh
 
 browser-ctl is purpose-built for AI agent workflows:
 
+- **Snapshot-first workflow** — `bctl snapshot` lists interactive elements as `e0`, `e1`, … then operate by ref (`bctl click e3`) — no CSS selector guessing
 - **Tool-calling ready** — every command is a single shell call returning structured JSON, perfect for function-calling / tool-use patterns
 - **Built-in AI skill** — ships with `SKILL.md` that teaches AI agents (Cursor, OpenCode, etc.) the full command set and best practices
 - **Real browser = real access** — your LLM can operate on authenticated pages (Gmail, Jira, internal tools) without credential management
-- **Deterministic output** — JSON responses with CSS-selector-based queries, no vision model needed for most tasks
-- **Minimal token cost** — `bctl select "a.link" -l 5` returns structured data in one call vs multi-step screenshot → vision → parse loops
+- **Deterministic output** — JSON responses with element refs or CSS selectors, no vision model needed for most tasks
+- **Minimal token cost** — `bctl snapshot` + `bctl click e5` vs multi-step screenshot → vision → parse loops
 
 ```bash
 # Install the AI skill for Cursor IDE in one command

{browser_ctl-0.2.0 → browser_ctl-0.2.2}/README.md

@@ -21,8 +21,9 @@
 pip install browser-ctl
 
 bctl go https://github.com
-bctl click "a.search-button"
-bctl type "input[name=q]" "browser-ctl"
+bctl snapshot                        # List interactive elements → e0, e1, e2, …
+bctl click e3                        # Click by ref — no CSS selector needed
+bctl type e5 "browser-ctl"          # Type into element by ref
 bctl press Enter
 bctl screenshot results.png
 ```
@@ -48,11 +49,12 @@ Tools like [browser-use](https://github.com/browser-use/browser-use), [Playwrigh
 
 browser-ctl is purpose-built for AI agent workflows:
 
+- **Snapshot-first workflow** — `bctl snapshot` lists interactive elements as `e0`, `e1`, … then operate by ref (`bctl click e3`) — no CSS selector guessing
 - **Tool-calling ready** — every command is a single shell call returning structured JSON, perfect for function-calling / tool-use patterns
 - **Built-in AI skill** — ships with `SKILL.md` that teaches AI agents (Cursor, OpenCode, etc.) the full command set and best practices
 - **Real browser = real access** — your LLM can operate on authenticated pages (Gmail, Jira, internal tools) without credential management
-- **Deterministic output** — JSON responses with CSS-selector-based queries, no vision model needed for most tasks
-- **Minimal token cost** — `bctl select "a.link" -l 5` returns structured data in one call vs multi-step screenshot → vision → parse loops
+- **Deterministic output** — JSON responses with element refs or CSS selectors, no vision model needed for most tasks
+- **Minimal token cost** — `bctl snapshot` + `bctl click e5` vs multi-step screenshot → vision → parse loops
 
 ```bash
 # Install the AI skill for Cursor IDE in one command

{browser_ctl-0.2.0 → browser_ctl-0.2.2}/browser_ctl/cli.py

@@ -421,8 +421,18 @@ def handle_serve(args):
 
 
 def _get_extension_source_dir() -> str | None:
-	"""Locate the extension source directory (from project root)."""
+	"""Locate the extension source directory.
+
+	Looks in two places:
+	1. Inside the package (works for pip install)
+	2. Project root (works for editable/dev install)
+	"""
 	pkg_dir = os.path.dirname(os.path.abspath(__file__))
+	# 1. Bundled inside the package (pip install browser-ctl)
+	ext_dir = os.path.join(pkg_dir, "extension")
+	if os.path.isdir(ext_dir) and os.path.exists(os.path.join(ext_dir, "manifest.json")):
+		return ext_dir
+	# 2. Project root (pip install -e . / dev checkout)
 	project_root = os.path.dirname(pkg_dir)
 	ext_dir = os.path.join(project_root, "extension")
 	if os.path.isdir(ext_dir) and os.path.exists(os.path.join(ext_dir, "manifest.json")):