req-114: Compilação Tailwind Incremental por Recurso e Três Camadas de CSS

• Status do intake: implemented-pending-homologation

• Data: 2026-08-14

• Origem: solicitação direta do Engenheiro Chefe durante a análise de performance CSS da instância https://[REDACTED].com/

• Classificação preliminar: mudança arquitetural nos pipelines de recursos, banco de dados, release, sincronização, deploy privado e editor HTML

• Batch candidato: BATCH-114

• Dependência relacionada: req-113 continua independente para JS, imagens, fontes, downloads e demais assets estáticos; o CSS Tailwind de recursos não dependerá do controlador estático

Decisão de arquitetura

Manter o Tailwind CSS CLI já utilizado no desenvolvimento, CI, release do core e deploy de projetos privados. A hospedagem pública não executará CLI, Node, PHP CLI, proc_open nem compilação por CRON obrigatório.

O modelo de cada recurso passa a ter três camadas independentes:

1. css: CSS escrito pelo usuário/desenvolvedor;

2. css_precompiled: CSS Tailwind gerado offline pelo CLI no release/deploy, com base nos arquivos físicos do recurso;

3. css_compiled: CSS Tailwind gerado online pelo compilador de navegador quando o conteúdo é criado ou alterado no editor.

Essa separação evita que o release sobrescreva o CSS dinâmico do editor e permite que o editor use o CSS pré-compilado do próprio recurso como uma base estável para remover duplicações.

O pipeline deixará de varrer todo o diretório gestor para produzir um único CSS com as classes de todos os recursos. Em seu lugar:

• cada recurso declarado com framework_css = tailwindcss será compilado isoladamente;

• a saída física será gravada como <id>.precompiled.css, sem alterar <id>.css;

• atualizacao-dados-recursos.php importará o sidecar para css_precompiled;

• os JSONs continuarão sendo enviados ao banco pelo atualizador existente;

• o runtime carregará css_precompiled e css_compiled como camadas distintas;

• um manifesto de fingerprints evitará recompilar recursos inalterados;

• system-output.css e o output.css global do projeto deixarão de existir como artefatos e dependências do runtime depois da migração;

• tema, tokens e Preflight serão propriedade do css_precompiled do layout Tailwind, enquanto página, componentes e demais recursos fornecerão suas próprias utilities.

O nome de coluna recomendado é css_precompiled, coerente com o existente css_compiled. O nome final deve ser congelado na migração e aplicado de forma uniforme em banco, PHP, JSON e JavaScript.

Evidências confirmadas no código atual

Core e projeto

• Core:

  • entrada: gestor/assets/tailwindcss/system-input.css;

  • saída: gestor/assets/tailwindcss/system-output.css;

  • tamanho observado: aproximadamente 122 KB bruto e 16,7 KB gzip;

  • a entrada varre gestor/modulos/**/*.{html,css,js} e gestor/resources/**/*.{html,css,js};

  • .github/workflows/release-gestor.yml compila o CSS global e depois executa atualizacao-dados-recursos.php.

• Projeto privado [REDACTED]:

  • entrada: [REDACTED]/gestor/contents/tailwindcss/input.css;

  • saída: [REDACTED]/gestor/contents/tailwindcss/output.css;

  • tamanho observado: aproximadamente 70 KB bruto e 11,7 KB gzip;

  • contém o tema Photon e usa detecção ampla de fontes;

  • o deploy lê devProjects.<id>.tailwindcss/cli, compila o CSS e depois executa o compilador PHP de recursos.

Recursos e runtime

• resourcePaths() em gestor/controladores/agents/arquitetura/atualizacao-dados-recursos.php conhece hoje <id>.html, <id>.css e <id>.md.

• buildChecksum() considera apenas HTML e CSS autoral.

• A coleta de páginas, layouts, componentes e templates globais e de módulos envia html e css aos JSONs, mas não uma camada offline compilada.

• O inventário inicial encontrou 165 recursos Tailwind no core e 56 no [REDACTED]. A descoberta deve usar os metadados, não todos os 653 HTMLs físicos do core.

• O runtime já injeta css_compiled. Em gestor.php, a ordem atual é CSS padrão/projeto, css-compiled, CSS autoral e CSS final.

• gestor_pagina_recursos_incluir() deduplica conteúdos idênticos pelo MD5 integral na mesma resposta, mas alguns caminhos de layout acrescentam o CSS diretamente e precisam ser normalizados.

Editor HTML

gestor/assets/interface/html-editor-interface.js::updateCSSCompiled() atualmente:

1. espera 750 ms depois de atribuir srcdoc ao iframe;

2. coleta seletores de system-output.css e output.css;

3. presume que a última <style> do <head> é a saída do Tailwind no navegador;

4. remove uma regra quando encontra o mesmo seletor, sem comprovar igualdade de declarações, layer ou contexto;

