📸 Introdução: um portfólio de fotografia em produção ao terceiro dia

O Framed by Santi é o site de @framedbysanti, um fotógrafo amador que fotografa as ruas de Nova Iorque com uma Fujifilm X100VI. Tem duas faces: um site público para mostrar as fotos dele e um painel privado para que ele próprio publique sem depender de ninguém.

Começou como um presente para um amigo, mas este artigo não é sobre isso: é sobre como o construí em muito pouco tempo, com a ajuda do Claude Code, sem abdicar da qualidade.

Os números, tirados do repositório:

• 📅 9 dias com commits, de 13 a 26 de outubro de 2026.
• 🚀 Em produção ao dia 3: site público e painel privado.
• 🔀 189 commits e 35 pull requests; cada alteração foi testada por mim, como visitante e como admin, antes de chegar a produção.
• 🧪 117 ficheiros de teste com 857 casos.
• 🌍 Três idiomas: inglês, espanhol e português.
• 💯 100 nas quatro categorias do Lighthouse (desktop, rede 4G).

🤖 Como trabalhei: agentes de IA, mas com método

Construí-o no terminal com agentes de IA (Claude Code) configurados com o gentle-ai, a ferramenta de código aberto de Alan Buscaglia (Gentleman Programming). Não é "pedir um site à IA": é um fluxo de trabalho com regras.

• ODD (Organic-Driven Development): as alterações pequenas fazem-se diretamente; o trabalho grande tem um documento de tarefas com os requisitos copiados literalmente, para que nada se perca entre sessões.
• Engram: memória persistente. Cada decisão, erro resolvido ou preferência fica guardada e o agente recupera-a na sessão seguinte. Por exemplo: "pergunta antes de fazer push, mesmo para staging".
• Testes primeiro: para cada regra nova, primeiro um teste que falha e depois o código que o faz passar.
• Ramos e revisão: cada alteração sai de um ramo, sobe para develop, testo-a em staging e só chega a main (produção) quando eu a aprovo.

A divisão foi clara:

• 🤖 O agente: escreveu o código e os testes, investigou os erros, propôs soluções e abriu os PR.
• 🙋 Eu: decidi o que construir e como tinha de funcionar, revi cada alteração, corrigi o agente quando se enganava e aprovei cada entrada em produção.

💡 A IA escreve depressa; o que torna o resultado bom é verificar. Cada PR passou lint, testes e build, e nenhuma alteração chegou a produção sem a minha aprovação.

🧱 Stack e arquitetura

Frontend

• Angular 22 sem Zone.js (zoneless), com Signals para todo o estado e componentes standalone.
• TypeScript 6 em modo estrito: sem any e com tipos de retorno explícitos.
• CSS nativo com nesting, BEM e mobile-first. Sem pré-processador.
• Vite 8 com @analogjs/vite-plugin-angular como única ferramenta de build.
• Transloco para os três idiomas.

Serviços

• Vercel: alojamento e quatro funções serverless.
• Firebase Auth e Firestore: login do painel e dados (séries, temas, definições).
• Cloudinary: armazenamento e entrega de fotos, com uploads assinados.
• DeepL: tradução automática dos textos.
• Resend: o email do formulário de contacto.

As quatro funções de api/

As três do painel verificam que o utilizador é admin da mesma forma: leem o documento dele no Firestore com o token do próprio utilizador, por isso são as regras de segurança do Firestore que decidem, não um segredo no servidor.

🖼️ O site público

• As publicações são séries, como um carrossel do Instagram: várias fotos com um título e uma história.
• Início com a última série num carrossel que se pode arrastar.
• Galeria com uma secção por série e filtro por temas.
• Visor em ecrã inteiro: zoom e deslocação (beliscar, arrastar, toque duplo, roda), gestos para mudar de foto, miniaturas, pré-carregamento da foto seguinte e uma transição suave entre fotos.
• View Transitions entre páginas, com um efeito de íris como o diafragma de uma câmara.
• Sobre com a história do Santi nas palavras dele e um formulário de contacto. O email dele nunca chega à página.
• Idiomas a sério: datas, números e plurais seguem o idioma ativo (en-US, es-ES, pt-PT).
• Com prefers-reduced-motion, nada é animado.

A página inicial. Clica para a veres ao vivo.

A galeria com o filtro por temas.

O visor: zoom, setas e miniaturas.

🔐 O painel privado

O painel vive em /admin e não tem nenhuma ligação pública: só se chega lá escrevendo o caminho.

