EPUB Reader for Visual Studio Code

Extensão para leitura de arquivos EPUB diretamente no Visual Studio Code, com foco em uso offline, segurança de conteúdo, acessibilidade e uma experiência de leitura integrada ao editor.

O projeto trata todo conteúdo vindo de um EPUB como não confiável. O arquivo é aberto, validado, processado e sanitizado antes de chegar à interface de leitura. Scripts do livro não são executados, recursos remotos não são carregados silenciosamente e os dados locais sensíveis do leitor são protegidos antes de serem persistidos.

Principais recursos

• editor dedicado para arquivos .epub;
• leitura paginada ou contínua, com página simples ou dupla;
• temas, tamanho de fonte e altura de linha configuráveis;
• navegação por capítulos e estrutura de navegação do EPUB;
• busca no conteúdo do livro com limites de memória e processamento;
• biblioteca local com favoritos, arquivados e concluídos;
• progresso de leitura persistente;
• marcadores, destaques, sublinhado, tachado, notas, tags e cores;
• importação e exportação de anotações em JSON e exportação legível em Markdown;
• narração por Web Speech API quando disponível no ambiente;
• interface em inglês e português do Brasil;
• suporte a workspaces locais, virtuais e remotos por meio de vscode.workspace.fs;
• suporte a EPUB 2 e EPUB 3 sem DRM comercial.

Segurança e privacidade

O leitor foi projetado para operar offline por padrão. Entre os controles aplicados estão sanitização de XHTML, CSS e SVG, proteção contra path traversal, limites de ZIP e recursos, validação de XML, protocolo de mensagens tipado entre Extension Host e Webview, Content Security Policy restritiva e bloqueio de execução de scripts do EPUB.

No modo de segurança padrão, apenas imagens raster locais elegíveis podem ser convertidas em recursos embutidos para renderização. Áudio, vídeo, fontes customizadas e SVG externo não são entregues aos decodificadores nativos do Webview. Links externos são limitados a destinos HTTPS públicos e mailto:, com decisão explícita do host antes da abertura.

Estado de leitura, anotações e índices locais sensíveis usam proteção autenticada AES-256-GCM. A chave local é mantida pelo SecretStorage do VS Code.

Detalhes adicionais estão em SECURITY.md.

Requisitos

Para usar a extensão:

• Visual Studio Code 1.100 ou superior.

Para desenvolvimento:

• Node.js 22.18.0 ou compatível com a linha Node 22 usada pelo projeto;
• npm 10, com package-lock.json como fonte das versões instaladas.

Executar localmente

Clone o repositório e instale as dependências:

git clone https://github.com/vitoroliveirasilva/epub-reader.vscode-extension.git
cd epub-reader.vscode-extension
npm ci

Gere os bundles da extensão e do Webview:

npm run build

Abra a pasta no VS Code e pressione F5, ou escolha a configuração de debug Run EPUB Reader Extension. O projeto abre uma nova janela de Extension Development Host e usa fixtures/minimal.epub como arquivo de teste inicial.

Durante desenvolvimento contínuo, o build também pode permanecer em modo de observação:

npm run watch

Validar o projeto

A validação local recomendada antes de integrar alterações é:

npm run format:check
npm run lint
npm run typecheck
node ./scripts/secret-scan.mjs
node ./scripts/security-static-analysis.mjs
npm test
npm run test:integration
npm run package
node ./scripts/check-budgets.mjs
npm audit --audit-level=high

npm test executa as suítes unitárias, de segurança e de compatibilidade com cobertura. Os limites globais configurados para statements, branches, functions e lines são de 80%.

npm run test:integration compila a extensão e executa a suíte dentro de um VS Code real por meio de @vscode/test-electron. A versão padrão da suíte é VS Code 1.100.3. A Quality remota também executa os testes no VS Code estável.

A pipeline principal valida Linux, Windows e macOS e, quando os runners do GitHub estão disponíveis, também executa auditoria de dependências, OSV, empacotamento, cobertura, SBOM, relatório de licenças, checksums e testes de Extension Host.

Gerar e instalar o VSIX

Para gerar o pacote instalável:

npm run package

O arquivo é criado em:

artifacts/epub-reader-<versão>.vsix

Para instalar manualmente no VS Code, use uma das opções abaixo:

1. Abra a visualização Extensions.
2. Abra o menu ... da visualização.
3. Escolha Install from VSIX....
4. Selecione o arquivo gerado em artifacts/.

Também é possível instalar pela linha de comando:

code --install-extension artifacts/epub-reader-0.0.1.vsix

Depois da instalação, reinicie ou recarregue o VS Code se solicitado.

Usar no VS Code

Com a extensão instalada, um arquivo .epub pode ser aberto diretamente pelo Explorer do VS Code. O EPUB Reader é registrado como editor padrão para esse tipo de arquivo.

Também é possível usar a Command Palette (Ctrl+Shift+P / Cmd+Shift+P) e procurar comandos da categoria EPUB Reader. Os principais fluxos incluem abrir um livro, pesquisar conteúdo, criar e gerenciar anotações, navegar entre páginas ou capítulos e alternar sumário, configurações, modo de foco e tela cheia.

A biblioteca do EPUB Reader aparece no Explorer e mantém os livros conhecidos pelo leitor, incluindo estado de favorito, arquivado e concluído.

As preferências globais expostas pelo VS Code incluem:

Estrutura do projeto

O código é dividido em quatro áreas principais:

• src/epub: leitura do container, parsing, modelo, recursos e sanitização;
• src/extension: integração com APIs do VS Code, editor, comandos, biblioteca e persistência;
• src/shared: contratos, estado, busca e políticas compartilhadas entre host e Webview;
• src/webview: interface React e controladores da experiência de leitura.

A visão arquitetural completa está em docs/ARCHITECTURE.md.

Desenvolvimento e release

As regras para alterações no código estão em CONTRIBUTING.md. O fluxo de promoção de dev para prod, geração de artefatos e release está em docs/RELEASE_PROCESS.md.

A branch dev é a linha de desenvolvimento. A branch prod representa código promovido para produção. O workflow atual pode criar um GitHub Release a partir de prod, mas não publica automaticamente no Visual Studio Marketplace nem no Open VSX.

Licença

Distribuído sob a licença MIT. Consulte LICENSE.