5. substitui CodeMirrorCssCompiled pelo resultado filtrado.

O valor existente de css_compiled é carregado no CodeMirror, mas não participa do iframe com identidade explícita.

Objetivos

1. Eliminar o CSS Tailwind global bloqueante e entregar todo CSS Tailwind de runtime pelos recursos no banco.

2. Recompilar somente recursos alterados durante release, sync e deploy.

3. Manter a compilação offline fora da hospedagem pública e reutilizar o CLI atual.

4. Transportar html, css, css_precompiled e css_compiled sem misturar suas responsabilidades.

5. Preservar alterações online durante atualização de core/projeto.

6. Eliminar CSS online obsoleto quando classes forem retiradas no editor.

7. Tornar a deduplicação determinística, estrutural e independente de espera fixa.

8. Cobrir classes em JavaScript, PHP ou dados dinâmicos que não aparecem literalmente no HTML.

Não objetivos

• Criar um compilador Tailwind em PHP.

• Executar compilação offline em request público ou em CRON obrigatório.

• Substituir o Tailwind CLI já configurado.

• Mover os CSS de recurso para URLs públicas individuais.

• Sobrescrever <id>.css.

• Tratar MD5 como segurança; ele será somente fingerprint de alteração.

Contrato de dados

Campos

Abrangência da migração

Embora a solicitação se origine na tabela paginas, o pipeline fixo do gerador confirma quatro destinos construídos a partir de arquivos HTML/CSS físicos. Criar css_precompiled obrigatoriamente em:

• paginas;

• layouts;

• componentes;

• templates.

O pipeline fixo também gera FormsData.json, WidgetsData.json, variáveis e recursos de IA, mas eles não possuem o mesmo contrato físico HTML/CSS e não recebem a coluna por associação automática.

Auditar separadamente o pipeline declarativo sync_resources. Atualmente pages_index é o caso concreto: declara html/css via field_types e possui recurso físico padrao, mas o registro não declara framework_css. Para tabelas dinâmicas, o suporte deverá ser opt-in por metadado explícito, por exemplo tailwind_precompile = true e/ou framework_css = tailwindcss; não criar coluna nem compilar somente porque existe um arquivo .html.

Preservação

• css_precompiled pertence ao core/projeto e pode ser atualizado pelo release/deploy quando o recurso não estiver protegido por uma regra mais específica.

• css_compiled pertence ao conteúdo online e deve constar em preserve_on_user_modified junto de html e css.

• A migração começa com css_precompiled nulo ou vazio; o runtime mantém compatibilidade enquanto os recursos são recompilados.

• Rollback da aplicação deve tolerar a coluna extra; rollback destrutivo da coluna não será automático.

Contrato físico dos recursos

<diretório-do-tipo>/<id>.html
<diretório-do-tipo>/<id>.css
<diretório-do-tipo>/<id>.precompiled.css

• <id>.html: fonte estrutural e principal fonte Tailwind.

• <id>.css: CSS autoral.

• <id>.precompiled.css: artefato minificado destinado a css_precompiled.

• O sidecar só existe quando framework_css = tailwindcss.

• Remoção do recurso ou troca de framework remove sidecar e entrada do manifesto de forma controlada.

O contrato vale para recursos globais em gestor/resources e recursos de módulos em gestor/modulos/<modulo>/resources, respeitando idioma, tipo e ID dos JSONs existentes.

Manifesto incremental

Criar um manifesto central por árvore, por exemplo gestor/resources/.tailwind-build-manifest.json. Cada entrada será identificada por escopo, módulo, idioma, tipo e ID e conterá:

• fingerprint integral da entrada;

• hash do sidecar gerado;

• versão fixada do Tailwind;

• versão do algoritmo do builder;

• fontes adicionais e safelist ordenadas;

• data informativa da última compilação bem-sucedida.

O fingerprint combinará:

1. HTML;

2. fontes adicionais;

3. safelist/tokens dinâmicos;

4. entrada de tema/base do core ou projeto;

5. versão do Tailwind;

6. flags e versão do builder;

7. CSS autoral apenas quando ele realmente participar da entrada Tailwind.

Regras operacionais:

• release/deploy usa loop finito; --watch infinito é exclusivo de desenvolvimento;

• primeira compilação usa fila com concorrência limitada, nunca centenas de processos simultâneos;

• sidecar é publicado por temporário + renomeação atômica;

• manifesto só é atualizado após sucesso;

• falha aborta release/deploy, preserva a saída anterior e identifica o recurso;

• fingerprints idênticos podem reutilizar resultados dentro da mesma execução.

Fontes Tailwind e classes dinâmicas

Somente o HTML não cobre classes presentes em JavaScript, PHP, templates auxiliares ou dados. Adicionar metadados opcionais equivalentes a:

{
  "tailwind_sources": ["./arquivo.js", "./arquivo.php"],
  "tailwind_safelist": ["bg-red-500", "md:grid-cols-3"]
}

• caminhos são relativos a uma raiz permitida e não podem escapar do projeto;

• classes dinâmicas devem ser tokens completos;

• fontes comuns a muitos recursos podem pertencer à base compartilhada do módulo/core;

• todas as dependências participam do fingerprint.

Distribuição Tailwind sem arquivo global

Input central continua existindo

A remoção de system-output.css não elimina o papel de gestor/assets/tailwindcss/system-input.css. Esse arquivo deixa de ser um scanner global que produz CSS servido ao navegador e passa a ser o contrato central de design do core, usado somente no build.

De forma equivalente, cada projeto pode manter um único input central, como contents/tailwindcss/input.css, para declarar uma vez:

• @theme e tokens de cores, tipografia, espaçamentos e breakpoints;

• @custom-variant, @utility e demais extensões Tailwind suportadas;

• plugins/configurações compatíveis com o CLI adotado;

• CSS base ou regras compartilhadas que devam ser emitidas pelo layout;

• referências/herança do contrato de design do core.

O desenvolvedor altera esse input central uma vez. Não haverá um input Tailwind manual para cada página, layout ou componente.

Inputs por recurso são temporários e gerados

O builder cria, em diretório temporário ignorado pelo Git, um input mínimo para cada recurso. Esse arquivo apenas combina:

1. referência ao input central aplicável;

2. import das camadas necessárias;

3. @source apontando para o HTML e fontes adicionais daquele recurso;

4. safelist/tokens declarados nos metadados.

Exemplo conceitual de layout, que precisa emitir tema/Preflight:

@import "<input-central-do-projeto>";
@source "<layout-id>.html";

Exemplo conceitual de página/componente, que precisa somente das utilities e deve conhecer o tema sem reemiti-lo:

@reference "<input-central-do-projeto>";
@import "tailwindcss/utilities.css" layer(utilities) source(none);
@source "<recurso-id>.html";

A sintaxe e ordem exatas deverão ser validadas na prova de conceito com a versão Tailwind fixada; os exemplos definem a responsabilidade, não um template já aprovado.

O input central deve desativar descoberta ampla/automática quando usado pelo builder, por exemplo com source(none). Somente os inputs temporários informam as fontes pontuais. Dessa forma, manter tema e regras em um único local não volta a gerar o antigo CSS de todo o sistema.

Perfis e invalidação

• recursos do core usam, por padrão, o perfil/input central do core;

• recursos privados usam o perfil/input central do projeto, que pode estender o core;

• layouts podem selecionar outro perfil por metadado quando um projeto possuir mais de um tema;

• páginas/componentes herdam o perfil da composição ou declaram explicitamente um perfil compatível;

• o hash do input central e de toda sua cadeia de referências participa do fingerprint de cada consumidor;

• alterar tema, utility ou variant no input central recompila automaticamente todos os recursos afetados, mesmo que seus HTMLs não tenham mudado.

Assim, a fragmentação ocorre somente nas saídas css_precompiled; a manutenção de tema e regras continua centralizada.

Simetria entre release do core e deploy do projeto

O mesmo builder deve operar nos dois modos já existentes de atualizacao-dados-recursos.php:

O modo --project-path já troca BASE_PATH, RESOURCES_DIR, MODULES_DIR e DB_DATA_DIR para a raiz do projeto. O novo estágio Tailwind deve usar essa mesma decisão para localizar o input central, manifesto e sidecars, sem duplicar o gerador PHP.

No [REDACTED], todo o tema Photon existente em contents/tailwindcss/input.css permanece centralizado nesse arquivo. O deploy percorre pontualmente cada recurso Tailwind presente no gestor do projeto — inclusive recursos do core copiados e recursos privados — e compila cada saída contra o perfil do projeto. Alterar qualquer token Photon invalida os consumidores do projeto pelo hash do input central.

O wrapper atual executa antecipadamente um comando completo configurado em tailwindcss/cli, com -i e -o apontando para o output global. Esse passo deverá ser removido. Em seu lugar:

1. o wrapper resolve projeto e comando-base do CLI;

2. chama uma única vez atualizacao-dados-recursos.php --project-path=... com a configuração estruturada;

3. o PHP/builder cria e executa os inputs temporários por recurso;

4. importa os sidecars nos Data.json;

5. somente depois o deploy cria o ZIP ou sincroniza arquivos.

A configuração deve separar comando e input central, por exemplo com contratos equivalentes a tailwindcss/command e tailwindcss/input, mantendo fallback transitório de leitura do antigo tailwindcss/cli. O builder controla -i, -o, minificação e fontes; o environment.json não deverá mais guardar um comando fechado para um output global.

Layout como proprietário da base

Como o documento final é sempre composto por layout + página, todo layout cujo framework_css = tailwindcss será o proprietário da base necessária àquela composição. Seu css_precompiled deverá conter:

• tema e tokens aplicáveis ao core ou ao projeto;

• Preflight, emitido uma única vez na composição;

• utilities utilizadas pelo próprio layout;

• classes compartilhadas que sejam responsabilidade explícita daquele layout.

O tema Photon atualmente presente no input global do [REDACTED] passa a ser entrada de build dos layouts Tailwind do projeto. Ele pode continuar existindo como fonte de compilação não pública, mas não produzirá um output.css global servido aos visitantes.

Demais recursos

O css_precompiled de página, componente, template e recurso dinâmico opt-in contém somente utilities/variants necessárias ao próprio recurso. Durante a compilação, ele referencia o contrato de tema do layout sem reemitir tema e Preflight. A prova de conceito Tailwind v4 validará imports utilities-only, source(none)/@source e @reference.

Componentes reutilizáveis não devem incorporar uma cópia de Preflight. Se dependerem de tokens não presentes em todos os layouts compatíveis, essa dependência precisa ser declarada e validada.

Ausência de layout e previews

• uma página Tailwind sem layout compatível deve falhar na validação ou declarar explicitamente modo autossuficiente que emita sua própria base;

• o editor de páginas carrega o css_precompiled do layout selecionado;

• previews de componentes/templates usam um layout/base de preview declarado por framework/projeto, também vindo de um recurso no banco;

• não reintroduzir uma folha global oculta apenas para fazer o preview funcionar.

Remoção dos artefatos globais

Após o modo sombra e a validação:

• remover a inclusão de tailwindcss/system-output.css em gestor_pagina_css();

• remover as inclusões de system-output.css e output.css montadas pelo editor e pelos previews;

• remover a dependência de contents/tailwindcss/output.css das configurações do projeto;

• parar de gerar e empacotar os dois outputs globais nos workflows/scripts;

• remover os arquivos gerados do repositório quando nenhum consumidor restante for encontrado;

• manter somente fontes de tema/build necessárias ao compilador por recurso, sem servi-las diretamente no runtime.

Durante a migração, os arquivos globais podem continuar temporariamente sob feature flag apenas para comparação/rollback. O estado final aceito não possui CSS Tailwind global.

Integração em atualizacao-dados-recursos.php

O script será o ponto autoritativo da sequência:

1. carregar metadados;

2. descobrir somente recursos Tailwind válidos;

3. executar o builder incremental;

4. calcular checksums incluindo o sidecar;

5. ler <id>.html, <id>.css e <id>.precompiled.css;

6. gravar html, css e css_precompiled nos arrays/JSONs;

7. continuar schema, hooks, validações e órfãos.

Essa alteração deve ser aplicada simetricamente aos quatro coletores fixos, tanto globais quanto de módulos. O coletor genérico sync_resources deve reconhecer um tipo declarativo file:precompiled.css (ou contrato equivalente) somente para tabelas opt-in.

Não executar a configuração por eval. Migrar para comando-base estruturado, preferencialmente lista de argumentos, mantendo compatibilidade transitória com tailwindcss/cli. Os parâmetros -i, -o, fontes e flags pertencem ao builder.

Opções esperadas:

• compilar e importar;

• importar sidecars existentes sem CLI;

• forçar rebuild;

• informar comando-base;

• limitar concorrência;

• diagnóstico sem escrita.

Nenhuma opção é chamada pelo runtime web público.

Recuperação inversa

• <id>.precompiled.css é artefato regenerável e normalmente não precisa ser tratado como fonte autoral.

• A recuperação do banco deve preservar css_compiled online sem convertê-lo em sidecar offline.

• Se for necessário exportar css_precompiled, fazê-lo explicitamente como artefato, nunca como <id>.css.

Runtime e ordem das camadas

Criar um acumulador separado, por exemplo $_GESTOR['css-precompiled'], com deduplicação pelo conteúdo integral. A composição recomendada é:

1. CSS padrão não Tailwind e CSS próprio do projeto que não seja gerado pelo Tailwind;

2. css_precompiled do layout Tailwind, incluindo tema/Preflight;

3. css_precompiled de página, componentes e widgets;

4. css_compiled online;

5. css autoral;

6. CSS final já existente.

Isso preserva a precedência atual em que CSS autoral vem depois do compilado. A ordem exata entre recursos deve ser validada com layers e composição real. Layouts devem usar o mesmo helper de deduplicação dos componentes, evitando caminhos diretos sem hash.

Nova regra de updateCSSCompiled()

Paridade entre CLI e compilador live

O problema atual não é apenas deduplicação posterior. O iframe carrega @tailwindcss/browser@4, system-output.css e o output.css Photon, mas o compilador live não recebe o @theme e as extensões declaradas no input central do projeto. Ele pode gerar uma utility com o mesmo seletor e declarações diferentes; em seguida, o filtro atual remove uma delas somente pelo nome do seletor.

