frontend-perception-engine 0.1.1__tar.gz → 0.2.0__tar.gz

{frontend_perception_engine-0.1.1 → frontend_perception_engine-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frontend-perception-engine
-Version: 0.1.1
+Version: 0.2.0
 Summary: Frontend perception engine with optional CRG-powered navigation hints for Browser Use.
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -8,6 +8,7 @@ Requires-Dist: browser-use>=0.13.3
 Requires-Dist: code-review-graph>=2.3.6
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: mcp>=1.0.0
+Requires-Dist: pillow>=10.0.0
 Provides-Extra: aws
 Requires-Dist: boto3>=1.35.0; extra == "aws"
 
@@ -55,12 +56,25 @@ Your coding agent (Cursor/Claude/Codex) remains the brain.
 
 ### Install
 
+Both PyPI names install the same MCP server:
+
+| Package | Install |
+|---------|---------|
+| `frontend-perception-engine` | `pip install frontend-perception-engine` |
+| `frontend-mcp` (alias) | `pip install frontend-mcp` |
+
 Recommended (quiet output + next steps):
 
 ```bash
 uvx --from frontend-perception-engine frontend-perception-install
 ```
 
+Or the shorter alias name:
+
+```bash
+uvx --from frontend-mcp frontend-mcp-install
+```
+
 With Chromium for Browser Use:
 
 ```bash
@@ -97,6 +111,8 @@ Using `uvx` (no local install in current environment):
 
 ```bash
 uvx --from frontend-perception-engine frontend-perception-mcp
+# or
+uvx --from frontend-mcp frontend-mcp
 ```
 
 ### Cursor MCP config

{frontend_perception_engine-0.1.1 → frontend_perception_engine-0.2.0}/README.md

@@ -42,12 +42,25 @@ Your coding agent (Cursor/Claude/Codex) remains the brain.
 
 ### Install
 
+Both PyPI names install the same MCP server:
+
+| Package | Install |
+|---------|---------|
+| `frontend-perception-engine` | `pip install frontend-perception-engine` |
+| `frontend-mcp` (alias) | `pip install frontend-mcp` |
+
 Recommended (quiet output + next steps):
 
 ```bash
 uvx --from frontend-perception-engine frontend-perception-install
 ```
 
+Or the shorter alias name:
+
+```bash
+uvx --from frontend-mcp frontend-mcp-install
+```
+
 With Chromium for Browser Use:
 
 ```bash
@@ -84,6 +97,8 @@ Using `uvx` (no local install in current environment):
 
 ```bash
 uvx --from frontend-perception-engine frontend-perception-mcp
+# or
+uvx --from frontend-mcp frontend-mcp
 ```
 
 ### Cursor MCP config

{frontend_perception_engine-0.1.1 → frontend_perception_engine-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "frontend-perception-engine"
-version = "0.1.1"
+version = "0.2.0"
 description = "Frontend perception engine with optional CRG-powered navigation hints for Browser Use."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -9,6 +9,7 @@ dependencies = [
   "code-review-graph>=2.3.6",
   "python-dotenv>=1.0.0",
   "mcp>=1.0.0",
+  "pillow>=10.0.0",
 ]
 
 [project.scripts]

{frontend_perception_engine-0.1.1 → frontend_perception_engine-0.2.0}/src/frontend_perception_engine.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frontend-perception-engine
-Version: 0.1.1
+Version: 0.2.0
 Summary: Frontend perception engine with optional CRG-powered navigation hints for Browser Use.
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -8,6 +8,7 @@ Requires-Dist: browser-use>=0.13.3
 Requires-Dist: code-review-graph>=2.3.6
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: mcp>=1.0.0
+Requires-Dist: pillow>=10.0.0
 Provides-Extra: aws
 Requires-Dist: boto3>=1.35.0; extra == "aws"
 
@@ -55,12 +56,25 @@ Your coding agent (Cursor/Claude/Codex) remains the brain.
 
 ### Install
 
+Both PyPI names install the same MCP server:
+
+| Package | Install |
+|---------|---------|
+| `frontend-perception-engine` | `pip install frontend-perception-engine` |
+| `frontend-mcp` (alias) | `pip install frontend-mcp` |
+
 Recommended (quiet output + next steps):
 
 ```bash
 uvx --from frontend-perception-engine frontend-perception-install
 ```
 
+Or the shorter alias name:
+
+```bash
+uvx --from frontend-mcp frontend-mcp-install
+```
+
 With Chromium for Browser Use:
 
 ```bash
@@ -97,6 +111,8 @@ Using `uvx` (no local install in current environment):
 
 ```bash
 uvx --from frontend-perception-engine frontend-perception-mcp
+# or
+uvx --from frontend-mcp frontend-mcp
 ```
 
 ### Cursor MCP config

{frontend_perception_engine-0.1.1 → frontend_perception_engine-0.2.0}/src/frontend_perception_engine.egg-info/SOURCES.txt

@@ -30,6 +30,7 @@ src/navigation/mcp/scan_registry.py
 src/navigation/mcp/server.py
 src/navigation/mcp/session_store.py
 src/navigation/mcp/tools.py
+src/navigation/mcp/visual_response.py
 src/navigation/perception/__init__.py
 src/navigation/perception/artifacts.py
 src/navigation/perception/auth_gate.py
@@ -52,4 +53,7 @@ src/navigation/perception/scripted_actions.py
 src/navigation/perception/state_manager.py
 src/navigation/perception/verification.py
 src/navigation/perception/virtual_scroll.py
+src/navigation/perception/visual_capture.py
+src/navigation/perception/visual_diff.py
+src/navigation/perception/visual_insights.py
 src/navigation/perception/websocket_observer.py

{frontend_perception_engine-0.1.1 → frontend_perception_engine-0.2.0}/src/frontend_perception_engine.egg-info/requires.txt

@@ -2,6 +2,7 @@ browser-use>=0.13.3
 code-review-graph>=2.3.6
 python-dotenv>=1.0.0
 mcp>=1.0.0
+pillow>=10.0.0
 
 [aws]
 boto3>=1.35.0

{frontend_perception_engine-0.1.1 → frontend_perception_engine-0.2.0}/src/navigation/cli/install.py

@@ -45,22 +45,47 @@ class _Spinner:
 			time.sleep(0.1)
 
 
-def _build_pip_command(*, upgrade: bool, editable: str | None) -> list[str]:
-	cmd = [
-		sys.executable,
-		'-m',
-		'pip',
-		'install',
-		'-q',
-		'--disable-pip-version-check',
-	]
-	if upgrade:
-		cmd.append('--upgrade')
+def _pip_available() -> bool:
+	result = subprocess.run(
+		[sys.executable, '-m', 'pip', '--version'],
+		capture_output=True,
+	)
+	return result.returncode == 0
+
+
+def _build_install_command(*, upgrade: bool, editable: str | None) -> list[str]:
+	target: list[str]
 	if editable is not None:
-		cmd.extend(['-e', editable])
+		target = ['-e', editable]
 	else:
-		cmd.append(PACKAGE_NAME)
-	return cmd
+		target = [PACKAGE_NAME]
+
+	if _pip_available():
+		cmd = [
+			sys.executable,
+			'-m',
+			'pip',
+			'install',
+			'-q',
+			'--disable-pip-version-check',
+		]
+		if upgrade:
+			cmd.append('--upgrade')
+		cmd.extend(target)
+		return cmd
+
+	uv = shutil.which('uv')
+	if uv is not None:
+		cmd = [uv, 'pip', 'install', '-q']
+		if upgrade:
+			cmd.append('--upgrade')
+		cmd.extend(target)
+		return cmd
+
+	raise SystemExit(
+		'No installer available. Install pip or uv, or use:\n'
+		'  uvx --from frontend-perception-engine frontend-perception-mcp\n',
+	)
 
 
 def _build_browser_install_command() -> list[str]:
@@ -102,7 +127,9 @@ def _print_success(*, with_browser: bool) -> None:
 	sys.stdout.write('    frontend-perception-mcp\n\n')
 	sys.stdout.write('  Or with uvx (no global install):\n')
 	sys.stdout.write('    uvx --from frontend-perception-engine frontend-perception-mcp\n\n')
-	sys.stdout.write('  Cursor MCP config:\n')
+	sys.stdout.write('  Or shorter PyPI name:\n')
+	sys.stdout.write('    uvx --from frontend-mcp frontend-mcp\n\n')
+	sys.stdout.write('  Cursor MCP config (either name):\n')
 	sys.stdout.write('    {\n')
 	sys.stdout.write('      "mcpServers": {\n')
 	sys.stdout.write('        "frontend-perception": {\n')
@@ -111,6 +138,7 @@ def _print_success(*, with_browser: bool) -> None:
 	sys.stdout.write('        }\n')
 	sys.stdout.write('      }\n')
 	sys.stdout.write('    }\n')
+	sys.stdout.write('\n  Alias package: pip install frontend-mcp  →  frontend-mcp / frontend-mcp-install\n')
 	if with_browser:
 		sys.stdout.write('\n  Chromium is ready for Browser Use.\n')
 	sys.stdout.flush()
@@ -151,7 +179,16 @@ def main(argv: Sequence[str] | None = None) -> None:
 		editable_path = None
 		label = 'Installing frontend-perception-engine'
 
-	_run_quiet(_build_pip_command(upgrade=args.upgrade, editable=editable_path), label=label)
+	if (
+		not args.upgrade
+		and editable_path is None
+		and _installed_version() is not None
+		and not _pip_available()
+	):
+		_print_success(with_browser=False)
+		return
+
+	_run_quiet(_build_install_command(upgrade=args.upgrade, editable=editable_path), label=label)
 
 	if args.with_browser:
 		browser_cmd = _build_browser_install_command()

frontend_perception_engine-0.2.0/src/navigation/mcp/diff.py

@@ -0,0 +1,68 @@
+"""Compare two observation snapshots by scan_id."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from navigation.perception.visual_diff import VisualDiffResult, diff_screenshot_files
+
+
+def _blocking_issues(obs: dict[str, Any]) -> list[str]:
+	di = obs.get('dev_insights') or {}
+	summary = di.get('summary') or {}
+	blocking = list(summary.get('blocking_issues') or [])
+	visual = obs.get('visual_insights') or {}
+	blocking.extend(visual.get('blocking') or [])
+	return blocking
+
+
+def _visual_issues_delta(before: dict[str, Any], after: dict[str, Any]) -> dict[str, list[str]]:
+	b_vis = set((before.get('visual_insights') or {}).get('blocking') or [])
+	a_vis = set((after.get('visual_insights') or {}).get('blocking') or [])
+	return {
+		'new_visual_blocking': sorted(a_vis - b_vis),
+		'removed_visual_blocking': sorted(b_vis - a_vis),
+	}
+
+
+def diff_observations(
+	before: dict[str, Any],
+	after: dict[str, Any],
+	*,
+	artifacts_dir: Path | None = None,
+	scan_id_before: str = '',
+	scan_id_after: str = '',
+) -> dict[str, Any]:
+	b_block = set(_blocking_issues(before))
+	a_block = set(_blocking_issues(after))
+	b_dom = str(before.get('dom_text') or '')
+	a_dom = str(after.get('dom_text') or '')
+	excerpt_len = 500
+	visual_delta = _visual_issues_delta(before, after)
+
+	result: dict[str, Any] = {
+		'url_before': before.get('url') or '',
+		'url_after': after.get('url') or '',
+		'url_changed': (before.get('url') or '') != (after.get('url') or ''),
+		'dom_text_changed': b_dom != a_dom,
+		'new_blocking_issues': sorted(a_block - b_block),
+		'removed_blocking_issues': sorted(b_block - a_block),
+		'dom_excerpt_before': b_dom[:excerpt_len],
+		'dom_excerpt_after': a_dom[:excerpt_len],
+		**visual_delta,
+		'visual_diff': None,
+	}
+
+	before_shot = before.get('annotated_screenshot_path') or before.get('screenshot_path')
+	after_shot = after.get('annotated_screenshot_path') or after.get('screenshot_path')
+	if artifacts_dir and before_shot and after_shot:
+		prefix = f'{scan_id_before}_vs_{scan_id_after}'.replace('/', '_')[:80]
+		vd: VisualDiffResult = diff_screenshot_files(
+			before_shot,
+			after_shot,
+			artifacts_dir / 'diffs',
+			prefix=prefix,
+		)
+		result['visual_diff'] = vd.to_dict()
+
+	return result

{frontend_perception_engine-0.1.1 → frontend_perception_engine-0.2.0}/src/navigation/mcp/envelope.py

@@ -38,13 +38,22 @@ def envelope_json(**kwargs: Any) -> str:
 
 
 def agent_summary_from_observation(obs_dict: dict[str, Any]) -> dict[str, Any]:
-    """Compact summary for host agent reasoning (no planning hints)."""
-    di = obs_dict.get("dev_insights") or {}
-    summary = di.get("summary") or {}
-    page_meta = di.get("page_meta")
-    return {
-        "blocking": summary.get("blocking_issues") or [],
-        "advisory": summary.get("advisory_issues") or [],
-        "page_meta": page_meta,
-        "degraded": list(obs_dict.get("degraded") or []) + list(di.get("degraded") or []),
-    }
+	"""Compact summary for host agent reasoning (no planning hints)."""
+	di = obs_dict.get('dev_insights') or {}
+	summary = di.get('summary') or {}
+	page_meta = di.get('page_meta')
+	blocking = list(summary.get('blocking_issues') or [])
+	advisory = list(summary.get('advisory_issues') or [])
+	visual = obs_dict.get('visual_insights') or {}
+	for item in visual.get('blocking') or []:
+		if item not in blocking:
+			blocking.append(item)
+	for item in visual.get('advisory') or []:
+		if item not in advisory:
+			advisory.append(item)
+	return {
+		'blocking': blocking,
+		'advisory': advisory,
+		'page_meta': page_meta,
+		'degraded': list(obs_dict.get('degraded') or []) + list(di.get('degraded') or []),
+	}