req-158: Paridade Visual Estrita de Tailwind CSS entre Página Pública, Pré-Visualizador e Editor HTML Visual

Após as correções do BATCH-156 (que isolaram o semantic.min.css do preview de templates), constatou-se que o sistema ainda apresenta 3 renderizações distintas para o mesmo…

Status do intake: ready-for-intake
Data: 2026-09-02
Origem: relato do operador durante testes comparativos na rota /teste-de-pagina/ ([REDACTED]) e no CRUD de páginas ([REDACTED]), onde foram observados 3 comportamentos visuais divergentes entre a Página Pública, o Pré-Visualizador (data-tab="visualizacao-pagina") e o Editor HTML Visual (editorHtmlVisual)
Classificação: arquitetura CSS (3 ambientes), paridade visual de Tailwind v4, isolamento de iframe no Live Editor (html-editor-interface.js), integridade de tokens @theme, gradientes e tipografia
Batch candidato: BATCH-158
Nota de renumeração (2026-09-02): este intake foi cadastrado originalmente como req-156 (commit fef612a7). Um agente concorrente reutilizou o mesmo número para outro escopo (recompilação de recursos no CI/CD, commit 28bd97b6, BATCH-159), sobrescrevendo o arquivo. O conteúdo original foi recuperado do git e recadastrado aqui como req-158, sem alterar o req-156.md nem o BATCH-159 do outro agente. O batch de implementação continua o BATCH-158.

1. Contexto e Diagnóstico Técnico

Após as correções do BATCH-156 (que isolaram o semantic.min.css do preview de templates), constatou-se que o sistema ainda apresenta 3 renderizações distintas para o mesmo conteúdo HTML, dependendo do ambiente em que é visualizado:

Ambiente 1 — Pré-Visualizador (data-tab="visualizacao-pagina"):
- É o ambiente com melhor fidelidade visual, onde seções, espaçamentos e cartões renderizam de forma correta e mais próxima da realidade funcional projetada.
Ambiente 2 — Editor HTML Visual (editorHtmlVisual):
- Apresenta comportamento intermediário com distorções perceptíveis:
  - O botão "Quero escalar agora" perde características visuais (fundo, borda ou contraste);
  - O título "Revolução Digital" aparece com tamanho de fonte menor (font-size) em comparação com o preview;
  - Os botões de rodapé ("Começar gratuitamente" e "Falar com consultor") sofrem perda de formatação e cores;
  - Os espaçamentos internos/externos (padding/margin) e os degradês (gradients) divergem do preview.
Ambiente 3 — Página Pública Final ([REDACTED]):
- Entrega o conteúdo servido pelo roteador gestor.php, cuja cascata depende de paginas.css_precompiled, paginas.css_compiled e project-css. Se o bundle de entrega pública não receber a totalidade dos tokens e utilities compilados no editor, ou sofrer interferência de resets do layout, o resultado final diverge do que foi aprovado no pré-visualizador.

2. Causas-Raiz a Investigar nos Pipelines

Causa-Raiz 1: Contaminação de CSS ou Conflito de Reset no Editor HTML Visual

No Editor HTML Visual (html-editor-interface.js / html-editor.js), o iframe de edição carrega a infraestrutura do Live Editor (overlays, seletores, Styler, CodeMirror, etc.).
Se regras globais de tipografia, resets de fontes ou heranças da barra/painéis do sistema vazarem para o corpo do iframe, classes utilitárias como text-4xl, text-5xl, py-* e px-* têm seus tamanhos sobrescritos por estilos herdados da UI.

Causa-Raiz 2: Assimetria de Tokens `@theme` entre `@tailwindcss/browser` (CDN) e Compilação Offline

O Editor HTML Visual executa o @tailwindcss/browser em tempo real baseado no contrato @theme static injetado pelo html-editor-interface.js.
Se as definições de tokens de cor, famílias tipográficas e escalas de gradiente (linear-gradient, from-*, to-*, bg-gradient-to-*) no contrato do browser divergirem dos sidecars pré-compilados (.precompiled.css) ou do baseline do preview, os degradês e cores de botões CTA renderizam com saturação, opacidade ou escala incorretas.