O release/deploy deverá derivar automaticamente, a partir do mesmo input central usado pelo CLI, um contrato Tailwind para o navegador. Não haverá um segundo tema mantido manualmente.

Esse contrato deverá:

• preservar @theme, tokens, utilities e variants compatíveis com o browser build;

• remover @source de filesystem e imports exclusivos do CLI, pois o navegador detecta classes no DOM do iframe;

• converter o tema para modo de referência quando o layout já fornece as variáveis, evitando reemissão desnecessária;

• reescrever/validar URLs relativas quando houver assets referenciados;

• registrar hash, versão Tailwind e perfil de origem;

• falhar no build com diagnóstico quando encontrar plugin/diretiva que o browser build não suporte, em vez de compilar silenciosamente com comportamento diferente.

O artefato browser-safe pode ser armazenado como metadado do perfil no banco ou como artefato interno do deploy, mas deve ser sempre gerado do input central. O editor recebe seu conteúdo junto de gestor.html_editor, com codificação segura, e cria no iframe uma folha identificada:

<style type="text/tailwindcss" data-tailwind-role="design-contract">
  /* contrato browser-safe gerado do input central */
</style>

Para evitar injeção ou encerramento acidental de </style> dentro do srcdoc, preferir transportar o conteúdo codificado e atribuí-lo por textContent antes de carregar o browser compiler. Fixar a versão exata de @tailwindcss/browser igual à versão do CLI; não usar o alias móvel @4.

Há dois modos:

1. Delta normal: o layout já possui css_precompiled; o contrato fornece tema por referência e o browser gera somente utilities novas do recurso.

2. Layout online ainda sem precompiled: o browser gera temporariamente uma saída autossuficiente em css_compiled, incluindo a base necessária. No próximo release/deploy, o layout recebe css_precompiled canônico e o delta online é recalculado sem duplicar a base.

Com isso, o fluxo passa a ser:

input central do CLI
        ├── sidecars css_precompiled (release/deploy)
        └── contrato browser-safe (editor online)
                    ↓
             compilação live com o mesmo tema

Somente depois dessa paridade updateCSSCompiled() faz a deduplicação estrutural contra layout, recurso e dependências.

Papéis explícitos no iframe

Marcar as folhas pelo papel, não pelo nome do arquivo ou posição no <head>:

• layout-precompiled;

• resource-precompiled;

• dependency-precompiled;

• dependency-compiled;

• resource-existing-compiled;

• live-output.

Base de deduplicação

A nova saída online será comparada com:

• css_precompiled do layout, que inclui tema/Preflight;

• css_precompiled do próprio recurso;

• CSS pré-compilado/compilado das dependências já carregadas.

O css_compiled existente do próprio recurso não entra na base de exclusão. Ele é usado somente para preview de fallback e para detectar se o resultado novo mudou. Caso fosse usado para exclusão, regras antigas poderiam sumir do valor persistido no próximo carregamento.

Resultado canônico

CodeMirrorCssCompiled é substituído integralmente pelo delta novo canônico. Não fazer união cumulativa. Assim, retirar uma classe do HTML também elimina sua regra online obsoleta.

A equivalência deve considerar:

• cadeia de contexto (@layer, @media, @supports etc.);

• seletor;

• declarações normalizadas/cssText;

• regras globais relacionadas, como @keyframes, quando aplicável.

Mesmo seletor com contexto ou declarações diferentes não é duplicata.

Sincronização orientada a eventos

Remover setTimeout(750) e a suposição da última <style>:

1. aguardar load do iframe;

2. observar a folha marcada live-output;

3. aguardar conteúdo não vazio e estável, com timeout explícito;

4. opcionalmente validar uma classe sentinela;

5. calcular o delta canônico;

6. atualizar CodeMirror e a folha de preview do recurso;

7. em falha, manter resource-existing-compiled e mostrar erro.

CLI e navegador devem usar a mesma versão Tailwind e o mesmo contrato de tema.

Integração em release, sync e deploy

Convergir para a mesma operação autoritativa:

• .github/workflows/release-gestor.yml;

• tarefa Manager - GIT Release;

• build/sincronização local do gestor;

• sync core → projeto;

• tarefa Projects - Deploy Project -> ID;

• scripts equivalentes em ai-workspace/en e ai-workspace/pt-br;

• variantes de update-resource-data.sh/atualizacao-dados-recursos.sh.

O builder roda antes de empacotar/copiar JSONs. O ZIP pode continuar excluindo as pastas físicas de recursos, porque css_precompiled já estará nos dados do banco.

Definir política explícita de Git para sidecars e manifesto. Recomendação: versioná-los para reprodutibilidade e revisão; não versionar inputs temporários.

Progresso e observabilidade do gerador de recursos

