Surface
zigrivers/surface
Auditoria de UI com verificação mensurável + análise de IA local
Ver no GitHubMCP server e CLI para auditoria de UIs web em execução, combinando verificações mensuráveis com análise assistida por IA. Detecta problemas de interface, explica achados e verifica correções localmente, sem enviar dados capturados para servidores externos.
Instalação
npx convez-ai zigrivers/surface1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Detectar problemas visuais e de acessibilidade em aplicações web rodando
- Validar correções de UI antes de deploy com QA automatizado
- Executar fluxos de browser QA determinísticos e controlados em CI/CD
Veredito

Ferramenta robusta para QA de UI que une medições determinísticas com capacidades de modelo, mantendo privacidade local. Excelente para times que precisam validar UIs antes de release com rigor técnico e automatização.
README
A tradução para o português deste README ainda está na fila.
Surface
Surface is a local-first CLI and MCP server for auditing built, running web UIs. It combines measured checks, deterministic local state, and optional model-assisted review so agents can find UI issues, explain them, and verify fixes without sending captured UI data anywhere by default.
Install
npm install --global @zigrivers/surface
surface --help
Run without installing:
npx @zigrivers/surface --help
Homebrew installation is available through the zigrivers/surface tap:
brew tap zigrivers/surface
brew install surface
Local Development
corepack enable
pnpm install
pnpm run check
Build and link the CLI locally:
pnpm --filter @zigrivers/surface build
pnpm --filter @zigrivers/surface exec npm link
surface --help
If npm link reports that surface already exists because Homebrew or another global install owns
the binary, avoid overwriting that package-manager-owned file unless you intend to replace it. For a
one-off local smoke test, run the built CLI directly:
node packages/cli/dist/index.js --help
Browser QA
Surface includes agent-led browser QA powered by agent-browser. Use it when you want an agent to
run reviewed browser flows, explore a target within policy limits, collect redacted evidence, replay
candidate findings, and make release gates aware of browser-flow failures.
Run QA against the default local target:
surface qa --localhost --explore --task "complete checkout"
Run a reviewed flow file against a custom local port:
surface flow run surface-flows/checkout.yml --url http://localhost:5173
Apply an action policy to allow only the browser actions, origins, routes, fixture accounts, and teardown contracts that are safe for the target:
surface qa --url https://app.example.com \
--flows "surface-flows/*.yml" \
--action-policy .surface/qa/action-policy.json
Use reviewed flow results in CI gates:
surface gate --ci --with-flows --url http://localhost:5173
Primary browser QA commands:
| Command | Purpose |
|---|---|
surface qa | Run agent-led QA over a target, optional reviewed flows, and bounded exploration |
surface flow run <flow.yml> | Run deterministic source-controlled browser QA flows |
surface evidence <ref> | Read redacted browser QA evidence metadata |
surface replay <ref> | Replay a browser QA finding or candidate |
surface report qa --run <qaRunId> | Render QA reports as Markdown, JSON, or manifest output |
surface gate --with-flows | Include verified browser QA flow results in the quality gate |
Safety defaults are intentionally strict:
- Action policies gate destructive or browser-mutating behavior, including payment, account, save, delete, upload, submit, and externally visible actions.
- Resolved secrets must not be passed through argv, logs, traces, serialized step payloads, or artifacts.
- Browser QA state and evidence are stored under
.surface/qa. --localhostis a boolean shortcut forhttp://localhost:3000; use--urlor--targetfor custom ports.
For deeper implementation details, see
docs/superpowers/specs/2026-06-08-browser-qa-orchestrator-design.md
and
docs/superpowers/plans/2026-06-08-browser-qa-orchestrator-implementation.md.
Model Fallback
Surface audits stay measured-only by default. When you explicitly opt in, surface audit can reuse
authenticated subscription CLIs for judged synthesis without requiring project API keys.
Run a one-off audit through direct subscription providers:
surface audit --url http://localhost:5173 \
--model-fallback direct \
--model-channels claude,gemini \
--model-depth 3
Let Surface try direct providers first and report compatible MMR fallback availability if direct providers cannot run:
surface audit --url http://localhost:5173 --model-fallback auto
Screenshot egress is separate from model fallback consent. Binary screenshots are blocked for
subscription-backed providers in this release; use --model-screenshots redacted-only only when
you want redacted screenshot metadata considered alongside text artifacts.
Primary model fallback controls:
| Control | Purpose |
|---|---|
--model-fallback off|direct|mmr|auto | Select measured-only, direct CLI, MMR-only, or direct-then-MMR behavior |
--model-channel <id> | Add a direct subscription channel; repeatable |
--model-channels <ids> | Set comma-separated direct subscription channel order |
--model-depth <1-5> | Control judged synthesis depth and reconciliation |
--model-screenshots blocked|redacted-only | Keep screenshots blocked or permit redacted screenshot metadata |
surface cleanup model-egress | Remove persisted model egress artifacts from the Surface state directory |
BYO-key and local model providers still take precedence over subscription fallback when configured. MMR is a fallback boundary only when a compatible Surface audit capability is available; the current diff-shaped MMR review flow is reported as unavailable instead of receiving captured UI artifacts.
Reliability and State Safety
Surface persists audit, gate, browser QA, and verdict records through a durable local state store. Recent releases tighten those paths so state transitions are atomic, canonical durable fields are validated before persistence, and CLI/MCP verdict writes produce the same canonical records.
Capture and browser automation failures are also sanitized before they reach machine-readable error
envelopes. Unsafe agent-browser command details are replaced with redacted context, keeping raw
capture output and command failure payloads out of logs and artifacts.
The 0.2.3 release also aligns live agent-browser computed-style artifacts with the visual
hierarchy and responsiveness lenses, honors requested capture configuration through surface capture, and projects completed or failed pipeline runs through surface status and surface next.
Packages
| Package | Purpose |
|---|---|
@zigrivers/surface | CLI package; publishes the surface binary |
@zigrivers/surface-core | Core schemas, state, scoring, and orchestration |
@zigrivers/surface-mcp | MCP server adapter |
@zigrivers/surface-grounding | Measured grounding tools |
@zigrivers/surface-adapter-agnostic | Framework-agnostic HTML adapter |
@zigrivers/surface-adapter-react | React adapter |
@zigrivers/surface-adapter-svelte | Svelte adapter |
@zigrivers/surface-adapter-vue | Vue adapter |
Release Checks
Release preparation is local-first to avoid routine GitHub Actions usage:
pnpm run check
pnpm run release:verify
The GitHub release workflow is manual and intended only for release publication, primarily to support npm trusted publishing and provenance.
License
MIT. See LICENSE.