req-115: Extração de HTML Dinâmico de PHP/JavaScript para Recursos

• Status do intake: implementation-in-progress

• Data: 2026-08-14

• Origem: solicitação direta durante a homologação da compilação Tailwind por recurso

• Classificação preliminar: refatoração arquitetural incremental de Core e projetos privados

• Batch candidato: BATCH-115

• Dependência: req-114 fornece css_precompiled e tailwind_sources; este lote reduz e governa as fontes dinâmicas que ficaram fora dos recursos

Problema confirmado

O compilador Tailwind por recurso examina o HTML físico e as fontes adicionais declaradas em tailwind_sources. Há, porém, HTML de interface construído diretamente em PHP e JavaScript. As classes presentes somente nesses fragmentos podem ser eliminadas do sidecar do recurso.

O primeiro caso reproduzido foi dashboard-site-toolbar: o HTML físico contém o shell, mas o elemento #c2f-toolbar-menu e seus itens são montados em dashboard.php. Utilities exclusivas desse fragmento, como max-h-96, overflow-auto, text-[10px], italic e estados focus:*, não existiam no css_precompiled original.

tailwind_sources resolve a cobertura de compilação, mas é uma ponte. A direção arquitetural é:

1. estrutura visual estável em componentes/templates de recursos;

2. dados e estado continuam sendo produzidos por PHP/JavaScript;

3. textos localizáveis saem do código e usam recursos por idioma/variáveis;

4. o código clona/preenche estruturas declaradas, em vez de concatenar HTML.

Inventário heurístico inicial

Os números abaixo contam arquivos ou linhas candidatas e precisam de revisão semântica; não significam que toda ocorrência deve virar um componente.

Core

• 32 arquivos JavaScript usam innerHTML, insertAdjacentHTML, outerHTML, document.write ou createElement;

• 36 arquivos PHP contêm literais HTML com classes;

• maiores produtores JavaScript: html-editor.js (123 tags candidatas), admin-arquivos.js (64), menus.js (45), galleries.js (25) e html-editor-visual-controls.js (21);

• módulos com recursos Tailwind e HTML dinâmico relevante:

  • dashboard: PHP e JavaScript do toolbar;

  • forms e forms-search;

  • galleries e menus;

  • pages-index, publisher-index e publisher-highlights;

  • publisher.

Projeto REDACTED/REDACTED

• [REDACTED]-system.js: 358 linhas candidatas e 14 recursos Tailwind relacionados;

• subscriptions.php: 40 linhas candidatas e 16 páginas Tailwind;

• busca-clinica.js: 14 linhas candidatas;

• subscriptions-plans.js: 14 linhas candidatas;

• utilities observadas no JavaScript e ausentes de todos os 14 sidecars do módulo [REDACTED]-system: text-red-500 e min-w-full.

Também há textos de interface diretamente no JavaScript, por exemplo estados vazios, mensagens de erro, upload, busca, documentos, categorias e histórico. A extração deve tratar estrutura e localização juntas para não apenas mover strings HTML entre arquivos.

Diagnóstico dos registros vazios no banco local

Na instalação [REDACTED]-local, a tabela paginas possui 53 registros Tailwind: 41 com css_precompiled e 12 vazios. Os 12 vazios não correspondem a recursos físicos atuais descobertos pelo builder:

• home-alternativa e teste-de-pagina;

• contacts e contacts-success antigos sob o módulo removido/renomeado signatures;

• signature, signature-checkout e welcome-pro, em português e inglês.

As versões atuais de contacts e contacts-success, sob subscriptions, coexistem no banco e possuem 7.333 e 4.501 bytes de pré-compilado. Portanto:

• apagar manager_updates não cria fonte física ausente;

• registros antigos são uma questão de reconciliação/órfãos, não de checksum;

• páginas criadas apenas no editor podem legitimamente não ter css_precompiled e dependem de css_compiled;

• um recurso que deveria pertencer ao código precisa primeiro ser recuperado/criado na árvore de recursos para então ser compilado.

Classificação de destino

Componente

Usar para fragmento reutilizável ou shell visual estável: menu do toolbar, estados vazios, cards, feedback, badges, cabeçalhos, linhas de resultado, modais e controles repetidos.