O gerador atualmente envia quase todos os detalhes somente para log_disco_local() quando --log-disco está ativo e imprime no terminal apenas o relatório final. Em execuções demoradas, a tela aparenta estar travada. A saída padrão deverá mostrar progresso útil em tempo real sem despejar detalhes internos.

Nível padrão

Imprimir uma linha ao iniciar e concluir cada macroetapa, com duração, e resumos ao terminar cada tipo de recurso:

? Atualizando recursos do projeto: <caminho resumido>
[1/8] Carregando mapa de idiomas e recursos...
[1/8] Mapa carregado: 2 idiomas (0,04s)
[2/8] Atualizando metadados dos arquivos de origem...
[2/8] Metadados atualizados (0,18s)
[3/8] Carregando dados existentes para comparação...
[4/8] Compilando Tailwind por recurso: 12 alterados, 44 em cache...
       [7/12] templates/pages-index-grid (pt-br)
[5/8] Coletando recursos...
       Layouts: 4 | Páginas: 79 | Componentes: 29 | Templates: 14
[6/8] Gravando arquivos Data.json e órfãos...
[7/8] Atualizando schema-metadata e executando hooks...
[8/8] Validando resultado...
♻️  Relatório Final:
...

Regras do nível padrão:

• não imprimir cada variável ou cada registro dos 718 itens;

• imprimir cada recurso que efetivamente disparar o Tailwind CLI, pois é a unidade que pode demorar ou falhar;

• recursos encontrados no cache são resumidos por tipo, não listados individualmente;

• coletores sem CLI mostram uma linha por tipo concluído com quantidade;

• etapas longas sem mudança de item emitem heartbeat periódico, por exemplo a cada 10 segundos, com etapa, progresso e tempo decorrido;

• caminhos exibidos devem ser relativos/resumidos; caminhos absolutos e detalhes técnicos ficam no modo verbose/log em disco;

• preservar integralmente o relatório final atual e acrescentar estatísticas do Tailwind: descobertos, compilados, cacheados, removidos e falhos.

Modos de saída

• padrão: etapas, contadores e recursos efetivamente compilados;

• --quiet: somente avisos, erros e relatório final, apropriado para automações que desejem pouca saída;

• --verbose: inclui cada arquivo/metadado, decisões de cache, sidecars, Data.json e hooks;

• --no-ansi: sem cores, emojis de controle ou atualização da mesma linha, para logs de CI/arquivo;

• --log-disco: continua gravando o diagnóstico técnico completo, independente do nível visual escolhido.

Não depender de barra reescrita com \r, pois VS Code Tasks, GitHub Actions e redirecionamentos podem não renderizá-la corretamente. Cada evento relevante deve terminar com quebra de linha.

Flush e diagnóstico de falha

Criar uma função central de progresso, separada de log_disco_local(), que:

• escreva em STDOUT e force flush após cada mensagem;

• desative/contorne buffering de saída no modo CLI quando possível;

• registre horário/duração internamente sem poluir o texto padrão;

• mantenha a última etapa e o último recurso corrente;

• em exceção, mostre imediatamente etapa, recurso, mensagem e localização do log detalhado;

• devolva exit code diferente de zero em erro fatal. O catch atual imprime o erro, mas precisa garantir falha do processo para que os wrappers não mostrem [SUCCESS] indevidamente.

Os wrappers em inglês e português devem anunciar claramente a transição entre Tailwind, compilador de recursos e empacotamento, evitando mensagens de sucesso duplicadas ou sucesso após falha.

Migração de banco

1. Adicionar css_precompiled como MEDIUMTEXT/tipo Phinx equivalente ao atual css_compiled, anulável e sem conteúdo inicial obrigatório. A migração 20250918120000_add_css_compiled_to_tables.php é a referência para páginas, layouts e componentes; templates já nasceram com css_compiled e entram na nova migração.

2. Atualizar schema declarativo, metadados, instalador e atualizador incremental.

3. Atualizar selects, modelos e helpers das tabelas abrangidas.

4. Adicionar o campo aos JSONs gerados pelo compilador de recursos.

5. Não expor css_precompiled como textarea editável comum: ele é artefato de build, preferencialmente somente leitura/diagnóstico.

6. Preservar css_compiled online em registros user_modified.

7. Fazer rollout compatível: código novo tolera vazio; coluna é criada antes de o runtime tentar lê-la.

No ambiente de desenvolvimento, os loaders hoje substituem html e css do banco pelos arquivos físicos. Eles também deverão procurar <id>.precompiled.css; caso contrário, o teste local enxergará uma combinação diferente daquela publicada no banco.

Fases

Fase 0 — baseline e prova de conceito

• Medir tamanho, CSS não utilizado, render-blocking e LCP.

• Provar recurso global e de módulo no core e no [REDACTED].

• Validar utilities-only, tema, variants, arbitrary values, media e keyframes.

