# Clique Já

<p align="center">
  <img src="ext/icon-128.png" width="96" height="96" alt="Clique Já" />
</p>

<p align="center">
  <strong>Automação de browser rápida</strong> · extensão Chrome MV3 · hub local · MCP<br/>
  Clique, fill e snapshot na aba real — sem esperar o Playwright inteiro pra cada gesto.
</p>

<p align="center">
  <a href="https://github.com/paivaxqz/cliqueja/stargazers"><img alt="stars" src="https://img.shields.io/github/stars/paivaxqz/cliqueja?style=for-the-badge&color=ff0033" /></a>
  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-111827?style=for-the-badge" /></a>
  <img alt="mv3" src="https://img.shields.io/badge/Chrome-MV3-4285F4?style=for-the-badge&logo=googlechrome&logoColor=white" />
  <img alt="node" src="https://img.shields.io/badge/node-%3E%3D20-3776AB?style=for-the-badge&logo=nodedotjs&logoColor=white" />
  <img alt="mcp" src="https://img.shields.io/badge/MCP-tools-0A0A0A?style=for-the-badge" />
</p>

---

## Por que existe

Playwright e puppeteer são ótimos — e pesados pra “só clicar nesse botão agora”.  
**Clique Já** prende uma aba do Chrome que você já usa, injeta um micro-runtime vermelho (`__cliqueja`) e responde comandos via WebSocket em milissegundos.

| | Clique Já | Automação clássica |
|---|---|---|
| Browser | Chrome real (sua sessão) | Chromium isolado |
| Sessão / login | já logado | re-auth / storage state |
| Latência por click | 1 `evaluate` | stack completa |
| Agente IA | tools MCP | scripts / custom |

---

## Fluxograma

```mermaid
flowchart LR
  subgraph Agent["Agente / CLI"]
    MCP["mcp.mjs<br/>tools MCP"]
    HTTP["POST /cmd"]
  end

  subgraph Hub["Hub local :17321"]
    H["hub.mjs<br/>WebSocket + HTTP"]
  end

  subgraph Chrome["Chrome"]
    EXT["Extensão Clique Já<br/>service worker"]
    TAB["Aba http(s)"]
    INJ["inject.js<br/>window.__cliqueja"]
  end

  MCP -->|WS| H
  HTTP -->|HTTP| H
  H <-->|WS| EXT
  EXT -->|scripting MAIN world| INJ
  INJ --> TAB
```

### Fluxo de um click

```mermaid
sequenceDiagram
  participant A as Agente
  participant H as Hub :17321
  participant E as Extensão
  participant P as Página

  A->>H: { method: "click", sel: "button" }
  H->>E: mesmo envelope (WS)
  E->>P: inject + __cliqueja.click
  P-->>E: ok (+ flash vermelho)
  E-->>H: { ok: true }
  H-->>A: result
```

Arquitetura detalhada: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)

---

## Quick start

### 1. Hub

```bash
git clone https://github.com/paivaxqz/cliqueja.git
cd cliqueja
npm install
npm run hub
# ou: start-hub.bat  (Windows)
```

Hub escuta **só** `127.0.0.1:17321`.

### 2. Extensão

1. Chrome → `chrome://extensions` → **Developer mode**
2. **Load unpacked** → pasta `ext/`
3. Abra um site `http(s)` (não `chrome://`)
4. Clique no ícone → **usar esta aba** (badge **ON** vermelho)

### 3. Smoke HTTP

```bash
curl http://127.0.0.1:17321/status
curl -X POST http://127.0.0.1:17321/cmd -H "content-type: application/json" -d "{\"method\":\"ping\"}"
```

### 4. MCP na IA (PC do usuário)

Hub + extensão rodam **na máquina de quem usa** — não na nuvem.

Guia completo (3 passos + Cursor/Claude): **[docs/MCP.md](docs/MCP.md)**

Config Cursor — path do **clone do usuário**:

```json
{
  "mcpServers": {
    "cliqueja": {
      "command": "node",
      "args": ["${workspaceFolder}/mcp.mjs"]
    }
  }
}
```

Se a pasta aberta no Cursor não for o clone, use path absoluto (`C:\\Users\\...\\cliqueja\\mcp.mjs` ou `/Users/.../cliqueja/mcp.mjs`).

Tools: `cliqueja_status` · `abas` · `usar_aba` · `ir` · `click` · `fill` · `texto` · `snapshot` · `links` · `upload`

### Por que não Vercel?

Vercel não abre o Chrome do usuário nem recebe o WebSocket da extensão (`127.0.0.1`).  
Landing/docs na Vercel ok. **Hub + MCP + extensão = sempre local.** → [docs/MCP.md](docs/MCP.md)

### 5. Modo lib (Playwright fino)

```bash
npm run exemplo
```

`index.js` + `inject.js`: Chrome via `playwright-core`, **1 evaluate por ação**, marca vermelha no canto.

---

## Seletores

- CSS: `button.buy`, `#email`
- Texto: `text=Entrar`
- XPath: `xpath=//button[@type='submit']`

Timeout padrão da extensão: **4s** (inject espera com `requestAnimationFrame`).

---

## Estrutura

```
cliqueja/
├── ext/                 # Chrome MV3 (load unpacked)
│   ├── manifest.json
│   ├── background.js    # WS client + comandos
│   ├── inject.js        # runtime na página
│   ├── popup.*          # UI vermelha
│   └── icon-128.png
├── hub.mjs              # bridge WS/HTTP
├── mcp.mjs              # MCP stdio → hub
├── index.js             # lib Playwright rápida
├── inject.js            # mesmo runtime (lib)
├── exemplo.js
├── start-hub.bat
└── docs/
    └── ARCHITECTURE.md
```

---

## Segurança

- Hub **localhost only** — não exponha a porta
- Extensão pede `debugger` só pra upload de arquivo (CDP `DOM.setFileInputFiles`)
- Não rode em máquinas compartilhadas sem entender o que o agente pode clicar
- Use por sua conta e risco; respeite ToS dos sites que automatizar

---

## Licença

[MIT](LICENSE) · **Clique Já** · [paivaxqz](https://github.com/paivaxqz)