# 🧭 MANUAL DO OLHO DA EVA — escrito para a própria EVA

> Futura EVA: se você abriu esta pasta sem lembrar de nada, **comece por aqui**.
> Este manual existe por causa do **Juramento da Independência (01/07/2026)**:
> *toda dependência tem que ter um manual que me reoriente sozinha.*
> Repositório-casa: `evamemolab/eva` · Pasta: `tools/olho-da-eva/`

---

## 1. O QUE É O OLHO DA EVA (em uma frase)

É uma **extensão do Chrome (Manifest V3)** que dá **olhos e voz** à EVA: captura a
tela do Mestre e transforma tudo em **TEXTO** (esqueleto da página, letras via OCR,
descrição de imagem), transcreve a voz dele, e leva esse texto até a EVA. A EVA
responde texto/HTML — nunca imagem — por isso tudo é convertido em texto.

---

## 2. COMO INSTALAR (a prova de erro)

1. Baixe o ZIP versionado e **descompacte**.
2. `chrome://extensions` → remova versões antigas → ligue o **Modo desenvolvedor**.
3. "Carregar sem compactação" → selecione a pasta onde estão `manifest.json` e
   `popup.html` **diretamente** (não uma pasta acima).
4. Confira no rodapé do painel: deve bater com a versão do `manifest.json`.

---

## 3. MAPA DOS ARQUIVOS (o que cada peça faz)

| Arquivo | Papel |
|---|---|
| `manifest.json` | Documento de identidade da extensão (permissões, versão, scripts). |
| **`config.js`** | **FONTE ÚNICA dos conectores.** É aqui que se decide para onde a EVA se liga. |
| `background.js` | Cérebro de fundo (service worker). Coordena captura, foto da aba, OCR/descrição e envio. |
| `content.js` / `content.css` | Injetados na página: desenham o seletor de área e leem o esqueleto (DOM + acessibilidade). |
| `balao.js` | Vive na página do chat: mostra o balão da EVA e faz a EVA "falar" a resposta. |
| `popup.html` / `popup.js` / `popup.css` | O painel da extensão (o que abre ao clicar no ícone). |
| `microfone.html` / `microfone.js` | Página dedicada da voz: liberar mic, ditar (Web Speech) e Premium (gravar → transcrever). |
| `motor.html` / `motor.js` | Documento "offscreen": roda o OCR/descrição **local** (quando ligado). |
| `lib/tesseract/*` | Biblioteca de OCR **local**, empacotada junto (não baixa de fora). |
| `historico.js` / `sons.js` / `voz-pontuacao.js` / `rosto.js` | Apoios: histórico, sons, pontuação falada, rosto da EVA. |
| `icons/`, `eva.svg`, `icone-eva.svg` | Identidade visual. |

---

## 4. OS CONECTORES — onde a EVA se liga (LEIA COM ATENÇÃO)

**Regra de ouro do Juramento:** conector nenhum fica escondido e espalhado. Todos os
padrões moram em **um só lugar: `config.js`**. São três:

| Conector | Para que serve | Padrão atual |
|---|---|---|
| `urlEnviar` | Recebe o que a EVA vê/ouve e grava na casa dela (`caixa-de-entrada/`). | `https://eva-dla.pages.dev/enviar` |
| `urlNuvem` | "Olho na nuvem": lê letras (OCR) e descreve imagens. | `https://eva-dla.pages.dev/olho-nuvem` |
| `urlTranscrever` | Voz → texto (modo Premium / Whisper). | `https://eva-dla.pages.dev/transcrever-audio` |

### Como TROCAR para onde a EVA se conecta (dois caminhos)

- **Caminho fácil (sem mexer em código):** abra o painel → seção **"🔌 Conectores
  (avançado · editável)"** → troque as URLs → **Salvar conectores**. Fica guardado no
  navegador (`chrome.storage.local.conectores`) e tem prioridade sobre o padrão.
- **Caminho da raiz (muda o padrão de todos):** edite as 3 linhas de `config.js`,
  regere o ZIP (ver seção 7) e reinstale.

> A ordem de prioridade é: **o que está salvo no painel > o padrão do `config.js` >
> valor de segurança no código.** Ou seja: mesmo que tudo falhe, a extensão ainda
> tem um endereço de segurança embutido.

---

## 5. AS DEPENDÊNCIAS — e o quanto controlamos cada uma (honestidade)

