Tab URL Extractor

Uma extensão Chrome (Manifest V3) para coletar URLs das abas, normalizar, deduplicar, agrupar por domínio e exportar em formatos amigáveis para automação.

MV3 Service Worker (module)

Export json / txt / txt-simple

Estado temporário em memória

Privacidade sem nuvem

🔎

Por que existe

Transforma “um monte de abas abertas” em um dataset exportável e previsível para pipelines, scripts e apps.

Destaque: é uma ferramenta de extração/estruturação — não interpreta conteúdo.

⛔

O que ele não faz

Não classifica conteúdo, não faz scraping, não sincroniza dados e não mantém histórico (estado é temporário).

Princípio Mesmo input → mesma saída Sem rede/terceiros

⚡

Como usar

Analisar → revisar matrizes → exportar tudo ou por domínio (json/txt/txt-simple).

Referências popup/popup.js background/service-worker.js core/matrix-builder.js core/exporter.js

🧩

Pontos principais do código

Onde cada parte do fluxo mora: UI → orquestração → core → infra (downloads).

Referências manifest.json popup/popup.js background/service-worker.js infrastructure/tab-collector.js core/url-processor.js core/matrix-builder.js core/exporter.js infrastructure/download-manager.js utils/validators.js utils/logger.js

Overview

Visão Geral

Tab URL Extractor (TUE) é uma extensão Chrome (MV3) focada em uma tarefa: extrair URLs das abas abertas, aplicar um processamento técnico consistente (normalização + deduplicação) e entregar um export pronto para ser consumido por scripts e aplicações.

🧾

O que faz

Executa uma coleta de URLs, processa tecnicamente e entrega uma URL-Matriz por domínio pronta para export.

Referências infrastructure/tab-collector.js core/url-processor.js core/matrix-builder.js

🛡️

Segurança & Privacidade

Processamento local no navegador; sem envio para rede. Ações são iniciadas pelo usuário e validadas antes do export.

Referências manifest.json utils/validators.js background/service-worker.js

🏗️

Arquitetura

Camadas claras: core (lógica), infrastructure (Chrome APIs), background (fluxo) e popup (UI).