Causa-Raiz 3: Transição de Estado e Baseline entre Abas do CRUD

Ao alternar entre a aba de Código HTML, a aba de Visualização (Preview) e o acionamento do Editor HTML Visual, a extração e re-injeção do CSS de baseline (HtmlEditorCssCapture / html_editor_css_precompiled_baseline) deve ser atômica e cumulativa, sem descartar sidecars de seções inseridas nem re-introduzir folhas concorrentes sem camada (@layer).

3. Escopo Técnico Requerido

Módulo 1: Isolamento Rigoroso e Paridade do Iframe do Editor HTML Visual (`editorHtmlVisual`)

Localização: gestor/assets/interface/html-editor-interface.js e gestor/assets/interface/html-editor.js.
Ações:
1. Garantir que o iframe do Live Editor (editorHtmlVisual) seja blindado contra qualquer injeção ou vazamento de CSS da UI administrativa do Gestor (Fomantic UI, CSS da editbar, painéis flutuantes);
2. Alinhar o contrato de tema @theme static injetado para o @tailwindcss/browser para que seja 100% idêntico aos tokens e variáveis do runtime de preview;
3. Validar que o tamanho de fonte dos títulos (ex: "Revolução Digital" em text-4xl/text-5xl), botões CTA ("Quero escalar agora", "Começar gratuitamente") e gradientes renderizem com getComputedStyle() idêntico ao pré-visualizador.

Módulo 2: Paridade na Rota Pública (`gestor.php` / `/teste-de-pagina/`)

Localização: gestor/gestor.php (montagem de $csss no cabeçalho público) e gestor/modulos/admin-paginas/.
Ações:
1. Assegurar que ao salvar uma página a partir do editor ou CRUD, o css_compiled / css_precompiled contenha todas as classes de gradiente, botões e tipografia necessárias;
2. Verificar se a ordem de injeção na página pública não permite que folhas de tema do projeto (project-css) sobrescrevam as utilities de gradiente ou cores do conteúdo.

Módulo 3: Sincronização sem Perdas entre Abas do CRUD de Páginas

Localização: gestor/modulos/admin-paginas/admin-paginas.js e html-editor-interface.js.
Ações:
1. Garantir que a alternância entre data-tab="visualizacao-pagina" e editorHtmlVisual preserve exatamente o mesmo estado de CSS, classes e marcação HTML, sem desfasamentos visuais entre as abas.

Módulo 4: Testes Automatizados Unitários e de Integração

Localização: tests/Unit/JS/ e tests/Unit/PHP/.
Cobertura:
1. Testes no Vitest validando a integridade das classes de gradiente, tamanhos de fonte de títulos e cores de botões no ambiente do Live Editor;
2. Testes no PHPUnit validando a entrega correta das folhas no cabeçalho público sem descarte de utilities.

4. Critérios de Aceite e Validação

Paridade Visual Absoluta (3/3 Ambientes):
- A Página Pública (/teste-de-pagina/), o Pré-Visualizador (data-tab="visualizacao-pagina") e o Editor HTML Visual (editorHtmlVisual) devem renderizar com estilização idêntica:
  - Botão "Quero escalar agora" com cor de fundo, contraste e bordas corretas nos 3 ambientes;
  - Título "Revolução Digital" com o mesmo tamanho tipográfico e peso nos 3 ambientes;
  - Botões "Começar gratuitamente" e "Falar com consultor" com estilo, cores e espaçamentos uniformes;
  - Degradês (gradients) com as mesmas cores de início/fim e ângulo nos 3 ambientes.
Sem Vazamento de Estilos de UI: Nenhum seletor da interface do Gestor deve interferir na renderização interna do editor visual.
Suíte Automatizada 100% Verde: Todos os testes PHPUnit e Vitest devem passar com sucesso sem regressões.