Template

Usar para modelos escolhidos/instanciados pelo usuário, como menus, galerias, formulários, publicações e índices. O JavaScript deve manipular dados/atributos e clonar o template, não manter uma segunda cópia estrutural em string.

Página/layout

Manter o shell completo e slots explícitos para componentes dinâmicos. O layout continua dono de tema e Preflight; página/componente/template possuem suas utilities específicas.

Variável/localização

Usar para rótulos, mensagens, títulos, placeholders, estados vazios e erros consumidos fora de um HTML localizado. Texto fixo que pertence exclusivamente a um componente pode ficar no próprio recurso por idioma; textos reutilizados ou montados pelo código devem virar variáveis.

Exceção declarada

HTML altamente dependente de dados pode permanecer temporariamente no código quando extraí-lo criaria uma API artificial ou insegura. Toda exceção precisa:

• declarar a fonte em tailwind_sources no recurso consumidor;

• escapar dados variáveis;

• usar identificador/justificativa auditável;

• não conter texto localizável duplicado;

• possuir teste de cobertura das utilities exclusivas.

Estratégia de implementação

Fase 0 — Cobertura imediata

• manter dashboard.php em tailwind_sources de dashboard-site-toolbar até a extração;

• mapear fontes dinâmicas por recurso e adicionar somente as necessárias para evitar regressão visual durante a refatoração;

• testar utilities exclusivas, não apenas tamanho não zero do CSS.

Fase 1 — Contrato de fragmentos para JavaScript

• definir um helper único para expor componentes localizados ao navegador, preferencialmente por elementos <template data-c2f-component="..."> já renderizados pelo servidor;

• JavaScript clona o template e preenche dados por textContent, atributos e nós, evitando interpolação insegura;

• para respostas AJAX, retornar dados mais identificadores de template; HTML pronto só quando o endpoint usar oficialmente o renderizador de recursos.

Fase 2 — Migração por risco

1. dashboard-site-toolbar;

2. [REDACTED]-system e busca-clinica;

3. subscriptions e subscriptions-plans;

4. módulos reutilizáveis menus, galleries, forms*, pages-index e publisher*;

5. infraestrutura administrativa/editor (html-editor.js, admin-arquivos.js), com contrato próprio para não misturar componentes de conteúdo com chrome interno do editor.

Cada migração deve remover a string antiga no mesmo lote; não manter HTML duplicado no recurso e no JavaScript/PHP.

Fase 3 — Textos e tradução

• inventariar strings visíveis em PHP/JavaScript;

• mover mensagens reutilizáveis para variáveis por módulo/idioma;

• manter no componente apenas cópia estritamente pertencente ao fragmento localizado;

• proibir novos fallbacks visíveis em português dentro de JavaScript compartilhado.

Fase 4 — Governança

• auditoria automatizada para novos innerHTML, insertAdjacentHTML e literais <tag...> em PHP/JavaScript fora de allowlist;

• validação de que cada tailwind_sources existe e permanece dentro da raiz do gestor;

• relatório do gerador com quantidade de fontes adicionais por recurso;

• teste que compile um recurso de prova e confirme classes presentes somente na fonte dinâmica;

• relatório de banco distingue recurso atual, página exclusiva do editor e registro órfão.

Critérios de aceite

• c2f-toolbar-menu não depende de HTML concatenado em dashboard.php;

• classes usadas em fragmentos dinâmicos aparecem no sidecar do recurso consumidor;

• nenhum recurso Tailwind versionado pelo código chega ao Data.json com pré-compilado vazio;

• páginas exclusivamente autorais/editor são classificadas separadamente e continuam usando css_compiled;

• Core e projeto não mantêm duas cópias do mesmo fragmento;

• textos visíveis não ficam espalhados em JavaScript/PHP sem contrato de localização;

• CI impede a reintrodução silenciosa de HTML dinâmico fora dos recursos/allowlist;

• regressões cobrem português e inglês, Core e projeto.

Estado da implementação

• inventário inicial e causa raiz confirmados;

• c2f-toolbar-menu extraído integralmente de dashboard.php para quatro componentes de recurso por idioma (menu, item, group e empty);