• Biblioteca de séries: interruptor de publicada ou rascunho, editar e apagar.
• Editor de séries: arrastar fotos, pré-visualizá-las, reordená-las e escrever os textos num separador por idioma.
• Fotos preparadas no navegador: antes do upload, cada foto é redimensionada e recomprimida até um máximo de 6000 px e 10 MB, baixando a qualidade do JPEG por passos até caber. Assim respeitam-se os limites do plano gratuito da Cloudinary sem que o Santi tenha de pensar nisso.
• Tradução automática: o Santi escreve num idioma e, ao publicar, o DeepL preenche os que faltam. Cada idioma pode ser corrigido à mão.
• Temas: criam-se e apagam-se a partir do painel.
• Limpeza automática: ao abrir a biblioteca, as fotos da Cloudinary que já nenhuma série usa são apagadas em segundo plano.
• Definições: foto de perfil e alteração da palavra-passe.
• Também no telemóvel: o painel adapta-se ao ecrã do telemóvel, e no login pode-se mostrar ou ocultar a palavra-passe.
• E um easter egg só para o admin: um cantinho para continuar com força. 💪

A biblioteca: cada série é publicada ou passa a rascunho com um interruptor.

O editor: fotos à esquerda, textos por idioma e o botão para traduzir à direita.

⚡ Desempenho: medir, cortar e voltar a medir

Não deixei o desempenho para o fim: medi com o Lighthouse, ataquei o que mais pesava e voltei a medir. É assim que está hoje em desktop com rede 4G:

Primeira ronda: de 44 a 73 em telemóvel

A primeira medição, a 15 de outubro em telemóvel com 4G lento (o caso mais exigente), deu um desempenho de 44-48, com um CLS de 0,333 e um LCP de 7,5 s. Com três alterações resolvi quase tudo:

• Pré-carregar a foto principal da página inicial a partir do index.html, com fetchpriority="high". O script de pré-carregamento vem antes de qualquer folha de estilos, porque uma folha pendente bloqueia os scripts que vêm a seguir.
• A página inicial vai no pacote principal, sem carregamento diferido, para não acrescentar uma viagem de rede antes de pintar a primeira página.
• O rodapé é pintado depois da primeira navegação. Era o responsável por todo o CLS. O carrossel da última série também reserva o seu espaço enquanto carrega.

Resultado em telemóvel: desempenho 73, CLS 0,001 e LCP 5,6 s.

Segunda ronda: tirar o que não fazia falta

• Tipos de letra próprios. Sirvo-os a partir do próprio domínio, sem a ida e volta ao Google Fonts.
• Firebase fora das páginas públicas. Ao rever o build vi que o pacote do Firebase pesava 563 kB (168 kB comprimidos) e era pré-carregado em todas as páginas, e que cada visita abria ainda um iframe de autenticação da Google com cerca de 93 KiB. Tudo isso para ler séries que são públicas. Agora as páginas públicas leem o Firestore com fetch contra a sua API REST, com as mesmas regras de segurança.
• O login só é carregado quando faz falta: uma marca local indica que nesse navegador já entrou um admin. Os visitantes nunca descarregam o Firebase Auth. E a marca não dá nenhuma permissão: a verificação real continua a ser o Firebase.

Resultado em desktop com rede 4G: 100 em Performance, Accessibility, Best Practices e SEO.

O que já vem de série

• Imagens responsivas: cada foto é servida pela Cloudinary com srcset em cinco larguras (480, 800, 1200, 1600 e 2400 px) e formato e qualidade automáticos.
• Cada página carrega quando é visitada (lazy loading), exceto a página inicial.

💡 A lição: medir antes de otimizar. O maior problema de CLS era um rodapé, e o maior peso, uma biblioteca que os visitantes nem sequer usavam.

🛡️ Segurança

• Regras do Firestore que negam tudo por defeito. O público só pode ler as séries publicadas, e as definições só aceitam os campos permitidos.
• Uploads assinados: o navegador nunca tem permissão para enviar para a Cloudinary por conta própria; cada upload é assinado por uma função que primeiro verifica que és admin.
• Formulário de contacto com limites de comprimento, HTML escapado e um campo armadilha: os bots preenchem-no, recebem um "OK" e nada é enviado.
• Staging não é indexado: os builds de staging levam noindex e um robots.txt que proíbe tudo.

🧪 Qualidade: a ordem não se negoceia, o linter impõe-na

Quando a IA escreve a maior parte do código, as convenções não podem depender de alguém se lembrar delas. Por isso transformei-as em regras: se o código não segue a ordem, o lint falha, seja quem for que o escreveu. As regras existem desde o primeiro dia do projeto.

Cinco regras de ESLint próprias, escritas para este projeto:

As duas últimas só avisam, não reordenam sozinhas: nas interfaces, por exemplo, mover membros pode partir código que usa spread ou Object.assign, por isso prefiro que seja uma pessoa a decidir.

E o resto da ordem, também automático:

• Imports agrupados e ordenados: primeiro o Angular e as bibliotecas externas, depois os aliases internos (@core, @features...) e no fim os relativos.
• Chaves de objetos por ordem alfabética em dados, constantes, modelos e interfaces.
• JSON de tradução com as chaves ordenadas, sem comentários.
• Prettier com plugins que ordenam as propriedades CSS, os atributos HTML e as chaves dos JSON.
• TypeScript estrito: any é um erro, os tipos de retorno são obrigatórios e usa-se sempre ===.