# req-158: Paridade Visual Estrita de Tailwind CSS entre Página Pública, Pré-Visualizador e Editor HTML Visual
- **Status do intake**: ready-for-intake
- **Data**: 2026-09-02
- **Origem**: relato do operador durante testes comparativos na rota `/teste-de-pagina/` (`[REDACTED]`) e no CRUD de páginas (`[REDACTED]`), onde foram observados 3 comportamentos visuais divergentes entre a Página Pública, o Pré-Visualizador (`data-tab="visualizacao-pagina"`) e o Editor HTML Visual (`editorHtmlVisual`)
- **Classificação**: arquitetura CSS (3 ambientes), paridade visual de Tailwind v4, isolamento de iframe no Live Editor (`html-editor-interface.js`), integridade de tokens `@theme`, gradientes e tipografia
- **Batch candidato**: BATCH-158
- **Nota de renumeração (2026-09-02)**: este intake foi cadastrado originalmente como `req-156` (commit `fef612a7`). Um agente concorrente reutilizou o mesmo número para outro escopo (recompilação de recursos no CI/CD, commit `28bd97b6`, BATCH-159), sobrescrevendo o arquivo. O conteúdo original foi recuperado do git e recadastrado aqui como `req-158`, sem alterar o `req-156.md` nem o BATCH-159 do outro agente. O batch de implementação continua o **BATCH-158**.
---
## 1. Contexto e Diagnóstico Técnico
Após as correções do **BATCH-156** (que isolaram o `semantic.min.css` do preview de templates), constatou-se que o sistema ainda apresenta **3 renderizações distintas** para o mesmo conteúdo HTML, dependendo do ambiente em que é visualizado:
1. **Ambiente 1 — Pré-Visualizador (`data-tab="visualizacao-pagina"`)**:
   - É o ambiente com **melhor fidelidade visual**, onde seções, espaçamentos e cartões renderizam de forma correta e mais próxima da realidade funcional projetada.
2. **Ambiente 2 — Editor HTML Visual (`editorHtmlVisual`)**:
   - Apresenta comportamento intermediário com distorções perceptíveis:
     - O botão *"Quero escalar agora"* perde características visuais (fundo, borda ou contraste);
     - O título *"Revolução Digital"* aparece com tamanho de fonte menor (`font-size`) em comparação com o preview;
     - Os botões de rodapé (*"Começar gratuitamente"* e *"Falar com consultor"*) sofrem perda de formatação e cores;
     - Os espaçamentos internos/externos (`padding`/`margin`) e os degradês (*gradients*) divergem do preview.
3. **Ambiente 3 — Página Pública Final (`[REDACTED]`)**:
   - Entrega o conteúdo servido pelo roteador `gestor.php`, cuja cascata depende de `paginas.css_precompiled`, `paginas.css_compiled` e `project-css`. Se o bundle de entrega pública não receber a totalidade dos tokens e utilities compilados no editor, ou sofrer interferência de resets do layout, o resultado final diverge do que foi aprovado no pré-visualizador.