Referências core/* infrastructure/* background/service-worker.js popup/popup.js

🎛️

Principais ações

Fluxo minimalista, com estado temporário entre análise e exportação.

Analisar: coleta abas e monta URL-Matrizes.
Exportar tudo: gera arquivo com todas as matrizes.
Exportar por domínio: gera arquivo apenas do grupo escolhido.
Nova análise: reinicia o estado e reprocessa as abas.

Destaque: export depende do resultado da última análise em memória.

🚀

Como usar (30s)

Do objetivo ao arquivo gerado, em poucas etapas.

Abra o popup da extensão.
Clique em Analisar.
Revise os domínios e contagens.
Escolha o formato (json / txt / txt-simple) e exporte.

Referências popup/popup.js core/exporter.js infrastructure/download-manager.js

Fluxo de alto nível

Coletar

Busca abas via Chrome Tabs API e extrai URLs válidas.

Processar

Normaliza e valida URLs; remove duplicatas exatas.

Agrupar

Constrói URL-Matrizes por domínio para revisão e export seletivo.

Exportar

Gera payload e inicia download via chrome.downloads.

Referências infrastructure/tab-collector.js core/url-processor.js core/matrix-builder.js core/exporter.js infrastructure/download-manager.js background/service-worker.js

Quick Start

Instalação & Uso

Primeiros passos para rodar a extensão no navegador (modo desenvolvedor) e gerar seu primeiro export.

🧩

1) Instalar (modo desenvolvedor)

Carregue a pasta do projeto como uma extensão sem compactação.

Abra chrome://extensions (ou edge://extensions).
Ative Modo do desenvolvedor.
Clique em Carregar sem compactação.
Selecione a pasta raiz do projeto (onde está o manifest.json).

Referências manifest.json popup/popup.html background/service-worker.js

⚡

2) Usar (primeiro export)

Analise as abas, revise os grupos e exporte no formato desejado.

Abra o popup da extensão.
Clique em Analisar para gerar as URL-Matrizes.
Exporte tudo ou por domínio.
Escolha json, txt ou txt-simple.

Importante

Como o estado é temporário em memória, exportações dependem de uma análise prévia.

Referências popup/popup.js core/matrix-builder.js core/exporter.js infrastructure/download-manager.js

✅

Checklist rápido

Valide o fluxo ponta a ponta em 60s.

Abra 10+ abas em domínios diferentes e confirme o agrupamento.
Duplique uma URL e confirme a deduplicação após normalização.
Gere export em txt-simple e verifique “uma URL por linha”.

Referências core/url-processor.js core/matrix-builder.js core/exporter.js

Funcionalidades

O que já existe

Guia prático do que a extensão faz e como usar.

v1.0

📥

Coleta de URLs

Extrai URLs das abas abertas (janela atual ou todas), filtrando entradas inválidas/restritas.

Referências infrastructure/tab-collector.js background/service-worker.js

v1.0

🧹

Normalização + validação

Reduz ruído (ex.: parâmetros), aplica regras de consistência e valida antes de agrupar/exportar.

Referências core/url-processor.js utils/validators.js

v1.0

✅

Deduplicação exata

Remove duplicatas idênticas após normalização, mantendo saída enxuta e previsível.

Referências core/url-processor.js

v1.0

🧱

URL-Matriz

Agrupa por domínio e produz estrutura estável para UI e export (com contagens por grupo).

Referências core/matrix-builder.js

v1.0

📤

Exportação (json/txt/txt-simple)

Gera arquivos para inspeção humana e automação (uma URL por linha no txt-simple).

Referências core/exporter.js utils/constants.js

v1.0

⬇️

Download

Inicia o download via chrome.downloads com nome sugerido e MIME adequado ao formato.

Referências infrastructure/download-manager.js background/service-worker.js

v1.0

🧠

Estado temporário em memória

Resultado da análise é mantido apenas durante a sessão (entre analisar e exportar).

Referências background/service-worker.js

v1.0

🧾

Observabilidade (logs)

Logs estruturados ajudam a depurar validações, erros de export e respostas do Service Worker.

Referências utils/logger.js background/service-worker.js

v1.1

🪟

Seleção de janelas específicas

Permite escolher janelas específicas de um domínio para exportação seletiva, filtrando por windowId.

Referências popup/popup.js background/service-worker.js

Requisitos Funcionais

Escopo Atual

Especificações funcionais implementadas, mapeadas para os módulos responsáveis.

RF01 Implementado v1.0

Coleta de abas (Scan)

Coleta URLs de abas abertas (janela atual ou todas as janelas), ignorando URLs inacessíveis/restritas.

Orquestração\nbackground/service-worker.js\n\nInfra\ninfrastructure/tab-collector.js

RF02 Implementado v1.0

Normalização e validação

Normaliza URLs para consistência e valida entradas para reduzir erros no processamento e export.

Core\ncore/url-processor.js\n\nUtils\nutils/validators.js

RF03 Implementado v1.0

Deduplicação exata

Remove duplicatas exatas após normalização, mantendo o conjunto final enxuto e previsível.

Core\ncore/url-processor.js

RF04 Implementado v1.0

Agrupamento por domínio (URL-Matriz)

Constrói matrizes por domínio para permitir export total ou seletivo, com contagens por grupo.

Core\ncore/matrix-builder.js

RF05 Implementado v1.0

Exportação (json / txt / txt-simple)

Gera arquivos em formatos pensados para automação e inspeção humana, com saída consistente.

Core\ncore/exporter.js\n\nUtils\nutils/constants.js

RF06 Implementado v1.0

Download do arquivo exportado

Dispara o download do conteúdo exportado via chrome.downloads com nome sugerido.

Orquestração\nbackground/service-worker.js\n\nInfra\ninfrastructure/download-manager.js

RF07 Implementado v1.1

Seleção de janelas específicas

Permite escolher janelas específicas de um domínio para exportação seletiva, filtrando URLs por windowId.

UI\npopup/popup.js\n\nOrquestração\nbackground/service-worker.js

Requisitos Não Funcionais

Qualidade

Requisitos de qualidade, segurança, compatibilidade e manutenibilidade do projeto.

RNF01 Implementado v1.0

Compatibilidade (Manifest V3)

Arquitetura e execução compatíveis com MV3: Service Worker como módulo e mensagens runtime.

Config\nmanifest.json\n\nSW\nbackground/service-worker.js

RNF02 Implementado v1.0

Privacidade por padrão

Não envia dados para rede/terceiros: processamento e export acontecem localmente no navegador.

Design\nSem integração de rede\nSem serviços externos

RNF03 Implementado v1.0

Estado temporário e previsível

Mantém matrizes somente em memória entre “Analisar” e “Exportar” (sem persistência/histórico).

SW\nbackground/service-worker.js

RNF04 Implementado v1.0

Manutenibilidade e separação de camadas

Core isolado de UI e APIs do Chrome, facilitando evolução e testes unitários.

Core\ncore/*\n\nInfra\ninfrastructure/*\n\nUI\npopup/*

RNF05 Implementado v1.0

Segurança e validações

Valida entradas e formatos de export para reduzir erros e evitar comportamentos inesperados.

Utils\nutils/validators.js\n\nCore\ncore/exporter.js

RNF06 Implementado v1.0

Observabilidade (logs)

Logging estruturado para facilitar diagnóstico durante desenvolvimento e troubleshooting.

Utils\nutils/logger.js

Req. Funcionais Futuros

Roadmap

Itens planejados para versões futuras (prospectação). Mantém o foco: extrair e estruturar URLs, sem virar um gerenciador de abas.

v1.2.0 Planejado

Novas fontes de URLs

Adicionar coleta opcional via Bookmarks e Histórico para montar matrizes além das abas abertas.

Área\nInfrastructure + Core\n\nIdeia\nNovos coletores com mesma interface

v1.3.0 Planejado

Export mais flexível

CSV e opções de export (ordenar, incluir/excluir colunas, presets para automação).

Área\ncore/exporter.js\n\nNota\nSem dependências externas

v1.4.0 Planejado

Filtros e seleção na UI

Busca/filtros simples por domínio e seleção rápida (ex.: incluir/excluir domínios).

Área\npopup/popup.js\n\nNota\nMantém UI minimalista

v1.5.0 Planejado

Critérios adicionais de agrupamento

Agrupar por TLD, prefixos de path e regras configuráveis (sem interpretação semântica).

Área\ncore/matrix-builder.js\n\nNota\nConfig simples e previsível

Tech Planejado

Qualidade (tests + CI)

Testes automatizados do core (normalização/dedup/export) e pipeline de validação em CI.

Área\nCore + docs/TEST_EXAMPLES.md\n\nIdeia\nIntroduzir testes sem mudar arquitetura

Casos de Uso

Cenários

Cenários que descrevem como o usuário executa tarefas, do objetivo ao resultado esperado.

UC01 Definido v1.0

Analisar abas (gerar matrizes)

Objetivo: transformar abas abertas em URL-Matrizes prontas para exportação.

Atores: Usuário

Pré-condições: extensão instalada e popup acessível.

Pós-condições: matrizes exibidas (ou estado vazio/erro com mensagem).

Referências popup/popup.js background/service-worker.js infrastructure/tab-collector.js core/url-processor.js core/matrix-builder.js

UC02 Definido v1.0

Exportar tudo

Objetivo: exportar todas as matrizes/URLs em um único arquivo.

Atores: Usuário

Pré-condições: análise concluída com matrizes em memória.

Pós-condições: download iniciado no formato escolhido.

Destaque: o export é uma ação explícita do usuário e depende do estado da última análise.

Referências popup/popup.js background/service-worker.js core/exporter.js infrastructure/download-manager.js

UC03 Definido v1.0

Exportar por domínio

Objetivo: exportar apenas uma URL-Matriz específica (um domínio).

Atores: Usuário

Pré-condições: análise concluída e domínio disponível na lista.

Pós-condições: download iniciado contendo somente aquele grupo.

Referências popup/popup.js background/service-worker.js core/exporter.js core/matrix-builder.js

UC04 Definido v1.0

Nova análise (reset)

Objetivo: reiniciar o fluxo para refletir mudanças nas abas/janelas.

Atores: Usuário

Pré-condições: usuário está na tela de resultados ou com estado carregado.

Pós-condições: estado do popup é resetado e uma nova análise pode ser executada.

Referências popup/popup.js background/service-worker.js

UC05 Definido v1.1

Exportar por janelas específicas

Objetivo: exportar URLs de um domínio filtradas por janelas específicas.

Atores: Usuário

Pré-condições: análise concluída e domínio com múltiplas janelas disponível.

Pós-condições: download iniciado contendo apenas URLs das janelas selecionadas.

Destaque: permite granularidade adicional ao exportar por domínio, selecionando apenas janelas relevantes.

Referências popup/popup.js background/service-worker.js core/exporter.js

Diagramas de Casos de Uso

Fluxo

Fluxos em cards (sem imagens), no formato passo a passo.

UC01 Scan v1.0

UC01 — Analisar abas

Abrir popup

Usuário abre a extensão e visualiza o estado atual.

Iniciar análise

Usuário aciona “Analisar” para coletar URLs das abas.

Coletar + processar

Coleta abas, aplica validações, normaliza e deduplica URLs.

Agrupar + exibir

Constrói URL-Matrizes por domínio e renderiza o resultado no popup.

Pré-condições

Extensão instalada e permissões concedidas; popup acessível.

Pós-condições

Lista de matrizes exibida (ou estado vazio/erro com mensagem).

Fluxo alternativo

Sem URLs válidas: exibe estado vazio. Em falha: exibe erro e permite tentar novamente.

Referências popup/popup.js background/service-worker.js infrastructure/tab-collector.js core/url-processor.js core/matrix-builder.js

UC02 Export v1.0

UC02 — Exportar tudo

Escolher formato

Usuário seleciona o formato (json/txt/txt-simple).

Gerar payload

Core gera o conteúdo exportável de forma consistente.

Iniciar download

Infra dispara o download via chrome.downloads.

Confirmar resultado

Usuário recebe o arquivo; pode repetir com outro formato se desejar.

Pré-condições

Uma análise foi executada e há matrizes em memória para export.

Pós-condições

Download iniciado com nome sugerido e mime compatível com o formato.

Fluxo alternativo

Sem análise: UI solicita executar “Analisar” antes. Em erro de download: exibe mensagem e permite repetir.

Referências popup/popup.js background/service-worker.js core/exporter.js infrastructure/download-manager.js utils/constants.js

UC03 Export v1.0

UC03 — Exportar por domínio

Selecionar matriz

Usuário escolhe um domínio específico na lista.

Gerar subset

Export limita o payload ao grupo selecionado.

Iniciar download

Infra inicia o download do arquivo do grupo.

Repetir por grupos

Usuário pode exportar outros domínios sem refazer a análise.

Pré-condições

Análise concluída; domínio disponível na lista de matrizes.

Pós-condições

Arquivo exportado contém apenas as URLs do domínio selecionado.

Fluxo alternativo

Domínio vazio: export desabilitado/mostra aviso. Em erro: exibe mensagem e mantém a lista.

Referências popup/popup.js background/service-worker.js core/exporter.js core/matrix-builder.js

UC04 Reset v1.0

UC04 — Nova análise (reset)

Abrir resultados

Usuário está na tela de resultados ou com estado carregado.

Acionar reset

Usuário clica em “Nova análise”.

Limpar estado UI

Popup volta ao estado inicial e limpa indicadores do resultado anterior.

Reanalisar

Usuário executa uma nova análise para refletir mudanças nas abas.

Pré-condições

Usuário tem a extensão aberta; deseja atualizar o dataset.

Pós-condições

Fluxo reiniciado; uma nova análise pode ser executada imediatamente.

Fluxo alternativo

Se o popup já está no estado inicial, o reset apenas mantém o estado e orienta a analisar.

Referências popup/popup.js background/service-worker.js

UC05 Export v1.1

UC05 — Exportar por janelas específicas

Abrir seleção de janelas

Usuário clica no botão de seleção de janelas em um domínio.

Selecionar janelas

Usuário marca as janelas desejadas via checkboxes na lista.

Filtrar + gerar subset

Export filtra URLs pelo windowId das janelas selecionadas.

Iniciar download

Infra inicia o download do arquivo filtrado por janelas.

Pré-condições

Análise concluída; domínio com múltiplas janelas disponível.

Pós-condições

Arquivo exportado contém apenas URLs das janelas selecionadas.

Fluxo alternativo

Nenhuma janela selecionada: botão de export desabilitado. Em erro: exibe mensagem e permite tentar novamente.

Referências popup/popup.js background/service-worker.js core/exporter.js

Arquitetura e Estrutura Completa

Clean Architecture v1.0

Clean Architecture com dependências unidirecionais (camadas externas dependem das internas). Separação clara entre core (puro), orquestração (MV3) e integrações com Chrome APIs.

Core

Lógica de negócio pura (core/)

Browser

Integração com Chrome APIs (infrastructure/)

Orquestração

Coordenação de fluxos MV3 (background/)

UI

Interface do usuário (popup/)

📁Estrutura do Projeto

Somente o que é essencial para a extensão funcionar (runtime).

📄

manifest.json

Manifest V3: define permissões, action/popup, service worker e recursos da extensão.

📁

background/

Orquestração MV3: recebe comandos do popup, coordena análise/export e mantém estado temporário em memória.

background/service-worker.js

Ponto central do runtime: handlers de mensagem, cache do resultado da análise, filtragem por windowIds v1.1 e gatilhos de export/download.

📁

core/

Processamento browser-agnostic: normalização, validações, construção de matrizes e geração de payloads.

core/url-processor.js

Normaliza/filtra URLs e aplica regras (ex.: remover parâmetros, ignorar internos, validar formato).

core/matrix-builder.js

Agrupa por domínio e constrói a URL-Matriz (estrutura usada no popup e no export).

core/exporter.js

Converte matrizes em formatos de export (json/txt/txt-simple), incluindo metadados e ordenação.

📁

infrastructure/

Integração com Chrome APIs (tabs/downloads): coleta abas e gerencia downloads.

infrastructure/tab-collector.js

Coleta abas, extrai URLs e entrega um dataset consistente para o core processar.

infrastructure/download-manager.js

Inicia o download com nome e MIME apropriados, via chrome.downloads.

📁

popup/

UI: dispara comandos (analisar/exportar), exibe métricas, lista de matrizes e tela de seleção de janelas v1.1.

CSS

popup/popup.css

Estilos do popup (tema/cores), mantendo UX consistente com a extensão.

popup/popup.js

Handlers de UI: envia mensagens, renderiza resultados, controla estado da tela e seleção de janelas v1.1.

📁

utils/

Constantes, logger e validações reutilizadas entre camadas.

📦

types/index.js

Tipos via JSDoc para guiar estrutura de dados e manter o core previsível.

Módulos JS (runtime)

CSS

Arquivo CSS (popup)

<800

704

Maior arquivo (linhas) — popup/popup.css

ES6

Modules

Imports/exports nativos (MV3)

Tecnologias Utilizadas

Stack

Stack do projeto e onde cada tecnologia aparece no código.

Core & Qualidade

JavaScript (ES Modules)

Uso no projeto: módulos independentes por responsabilidade (core/infra/background/popup).

Exemplos core/url-processor.js core/matrix-builder.js core/exporter.js

Clean Architecture (camadas)

Uso no projeto: core puro; infraestrutura isola APIs; service worker coordena fluxos; UI só apresenta.

Referências core/* infrastructure/* background/service-worker.js popup/popup.js

Tipagem via JSDoc

Types

Uso no projeto: estrutura de dados documentada para manter matrizes/export previsíveis.

Referências types/index.js

Extensão & APIs

Manifest V3

MV3

Uso no projeto: define permissões, popup e Service Worker como módulo.

Config manifest.json

Chrome Tabs API

API

Uso no projeto: coleta URLs de abas abertas para montar o dataset.

Referências infrastructure/tab-collector.js

Chrome Downloads API

API

Uso no projeto: dispara o download do conteúdo exportado (com nome/mime adequados).

Referências infrastructure/download-manager.js

UI & Docs

HTML + CSS (Popup)

Uso no projeto: interface enxuta com estados claros (carregando/resultado/erro).

Referências popup/popup.html popup/popup.css popup/popup.js

Mensageria runtime

runtime

Uso no projeto: UI manda comandos; Service Worker responde com resultados/erros.

Referências popup/popup.js background/service-worker.js

Documentação

DOC

Uso no projeto: guias técnicos (dados, fluxos e formatos) + página consolidada (este HTML).

Referências docs/ARCHITECTURE.md docs/EXPORT_FORMAT.md docs/DATA_FLOW.md docs/TUE-Documentation-v1.html

Desenvolvimento

Como evoluir

Decisões práticas para manter o projeto simples, seguro e evolutivo — sempre preservando a separação de camadas.

🧭

Visão Geral

A extensão é construída em JavaScript com ES Modules e Manifest V3, sem dependências externas no runtime. O core permanece independente das APIs do Chrome.

Referências manifest.json core/* infrastructure/* background/service-worker.js popup/*

🛡️

Segurança

Permissões mínimas e ações explícitas do usuário. Sem tráfego de rede: os dados ficam locais.

Destaque: valide entradas antes de exportar.

Referências manifest.json utils/validators.js

⚡

Desempenho

Coleta apenas dados essenciais e processa em memória; UI renderiza grupos de forma direta para evitar overhead.

Destaque: normalização reduz duplicidade falsa e melhora agrupamento.

Referências core/url-processor.js core/matrix-builder.js popup/popup.js

🧱

Estrutura & Boas Práticas

Regras de evolução: mudanças de regra em core/; integrações em infrastructure/; coordenação no SW; UI só apresenta.

Mapa rápido core/ regras e transformações infrastructure/ Chrome APIs background/ fluxo/estado popup/ UI

🧪

Testes & CI

O caminho natural é começar testando o core (normalização/dedup/export) e automatizar validações de regressão.

Referências core/url-processor.js core/exporter.js docs/TEST_EXAMPLES.md

🤝

Contribuição

Para evoluir sem quebrar camadas: implemente regras no core, mantenha APIs em infrastructure e conecte tudo via mensagens no Service Worker.

Referências popup/popup.js background/service-worker.js core/* infrastructure/*

Estrutura (visão rápida)

background/          Service Worker (MV3)
core/               Lógica de processamento (browser-agnostic)
infrastructure/     Integrações com APIs do Chrome (tabs, downloads)
popup/              UI (HTML/CSS/JS)
utils/              Constantes, logger e validadores
types/              Tipos via JSDoc
docs/               Documentação

Checks manuais úteis

Abrir 10–20 abas com domínios diferentes e confirmar agrupamento por domínio.
Duplicar a mesma URL em abas diferentes e confirmar deduplicação após normalização.
Exportar json, txt e txt-simple e validar o arquivo gerado.