• quatro textos da toolbar extraídos para variáveis localizadas em português e inglês;

• a página dashboard-site-toolbar deixou de usar tailwind_sources; os utilitários exclusivos agora pertencem aos sidecars dos componentes;

• teste estrutural da toolbar verifica ausência do HTML/textos no PHP, presença dos oito recursos localizados e utilities críticas nos sidecars;

• pontes temporárias por módulo adicionadas em [REDACTED]-system, busca-clinica e subscriptions, cobrindo seis componentes (pt-br/en) e as classes dinâmicas antes ausentes, incluindo min-w-full, text-red-500 e animate-spin;

• toda declaração tailwind_sources passou a exigir tailwind_sources_reason; fontes inexistentes ou fora da raiz continuam causando erro fatal;

• o relatório incremental agora informa recursos e quantidade de fontes adicionais (Core: 0/0;

• sidecar vazio deixou de ser cache válido e também é recusado no modo --tailwind-import-only;

• tarefa updates-manager-database.sh ganhou encaminhamento explícito de --force-all e filtro seguro --tables, eliminando a necessidade de apagar registros de manager_updates;

• geradores do Core e do projeto concluídos sem erro; teste focado aprovado com 11 testes e 56 asserções;

• suíte completa aprovada com 264 testes e 1.041 asserções (quatro testes ignorados e uma depreciação já reportada pelo PHPUnit);

• deploy privado local concluído via API com HTTP 200 após renovação automática do token: seis componentes de cobertura inseridos no banco;

• banco local confirmado em leitura: os seis componentes privados possuem pré-compilado entre 4.109 e 14.019 bytes; a página da toolbar possui 6.303/6.331 bytes;

• http://localhost/photon/ respondeu HTTP 200 com dois blocos pré-compilados na página pública;

• sincronização direcionada da tabela componentes concluída após autorização explícita no ambiente de testes. A primeira execução confirmou que o deploy privado havia deixado o Data do projeto (39 componentes) no destino; o Core foi sincronizado novamente e a repetição processou 128 componentes, inserindo exatamente os oito novos, sem atualizações e sem órfãos;

• banco local confirmado com os quatro componentes da toolbar em português e inglês: sidecars de 4.063 bytes (menu), 285 (empty), 914 (group) e 801 (item), todos com user_modified=0;

• homologação visual inicial mostrou menu estruturalmente recuperado, porém rótulo do botão e placeholder vazios. Causa confirmada: a sincronização anterior havia sido limitada a componentes, deixando de fora as oito novas variáveis localizadas;

• tabela variaveis sincronizada isoladamente após restauração do Data do Core: exatamente oito inserções, zero atualizações e zero órfãos. O banco passou a conter Módulos, Filtre os módulos..., Sem módulos e Outros, além das quatro versões em inglês;

• cobertura dos sidecars conferida diretamente: group-hover:block, focus:outline-none, hover:bg-slate-100, text-[10px] e italic estão presentes nos componentes responsáveis;

• comparação do DOM autenticado de produção e local confirmou que a estrutura dos dropdowns de Módulos, Página e Usuário permaneceu equivalente. Produção carregava o antigo system-output.css; local possuía cinco sidecars de recurso, mas nenhum layout-precompiled/@layer base;

• causa dos controles com aparência/comportamento irregular: dashboard-site-toolbar era uma página Tailwind associada ao layout Fomantic layout-pagina-simples. No contrato por recurso, páginas e componentes emitem utilities, enquanto o layout é responsável pelo Preflight;

• criado o layout global layout-iframe-tailwindcss em português e inglês e a toolbar passou a utilizá-lo. Cada sidecar do layout possui 4.011 bytes e inclui @layer base, box-sizing:border-box, appearance:button e o reset de bordas;

• sincronização local direcionada concluída para layouts,paginas: dois layouts inseridos e as duas páginas localizadas da toolbar ligadas ao novo layout. O banco confirma Preflight e utilities preenchidos, sem user_modified nesses registros;

• segunda captura local mostrou o layout ativo, mas revelou ordem incorreta dos estilos: quatro resource-precompiled eram emitidos antes de layout-precompiled. Como a primeira aparição de uma CSS Cascade Layer fixa sua posição, utilities ficava registrada antes de base, permitindo ao Preflight posterior sobrescrever utilities de controles e afetar a geometria dos dropdowns;

• pipeline runtime corrigido para armazenar cada sidecar como bloco e ordenar estavelmente por papel antes de montar o <head>: layout-precompiled, dependency-precompiled e somente então resource-precompiled. Teste cobre inclusive o caso real em que componentes são carregados antes do layout;

• migração estrutural dos demais fragmentos de [REDACTED]-system, subscriptions e módulos do Core continua incremental. As pontes garantem cobertura visual durante essa transição e não são consideradas estado arquitetural final.

Fechamento da rodada de homologação da Editbar

• homologação do Chefe após Ctrl+F5 confirmou que a Editbar voltou a ficar visualmente muito próxima da versão de produção; a geometria e as cores principais dos dropdowns foram recuperadas;

• a diferença residual percebida como "zoom" não vem da meta viewport: as capturas local e de produção usam igualmente width=device-width, initial-scale=1. O BATCH-083 altera apenas o preview Tablet/Mobile para viewport real em iframe. A diferença restante deve ser tratada como tipografia/cascata entre o pacote global legado e o Tailwind por recurso, sem zoom artificial;

• gestor_componente() revisada: filtros de id, idioma e módulo são escapados; o ID numérico é convertido para inteiro; múltiplos IDs ficam agrupados para idioma e módulo valerem para todo o lote; return_css=false deixou de ser interpretado como ativo; development-env não gera aviso quando ausente; e o sidecar entra explicitamente como resource-precompiled;

• regressão da montagem em lote coberta por GestorComponenteTest. Suíte completa aprovada com 268 testes e 1.060 asserções (quatro ignorados e uma depreciação preexistente do PHPUnit);

• sincronização final para [REDACTED]-local concluída: 173 recursos Tailwind encontrados, 173 em cache e zero erros; bibliotecas/gestor.php foi atualizada no destino de teste.

Migração dos bridges privados — rodada 2

• busca-clinica-runtime-tailwind foi substituído por busca-clinica-runtime-fragments em português e inglês. O componente contém sete elementos <template> reais: ausência de sintomas, tag selecionada, loading, erro, vazio, ausência de sugestões e item de sugestão;

• busca-clinica.js passou a clonar esses templates e preencher dados com textContent e atributos. A única atribuição de innerHTML restante nessa área recebe o HTML de protocolos do renderizador oficial do servidor, exceção prevista no contrato da Fase 1;

• o componente de fragmentos da busca é anexado pelo PHP independentemente do HTML físico da página. Assim páginas com user_modified também recebem os templates e o respectivo css_precompiled sem precisar ganhar um marcador novo;

• subscriptions-runtime-tailwind foi substituído por três componentes de preço do checkout por idioma: plano gratuito, proposta sob medida e plano pago. O controlador agora escolhe o recurso da variação e aplica somente valores escapados; nenhuma classe Tailwind do card permanece no PHP;

• o relatório do gerador caiu de seis para dois recursos com fontes adicionais. Os dois restantes são exclusivamente [REDACTED]-system-runtime-tailwind (pt-br/en);

• [REDACTED]-system.js foi inventariado e concentra busca, síntese, documentos, editor, categorias, cache e arquivos num único asset com dezenas de fragmentos. A ponte foi preservada até essas famílias serem extraídas por tela, pois removê-la agora reintroduziria a regressão visual;

• a diferença residual de escala foi identificada pelo operador como zoom de 110% no navegador. A experiência correta é 100% com o font-size padrão de 16px; a tentativa local de 14px foi removida e todos os 66 recursos do projeto foram recompilados;

• testes estruturais do projeto aprovados: quatro casos cobrem os recursos pt-br/en, ausência das pontes antigas, sidecars preenchidos e propagação para ComponentesData.json.

• deploy para [REDACTED]-local concluído com HTTP 200; a sincronização direcionada de componentes --force-all confirmou 43 registros sem divergência;

• leitura direta da base photon confirmou os oito recursos novos com user_modified=0: fragmentos da busca com 5.036 bytes por idioma e cards do checkout entre 1.383 e 2.291 bytes;

• os quatro registros antigos dos bridges permanecem no banco como legado, porém nenhum controlador os carrega. A remoção física ficou fora desta rodada por ser destrutiva e não ter impacto no runtime.

Homologação da Busca Clínica e bundle canônico por página

• a homologação de busca-clinica revelou uma limitação diferente de cobertura: sidecars individualmente corretos não podem ser simplesmente concatenados, porque os seletores Tailwind continuam globais. Um .hidden de recurso posterior venceu o lg:flex do layout, invertendo sidebar e navegação mobile no desktop;

• o resultado clínico tinha uma segunda causa: busca_clinica_resolve_template() não selecionava nem encaminhava templates.css_precompiled. Por isso utilities existentes no template, como max-h-56 e lg:grid-cols-3, não chegavam ao documento;

• o Core ganhou o papel page-precompiled e a opção explícita $_GESTOR['tailwind-page-bundle']. Quando ativa, somente o bundle canônico da página participa da faixa pré-compilada; CSS autoral e css_compiled do editor continuam no pipeline;

• a página busca-clinica-dashboard declara como fontes seu layout, o componente de fragmentos e os dois templates clínicos selecionáveis. O sidecar final tem 22.427 bytes e conserva a ordem canônica (hidden antes de lg:flex), além de conter max-h-56 e lg:grid-cols-3;

• a adoção é opt-in. Páginas ainda não convertidas continuam usando o contrato anterior de layout/dependências/recursos, evitando uma migração silenciosa e incompleta;

• sincronização do core fonte e deploy privado local concluídos. Core, biblioteca, módulo e sidecar implantados foram confirmados por hash contra os fontes.

• validação final desta fatia: suíte do Core com 269 testes e 1.064 asserções (quatro ignorados e uma depreciação preexistente), além de cinco testes Node do projeto aprovados.

Regressão encontrada após o primeiro deploy do bundle

• o deploy não sobrescreveu os commits: ele ativou no banco o page-precompiled novo. A homologação então revelou que o compilador tratava qualquer página como sidecar isolado, importando apenas tailwindcss/utilities.css;

• como o runtime do bundle elimina o sidecar do layout, também desapareceram @layer theme, @layer base, Preflight, fonte padrão e tokens do projeto. O CSS continha as classes corretas, mas sem o contrato global necessário para interpretá-las de forma consistente;

• tailwind_bundle: true passou a ser metadado explícito de páginas. Nesse modo o compilador importa o input central completo; páginas comuns, componentes e templates continuam gerando somente utilities;

• a página dashboard-site-toolbar também foi convertida em bundle canônico com seu layout iframe e quatro componentes dinâmicos, evitando que a Editbar volte a depender da concatenação de cinco saídas Tailwind independentes.

Diretriz final do operador: produção não possui resources/

• o operador esclareceu que gestor/resources e gestor/modulos/*/resources são apagados dos pacotes de teste/produção; todo recurso consumido em runtime deve vir das tabelas por helpers como gestor_componente(), gestor_layout() e gestor_variaveis();

• apesar de tailwind_sources ser lido apenas antes da compactação, caminhos físicos não devem ser o contrato de dependência entre recursos. O metadado deve referenciar type, module, language e id; somente o compilador local traduz essa referência para um HTML físico;

• tailwind_sources permanece permitido apenas como escape hatch auditado para arquivos brutos ainda não extraídos (PHP/JavaScript). Dependências que já são recursos do Gestor devem usar tailwind_dependencies.

Fechamento técnico do contrato semântico

• Busca Clínica e Editbar foram convertidas para tailwind_dependencies; nenhum dos dois bundles mantém caminho físico de componente/layout/template no metadado;

• o compilador infere o layout pelo ID já existente na página, aceita referência entre módulos e idioma explícito e resolve o arquivo somente na etapa local de build;

• suíte completa do Core aprovada com 272 testes e 1.096 asserções; testes estruturais privados aprovados 3/3. A única pendência desta correção é homologação visual autenticada após Ctrl+F5.