pi-ui-observer

A global Pi package for evidence-first web UI inspection. Capture a real screenshot and accessibility snapshot, inspect console/network failures and computed layout, and check responsive horizontal overflow without adding code to each web app.

Install and start

Requires Pi with extension and MCP support, Node.js >=22.19, and Chrome/Chromium (or a compatible installed browser). Install once at user scope:

pi install npm:pi-ui-observer@0.1.0
# Alternatively: pi install git:github.com/hoanganhdev57/pi-ui-observer@v0.1.0

Start Pi in any project and start that project's dev server separately. Then:

/ui status
/ui connect isolated http://127.0.0.1:3000
/ui inspect
/ui screenshot
/ui audit
/ui disconnect

Pi also exposes ui_current_page, ui_snapshot, ui_screenshot, ui_styles, ui_console, ui_network, and ui_audit as model-callable tools. ui_screenshot returns an image to Pi plus a local artifact path. /ui audit takes screenshots at 1280, 768, 414, 375, and 320 CSS-pixel widths in isolated mode, flags horizontal overflow and console/network errors, and restores the original viewport. Screenshots are stored in a private per-process pi-ui-observer-* directory in the system temporary directory and may contain private page data; remove them when no longer needed.

These checks collect evidence, not an automatic design verdict. Ask Pi to compare the screenshots and semantic snapshot with your project's design specification. The included ui-verification skill describes that workflow. A screenshot alone never produces a visual PASS.

Browser modes

BrowserTools can see data in your actual Chrome session. Do not attach a personal tab unless you intend to share its contents with Pi. The first /ui connect current may download the pinned MCP server through npx; review the dependency before connecting. /ui disconnect unregisters it.

Security defaults and limitations

• Page navigation from /ui connect is limited to localhost and 127.0.0.1 by default. Isolated mode blocks outbound HTTP requests to other hosts and blocks new document navigations/popups after the initial page. This can block third-party assets, APIs, app redirects, or popup workflows; blocked requests are reported in the audit. Use the initial URL for each isolated observation run.
• Chrome CDP and current-tab connections require user confirmation. A CDP endpoint must be loopback, and an attached tab outside the allowlist is rejected by the ui_* adapter.
• Network/console text is redacted for common token patterns before reaching the model. This is best-effort: screenshots, page text, URLs, and third-party MCP tools can still expose sensitive material.
• This read-only v0.1 does not provide working click/fill/upload tools, automatic watch mode, native WebView2 capture, or a machine-verified design comparison. Interaction and watch mode are reserved for later releases.
• The package itself adds no telemetry. Third-party browser components may have independent privacy policies.

Read SECURITY.md before connecting a real browser session. Pi packages and MCP servers execute with your user permissions.

Development

npm ci
npm run ci
npm pack --dry-run

The repository's tests include a real local Chrome integration test when a Chrome executable is detected. Tests skip browser integration when none is installed. pi-package makes the npm distribution eligible for Pi's package gallery; gallery indexing may take time and must be checked separately from successful npm publication.