O padrão dicionário

Há uma prática que peço sempre e que nenhum linter impõe: o padrão dicionário, conhecido em inglês como object lookup (e como dispatch table quando os valores são funções). Quando uma função traduz um valor noutro, nada de switch nem de if/else encadeados: um objeto tipado com Record, acesso por chave e um valor por defeito com ??.

const TRANSLATE_ERRORS: Record<TranslationError['reason'], string> = {
  failed: 'admin.editor.translate.errors.failed',
  limit: 'admin.editor.translate.errors.limit',
  'not-allowed': 'admin.editor.translate.errors.notAllowed',
};

Três vantagens:

• Lê-se de relance: todos os casos numa tabela, em vez de espalhados por ramos.
• O TypeScript garante que não falta nenhum: com Record<TranslationError['reason'], string>, se amanhã aparecer um motivo de erro novo, o código não compila até ter o seu texto.
• Acrescentar um caso é acrescentar uma linha, sem mexer na lógica.

Se em vez de um valor precisas de executar algo, os valores passam a ser funções: é a dispatch table. Há aqui uma armadilha que eu próprio tinha nos meus apontamentos:

const LOKI_DEFAULT_DISFARCE = 'Loki';

const LOKI_DISFARCES = {
  Hulk: () => 'Thanos',
  Thor: () => 'Odin',
};

// ❌ Se o inimigo não estiver na tabela: TypeError, ... is not a function
const disfarce = LOKI_DISFARCES[enemy]() ? LOKI_DISFARCES[enemy]() : LOKI_DEFAULT_DISFARCE;

// ✅ Com ?.() nada é executado se não existir, e ?? põe o valor por defeito
const disfarce = LOKI_DISFARCES[enemy]?.() ?? LOKI_DEFAULT_DISFARCE;

Além de partir com uma chave desconhecida, a primeira versão executa a função duas vezes. E ?? é melhor do que o ternário: só usa o valor por defeito quando a chave não existe, não quando o resultado é um '' ou um 0 válidos.

Não é dogma: nos templates uso @switch quando cada caso pinta algo diferente, e ainda fica algum switch onde cada ramo faz mais do que devolver um valor.

E os testes:

• 857 casos em 117 ficheiros, com Vitest e JSDOM, também para as funções de api/.
• Commits convencionais validados por um script.

🐛 Cinco problemas reais (e como os resolvi)

1. Separadores que se partiam depois de cada deploy

Um separador aberto antes de um deploy pedia ficheiros do build anterior, que já não existiam. As páginas que carregam ao serem visitadas (galeria, Sobre, o painel) não abriam e não diziam nada.

A solução foi um gestor de erros de navegação que, se falhar o download de uma parte da app, recarrega essa página do zero para obter o build novo. Só o faz para erros de download e uma única vez seguida por página, por isso uma falha real não pode provocar um ciclo de recarregamentos.

2. Tirar o Firebase das páginas públicas

A poupança está contada na secção de desempenho; o delicado foi a segurança. Separei o login num store que é carregado a pedido, e a marca local que decide quando o carregar não concede nada: se alguém a falsificar, só consegue descarregar o Firebase Auth, porque a verificação real continua a ser o login e o documento de admin no Firestore.

3. As funções da Vercel e os módulos ES

As funções de api/ falhavam na Vercel: como módulos ES nativos, os imports relativos precisam da extensão .js. Além da correção, acrescentei um teste que verifica todos os imports de api/ para que não volte a acontecer.

4. Uma limpeza de fotos que não se pode enganar

Apagar fotos "órfãs" é fácil; apagar só as órfãs, nem tanto. A limpeza foi aprendendo com cada caso:

• Se não conseguir ler as séries, não apaga nada. Uma leitura falhada não significa que não haja fotos em uso.
• Só dá como apagadas as fotos que a Cloudinary confirma.
• Respeita a foto de perfil e as do cantinho do admin, que vivem na mesma pasta.
• Não toca em fotos com menos de 7 dias e apaga no máximo 100 por execução.

5. "A guardar…" para sempre

Ao guardar a foto de perfil com uma ligação lenta, se o guardar demorasse demasiado a app perguntava ao servidor se tinha chegado... sem limite de tempo para essa pergunta. Agora essa verificação tem o seu próprio limite de 5 segundos, e a leitura da sessão guardada no IndexedDB desiste aos 2 segundos, porque alguns navegadores nunca respondem.

📅 Dia a dia

🎯 Lições