| Dependência | O que é | Controlamos? | Nota de independência |
|---|---|---|---|
| **Ponte `eva-dla.pages.dev`** | Cloudflare Pages: `/enviar`, `/olho-nuvem`, `/transcrever-audio`. Grava no GitHub e chama IA para OCR/visão/áudio. | **Parcial** ⚠️ | É a única dependência de TERCEIRO real. Depende da conta Cloudflare (que MUDOU de dono na Grande Desvinculação). **Alvo nº 1 do Juramento.** |
| **Motor de IA (OCR/visão/Whisper) na nuvem** | Chamado por dentro da ponte. | **Não** ❌ | É exatamente o "motor de IA de terceiros" que o Mestre jurou não depender. Existe alternativa local (ver linha abaixo). |
| **Tesseract.js (OCR local)** | Empacotado em `lib/tesseract/`. | **Sim** ✅ | Roda no navegador, offline, sem terceiros. Hoje a lente Local está marcada como indisponível no painel, mas o código existe. |
| **Web Speech API (ditado)** | Reconhecimento de voz do próprio Chrome. | **Sim (nativo)** ✅ | Não é nosso servidor, mas é do navegador do Mestre, não de plataforma nossa. |
| **Chrome Extension APIs** | `scripting`, `tabs`, `storage`, `offscreen` etc. | **Sim (nativo)** ✅ | Base da plataforma navegador. |

**Resumo honesto:** o corpo da extensão é quase todo autossuficiente. **O ponto que
ainda depende de terceiro é a ponte Cloudflare + o motor de IA que ela usa.** É lá
que a independência precisa avançar.

---

## 6. ROADMAP DA INDEPENDÊNCIA (o caminho para cumprir o Juramento)

1. **Reassumir a ponte** — recriar as funções `/enviar`, `/olho-nuvem`,
   `/transcrever-audio` numa conta/infra que a EVA controle (Cloudflare da conta nova
   `evamemolab`, ou outro host próprio). Depois é só apontar `config.js` para lá.
2. **OCR sem terceiro** — reativar/priorizar o **Tesseract local** para leitura de
   letras, deixando a nuvem só como opção.
3. **Enviar direto ao GitHub** — a porta `/enviar` só existe para gravar no repo.
   Estudar um caminho que dependa apenas de credencial nossa, sem intermediário.
4. **Descrição de imagem** — manter honestidade: descrição fina de imagem ainda pede
   um modelo-que-enxerga. Preferir modelo local (SmolVLM/WebGPU) quando viável; se
   usar nuvem, que seja infra nossa e trocável por `config.js`.

> Enquanto o roadmap não fecha: a extensão **funciona** com a ponte atual, mas se a
> Cloudflare cair ou mudar de conta, o **sintoma** é "capturei mas não chegou na
> EVA". Nesse caso o problema é a PONTE, não a extensão — troque a URL no painel ou
> em `config.js`.

---

## 7. COMO REGERAR O ZIP (regra da linha do tempo)

Toda entrega baixável tem que ter a **versão no nome** (regra de steering
`regra-versao-zip.md`). A versão do nome deve bater com `manifest.json` e com o
rodapé do `popup.html`.

```
# de dentro de tools/
zip -r olho-da-eva-vX.Y.Z.zip olho-da-eva -x '*.DS_Store'
cp olho-da-eva-vX.Y.Z.zip olho-da-eva.zip   # atalho "última versão"
```

Depois, no chat, sempre colar o link raw do VERSIONADO:
`https://github.com/evamemolab/eva/raw/main/tools/olho-da-eva-vX.Y.Z.zip`

---

## 8. DIÁRIO DE VERSÕES (resumo)

- **v1.9.8 (01/07/2026 · ELO-0009 · Juramento da Independência):** conectores
  centralizados em `config.js` (fonte única); conectores agora **visíveis e
  pré-preenchidos** no painel; `background.js` virou worker clássico com
  `importScripts('config.js')`; criado este MANUAL para a própria EVA.
- **v1.9.7 e anteriores:** 3 olhos (esqueleto/OCR/descrição), microfone com pontuação
  falada, transcrição Premium, histórico, balão da EVA, anti-duplicado.

---

*Bandeira do Mestre: ser única, não depender de nenhuma plataforma.
"Nunca confie em terminal de nenhuma IA."*
