{
  "markdown": "<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/nuttaruj/rolepod-uiproof/main/docs/assets/rolepod-uiproof-banner.png\" alt=\"Rolepod uiproof — Browser Verification\" width=\"100%\" />\n</p>\n\n# rolepod-uiproof\n\n**rolepod-uiproof gives Claude Code, Cursor, Codex CLI, Gemini CLI, and Antigravity (CLI + IDE) a real browser/mobile driver — so the AI can actually click through your UI, audit accessibility, measure Core Web Vitals, check console errors, inspect network requests, diff screenshots, audit on-page SEO, and scaffold e2e tests instead of guessing.**\n\nOne MCP server, one tool surface, nine skills you invoke from chat. Web is production-ready via Playwright; iOS and Android use Appium (same client as alumnium — needs a local Appium daemon + simulator/emulator, or a real device). No internal LLM — your Lead agent drives every action.\n\n**v0.8 sharpens `visual_diff` for animated UIs** — `settle` (default on) scrolls + freezes the page so scroll-reveal / lazy content is captured instead of baselined blank; `selector` scopes a diff to one element; dimension mismatches degrade gracefully; plus a new `extract_computed_style` tool that reads an element's computed CSS for pixel-faithful redesign. 33 tools total (24 atomic + 9 composite). v0.7 added the measurement surface — Core Web Vitals, page-weight budgets, and on-page SEO. New in v0.7: `/measure-cwv` (LCP/INP/CLS via PerformanceObserver), `/audit-page-budget` (HAR-classified byte budget with third-party tagging), `/audit-seo` (DOM-based on-page SEO: title, meta, h1, lang, viewport, canonical, robots, OG/Twitter Cards, JSON-LD, hreflang, favicon). v0.5 had completed the UI verification surface (interaction + capture).\n\n## What it helps with\n\n- **Verify a UI change in seconds.** `/verify-ui` opens a real browser, runs your steps, checks your assertions, saves a screenshot + replay bundle (optionally HAR + video + trace + console logs).\n- **Gate merges on \"no regressions during this flow\".** `/check-errors` runs a flow with strict `no_console_errors` + `no_failed_requests` assertions baked in. PR-gate or post-merge smoke check.\n- **Catch a11y regressions before merge.** `/audit-a11y` runs axe-core against WCAG-A / AA / AAA and returns issues grouped by severity, with WCAG references and fix links.\n- **Lock down the visual contract.** `/visual-diff` captures a screenshot and compares against a named baseline under `./.rolepod-uiproof/baselines/`. First call seeds; subsequent calls diff. By default it settles the page first (scrolls to trigger reveal/lazy content + freezes animations) so reveal-heavy pages are captured fully-rendered; pass `selector` to diff a single element.\n- **Turn an interactive verify run into a real test file.** `/scaffold-e2e` transcribes a replay bundle into Playwright Test, Vitest+Playwright, or pytest+selenium — with first-class codegen for every step + expect kind. Mobile targets get Maestro YAML flows (`framework: \"maestro\"`) with TC-ID traceability in filenames, headers, and tags.\n- **Reproduce + minimize a bug deterministically.** `/verify-ui` with `mode: \"reproduce\"` runs ddmin step-elimination to find the shortest still-reproducing sequence.\n- **Discover flows on an app you have no source for.** `/discover-flows` crawls a running app read-only (same-origin, hard budget caps), maps pages/links/forms, and proposes a TC-ID/P1-P2 test-case table whose step sequences feed `/verify-ui` unchanged. Destructive-looking actions are flagged, never executed.\n\n## The nine skills\n\n| Skill | Wraps | What it does |\n|---|---|---|\n| `/verify-ui` | `verify_ui_flow` | Drive a session through steps, evaluate assertions (incl. console errors / failed requests / specific request made / response status), save evidence (screenshot / console / HAR / video / trace / a11y_tree) + replay bundle. `mode: assert` or `reproduce` with optional ddmin minimization. |\n| `/check-errors` | `verify_ui_flow` | Thin wrapper with strict `no_console_errors` + `no_failed_requests` baked in. Use as PR-gate or post-merge smoke. |\n| `/audit-a11y` | `audit_a11y` | axe-core audit at WCAG-A / AA / AAA. `scope: \"page\"` or `scope: { ref }`. Markdown or JSON report. |\n| `/visual-diff` | `visual_diff` | Pixel diff against a named baseline. Auto-seeds on first call. Configurable threshold + pixelmatch sensitivity. `settle` (default on) scrolls + freezes the page so scroll-reveal/lazy content is captured; `selector` scopes the diff to one element; size mismatches degrade gracefully (overlap diff + deltas, not a hard error). |\n| `/scaffold-e2e` | `scaffold_e2e` | Generate a runnable test file from a scenario + optional replay bundle. Four target frameworks — three web + Maestro YAML flows for mobile (TC-ID carried in filename/header/tags). v0.5 codegen handles every step + expect kind. |\n| `/measure-cwv` | `measure_cwv` | Measure Core Web Vitals (LCP / INP / CLS) on a live page via PerformanceObserver. Verdict per web.dev good / needs-improvement / poor bands. Chromium-only. |\n| `/audit-page-budget` | `audit_page_budget` | HAR-classified byte budget per asset category (js/css/image/font) with third-party tagging. Compares against declared budget, returns graduated pass/warn/fail. |\n| `/audit-seo` | `audit_seo` | On-page SEO check via DOM inspection: title, meta description, h1, lang, viewport, canonical, robots, OG + Twitter Cards, JSON-LD validity, hreflang, favicon. |\n| `/discover-flows` | `discover_flows` | Black-box flow discovery: crawl a running app (GET-only, same-origin, hard budget caps), derive candidate flows + a proposed TC-ID/P1-P2 test-case table. Flow steps are `/verify-ui`-compatible; destructive actions flagged, never executed; GET-form interaction opt-in with dummy data. |\n\nEvery skill is **single-backend** (D-024) — it calls the rolepod-uiproof server and only the rolepod-uiproof server. If the server is unavailable, the skill fails with a clear diagnostic. Multi-backend routing belongs in the parent [`rolepod`](https://github.com/nuttaruj/rolepod) plugin's phase skills, not here.\n\n## Standalone vs Combined\n\n`rolepod-uiproof` works either as a **standalone** browser MCP for any project, or **combined** with the [`rolepod`](https://github.com/nuttaruj/rolepod) parent plugin (v2.7+) where it becomes the Verify phase provider for UI artifacts.\n\n**Standalone** (default): use the 9 skills directly as atomic browser tools. Evidence saved under `./.rolepod-uiproof/artifacts/<run>/` with a `manifest.json` per Extension Protocol v1.\n\n**Combined with rolepod parent**: when the parent's SessionStart hook drops the marker file `<git-root>/.rolepod/parent-active` (single line of content = the protocol version, e.g. `v1`), uiproof writes evidence to `<git-root>/.rolepod/evidence/<ts>-rolepod-uiproof-<skill>/` instead, where parent's `check-work` skill auto-aggregates manifests into the verify report. The marker is re-detected per run, so a marker the parent writes after this server has already started is still honoured; no env-var, no daemon. To force combined mode without a parent session: `mkdir -p .rolepod && echo v1 > .rolepod/parent-active`. No skill changes — same 33 tools, same 9 skills, smarter routing.\n\n**Offline / registry-blocked machines**: the spawn configs fetch `@rolepod/uiproof` via `npx`, which needs npm-registry access. On an air-gapped or registry-blocked host, install once with `npm i -g @rolepod/uiproof@0.20.0` and set the MCP `command` to the global `rolepod-uiproof` binary (drop the `npx` / `-y` args) so no fetch is required at spawn time.\n\n**First launch after install or update: the `npm audit` trap.** Every new version is a fresh `npx` cache entry, and a cold `npx` install runs `npm audit` against the registry's bulk-advisory endpoint — measured at 190-320 s on 2026-09-04, while the actual download + extract of the tree takes 6-9 s. That blows every MCP client's startup timeout; Claude Code reports `Failed to connect — CONNECTION_CLOSED` and caches the failure for ~15 minutes, so the *next* session fails too even though the install finished in the background. Since 0.20.0 every shipped spawn config sets `npm_config_audit=false` and `npm_config_fund=false` in the server's `env`, which brings the cold start down to seconds (the flags cannot be passed in the `npx` args — npx treats leading flags as its own usage error). If you hand-write a spawn config, copy that `env` block from the snippets below. To pre-warm anyway, before opening an agent session:\n\n```bash\nnpm_config_audit=false npx -y @rolepod/uiproof@0.20.0 --help\n```\n\nor use the global-binary spawn config above, which never fetches at launch. Running the server from inside a checkout of *this* repo is a separate trap: `npx` sees the local `package.json` with the same name and version, skips the registry, and fails with `rolepod-uiproof: command not found` — use the repo's own `.mcp.json` (`node dist/bin/rolepod-uiproof.js`) there instead.\n\n**Artifacts from authenticated sessions are sensitive.** uiproof redacts `Cookie`, `Set-Cookie` and `Authorization` headers (and the structured cookie lists) from both `network.har` and `trace.zip` when the session closes, so neither file carries the session any more. Bodies are not redacted: the HAR embeds response bodies and the trace carries DOM snapshots and screenshots, so whatever an authenticated page rendered is still in there. Tool results that surface these paths carry a `credentials_note` / `har_note` reminder. Share them only with people cleared to see those pages. **Authenticated runs without re-logging in:** log in (or open a one-time link) once, call `browser_save_state` to write a Playwright storageState JSON, then pass that path as `storage_state` to later `browser_open` calls — reusable across runs and after `browser_close`. That state file IS the session; keep it out of issues, PRs, and shared drives, and delete it when done.\n\n**Headless Chromium presents a desktop Chrome user agent.** Playwright's headless shell announces itself as `HeadlessChrome/<v>`, and edge / WAF rules on real hosts key on that token — observed as authenticated wp-admin GETs succeeding while the first POST (a plugin upload) got a bare `403` from nginx, with the identical flow passing under a desktop UA. `browser_open` now strips the marker from the browser's own UA string (the Chrome version stays whatever Chromium is bundled, nothing hand-maintained). Pass `user_agent` to override it — including a `HeadlessChrome/…` string if you want the honest marker back, e.g. so analytics bot filters keep excluding audit runs. Client-Hint brands (`Sec-CH-UA`) are not rewritten. Firefox and WebKit carry no marker and are untouched.\n\n**Cheap refs on big pages.** A full `browser_snapshot` of an admin dashboard (WordPress wp-admin's tree is roughly 10k tokens, the sidebar alone ~300 nodes) is a lot to pay per click. `browser_find { query, role?, limit? }` snapshots server-side and returns only the ranked matches — `{ref, role, name, value, exact}`, exact name/value matches first, then substrings — and `browser_wait_for { kind: \"ref_exists\" }` now returns the same `matches` for the element it waited on. Both re-issue refs, so the ref that comes back is valid for the next `browser_click` / `browser_type` / `browser_hover` with no snapshot in between.\n\n| Install | Unlocks |\n|---|---|\n| uiproof alone | Browser test, a11y audit, visual diff, e2e scaffold, error gate |\n| uiproof + rolepod parent | + verify-phase aggregation, evidence handoff to `check-work` |\n\nThe `manifest.json` is written in BOTH modes, so installing the parent later still lets historic artifacts get picked up. Baselines for `/visual-diff` always live in `./.rolepod-uiproof/baselines/` regardless of mode — they are user-curated configuration, not per-run evidence. The evidence/artifacts root self-ignores in git: on its first write uiproof drops a `.gitignore` (`*`) there, so a `git add -A` in your repo never sweeps transient screenshots + manifests into a commit. Baselines are left out of that ignore — commit them if you want a shared golden set.\n\n## Install\n\nPick your CLI. All install paths share the same MCP server (`@rolepod/uiproof` on npm) and the same skill set.\n\n### Claude Code (recommended)\n\n```bash\n# Install\nclaude plugin marketplace add nuttaruj/rolepod-uiproof\nclaude plugin install rolepod-uiproof@rolepod-uiproof\n\n# Update\nclaude plugin marketplace update rolepod-uiproof\nclaude plugin install rolepod-uiproof@rolepod-uiproof\n\n# Uninstall\nclaude plugin uninstall rolepod-uiproof@rolepod-uiproof\nclaude plugin marketplace remove rolepod-uiproof\n```\n\nThe plugin auto-registers all nine skills (`/verify-ui`, `/check-errors`, `/audit-a11y`, `/visual-diff`, `/scaffold-e2e`, `/measure-cwv`, `/audit-page-budget`, `/audit-seo`, `/discover-flows`) AND spawns the MCP server (`npx -y @rolepod/uiproof`) on session start.\n\n### Cursor IDE\n\nCursor's plugin marketplace is enterprise-only (Free / Pro plans cannot install marketplace plugins). For everyone else, drop the workspace MCP config:\n\n```bash\n# Per project — copy from this repo, or run:\nmkdir -p .cursor\ncurl -fsSL https://raw.githubusercontent.com/nuttaruj/rolepod-uiproof/main/.cursor/mcp.json -o .cursor/mcp.json\n\n# Or global (across every project)\nmkdir -p ~/.cursor\ncurl -fsSL https://raw.githubusercontent.com/nuttaruj/rolepod-uiproof/main/.cursor/mcp.json -o ~/.cursor/mcp.json\n```\n\nThen **fully restart Cursor** — MCP servers load only at startup. Verify under **Settings → MCP**.\n\nSkills are not auto-registered under Cursor (no unified plugin format for skills + MCP in one). The MCP tools are still available; invoke them by name in chat (`Use verify_ui_flow to …`).\n\n> **Teams / Enterprise:** add `https://github.com/nuttaruj/rolepod-uiproof` as a team marketplace under **Settings → Plugins** for one-click install with skills auto-registered.\n\n### Codex CLI\n\n```bash\n# Install\ncodex plugin marketplace add nuttaruj/rolepod-uiproof\ncodex plugin add rolepod-uiproof@rolepod-uiproof\n\n# Update\ncodex plugin marketplace upgrade rolepod-uiproof\ncodex plugin add rolepod-uiproof@rolepod-uiproof\n```\n\nCodex reads the plugin from `.agents/plugins/marketplace.json` + `.codex-plugin/plugin.json` in this repo. Skills install to `~/.codex/skills/` (Codex's plugin loader handles registration).\n\n### Gemini CLI\n\nInstall directly from the GitHub repo:\n\n```bash\n# Install\ngemini extensions install https://github.com/nuttaruj/rolepod-uiproof\n\n# Update\ngemini extensions update rolepod-uiproof\n\n# Disable / re-enable\ngemini extensions disable rolepod-uiproof\ngemini extensions enable rolepod-uiproof\n\n# Uninstall\ngemini extensions uninstall rolepod-uiproof\n```\n\nGemini CLI clones the repo into `~/.gemini/extensions/rolepod-uiproof/`, reads `gemini-extension.json` at the root, spawns the MCP server (`npx -y @rolepod/uiproof`), and auto-discovers all 9 skills from `skills/<name>/SKILL.md`. After install, **restart the CLI session** — Gemini loads extensions on startup, and `gemini extensions install` is not supported in interactive mode.\n\nVerify with `/extensions list` inside the CLI.\n\n### Antigravity (CLI + IDE)\n\nAntigravity reads from `~/.gemini/` but at different sub-paths than Gemini CLI — MCP config and skills must be wired manually.\n\n**Step 1 — Skills:**\n\n```bash\n# Copy uiproof skills into Antigravity's shared skills dir\nmkdir -p ~/.gemini/skills\ngit clone --depth 1 https://github.com/nuttaruj/rolepod-uiproof /tmp/rolepod-uiproof\ncp -r /tmp/rolepod-uiproof/skills/* ~/.gemini/skills/\nrm -rf /tmp/rolepod-uiproof\n```\n\nIf you already installed via Gemini CLI (`gemini extensions install`), symlink instead:\n\n```bash\nln -s ~/.gemini/extensions/rolepod-uiproof/skills/measure-cwv ~/.gemini/skills/measure-cwv\n# repeat for each of the 9 skills, or:\nfor d in ~/.gemini/extensions/rolepod-uiproof/skills/*/; do\n  ln -s \"$d\" ~/.gemini/skills/$(basename \"$d\")\ndone\n```\n\n**Step 2 — MCP server:**\n\nOpen Antigravity Settings → Customizations → **Open MCP Config** (or edit `~/.gemini/config/mcp_config.json` directly). Add the `rolepod-uiproof` entry to the `mcpServers` map:\n\n```json\n{\n  \"mcpServers\": {\n    \"rolepod-uiproof\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@rolepod/uiproof@0.20.0\"],\n      \"env\": { \"npm_config_audit\": \"false\", \"npm_config_fund\": \"false\" }\n    }\n  }\n}\n```\n\nRestart Antigravity. Verify the MCP server is connected via Settings → Customizations → MCP Servers panel.\n\n**Notes:**\n- Antigravity's `mcp_config.json` is shared across all Agy tools (CLI + IDE) — one config, both surfaces.\n- Skills are auto-discovered from `~/.gemini/skills/` — no manifest needed.\n- The 32 MCP tools surface in chat the same way as in Claude Code / Cursor / Codex.\n\n### Direct npm (any MCP-aware tool)\n\nUse this when your tool reads a standard `mcpServers` config (most non-CLI MCP clients):\n\n```json\n{\n  \"mcpServers\": {\n    \"rolepod-uiproof\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@rolepod/uiproof@0.20.0\"],\n      \"env\": { \"npm_config_audit\": \"false\", \"npm_config_fund\": \"false\" }\n    }\n  }\n}\n```\n\n32 MCP tools (22 `browser_*` atomics + `extract_computed_style` + 9 composites including `verify_ui_flow`, `audit_a11y`, `visual_diff`, `scaffold_e2e`, `extract_ui_state`, `measure_cwv`, `audit_page_budget`, `audit_seo`, `discover_flows`) will appear in your client. Skills are not surfaced via this path — call the tools by name.\n\n## Quick start\n\nAfter install, in your Claude Code / Cursor / Codex session:\n\n```\n/verify-ui https://example.com\n  steps: []\n  expect: text_visible \"Example Domain\", text_visible \"Learn more\"\n```\n\nReturns a `run_id`, `passed: true`, and a path under `./.rolepod-uiproof/artifacts/verify_<run_id>/`:\n\n```\n.rolepod-uiproof/artifacts/verify_20260524T101512_a1b2c3d4/\n├── final.png            screenshot at end of run\n└── replay.json          replay bundle — re-runnable via `npx @rolepod/uiproof replay …`\n```\n\nConvert that to a Playwright Test file:\n\n```\n/scaffold-e2e from .rolepod-uiproof/artifacts/verify_…/replay.json using playwright-test\n```\n\n## Verify your setup\n\n```bash\nnpx @rolepod/uiproof doctor\n```\n\n```\n✓ Node ≥20                       24.14.0\n✓ Playwright Chromium installed  ~/Library/Caches/ms-playwright\n✓ webdriverio (mobile client)\n✓ Appium (mobile server)         found via path install\n✓ Appium drivers                 uiautomator2, xcuitest\n• Appium server                  Not running at 127.0.0.1:4723 — auto-started on first mobile session\n✓ Xcode (iOS)                    /Applications/Xcode.app\n✓ iOS simulators                 4 available\n• Android SDK                    Set ANDROID_HOME — needed only for Android\n• Android devices (adb)          No emulator/device connected\n• SeleniumEngine (roadmap v0.4)  Not implemented — deferred to v0.4\n✓ Artifact root writable\n```\n\n`✓` = ready · `•` = optional / deferred · `✗` = blocker.\n\n## Mobile (iOS / Android)\n\nMobile is auto-provisioned the same way browsers are: the first `ios`/`android`\nsession installs the `webdriverio` client, Appium and the platform driver if\nmissing (into `~/.rolepod-uiproof/`, never your project) and starts the daemon\nfor you. Since 0.19 `webdriverio` is no longer an npm dependency of the\npackage — it was most of the cold-install weight and web never needs it. Or\nprovision ahead of time:\n\n```bash\nnpx @rolepod/uiproof install:mobile              # installs Appium + drivers now\nnpx @rolepod/uiproof install:mobile --checklist  # just print the manual steps\n```\n\nOnly two things can't be automated and stay manual:\n\n- **iOS** — Xcode + an iOS Simulator (macOS only). Verify: `xcrun simctl list devices`\n- **Android** — Android SDK with `ANDROID_HOME` set + a running emulator/device. Verify: `adb devices`\n\nEnvironment overrides: `APPIUM_HOST` / `APPIUM_PORT` / `APPIUM_BASE_PATH` point at\nan existing Appium server (a remote host disables auto-start);\n`ROLEPOD_NO_AUTO_APPIUM=1` turns auto-provisioning off entirely.\n\n## What's inside\n\n- **33 MCP tools** — 24 atomic browser/mobile primitives (`browser_open`, `_close`, `_snapshot`, `_click`, `_type`, `_key`, `_scroll`, `_wait_for`, `_screenshot`, `_navigate`, plus v0.5 additions `_hover`, `_drag`, `_fill_form`, `_upload_file`, `_handle_dialog`, `_console`, `_network`, `_set_env`, `_evaluate`, `_pages`, `_switch_page`, v0.8 `_extract_computed_style`, v0.19 `_save_state`, and v0.20 `_find`) + 9 composites (`verify_ui_flow`, `audit_a11y`, `visual_diff`, `scaffold_e2e`, `extract_ui_state`, v0.7: `measure_cwv`, `audit_page_budget`, `audit_seo`, and v0.16: `discover_flows`). All prefixed `*` to namespace away from other MCP servers.\n- **2 engines behind one interface** — `PlaywrightEngine` for web (Chromium / Firefox / WebKit), `AppiumEngine` for iOS XCUITest + Android UIAutomator2. The Lead sees one unified `A11yNode` shape regardless of platform.\n- **Stable refs with explicit invalidation (D-010)** — every state-changing call invalidates prior refs; the engine returns a structured `stale_ref` error if you try to reuse one. No silent locator drift.\n- **Replay bundles** — every `/verify-ui` run writes a JSON replay you can re-run later with `npx @rolepod/uiproof replay <bundle.json>`, agent-free.\n- **No internal LLM (D-004)** — your Lead agent makes every decision. We don't double-bill you for inference.\n\n## Use with parent rolepod\n\nIf you also use [`rolepod`](https://github.com/nuttaruj/rolepod) (the markdown plugin), its `check-work`, `debug-issue`, and `review-code` skills auto-route to `/verify-ui`, `/audit-a11y`, and `/visual-diff` when the rolepod-uiproof server is present. Nothing breaks if it isn't — parent falls back to Playwright MCP / Chrome DevTools MCP / manual verification.\n\nThe two are **independent**: install rolepod-uiproof standalone and get a complete experience via slash commands, or install both together and let parent's phase router pick the right backend automatically.\n\n## Docs\n\n- [docs/sessions.md](docs/sessions.md) — session lifecycle, stale-ref semantics, multi-session\n- [docs/artifacts.md](docs/artifacts.md) — `.rolepod-uiproof/` layout, run_id convention, replay bundle format\n- [docs/recipes/](docs/recipes/) — `verify-a-checkout-flow`, `audit-a11y-during-review`, `visual-baseline-workflow`\n- [CHANGELOG.md](CHANGELOG.md) — release history with per-version \"Not yet verified\" notes mapped to milestones\n- [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)\n\n---\n\nMIT licensed — see [LICENSE](LICENSE) and [THIRD_PARTY.md](THIRD_PARTY.md). Mobile AT normalizers are alumnium-inspired ([UPSTREAM_TRACKING.md](UPSTREAM_TRACKING.md)). Feedback + runtime reports for Cursor / Codex / Gemini install paths especially welcome via [issues](https://github.com/nuttaruj/rolepod-uiproof/issues).\n",
  "bytes": 22704,
  "sha": "e5659fe7a1ff87a51a2e6164d343f3a09650adaa30a1c2d1f6cdaffae754e0c3",
  "repo_slug": "nuttaruj/rolepod-uiproof",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_nuttaruj_rolepod_uiproof_41b8e208/readme"
}