Alterar uma extensão para vários navegadores sem vazar segredos nem quebrar os dados salvos

## Identificar primeiro a camada afetada da extensão e suas regras locais Antes de alterar o código, identifique a camada afetada: lógica em segundo plano, interface do usuário, utilitários compartilhados, declarações de navegador, ferramentas de compilação, testes ou atualizações do estado armazenado. Leia as instruções específicas da camada mais próxima antes de editar; arquivos de automação do fluxo de trabalho muitas vezes têm conexões adicionais e regras da fila de mesclagem. Use o ambiente de execução gerenciado pelo repositório e o wrapper do gerenciador de pacotes. Mantenha a configuração no arquivo de ambiente local designado, nunca no código-fonte rastreado. Prefira a linguagem tipada atual em todo novo arquivo de implementação; arquivos legados sem tipos podem permanecer até que uma alteração solicitada justifique a conversão. Use o formatador atribuído a cada família de arquivos. O formatador de código é responsável pelos arquivos tipados e de componentes, enquanto o formatador de dados estruturados é responsável pelos dados de pacotes e configuração. Antes da entrega, execute a formatação dos arquivos alterados, a verificação de tipos estáticos, o lint e as verificações de dependências circulares. Mantenha as funções focadas, reduza o aninhamento com retornos antecipados, remova a lógica repetida somente quando a extração esclarecer a responsabilidade e não deixe registros de depuração nem código comentado. ## Manter segredos localmente e regenerar políticas ao mudar dependências Trate credenciais de API, endpoints de monitoramento, senhas de teste e material de assinatura como segredos locais. Forneça marcadores de posição documentados, mas nunca envie valores reais ao repositório nem inclua estados confidenciais em registros de diagnóstico. Toda adição, atualização ou remoção de dependência é uma alteração na cadeia de suprimentos. Conclua toda a sequência: 1. Atualize a declaração do pacote e o arquivo de bloqueio. 2. Remova duplicatas do arquivo de bloqueio por meio do comando compatível. 3. Recalcule a lista de pacotes autorizados a executar scripts de instalação. 4. Gere novamente as políticas de capacidades que restringem o acesso das dependências às APIs do hospedeiro. 5. Gere novamente a atribuição de terceiros. 6. Compile e teste com a política de segurança de produção ativada. Inclua na mesma revisão todas as alterações geradas de políticas e atribuições. Uma compilação de desenvolvimento sem políticas pode ser usada para iteração rápida, mas nunca substitui a compilação final protegida. Gere novamente as políticas sensíveis à plataforma na plataforma-alvo, em vez de enfraquecê-las para fazer a compilação passar. ## Projetar os controladores de segundo plano com estado declarado e ações de domínio Use controladores para a lógica de negócios em segundo plano e a comunicação por mensagens entre subsistemas. Para cada propriedade armazenada, declare se ela é anônima, segura para instantâneos de diagnóstico ou registros de estado, persistente e consumida pela interface. Siga estas regras de estado: - Exporte uma fábrica de estado padrão que retorne um objeto novo, nunca um objeto padrão mutável compartilhado. - Receba as dependências do construtor por meio de um único objeto nomeado de opções, em vez de argumentos posicionais. - Modele ações de domínio como adicionar, remover, aprovar ou rejeitar; evite definidores genéricos de campos. - Armazene somente o estado essencial e derive contagens, sinalizadores e projeções por meio de seletores exportados. - Valide as entradas das ações antes de atualizar o estado. - Implemente a limpeza do ciclo de vida para temporizadores, assinaturas, ouvintes e canais de mensagens e, depois, delegue à limpeza do controlador pai. Mantenha sincronizados o código-fonte, os tipos, os testes colocados junto ao controlador, o registro e os seletores afetados. Uma alteração na estrutura do estado também exige uma etapa de atualização numerada. ## Colocar o código na camada responsável e atualizar os arquivos ligados Coloque componentes reutilizáveis de interface junto com seus estilos, tipos, testes, histórias, documentação e exportação pública. Coloque componentes exclusivos de uma página na camada da página, auxiliares exclusivos do segundo plano junto ao código de segundo plano e utilitários, constantes e tipos realmente compartilhados em módulos compartilhados. Quando o comportamento mudar, inspecione os arquivos diretamente acoplados: - Alterações em controladores podem exigir testes, tipos, registro e atualizações de estado. - Alterações nas propriedades de componentes podem exigir testes, histórias, estilos, documentação e exportações. - Alterações no estado global podem exigir seletores e componentes que os consomem. - Alterações na compilação ou nas declarações de navegador podem exigir fixtures específicos do alvo e cobertura de ponta a ponta. Não copie lógica compartilhada apenas para evitar escolher um responsável. Mova-a para a camada comum mais restrita, use injeção de dependência quando necessário e resolva importações circulares em vez de aceitar uma lista ampliada de exceções. ## Compilar e testar separadamente cada navegador e sinalizador de recurso Mantenha um caminho distinto de compilação e teste para cada geração compatível de declarações de navegador. Considere diferenças como páginas persistentes em segundo plano em comparação com service workers, modelos de permissão e disponibilidade de namespaces. Use a abstração de API para vários navegadores no código compartilhado. Isole as diferenças inevitáveis entre alvos em uma pequena camada de compatibilidade, em vez de espalhar condições pelos recursos. Os sinalizadores de recursos devem ser entradas explícitas da compilação: - Use a configuração local documentada para um desenvolvimento reproduzível. - Use substituições de ambiente por um único comando em experimentos isolados. - Use uma substituição local da declaração somente em cenários de teste de sinalizadores remotos. - Compile e teste a mesma combinação de alvo e sinalizadores que será entregue. Se o usuário não indicar um navegador, use o alvo padrão documentado do projeto. Quando a solicitação indicar um alvo, escolha os comandos correspondentes de desenvolvimento, produção e ponta a ponta, em vez de presumir compatibilidade com base em outra compilação. ## Criar componentes de interface e otimizar só depois de medir Use componentes funcionais e hooks, desestruture as propriedades no limite, mantenha local o estado usado apenas localmente e use a camada de estado compartilhado somente para dados que atravessam recursos. Para garantir a correção e o desempenho da renderização: - Use identificadores estáveis do domínio como chaves de listas dinâmicas, nunca posições do array. - Calcule os valores derivados de exibição durante a renderização, em vez de copiá-los para o estado por meio de um efeito. - Memoize ordenações, filtragens ou agregações de alto custo somente quando o trabalho repetido for significativo. - Estabilize os retornos de chamada transmitidos a filhos memoizados quando a mudança de referências causar novas renderizações. - Defina objetos e estilos realmente estáticos fora do componente. - Considere a virtualização de listas grandes depois de medir o custo da renderização. Copie antes de ordenar quando as entradas forem imutáveis. Analise primeiro os componentes renderizados com frequência ou de cálculo dispendioso; não adicione memoização a componentes simples e raramente renderizados sem evidências. ## Reproduzir o bug com um teste que falha, corrigir e testar de novo Para um defeito, primeiro adicione um teste focado que reproduza a falha, execute-o e confirme a falha, implemente a menor correção, confirme que o teste passa e depois execute a cobertura diretamente relacionada. Coloque os testes unitários junto ao código-fonte e teste o comportamento por meio de interfaces públicas, em vez de métodos privados. Use testes de integração para os limites entre subsistemas. Use testes de ponta a ponta para fluxos de trabalho reais do navegador e compile primeiro o artefato de teste dedicado. Durante a iteração, uma compilação mais rápida e desprotegida pode ser aceitável; a verificação final deve usar a política de segurança de produção e o navegador-alvo solicitado. Quando a verificação visual for solicitada explicitamente: 1. Inicie o ambiente real de teste da extensão. 2. Inspecione a tela atual antes de agir. 3. Percorra o fluxo do usuário com os controles do navegador. 4. Capture uma imagem da tela ou uma descrição da tela final como evidência. 5. Limpe a sessão de teste mesmo depois de uma falha. Se a ferramenta visual necessária não estiver disponível, informe essa limitação e não alegue verificação visual apenas com base na inspeção do código. Revise as alterações dos instantâneos antes de aceitá-las; atualize um instantâneo somente quando a alteração de comportamento for intencional. ## Escrever uma atualização numerada quando a forma dos dados salvos mudar Crie uma atualização numerada sempre que a estrutura do estado persistente mudar. Gere-a por meio da ferramenta do repositório para manter consistentes a ordem e o registro. Uma atualização deve: - Aceitar corretamente entradas antigas, incompletas e parcialmente corrompidas. - Clonar a entrada e retornar um novo objeto de estado, em vez de alterar o valor do chamador. - Transformar somente o intervalo de versões e as propriedades sob sua responsabilidade. - Registrar explicitamente a versão de destino. - Preservar dados de usuário não relacionados. Teste estados antigos representativos, campos ausentes, valores opcionais malformados, expectativas de idempotência e o novo resultado exato. Execute tanto o teste de atualização quanto os testes do controlador ou do recurso que consomem o estado atualizado. ## Classificar os erros e corrigi-los sem desligar as verificações Leia o primeiro erro acionável antes de alterar o ambiente. Classifique-o como falha de formatação, tipo, dependência, política de capacidades, compilação do navegador, dados de teste, artefato obsoleto, porta ou importação circular e execute o diagnóstico mais restrito para essa classe. Quando um teste que antes passava falhar após a alteração, determine se a implementação sofreu uma regressão ou se o comportamento esperado mudou intencionalmente. Atualize o teste somente no segundo caso e documente a razão comportamental. Em falhas de ponta a ponta, verifique se existe a compilação de teste correta e atual, use a saída de depuração e mantenha o navegador em execução somente durante uma inspeção ativa. Em falhas de política, gere novamente a política a partir das dependências declaradas e do acesso ao hospedeiro; não desative permanentemente a aplicação. Remova caches, resultados de compilação, pacotes instalados, dados do navegador ou instantâneos somente depois de identificar o alvo exato e confirmar que a regeneração é segura. Não use uma limpeza ampla como primeira etapa de solução de problemas. ## Fazer commits, pushes e pedidos de revisão só quando solicitados Não altere a configuração do repositório nem execute comandos destrutivos de controle de versão. Não faça stage, commit ou push nem abra uma solicitação de revisão, a menos que o usuário tenha solicitado explicitamente essa ação específica. Quando houver autorização: - Inclua no stage somente os arquivos pertencentes à alteração solicitada. - Formate e teste a superfície alterada antes do commit. - Use a convenção estruturada de commits do repositório. - Faça push somente quando ele tiver sido solicitado. - Abra uma solicitação de revisão em rascunho, a menos que o usuário solicite explicitamente o status pronto. - Siga o modelo de revisão e oculte completamente as seções não aplicáveis. As seções de testes manuais devem descrever ações humanas e resultados visíveis, não comandos automatizados de lint ou teste. Inclua evidências de antes e depois para alterações visíveis da interface, explique decisões não óbvias, vincule o trabalho relacionado e identifique notas de alteração voltadas ao usuário quando necessário. Durante a revisão, responda aos comentários e adicione commits de acompanhamento, em vez de reescrever o histórico já revisado. Antes da mesclagem, exija conversas resolvidas, aprovações, automação bem-sucedida e o título de squash esperado pelo repositório. Finalize com uma lista de verificação proporcional: formatação dos arquivos alterados, tipos, dependências circulares, testes focados, compilações afetadas, arquivos relacionados, documentação, políticas de capacidades de produção quando as dependências mudarem e evidências visuais reais quando solicitadas.