🌐 If you want to read the English version of this README, click here. Si quieres leer la versión en español de este README, haz clic aquí.

SimplifAI - Extensão Chrome para Acessibilidade Web

Important

Este projeto é um protótipo experimental. Não é um produto oficial do Google e não possui nenhum mecanismo de suporte. Foi criado para explorar as possibilidades dos modelos Gemini e fomentar ideias de acessibilidade através de IA generativa. Use por sua conta e risco.

SimplifAI é uma extensão Chrome que utiliza Inteligência Artificial (Google Gemini API) para simplificar conteúdo web, tornando a informação mais acessível segundo os princípios da ISO 24495-1 (Linguagem Simples).

📚 Fundamentação Teórica

ISO 24495-1: Linguagem Simples

A SimplifAI baseia-se na ISO 24495-1 (Plain language - Part 1: Governing principles and guidelines), norma internacional que estabelece princípios e diretrizes para comunicação clara e acessível.

No Brasil, a linguagem simples é promovida pelo Governo Federal através do programa Linguagem Simples, que estabelece:

Princípios da Linguagem Simples (ISO 24495-1)

Foco no usuário: Adaptar a linguagem ao público-alvo
Clareza: Usar palavras comuns e frases curtas
Estrutura lógica: Organizar informações de forma coerente
Design acessível: Facilitar a leitura visual
Verificação: Testar com usuários reais

Implementação na SimplifAI

A extensão aplica estes princípios através de:

Redução de complexidade: Textos são reduzidos em até 50%
Vocabulário simplificado: Substituição de termos técnicos por sinônimos comuns
Estrutura clara: Parágrafos curtos (2-3 frases) com hierarquia mantida
Explicação de siglas: Acrônimos são explicados entre parênteses
Voz ativa: Preferência por construções diretas

🎯 Funcionalidades

1. Onboarding Guiado (Wizard)

3 etapas simples: Idioma → Configuração API → Sucesso
Multilíngue desde o início: Tela inicial exibe PT/ES/EN simultaneamente
Seleção de modelo Gemini: Escolha entre Gemini 2.5 (gratuito) e Gemini 3.0 (requer billing)
Validação de API key: Teste automático antes de salvar
Redirecionamento automático: Se tentar usar sem configurar, abre o wizard

2. Simplificação de Conteúdo com IA

Análise semântica profunda usando Google Gemini API
Suporte a múltiplos modelos: Gemini 2.5 Flash e Gemini 3.0 Flash Preview
Redução de até 50% do texto original mantendo significado
Preservação da hierarquia de títulos e seções
Remoção automática de conteúdo secundário e publicidade

3. Geração de Áudio (Text-to-Speech)

Motor TTS: Gemini 2.5 Flash Preview TTS
Qualidade: 24 kHz, 16-bit PCM, mono
Chunking inteligente: Divisão por parágrafos e frases
Processamento paralelo: Até 5 chunks simultâneos
Reprodução progressiva: Início antes da conclusão total
Retry automático: Tolerância a falhas de API
Controles: Play, pause, stop com barra de progresso

4. Descrição de Imagens com IA

Análise contextual usando Gemini API
Detecta e ignora: ícones, logos, banners, anúncios
Lazy loading: Suporte a imagens com carregamento diferido
Contexto do artigo: Descrições específicas baseadas no conteúdo
Validação de dimensões (>50x50px)

5. Dicionário Contextual Embutido

Ativação: Duplo clique ou seleção + atalho (Alt+D)
Prevenção de alucinações: Validação de siglas e termos técnicos
Popup flutuante: Posicionado próximo à seleção
Multi-idioma: Definições no idioma configurado
Contexto: Considera o artigo para termos ambíguos

6. Suporte Multilíngue Avançado

Idiomas Suportados

🇺🇸 Inglês (EN)
🇧🇷 Português (PT)
🇪🇸 Espanhol (ES)

Capacidade de Tradução Automática

A SimplifAI pode simplificar em um idioma uma página que está em outro:

Exemplo:

Página original: Português (notícia do G1)
Idioma configurado: Inglês
Resultado: Texto simplificado em inglês

📄 Original (PT): "O Supremo Tribunal Federal (STF) decidiu..."
📝 Simplificado (EN): "The Supreme Federal Court decided..."

Processo:

Extração do conteúdo no idioma original
Prompt Gemini: "Translate to {language} and simplify..."
Tradução + simplificação simultâneas
Validação de qualidade

7. Recursos de Acessibilidade

Atalhos de Teclado

Atalho	Função
`Alt/Cmd + S`	Simplificar página atual
`Alt/Cmd + A`	Gerar/pausar áudio (na página simplificada)

Modo Alto Contraste

Ativação: Botão na toolbar da página simplificada
Cores WCAG AAA: Contraste mínimo 7:1
Esquema: Texto branco (#FFFFFF) sobre fundo preto (#000000)
Persistência: Salvo em chrome.storage.sync
Aplicação: CSS separado (high-contrast.css)

Controle de Fonte

Tamanhos: 14px, 16px, 18px, 20px, 22px, 24px
Padrão: 18px
Incremento: ±2px por botão
Persistência: Salvo por usuário
Unidade: px absoluto para previsibilidade

🏗️ Arquitetura Técnica

Diagrama de Componentes

graph TB
    subgraph "Chrome Extension"
        BG[Background Service Worker]
        CS[Content Script]
        POP[Popup UI]
        
        subgraph "Content Modules"
            META[Metadata Extractor]
            CONT[Content Extractor]
            IMG[Image Processor]
            MD[Markdown Processor]
            OVL[Overlay Manager]
            ORCH[Simplification Orchestrator]
        end
        
        subgraph "Services"
            GEM[Gemini Service]
            AUD[Audio Service]
        end
        
        subgraph "Utilities"
            TRANS[Translations]
            PROM[Prompts]
            KBD[Keyboard Shortcuts]
        end
    end
    
    subgraph "External APIs"
        GEMAPI[Google Gemini API]
        TTS[Gemini TTS API]
    end
    
    subgraph "Chrome APIs"
        STORAGE[chrome.storage.sync]
        RUNTIME[chrome.runtime]
        SCRIPTING[chrome.scripting]
    end
    
    CS --> ORCH
    ORCH --> META
    ORCH --> CONT
    ORCH --> IMG
    ORCH --> MD
    ORCH --> OVL
    
    CONT --> GEM
    IMG --> GEM
    AUD --> TTS
    
    GEM --> GEMAPI
    AUD --> GEMAPI
    
    BG --> STORAGE
    CS --> STORAGE
    POP --> STORAGE
    
    BG --> RUNTIME
    CS --> RUNTIME
    
    POP --> TRANS
    ORCH --> PROM
    CS --> KBD
    
    style ORCH fill:#ff6b6b
    style GEM fill:#4ecdc4
    style AUD fill:#95e1d3
    style GEMAPI fill:#f38181

Fluxo de Onboarding (Primeira Execução)

sequenceDiagram
    participant U as Usuário
    participant BG as Background Script
    participant OB as Onboarding Page
    participant GEM as Gemini Service
    participant ST as Chrome Storage

    Note over BG: Extensão instalada
    BG->>ST: Verifica apiKey
    ST-->>BG: null (não configurado)
    BG->>OB: Abre onboarding.html
    
    Note over OB: Etapa 1: Idioma
    OB->>U: Exibe PT/ES/EN
    U->>OB: Seleciona idioma
    OB->>ST: Salva language
    
    Note over OB: Etapa 2: API Key
    OB->>U: Solicita modelo + API key
    U->>OB: Insere dados
    OB->>BG: testApiKey(key, model)
    BG->>GEM: validateApiKey(model)
    GEM-->>BG: isValid: true
    BG-->>OB: Validação OK
    OB->>ST: Salva apiKey + geminiModel
    
    Note over OB: Etapa 3: Sucesso
    OB->>U: ✅ Pronto para usar!

Fluxo de Simplificação

sequenceDiagram
    participant U as Usuário
    participant CS as Content Script
    participant ORCH as Orchestrator
    participant EXT as Extractors
    participant GEM as Gemini Service
    participant OVL as Overlay Manager

    U->>CS: Alt+S (simplificar)
    CS->>ORCH: orchestrateSimplification()
    
    ORCH->>EXT: extractMetadata()
    EXT-->>ORCH: {titulo, autor, data}
    
    ORCH->>EXT: extractMainContent()
    EXT-->>ORCH: {texto, imagens}
    
    ORCH->>GEM: simplifyText(conteúdo)
    GEM->>GEM: Prompts[idioma].textSimplification
    GEM-->>ORCH: texto simplificado
    
    loop Para cada imagem
        ORCH->>GEM: getImageDescription(img, contexto)
        GEM-->>ORCH: descrição
    end
    
    ORCH->>ORCH: renderMarkdown()
    ORCH->>OVL: showSimplifiedPage(html)
    OVL-->>U: Exibe página simplificada

Fluxo de Geração de Áudio

sequenceDiagram
    participant U as Usuário
    participant SP as Simplified Page
    participant AUD as AudioService
    participant GEM as Gemini TTS API
    participant QUEUE as AudioQueue

    U->>SP: Clica "Gerar Áudio"
    SP->>AUD: generateAudioInChunks(texto, idioma)
    
    AUD->>AUD: splitIntoLogicalChunks(400 chars)
    AUD->>QUEUE: new AudioQueue(totalChunks)
    
    par Processamento Paralelo (5 simultâneos)
        AUD->>GEM: convertTextToSpeech(chunk1)
        AUD->>GEM: convertTextToSpeech(chunk2)
        AUD->>GEM: convertTextToSpeech(chunk3)
    end
    
    GEM-->>AUD: WAV buffer (24kHz PCM)
    AUD->>QUEUE: addChunk(index, buffer)
    
    alt É o próximo chunk
        QUEUE->>QUEUE: playChunk()
        QUEUE-->>U: 🔊 Reproduz áudio
    else Não é o próximo
        QUEUE->>QUEUE: armazena em fila
    end
    
    loop Até todos chunks
        QUEUE->>QUEUE: playNextAvailableChunks()
    end
    
    QUEUE-->>U: ✅ Playback completo

Padrões Arquiteturais Implementados

1. Context Pass-through Pattern

// Contexto do artigo é passado para descrição de imagens
const pageContext = await generatePageContext(simplifiedText);
const imageDescriptions = await processImagesWithDescriptions(
    imageMap, 
    apiKey, 
    language, 
    pageContext  // ← Contexto passado
);

2. Stabilized Parallel Batched TTS

// Processamento paralelo com concorrência controlada
async generateAudioInChunks(fullText, language, progressCallback, maxConcurrency = 5) {
    const chunks = this.splitIntoLogicalChunks(fullText, 400);
    
    for (let i = 0; i < chunks.length; i += maxConcurrency) {
        const batch = chunks.slice(i, i + maxConcurrency);
        await Promise.all(batch.map(chunk => this.convertTextToSpeech(chunk)));
    }
}

3. State Guarding

// Previne execução dupla
if (window.extensionVariables.isSimplifying) {
    console.warn('Simplification already in progress');
    return;
}
window.extensionVariables.isSimplifying = true;

4. Extension Context Robustness

// Detecta contexto invalidado e orienta usuário
try {
    const result = await chrome.storage.sync.get(['language']);
} catch (error) {
    if (error.message?.includes('Extension context invalidated')) {
        alert('Extension was reloaded. Please refresh the page.');
        return;
    }
}

🌍 Capacidades Multilíngues

Arquitetura de Tradução/Simplificação

graph LR
    A[Página Original] --> B{Detecta Idioma Original}
    B --> C[Extrai Conteúdo]
    C --> D{Idioma Config ≠ Original?}
    
    D -->|Sim| E[Prompt: Translate + Simplify]
    D -->|Não| F[Prompt: Simplify Only]
    
    E --> G[Gemini API]
    F --> G
    
    G --> H[Texto Simplificado<br/>no Idioma Config]

Exemplos de Uso Multilíngue

Exemplo 1: Português → Inglês

📄 Input (PT - G1 Notícias):
"O Supremo Tribunal Federal (STF) julgou procedente a Ação Direta de 
Inconstitucionalidade (ADI) que questionava dispositivos da Lei..."

⚙️ Configuração: Idioma = English
🤖 Processo: Tradução + Simplificação
📝 Output (EN - Simplified):
"The Supreme Court ruled that parts of the law are unconstitutional. 
The case (ADI) challenged specific articles..."

Exemplo 2: Inglês → Português

📄 Input (EN - Wikipedia):
"Quantum mechanics is a fundamental theory in physics that provides 
a description of the physical properties of nature at the scale of 
atoms and subatomic particles..."

⚙️ Configuração: Idioma = Português
🤖 Processo: Tradução + Simplificação
📝 Output (PT - Simplificado):
"A mecânica quântica é uma teoria da física. Ela explica como 
funcionam átomos e partículas muito pequenas..."

Exemplo 3: Espanhol → Espanhol (Simplificação apenas)

📄 Input (ES - El País):
"El Tribunal Constitucional ha desestimado el recurso de 
inconstitucionalidad interpuesto contra diversos preceptos..."

⚙️ Configuração: Idioma = Español
🤖 Processo: Simplificação (sem tradução)
📝 Output (ES - Simplificado):
"El Tribunal Constitucional rechazó el recurso contra la ley. 
Los artículos cuestionados..."

Configuração de Prompts por Idioma

Os prompts são externalizados em src/utils/prompts.js:

const Prompts = {
    en: {
        textSimplification: `Translate to English and simplify...`,
        imageDescription: `Describe this image in short paragraph...`,
        wordDefinition: `Define the word "{word}"...`
    },
    pt: {
        textSimplification: `Traduza para Português e simplifique...`,
        imageDescription: `Descreva esta imagem em parágrafo curto...`,
        wordDefinition: `Defina a palavra "{word}"...`
    },
    es: { /* ... */ }
};

♿ Recursos de Acessibilidade

Toolbar de Acessibilidade

┌─────────────────────────────────────────────┐
│ 🎨 [H] Alto Contraste  │  A⁺ A⁻  Fonte      │
└─────────────────────────────────────────────┘

Implementação Alto Contraste

/* high-contrast.css */
.high-contrast-mode {
    background-color: #000000 !important;
    color: #FFFFFF !important;
}

.high-contrast-mode a {
    color: #FFFF00 !important; /* Amarelo para links */
}

.high-contrast-mode img {
    border: 2px solid #FFFFFF !important;
}

Contraste WCAG AAA:

Texto normal: 7:1 (branco sobre preto)
Texto grande: 4.5:1
Componentes UI: 3:1

Navegação por Teclado

Todos os elementos interativos são acessíveis via teclado:

Tab: Navegação entre elementos
Enter/Space: Ativação de botões
Esc: Fechar popups e overlays
Atalhos Alt+: Ações rápidas

ARIA Labels

<button 
    id="generate-audio-btn" 
    aria-label="Gerar áudio da página simplificada"
    data-i18n="simplified.generateAudio">
    🔊 Gerar Áudio
</button>

💾 Instalação e Configuração

Pré-requisitos

Navegador: Google Chrome 100+ ou Chromium
Chave API: Google AI Studio

Instalação

Clone o repositório:

git clone https://github.com/seu-usuario/SimplifAI.git
cd SimplifAI

Carregue a extensão no Chrome:
- Acesse chrome://extensions/
- Ative "Modo do desenvolvedor" (canto superior direito)
- Clique "Carregar sem compactação"
- Selecione a pasta src/
Configure via Wizard de Onboarding:
- O wizard abre automaticamente na primeira instalação
- Etapa 1: Escolha seu idioma (PT/ES/EN)
- Etapa 2: Selecione o modelo Gemini e insira sua API Key
- Etapa 3: Pronto! Extensão configurada

Nota: Se vocé fechar o wizard antes de configurar e tentar usar a extensão, o wizard reabrirá automaticamente.

Configuração Avançada

Modificar Concorrência TTS

// src/services/audio.js
async generateAudioInChunks(
    fullText, 
    language = 'en', 
    progressCallback = null, 
    maxConcurrency = 5  // ← Altere aqui (1-10)
) { ... }

Ajustar Tamanho de Chunk TTS

// src/services/audio.js
splitIntoLogicalChunks(
    text, 
    maxChunkSize = 2000  // ← Altere aqui (400-4000 chars)
) { ... }

📖 Guia de Uso

Simplificar uma Página

Método 1: Ícone da Extensão

Navegue até a página desejada
Clique no ícone SimplifAI
Aguarde o processamento (5-30s)

Método 2: Menu Contextual

Clique direito na página
Selecione "Simplificar esta página"

Método 3: Atalho de Teclado

Pressione Alt/Cmd + S

Gerar Áudio

Simplifique a página primeiro
Clique em "🔊 Gerar Áudio"
Aguarde o processamento progressivo
Use os controles:
- ▶️ Play/Pause
- ⏹️ Stop
- Barra de progresso

Usar o Dicionário

Método 1: Duplo Clique

Dê duplo clique na palavra