Fase 1 — schema e builder em modo sombra

• Criar migração e contrato css_precompiled.

• Implementar descoberta, fingerprint, manifesto, sidecars e logs.

• Derivar e validar o contrato browser-safe a partir de cada input central, fixando a mesma versão Tailwind do CLI.

• Implementar a função central de progresso, modos de saída, flush e exit code confiável.

• Manter temporariamente os CSS globais atuais como autoridade apenas durante comparação e rollback controlado.

Fase 2 — importação e runtime

• Estender paths, checksum, coleta e JSONs.

• Injetar css_precompiled como camada separada e deduplicada.

• Validar preservação de user_modified e recuperação.

Fase 3 — eliminar os outputs globais

• Fazer cada layout Tailwind emitir tema, Preflight e suas utilities.

• Retirar todas as inclusões runtime dos outputs globais.

• Parar sua geração e empacotamento e, após busca de consumidores, remover os arquivos gerados.

• Reexecutar testes visuais, de cascata e de performance.

Fase 4 — inverter o editor

• Injetar o contrato browser-safe antes do compilador live e remover a configuração implícita baseada no tema padrão.

• Passar css_precompiled ao iframe com marcador explícito.

• Usá-lo na base da deduplicação da saída online.

• Trocar temporização fixa por observação orientada a eventos.

• Substituir css_compiled por delta canônico e remover regras obsoletas.

Fase 5 — integrar todos os comandos

• Atualizar release, builds, syncs e deploys equivalentes.

• Testar clean build em Windows e Linux CI.

• Inspecionar pacote de deploy sem publicar.

• Rollout controlado com fallback temporário aos outputs globais anteriores; remover a flag após estabilização.

Critérios de aceite

• As três camadas possuem responsabilidades distintas e não se sobrescrevem.

• Somente recursos declarados Tailwind são compilados.

• <id>.css nunca é alterado; o artefato usa <id>.precompiled.css.

• Execução sem mudanças não inicia CLI para o recurso.

• HTML, fontes, safelist, tema, versão e flags invalidam os consumidores corretos.

• Alterar o input central recompila automaticamente seus consumidores; nenhum input por recurso é mantido manualmente.

• Core e projeto usam o mesmo builder, escolhendo respectivamente system-input.css e contents/tailwindcss/input.css pela raiz/modo de execução.

• O deploy do projeto não executa previamente o antigo comando global -i input.css -o output.css; a compilação acontece dentro do pipeline incremental antes dos Data.json e do ZIP.

• Recurso removido/trocado de framework não deixa órfãos.

• Falha aborta release/deploy sem saída parcial.

• JSONs e banco recebem css_precompiled.

• css_compiled online é preservado em atualização de registro protegido.

• Hospedagem pública não executa Node, CLI, PHP CLI, processo ou CRON.

• Nenhum runtime público ou administrativo depende de system-output.css ou do output.css Tailwind global do projeto.

• Os outputs globais deixam de ser gerados/empacotados e são removidos depois da confirmação de zero consumidores.

• Preflight/tema são emitidos pelo layout Tailwind e não se repetem em cada sidecar.

• updateCSSCompiled() deduplica contra css_precompiled, sem espera fixa ou igualdade apenas por seletor.

• O contrato browser-safe é sempre derivado do input central; nenhuma cópia manual do tema existe no JavaScript/configuração do editor.

• Classes Photon e demais tokens customizados produzem declarações equivalentes no CLI e no browser compiler.

• Diretiva incompatível com o browser build bloqueia a geração do contrato com erro acionável.

• Remover classe do HTML remove a regra obsoleta de css_compiled.

• A execução padrão apresenta avanço por macroetapa e por recurso Tailwind compilado, sem períodos longos de tela silenciosa.

• --quiet, --verbose, --no-ansi e --log-disco possuem comportamentos distintos e testados.

• Erro fatal termina com exit code não zero e nenhum wrapper imprime sucesso depois dele.

• Paridade visual é mantida e a eliminação do CSS global/não utilizado é mensurável.

Riscos a validar

• Muitos processos CLI podem alongar clean build; medir concorrência limitada e reutilização.

• CSS inline é retransmitido e pode se repetir entre recursos; medir mantendo a decisão de banco.

• Ordem de layers pode alterar a cascata; validar composição real, não apenas tamanho.

• Classes dinâmicas desaparecem sem fontes/safelist explícitas.

• A sintaxe exata de @reference, utilities-only e fontes depende da versão Tailwind fixada.

• Browser e CLI podem divergir se versão/tema não forem os mesmos; salvar deve acusar incompatibilidade.

Estado local que o futuro executor deve preservar

Este intake é de análise e planejamento. Existem alterações locais anteriores relacionadas à req-113, incluindo controlador estático, testes e documentos SDD. Elas não devem ser descartadas, sobrescritas ou incluídas acidentalmente em outra entrega.