---
## 2. Causas-Raiz a Investigar nos Pipelines
### Causa-Raiz 1: Contaminação de CSS ou Conflito de Reset no Editor HTML Visual
- No **Editor HTML Visual** (`html-editor-interface.js` / `html-editor.js`), o iframe de edição carrega a infraestrutura do Live Editor (overlays, seletores, Styler, CodeMirror, etc.).
- Se regras globais de tipografia, resets de fontes ou heranças da barra/painéis do sistema vazarem para o corpo do iframe, classes utilitárias como `text-4xl`, `text-5xl`, `py-*` e `px-*` têm seus tamanhos sobrescritos por estilos herdados da UI.
### Causa-Raiz 2: Assimetria de Tokens `@theme` entre `@tailwindcss/browser` (CDN) e Compilação Offline
- O Editor HTML Visual executa o `@tailwindcss/browser` em tempo real baseado no contrato `@theme static` injetado pelo `html-editor-interface.js`.
- Se as definições de tokens de cor, famílias tipográficas e escalas de gradiente (`linear-gradient`, `from-*`, `to-*`, `bg-gradient-to-*`) no contrato do browser divergirem dos sidecars pré-compilados (`.precompiled.css`) ou do baseline do preview, os degradês e cores de botões CTA renderizam com saturação, opacidade ou escala incorretas.
### Causa-Raiz 3: Transição de Estado e Baseline entre Abas do CRUD
- Ao alternar entre a aba de **Código HTML**, a aba de **Visualização (Preview)** e o acionamento do **Editor HTML Visual**, a extração e re-injeção do CSS de baseline (`HtmlEditorCssCapture` / `html_editor_css_precompiled_baseline`) deve ser atômica e cumulativa, sem descartar sidecars de seções inseridas nem re-introduzir folhas concorrentes sem camada (`@layer`).
---
## 3. Escopo Técnico Requerido
### Módulo 1: Isolamento Rigoroso e Paridade do Iframe do Editor HTML Visual (`editorHtmlVisual`)
* **Localização**: `gestor/assets/interface/html-editor-interface.js` e `gestor/assets/interface/html-editor.js`.
* **Ações**:
  1. Garantir que o iframe do Live Editor (`editorHtmlVisual`) seja blindado contra qualquer injeção ou vazamento de CSS da UI administrativa do Gestor (Fomantic UI, CSS da editbar, painéis flutuantes);
  2. Alinhar o contrato de tema `@theme static` injetado para o `@tailwindcss/browser` para que seja **100% idêntico** aos tokens e variáveis do runtime de preview;
  3. Validar que o tamanho de fonte dos títulos (ex: *"Revolução Digital"* em `text-4xl`/`text-5xl`), botões CTA (*"Quero escalar agora"*, *"Começar gratuitamente"*) e gradientes renderizem com `getComputedStyle()` idêntico ao pré-visualizador.
### Módulo 2: Paridade na Rota Pública (`gestor.php` / `/teste-de-pagina/`)
* **Localização**: `gestor/gestor.php` (montagem de `$csss` no cabeçalho público) e `gestor/modulos/admin-paginas/`.
* **Ações**:
  1. Assegurar que ao salvar uma página a partir do editor ou CRUD, o `css_compiled` / `css_precompiled` contenha todas as classes de gradiente, botões e tipografia necessárias;
  2. Verificar se a ordem de injeção na página pública não permite que folhas de tema do projeto (`project-css`) sobrescrevam as utilities de gradiente ou cores do conteúdo.
### Módulo 3: Sincronização sem Perdas entre Abas do CRUD de Páginas
* **Localização**: `gestor/modulos/admin-paginas/admin-paginas.js` e `html-editor-interface.js`.
* **Ações**:
  1. Garantir que a alternância entre `data-tab="visualizacao-pagina"` e `editorHtmlVisual` preserve exatamente o mesmo estado de CSS, classes e marcação HTML, sem desfasamentos visuais entre as abas.
### Módulo 4: Testes Automatizados Unitários e de Integração
* **Localização**: `tests/Unit/JS/` e `tests/Unit/PHP/`.
* **Cobertura**:
  1. Testes no Vitest validando a integridade das classes de gradiente, tamanhos de fonte de títulos e cores de botões no ambiente do Live Editor;
  2. Testes no PHPUnit validando a entrega correta das folhas no cabeçalho público sem descarte de utilities.
---
## 4. Critérios de Aceite e Validação
1. **Paridade Visual Absoluta (3/3 Ambientes)**:
   - A Página Pública (`/teste-de-pagina/`), o Pré-Visualizador (`data-tab="visualizacao-pagina"`) e o Editor HTML Visual (`editorHtmlVisual`) devem renderizar com **estilização idêntica**:
     - Botão *"Quero escalar agora"* com cor de fundo, contraste e bordas corretas nos 3 ambientes;
     - Título *"Revolução Digital"* com o mesmo tamanho tipográfico e peso nos 3 ambientes;
     - Botões *"Começar gratuitamente"* e *"Falar com consultor"* com estilo, cores e espaçamentos uniformes;
     - Degradês (*gradients*) com as mesmas cores de início/fim e ângulo nos 3 ambientes.
2. **Sem Vazamento de Estilos de UI**: Nenhum seletor da interface do Gestor deve interferir na renderização interna do editor visual.
3. **Suíte Automatizada 100% Verde**: Todos os testes PHPUnit e Vitest devem passar com sucesso sem regressões.