Depuração de Download de Exportação

Use isso quando uma exportação ou download parecer funcionar, mas produzir um arquivo vazio, ausente ou inutilizável. Ele é otimizado para pré-visualizações de navegador, captura de iframe e shells do Electron.

Regra principal

Separe a captura do salvamento. Prove que a carga útil da exportação tem bytes não nulos antes de depurar o caminho de destino. Um arquivo de 0 KB geralmente significa que o seletor nativo ou o host criou o arquivo de destino, e a gravação falhou ou foi bloqueada.

Evidências

• Registre o tipo de carga útil, tipo MIME, comprimento em bytes, URL do objeto ou caminho da URL de dados e o nome/mensagem do erro lançado.
• Verifique a saída do console do navegador e os logs do aplicativo em torno de showSaveFilePicker, createWritable, <a download>, URL.createObjectURL e revogação de URL.
• No Electron, inspecione o caminho will-download: nome do arquivo, MIME, extensão do arquivo, filtros de diálogo de salvamento, cancelamento e tamanho final do arquivo.
• Confirme o tamanho real do arquivo baixado no disco e se ele abre em um visualizador de imagens normal.

Ordem de correção

1. Prepare e valide a carga útil da exportação primeiro; desabilite Salvar até que os bytes estejam disponíveis.
2. Prefira o canal de salvamento estável mais simples para o host. Se showSaveFilePicker().createWritable() falhar, estiver em sandbox ou criar arquivos vazios, direcione para <a download> ou o gerenciador de downloads do Electron em vez disso.
3. Evite abrir um seletor nativo antes que a carga útil esteja pronta. Isso impede que o host crie um arquivo de destino vazio em caso de falha posterior na gravação.
4. Para fallback de PNG, prefira uma URL de dados verificada e não vazia quando URLs de blob, tempo de revogação, CSP ou sandboxing de iframe forem suspeitos.
5. No Electron, adicione filtros explícitos de Salvar como para extensões de imagem exportadas (.png, .jpg, .jpeg, .webp) para que os usuários possam escolher um destino de imagem real.
6. Mantenha a interface do usuário restrita: seleção de formato, dica de nome/caminho do arquivo, estados claros de pendência e erro, e uma ação de salvamento principal.

Validação

• Adicione ou atualize testes para preparação de carga útil não vazia, comportamento de salvamento de fallback, mapeamento de extensão de arquivo/MIME e estados de UI desabilitados/erro.
• Execute testes de exportação focados, depois pnpm --filter @open-design/web typecheck.
• Se o tratamento de download do Electron mudou, execute também pnpm --filter @open-design/desktop typecheck.
• Antes de enviar, execute pnpm guard, inspecione a diferença preparada para arquivos não relacionados, artefatos gerados e segredos acidentais, e use o fluxo de trabalho de portão de qualidade de PR do repositório se a correção estiver sendo preparada para revisão.