Implementação realizada em 2026-08-14

• migração css_precompiled criada para páginas, layouts, componentes e templates;

• builder incremental integrado ao gerador comum, com manifesto, fingerprint, sidecar atômico, limpeza controlada, safelist/fontes adicionais, falha com exit code e logs por etapa;

• inputs centrais mantidos como contratos de tema com source(none); inputs por recurso são temporários e ignorados pelo Git;

• layout emite tema/Preflight/utilities; página, componente e template emitem utilities-only;

• runtime e modo de desenvolvimento carregam css_precompiled separado de css_compiled;

• editor recebe contrato browser-safe derivado automaticamente, Tailwind Browser fixado em 4.3.0, baseline explícita e captura assíncrona estrutural do delta;

• removidos todos os consumidores e os arquivos globais system-output.css e output.css;

• release, build/sync do core e update/deploy do projeto usam o mesmo gerador incremental;

• resultado real: core 163 recursos e [REDACTED] 56; segunda execução compilou zero e reutilizou 163/56 entradas do cache;

• amostra [REDACTED] photon-admin + [REDACTED]-system-dashboard: 19.530 bytes brutos de CSS específico, contra o antigo output global de aproximadamente 70 KB;

• validação: PHPUnit completo com 255 testes/985 asserções, quatro skips e uma depreciação preexistente; sintaxe PHP, JavaScript e Git Bash aprovada.

Pendente para fechamento: executar migração e homologação visual do editor/páginas, inspecionar o ZIP sem publicá-lo e repetir PageSpeed após deploy controlado.

Correção de homologação 1 — resolução do CLI no Windows

• Sintoma: sync-core-to-project.sh falhava em proc_open() com CreateProcess failed enquanto a execução direta do gerador funcionava.

• Causa: o wrapper repassava a configuração legada iniciada por npx @tailwindcss/cli; no Windows, npx é um shim .cmd que não era resolvido pelo proc_open em modo de argumentos estruturados.

• Correção: o builder agora converte apenas os runners conhecidos npx @tailwindcss/cli e tailwindcss sem caminho para o executável absoluto já localizado em node_modules/.bin, preservando comandos customizados e caminhos absolutos explícitos.

• Diagnóstico: falhas de criação do processo não emitem mais o warning cru do PHP e passam a identificar o executável que não pôde ser iniciado.

• Validação: o comando legado foi reproduzido via TAILWINDCSS_COMMAND com 163 recursos em cache; em seguida, a tarefa completa de sincronização para [REDACTED]-local terminou com código zero e executou o rsync com sucesso.

Correção de homologação 2 — user_modified e propriedade do pré-compilado

• Sintoma: uma página publicada com user_modified=1 mantinha HTML e CSS autorais, mas também preservava o css_precompiled vazio existente antes da migração; o HTML final continha classes Tailwind sem as utilities correspondentes.

• Causa: css_precompiled havia sido incluído incorretamente em preserve_on_user_modified para páginas, layouts, componentes e templates.

• Contrato corrigido: html, css e css_compiled continuam pertencendo ao usuário/editor; css_precompiled pertence sempre ao pipeline local/CI e pode ser atualizado sem limpar user_modified nem sobrescrever conteúdo autoral.

• Defesa transitória: o atualizador de banco filtra css_precompiled mesmo quando recebe um schema-metadata.json antigo, permitindo backfill automático na primeira atualização após o rollout.

• Invalidação de dados: a versão da política passa a integrar o checksum salvo em manager_updates. Instalações que já haviam registrado os mesmos Data.json antes da correção reprocessam uma única vez páginas, layouts, componentes e templates; as demais tabelas permanecem no cache.

• Isolamento Core/projeto: uma atualização do Core não substitui o pré-compilado de um registro marcado como pertencente a projeto privado; esse artefato é atualizado pelo deploy do próprio projeto. Regras explícitas de forcar_atualizacao continuam prevalecendo.

• Orquestração: tanto atualizacoes-sistema.php quanto api.php delegam ao mesmo atualizacoes-banco-de-dados.php; a política foi centralizada no sincronizador e não duplicada nos entrypoints.

• Validação: contratos de Core e [REDACTED] foram regenerados sem css_precompiled na lista de preservação; o builder reutilizou 163/163 e 56/56 recursos em cache.

• Homologação local: após sincronizar o Core, o deploy de [REDACTED]-local reprocessou seletivamente as quatro tabelas de recursos e atualizou somente um layout e uma página (~2), sem apagar manager_updates e sem forçar as demais tabelas. http://localhost/photon/ passou a responder com os blocos layout-precompiled (7.791 bytes) e resource-precompiled (6.397 bytes), incluindo Preflight e as utilities .flex/.grid esperadas.

• Regressão: suíte completa aprovada com 260 testes e 996 asserções; quatro testes ignorados e uma depreciação preexistente.