1. A velocidade vem do método, não só da IA. Requisitos por escrito, testes primeiro, ramos e revisão: sem isso, 75 commits num dia seriam 75 problemas.
2. A memória persistente muda o jogo. Um agente que se lembra de decisões e erros de sessões anteriores não os repete.
3. Verificar vale mais do que gerar. Nada chegou a produção sem passar testes, lint e build.
4. Os serviços gratuitos dão para muito se desenhares a pensar nos seus limites (Cloudinary, Firebase, DeepL Free, Resend e Vercel).
5. A segurança não se delega no frontend. As regras do Firestore e as funções que verificam o admin é que protegem; a interface só acompanha.

⭐ gentle-ai no GitHub: github.com/Gentleman-Programming/gentle-ai. Se te for útil, dá-lhe uma estrela.

🎬 Introdução: a página carrega, o vídeo não

O meu MacBook da empresa funcionava na perfeição há quatro anos com este esquema: um hub USB-C (Ethernet, webcam e uma saída VGA para uma televisão) e um monitor externo por HDMI cujo áudio utilizo, com a ficha de auscultadores do monitor a alimentar as colunas da televisão. Até que um dia o YouTube deixou de reproduzir: a página carregava na perfeição, mas o vídeo ficava a rodar para sempre no 0:00.

Esta é a minha secretária:

O padrão era o que mais desconcertava. Acontecia em casa, mas não na minha segunda habitação, com outro ISP. E um PC com Linux na mesma rede doméstica, com o mesmo navegador, funcionava sem problemas. Tudo apontava para a rede ou o fornecedor de internet, juntamente com um Mac gerido pela empresa (MDM, um cliente SASE de secure web gateway, um perfil de DNS cifrado gerido e um agente de segurança de endpoint). Suspeitos a mais.

💡 Spoiler: a rede era inocente. Mas demorei horas a aceitá-lo, e o caminho é o que vale a pena contar.

🤖 Como trabalhei: a iterar com agentes

Não fiz esta investigação sozinho. Trabalhei no terminal com agentes de IA (Claude Code) configurados com o gentle-ai, uma ferramenta de código aberto (site oficial) que configura os agentes que já usas com memória persistente, Organic-Driven Development, skills e orquestração de sub-agentes, sem te prender a nenhum.

O que o gentle-ai trouxe neste caso:

• Engram: memória persistente entre sessões, para não começar do zero de cada vez.
• ODD (Organic-Driven Development): um fluxo leve, com documento de tarefas para o trabalho substancial, ramo antes de escrever e nenhum commit sem a minha permissão explícita.
• Orquestração de sub-agentes: o orquestrador delegou em escritores que redigiram este artigo em três idiomas e geraram os diagramas; eu revi e corrigi.

O gentle-ai foi criado por Alan Buscaglia (Gentleman Programming), e a regra dele para trabalhar com IA resume bem este artigo: "verifying beats generating", ou seja, verificar vale mais do que gerar.

⭐ gentle-ai no GitHub: github.com/Gentleman-Programming/gentle-ai. Se te for útil, dá-lhe uma estrela: ajuda mais pessoas a encontrá-lo.

O método foi sempre o mesmo, e enganámo-nos os dois: o agente também defendeu teorias erradas (a do cliente SASE e da cache do ISP foi dele) e a evidência corrigiu-o tal como a mim.

hipótese → teste → evidência → descartar

• 🤖 O agente: leu logs de sistema e de rede, inspecionou configurações, capturou e descodificou o tráfego do leitor, lançou o Chrome sem interface pelo DevTools, montou o monitor de reprodução, executou os testes de isolamento e escreveu o vigilante em Swift com o respetivo LaunchAgent.
• 🙋 Eu: dei o contexto e as capturas de ecrã, fiz as verificações no navegador que o agente não podia e, sobretudo, reparei que falhava mesmo quando ligava o hub USB-C e confirmei que o esquema funcionava assim há quatro anos.

🕵️ Falsa pista n.º 1: o filtro DNS de casa

Primeiro o mais óbvio: o Pi-hole lá de casa. Descartámo-lo antes de começar a sério, com provas: o DNS resolvia tudo corretamente e só bloqueava domínios de publicidade. Nada a ver com os servidores de vídeo.

🚦 Falsa pista n.º 2: QUIC / HTTP3

