Fazer mudanças pequenas em uma biblioteca de interface com estado sem quebrar quem a usa

## Encontrar o dono do estado e alterá-lo só onde a biblioteca permite Comece identificando o responsável pelo estado, o limite de atualização e o contrato público afetados pela solicitação. Em um modelo de estado imutável, leia a partir de um instantâneo consistente e faça alterações somente dentro do contexto de atualização autorizado pela biblioteca. Trate as referências a nós ou entidades como referências versionadas; não mantenha pressupostos de mutabilidade entre limites de atualização. Mantenha o registro de recursos, os comandos, as transformações e os observadores dentro do ciclo de vida documentado. Para trabalhos novos, prefira o mecanismo atual de extensão ou composição, mas preserve qualquer caminho de integração legado que continue sendo compatível. Garanta que todo registro tenha um caminho claro de limpeza e preserve os formatos de serialização que os consumidores existentes ainda possam carregar. ## Buscar com ferramentas que entendem a sintaxe e manter a mudança pequena Use pesquisa e reescrita sensíveis à sintaxe quando uma alteração envolver imports, locais de chamada, anotações de tipo ou código estruturado. Expressões regulares orientadas a linhas podem ignorar formas com várias linhas e corresponder a identificadores sem relação. Confirme as correspondências candidatas na árvore sintática antes de aplicar uma reescrita ampla. Mantenha a alteração orientada ao comportamento e restrita ao seu âmbito. Use nomes específicos do domínio, cláusulas de guarda para estados inválidos ou já tratados e um fluxo de sucesso claro. Extraia funções auxiliares somente quando elas nomearem uma responsabilidade ou simplificarem o chamador. Não misture refatoração oportunista, registros de depuração, nomes temporários ou formatação sem relação no ajuste final. Ao criar uma função de fábrica sem efeitos colaterais no âmbito do módulo, preserve a convenção de anotação do projeto para eliminação de código não utilizado e atualize a regra que a impõe caso a própria família de fábricas seja ampliada. ## Manter as APIs públicas compatíveis e usar o document e o window do próprio elemento Pressuponha que o código externo depende dos nomes públicos, das assinaturas, do comportamento e dos dados serializados existentes. Prefira APIs aditivas e parâmetros opcionais. Quando uma alteração incompatível for inevitável, preserve o caminho antigo e marque-o como obsoleto antes de retirá-lo, além de verificar tanto o caminho atual quanto o de compatibilidade. Mantenha todos os sistemas de tipos compatíveis e todas as superfícies de declarações geradas que forem afetadas pela API. O código voltado ao navegador deve obter o document e o window proprietários a partir da raiz ou do elemento correspondente, em vez de depender de objetos globais do ambiente. Use funções auxiliares cientes do contexto para seleção, foco, alvo de eventos e percurso de elementos pais, evitando que raízes de sombra e documentos incorporados leiam silenciosamente do ambiente errado. Em alterações de serialização, tratamento de solicitações, URLs, saída de HTML ou scripts, caminhos do sistema de arquivos, autenticação ou dependências, identifique a entrada não confiável e a proteção de validação mais próxima. Prefira um comportamento que bloqueie por padrão em caso de falha, mantenha segredos fora de registros e artefatos e verifique os lados de escrita e leitura de qualquer protocolo. ## Escrever primeiro um teste que falha e escolher entre teste unitário ou em navegador real Para uma alteração de comportamento ou correção de defeito, defina primeiro a invariante observável. Adicione ou atualize o teste focado mais próximo, execute-o antes da implementação quando for viável e confirme que ele falha pelo motivo esperado. Faça a menor alteração que o satisfaça, execute novamente o teste focado e só então amplie para a verificação exigida pela superfície afetada. Use testes unitários em ambiente simulado para lógica que não dependa do leiaute real nem do comportamento de seleção. Use testes em navegador real para leiaute, seleção, foco, raízes de sombra ou comportamento entre documentos. Reserve os testes de ponta a ponta para navegação, integração completa da aplicação ou protocolos que exijam um sistema em execução. Gere o artefato específico consumido pelo teste antes de confiar no resultado. Não substitua um teste focado por um comando amplo para todo o repositório sem uma razão. A aprovação de um conjunto de testes sem relação não comprova o limite alterado. ## Revisar as diferenças e adicionar a nota de lançamento antes de terminar Antes de concluir, revise as diferenças como faria uma pessoa que acaba de contribuir para o projeto. Confirme que os nomes revelam o significado do domínio, os casos extremos usam guardas explícitas, o fluxo principal é legível, a limpeza está completa e nenhum contrato público foi alterado acidentalmente. Execute o formatador, o verificador de regras, o verificador de tipos ou a tarefa de instantâneo da API exigida pelo pacote afetado. Adicione a nota de lançamento ou o registro de alterações definido pelo repositório quando um comportamento publicado mudar. Descreva a correção ou o recurso percebido pelo usuário, não os detalhes da implementação. Mantenha links de sessões privadas, credenciais e referências exclusivamente internas fora dos textos de commits e solicitações de alteração, e registre as evidências dos testes focados que sustentam a mudança.