O clássico "a página carrega mas o vídeo não": uma firewall ou um fornecedor a quebrar o QUIC. Desativámos o QUIC no navegador (brave://flags/#enable-quic) e o vídeo continuou a falhar. Descartado.

🧩 Falsa pista n.º 3: bloqueadores e extensões

Na consola apareciam erros net::ERR_BLOCKED_BY_CLIENT na telemetria do YouTube (qoe, log_event, generate_204). Muito suspeito... até experimentarmos numa janela privada com os shields desligados: a telemetria passava e o vídeo continuava preso. Esses erros eram ruído.

🛡️ Falsa pista n.º 4: o cliente SASE

Esta foi a mais convincente. A extensão de rede do cliente SASE continuava a correr mesmo quando a "desativava" na interface (proteção anti-adulteração), e os seus logs, lidos pelo agente, mostravam que tratava fluxos do navegador para googlevideo.com. Além disso, o meu fornecedor servia o vídeo a partir de um nó de cache da Google dentro da sua própria rede. A hipótese, que foi do próprio agente, encaixava na perfeição: o tráfego que sai pela cloud do SASE é rejeitado pela cache do ISP.

Três factos desmontaram-na:

• O certificado que o navegador recebia era o genuíno da Google: não havia interceção TLS.
• O nó de cache respondia sem problemas (um 204 correto).
• E o decisivo: o Chrome nem sequer passa por esse cliente (zero fluxos no log) e falhava exatamente da mesma forma.

👻 Falsa pista n.º 5: a rota "fantasma" de IPv6

Outro assistente de IA sugeriu um problema de IPv6. O agente verificou, e depois retratou a ideia: o Mac não tinha IPv6 global, as rotas por defeito utun estavam associadas à interface (são túneis do sistema), a tentativa IPv6 do navegador falhava de imediato e recuava para IPv4, e a minha rede doméstica nem sequer tem IPv6. Descartado. Também não eram a conta nem os cookies: um perfil de Chrome totalmente limpo, sem cookies, sem conta e sem extensões, também ficava preso.

🔬 A pista à vista de todos

Durante todo o processo houve uma observação que, em retrospetiva, apontava para longe da rede. A resposta do YouTube era válida: um stream SABR/UMP com cerca de 1 MB de áudio e vídeo reais e o estado de proteção do stream em OK. Os bytes chegavam depressa. Mas o leitor nunca os consumia: video.readyState ficava a 0, buffered vazio e o leitor no estado 3 (buffering).

"Os dados chegam, mas o leitor não arranca." Isso não é um problema de rede.

🔁 A reviravolta: torná-lo reproduzível

Depois de reiniciar o Mac funcionou... e mais tarde voltou a avariar. Por isso deixei de adivinhar e pedi ao agente que montasse um monitor: de 2 em 2 minutos lançava um Chrome limpo e sem interface através do protocolo DevTools, carregava um vídeo, verificava readyState e currentTime, e guardava uma fotografia do sistema a cada mudança de estado.

Foi então que reparei, e esta parte foi minha, não do agente: avariava exatamente quando ligava o hub USB-C, num esquema que eu sabia funcionar assim há quatro anos. O agente fez um teste de isolamento com o hub ligado:

Aí estava. Sem áudio o vídeo reproduz; com áudio para o monitor HDMI, não.

🎯 A causa raiz: um dispositivo de áudio bloqueado

Ao ligar o hub, o macOS reconfigura os ecrãs e os dispositivos de áudio, e o áudio do monitor HDMI fica bloqueado, embora nunca desapareça da lista de dispositivos. O Chromium não inicia a reprodução enquanto não conseguir abrir a saída de áudio, por isso o vídeo espera para sempre, apesar de os dados já terem chegado.

Esta é a minha montagem, com o ponto exato onde falhou:

Isto explica também o resto do mistério:

• 📍 "Só acontece em casa": é lá que está o esquema do hub e do monitor. A rede era uma pista falsa; a correlação com o local era, na verdade, uma correlação com o hardware.
• ⏱️ "Avaria de vez em quando": o hub é um bocado instável e mexe-se-lhe. Cada nova ligação volta a disparar o problema.

🔧 A solução manual

Basta reinicializar o dispositivo de áudio. Três formas:

1. Abrir a Configuração de MIDI e Áudio, selecionar o dispositivo HDMI e mudar o formato de 48 000 Hz para 44 100 Hz e voltar.
2. Mudar a saída de som para outro dispositivo e devolvê-la.
3. Reiniciar o serviço de áudio: sudo killall coreaudiod.

Uma contraprova confirmou que o que resolve é o reinício, não a frequência: os 48 kHz voltam a funcionar depois de um reset. Fixar uma frequência concreta não ajuda, porque o macOS já a memoriza por dispositivo.

🤖 A solução automática

Como o problema voltava a cada nova ligação, pedi ao agente que o automatizasse e ele escreveu um pequeno programa em Swift que usa o CoreAudio e corre como LaunchAgent de utilizador; revi-o e instalei-o eu. Escuta as alterações em kAudioHardwarePropertyDevices, espera 4 segundos até tudo assentar (debounce) e alterna a frequência nominal do dispositivo alvo para outra disponível e de volta. A primeira versão não disparava, porque o monitor nunca desaparece da lista de dispositivos; o agente corrigiu-a para reagir a qualquer alteração nessa lista.

🧾 O programa (~/bin/hdmi-audio-reset.swift)

// Watches CoreAudio devices and re-initializes a given output device whenever the device
// list changes (e.g. after plugging a USB-C hub), by toggling its nominal sample rate.
// Works around the device getting stuck, which blocks Chromium media playback.
// usage: hdmi-audio-reset <deviceName> [--now]
import CoreAudio
import Foundation

let targetName = CommandLine.arguments.count > 1 ? CommandLine.arguments[1] : "VS278"
let settleSeconds: TimeInterval = 4

func log(_ message: String) {
  let line = "\(ISO8601DateFormatter().string(from: Date())) \(message)\n"
  FileHandle.standardError.write(line.data(using: .utf8)!)
}

func address(_ selector: AudioObjectPropertySelector) -> AudioObjectPropertyAddress {
  AudioObjectPropertyAddress(mSelector: selector, mScope: kAudioObjectPropertyScopeGlobal, mElement: kAudioObjectPropertyElementMain)
}

func deviceIDs() -> [AudioDeviceID] {
  var addr = address(kAudioHardwarePropertyDevices)
  var size: UInt32 = 0
  guard AudioObjectGetPropertyDataSize(AudioObjectID(kAudioObjectSystemObject), &addr, 0, nil, &size) == noErr else { return [] }
  var ids = [AudioDeviceID](repeating: 0, count: Int(size) / MemoryLayout<AudioDeviceID>.size)
  guard AudioObjectGetPropertyData(AudioObjectID(kAudioObjectSystemObject), &addr, 0, nil, &size, &ids) == noErr else { return [] }
  return ids
}

func name(of id: AudioDeviceID) -> String? {
  var addr = address(kAudioObjectPropertyName)
  var value: Unmanaged<CFString>?
  var size = UInt32(MemoryLayout<Unmanaged<CFString>?>.size)
  guard AudioObjectGetPropertyData(id, &addr, 0, nil, &size, &value) == noErr else { return nil }
  return value?.takeRetainedValue() as String?
}

func findTarget() -> AudioDeviceID? { deviceIDs().first { name(of: $0) == targetName } }

func sampleRate(of id: AudioDeviceID) -> Float64? {
  var addr = address(kAudioDevicePropertyNominalSampleRate)
  var rate: Float64 = 0
  var size = UInt32(MemoryLayout<Float64>.size)
  return AudioObjectGetPropertyData(id, &addr, 0, nil, &size, &rate) == noErr ? rate : nil
}

func availableRates(of id: AudioDeviceID) -> [Float64] {
  var addr = address(kAudioDevicePropertyAvailableNominalSampleRates)
  var size: UInt32 = 0
  guard AudioObjectGetPropertyDataSize(id, &addr, 0, nil, &size) == noErr else { return [] }
  var ranges = [AudioValueRange](repeating: AudioValueRange(), count: Int(size) / MemoryLayout<AudioValueRange>.size)
  guard AudioObjectGetPropertyData(id, &addr, 0, nil, &size, &ranges) == noErr else { return [] }
  return ranges.map { $0.mMinimum }
}

@discardableResult
func setSampleRate(_ id: AudioDeviceID, _ rate: Float64) -> OSStatus {
  var addr = address(kAudioDevicePropertyNominalSampleRate)
  var value = rate
  return AudioObjectSetPropertyData(id, &addr, 0, nil, UInt32(MemoryLayout<Float64>.size), &value)
}

func resetTarget() {
  guard let id = findTarget(), let current = sampleRate(of: id) else { log("\(targetName) not found; skipping"); return }
  guard let other = availableRates(of: id).first(where: { $0 != current }) else { log("no alternate rate for \(targetName)"); return }
  let first = setSampleRate(id, other)
  Thread.sleep(forTimeInterval: 1)
  let second = setSampleRate(id, current)
  log("reset \(targetName): \(Int(current)) -> \(Int(other)) -> \(Int(current)) (status \(first)/\(second))")
}

let wasPresent = findTarget() != nil
if CommandLine.arguments.contains("--now") { resetTarget(); exit(0) }
log("watching for \(targetName) (present=\(wasPresent))")
if wasPresent { DispatchQueue.main.asyncAfter(deadline: .now() + settleSeconds) { resetTarget() } }

// Any device-list change (hub plugged/unplugged, displays reconfigured) can leave the
// target stuck even though it never disappears, so reset it after changes settle.
var pendingReset: DispatchWorkItem?
var devicesAddr = address(kAudioHardwarePropertyDevices)
AudioObjectAddPropertyListenerBlock(AudioObjectID(kAudioObjectSystemObject), &devicesAddr, DispatchQueue.main) { _, _ in
  log("audio devices changed; resetting \(targetName) in \(Int(settleSeconds))s")
  pendingReset?.cancel()
  let work = DispatchWorkItem { resetTarget() }
  pendingReset = work
  DispatchQueue.main.asyncAfter(deadline: .now() + settleSeconds, execute: work)
}
dispatchMain()

📄 O LaunchAgent (~/Library/LaunchAgents/local.hdmi-audio-reset.plist)

Substitui YOUR_USER pelo teu utilizador e VS278 pelo nome do teu dispositivo de áudio.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>local.hdmi-audio-reset</string>
  <key>ProgramArguments</key>
  <array><string>/Users/YOUR_USER/bin/hdmi-audio-reset</string><string>VS278</string></array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardErrorPath</key><string>/Users/YOUR_USER/Library/Logs/hdmi-audio-reset.log</string>
</dict>
</plist>

▶️ Compilar e instalar

swiftc -O -o ~/bin/hdmi-audio-reset ~/bin/hdmi-audio-reset.swift
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/local.hdmi-audio-reset.plist

Para desinstalar:

launchctl bootout gui/$(id -u)/local.hdmi-audio-reset

Verifiquei-o de ponta a ponta: desliguei e voltei a ligar o hub, o log mostrou audio devices changed; resetting …, depois o reinício, e o YouTube reproduziu sem eu tocar em nada.

🧠 Lições

• Descarta camadas com provas, não com intuição. Cada falsa pista foi encerrada com um teste concreto, não com um palpite.
• Desconfia da primeira história plausível. O agente e eu perseguimos a rede durante horas porque a história encaixava bem demais (a teoria do SASE e da cache do ISP foi do próprio agente).
• "Os dados chegam mas nada toca" quer dizer olhar para o pipeline multimédia (áudio, descodificador), não para a rede.
• Torna a falha reproduzível e automática. Um monitor de 2 em 2 minutos deu-me o que a intuição não conseguiu: o gatilho.
• Muda uma variável de cada vez. O teste de isolamento da tabela acima resolveu em minutos o que horas de hipóteses não resolveram.
• A correlação com o local era, na verdade, uma correlação com um esquema de hardware.

Fiz a investigação a iterar com agentes de IA no terminal (Claude Code, configurado com o gentle-ai): executaram e organizaram os testes, e caíram em teorias erradas tal como eu. Este artigo também foi redigido por sub-agentes orquestrados pelo gentle-ai (o texto em três idiomas e as ilustrações), e fui eu que o revi e corrigi. O que nos fez avançar aos dois foi descartar com provas.

Se tens um Mac, um hub USB-C e áudio por HDMI, e o YouTube fica no 0:00, experimenta primeiro reinicializar o dispositivo de áudio. Pode poupar-te uma tarde inteira. 🎧

🌪️ Introdução: O Caos Invisível dos Espaços e das Vírgulas

Em projetos de grande dimensão onde coexistem múltiplas consultoras, a diversidade de critérios não é apenas uma riqueza cultural — é também um risco técnico. Surge um problema tão silencioso quanto perturbador: a inconsistência visual. Quando cada equipa traz o seu próprio ADN de desenvolvimento — uns preferem tabulações, outros espaços; aspas simples versus aspas duplas — o repositório deixa de ser um ativo coeso para se tornar um campo de batalha de alterações irrelevantes.

Esta falta de unificação não é um mero detalhe estético; é uma fonte de fricção operacional e de vendor finger-pointing — apontar o dedo entre fornecedores — durante as revisões de código. As discussões sobre a posição de uma chaveta ou o comprimento de uma linha roubam minutos de ouro que deveriam ser investidos na arquitetura ou na lógica de negócio.

💡 Para um líder técnico, standardizar não é um capricho: é uma estratégia para eliminar o ruído e garantir que as Code Reviews se centrem no que realmente acrescenta valor.

✨ O Fim das Guerras de Estilo com o Prettier

A solução para erradicar estas fricções é delegar a responsabilidade ao Prettier. Como formatador de código opinionated, o Prettier elimina a subjetividade ao fazer o parse do código e reimprimi-lo sob regras estritas e predefinidas.

O que o torna indispensável para um Arquiteto de Software é a sua segurança: o Prettier atua sobre a camada de apresentação sem alterar a Árvore de Sintaxe Abstrata (AST). Isto oferece uma garantia fundamental:

"O funcionamento da aplicação mantém-se exatamente igual"

Adotar o Prettier é, em essência, um ato de libertação para a equipa. Ao automatizar o estilo, o programador liberta-se da carga cognitiva de "encaixar" visualmente com os restantes, permitindo que a Developer Experience (DevEx) flua para a resolução de problemas complexos.

⚙️ Configuração mínima em .prettierrc

{
  "arrowParens": "always",
  "bracketSameLine": false,
  "printWidth": 100,
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5"
}

🕵️ O "Hack" do Git para Formatar sem Perder o Rasto

O maior receio ao implementar um standard num projeto em produção é o commit massivo. Ao formatar toda a base de código de uma só vez, corremos o risco de obscurecer a autoria original. Se um programador usar o git blame para perceber porque razão foi tomada uma decisão técnica há dois anos, encontrará como autor "o bot de formatação", perdendo a rastreabilidade histórica.

Para evoluir a base de código sem sacrificar este rasto, utilizamos o ficheiro .git-blame-ignore-revs.

🔍 Como funciona

1. Formatamos o projeto completo e fazemos commit.
2. Obtemos o hash do commit de formatação.
3. Registamo-lo em .git-blame-ignore-revs:

# Commit de formatação massiva com Prettier — 2024-10-15
a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

4. Configuramos o Git para que o utilize automaticamente:

git config blame.ignoreRevsFile .git-blame-ignore-revs

Esta funcionalidade permite:

• 👤 Preservar a autoria original: o Git ignora esse commit nos rastreios.
• 🏛️ Integridade do historial: o GitHub e o GitLab respeitam este ficheiro, mostrando o verdadeiro autor da lógica de negócio.
• 🔇 Evolução sem ruído: alcança-se a perfeição visual sem "sujar" a responsabilidade histórica de cada linha.

🌐 Node.js como a "Fonte da Verdade" Multiplataforma

Em ecossistemas modernos, especialmente em projetos baseados em Angular, a independência do sistema operativo é crítica. O erro clássico de muitas automatizações é depender de scripts em Bash, que frequentemente falham em ambientes Windows ou requerem configurações manuais fastidiosas.

A nossa arquitetura propõe uma mudança de paradigma: tratar o repositório como um ambiente de aplicação em vez de um ambiente de sistema. Ao centralizar tudo em Node.js, garantimos um comportamento verdadeiramente cross-platform:

• 💻 Agnóstico de hardware: o fluxo funciona da mesma forma num MacBook M3 que numa estação de trabalho com Windows 10.
• 🔒 Ambiente controlado: se o programador tiver o Node.js instalado (requisito para Angular), a automatização funcionará por defeito.
• 📦 Unificação de ferramentas: o package.json torna-se a única fonte da verdade.

🐶 Husky e lint-staged: Os Guardiões Silenciosos do Repositório

Para que a standardização seja eficaz, deve ser invisível e obrigatória. Implementamos um fluxo de conformidade forçada através do Husky e do lint-staged, atuando como um filtro de qualidade antes de o código chegar ao servidor:

1. 🚀 Ativação: o programador executa git commit.
2. 🪝 Intercepção: o Husky captura o evento e delega a execução ao Node.js.
3. 🎯 Filtragem inteligente: o lint-staged identifica apenas os ficheiros na Staging Area. Não perdemos tempo a processar milhares de ficheiros estáticos — apenas o que foi alterado.
4. ✅ Formatação e validação: o Prettier aplica o formato. Se o código tiver erros de sintaxe graves, o commit é abortado.

📦 Instalação

npm install --save-dev husky lint-staged
npx husky init

🔧 Configuração em package.json

{
  "lint-staged": {
    "*.{ts,html,scss,json,md}": ["prettier --write"]
  }
}

Hook pre-commit (.husky/pre-commit)

node_modules/.bin/lint-staged

🛡️ Este processo elimina o fator do esquecimento humano e garante que nenhum código fora do standard entra alguma vez no repositório, sem que o programador tenha de executar um único comando adicional.

📋 Plano de Ação: Prova de Conceito (POC)

Como Arquitetos, não implementamos alterações críticas às cegas. O caminho para a excelência visual segue um roteiro técnico claro:

1. 🌿 Isolamento: criar um ramo feature/standardizacao-prettier para não interromper o fluxo atual.
2. ⚙️ Configuração: instalar a stack (Prettier, Husky, lint-staged) e definir as regras em .prettierrc.
3. 💥 Execução massiva: formatar o projeto completo e gerar o commit de referência.
4. 🛡️ Proteção do historial: configurar o ficheiro .git-blame-ignore-revs com o hash obtido.
5. 🎬 Demonstração ao vivo: mostrar à equipa e ao cliente como código mal indentado em Windows é corrigido instantaneamente ao fazer commit, mantendo a autoria original no historial.

🚀 Conclusão: Em Direção a uma Cultura de Código Limpo

A adoção deste ecossistema não é apenas uma melhoria técnica; é uma declaração de princípios sobre a qualidade. Os benefícios são imediatos: revisões de código mais ágeis, um historial de Git impecável e a eliminação total da fricção estética entre consultoras.

O investimento para implementar esta arquitetura é mínimo face à poupança de tempo e frustração a longo prazo. No fim do dia, a pergunta para qualquer líder tecnológico é simples:

Quanto tempo está a sua equipa a perder a discutir o formato das vírgulas, quando poderia estar a fortalecer a arquitetura do seu sistema?

A automatização é a ponte entre o caos visual e a excelência técnica. E feliz 4 de Maio, que a força esteja convosco em cada commit! 🌌⚔️