req-117: Paridade do Tailwind Browser CDN, Painel de Código na Editbar e Correção de Race Condition na Extração do CSS Compilado

• Status do intake: ready-for-intake

• Data: 2026-08-17

• Origem: solicitação do Engenheiro Chefe após diagnóstico de perda de estilos utilitários do Tailwind em páginas salvas, ausência de runtime CDN na Editbar e necessidade de botão/painel de Código no Live Editor

• Classificação: bugfix e extensão de arquitetura de frontend (Editor HTML + Editbar)

• Batch candidato: BATCH-117

1. Contexto e Diagnóstico

Cenário 1: Race Condition no Editor HTML Clássico (html-editor-interface.js)

No Editor HTML dos módulos administrativos (admin-paginas, etc.), a rotina updateCSSCompiled(iframe) dispara capture() aos 100ms.

• O @tailwindcss/browser injeta imediatamente o <style> com @layer theme, @layer base e a declaração vazia @layer utilities;.

• A checagem if (!tailwindStyle) avalia cssRules.length > 0 como verdadeiro prematuramente (devido às regras base).

• O CSS é extraído antes de o mutation observer do Tailwind processar o <body> e popular as classes reais (.text-3xl, .space-y-5, etc.), gravando um @layer utilities 100% vazio em CodeMirrorCssCompiled e no banco de dados.

Cenário 2: Ausência do Runtime Tailwind CDN no Editbar (dashboard.toolbar.js)

No modo de edição ao vivo na página pública (Site Toolbar / Editbar):

• A página pública nasce renderizada apenas com o CSS estático pré-compilado (sem @tailwindcss/browser).

• Ao clicar em "Editar Página", dashboard.toolbar.js injeta jQuery, CodeMirror e html-editor.js, mas não injeta o runtime do @tailwindcss/browser nem o @theme static.

• Se o usuário adiciona novas classes utilitárias no Styler lateral ou no CodeMirror durante a edição:

  1. Visualmente em tempo real: O elemento não reflete o novo estilo porque a classe inexiste no CSS estático da página.

  2. No salvamento: performSave() em dashboard.toolbar.js extrai e envia apenas o html, sem compilar nem enviar css_compiled ao endpoint site-toolbar-save. O backend em dashboard.php nunca atualiza a coluna paginas.css_compiled, e a página recarregada continua sem as novas classes.

Cenário 3: Ausência de Acesso ao Código-Fonte na Editbar (dashboard-site-toolbar.html)

• No Editor HTML clássico (html-editor-interface.js), a aba "Código" (data-tab="visualizacao-codigo") permite visualizar e editar o HTML (html), HTML Extra Head (html_extra_head), CSS autoral (css) e inspecionar o CSS Compilado (css_compiled).

• Na Editbar (c2f-toolbar-editbar), o usuário atualmente não dispõe de um botão para abrir o código da página de forma estruturada.

• É necessário disponibilizar um novo botão "Código" na barra de ferramentas da Editbar, abrindo um painel flutuante equivalente com as 4 sub-abas e sincronização bidirecional em tempo real.

2. Escopo Técnico Requerido

Módulo 1: Blindagem de Polling e Validação de Utilitários em html-editor-interface.js

1. Implementar a verificação recursiva hasGeneratedUtilities(rules) para inspecionar se o bloco @layer utilities (CSSLayerBlockRule com nome utilities e cssRules.length > 0) possui regras filhas reais.

2. Verificar se o documento possui classes a serem compiladas (iframeDoc.body.querySelectorAll('[class]').length > 0).

3. Condicionar o encerramento da captura à presença dos utilitários gerados quando houver classes no HTML (utilitiesReady).

4. Manter o loop de polling assíncrono (setTimeout(() => capture(attempt + 1), 100)) com limite seguro (até 40 tentativas / 4 segundos).

Módulo 2: Injeção do Tailwind Browser e Extração de css_compiled no Live Editor (dashboard.toolbar.js)

1. Ativação da Edição (activateEditor / startEdit):

   • Ao iniciar a edição in-place em páginas com Tailwind (framework === 'tailwindcss'), injetar na página hospedeira:

     • A tag <style type="text/tailwindcss" data-c2f-tailwind-role="browser-contract"> com o @theme static (mesmo contrato do build offline).

     • O script do CDN: <script src="[REDACTED]></script>.

   • Isso permite que qualquer classe nova adicionada pelo usuário via Styler, painel de inserção ou CodeMirror seja renderizada instantaneamente na tela.

2. Salvamento (performSave):

   • Capturar o CSS compilado gerado pelo runtime do Tailwind na página hospedeira (usando a mesma lógica robusta de filterRules e hasGeneratedUtilities).

   • Anexar css_compiled ao corpo do POST enviado para dashboardAjaxUrl() + '?ajax=1&ajaxOpcao=site-toolbar-save'.

   • O backend em dashboard.php (dashboard_ajax_site_toolbar_save) já aceita css_compiled no array $campos e persistirá o valor atualizado em paginas.css_compiled.

Módulo 3: Botão e Painel de "Código" na Editbar (dashboard-site-toolbar.html, dashboard.iframe-toolbar.js, dashboard.toolbar.js)

1. Botão na Editbar (dashboard-site-toolbar.html pt-br / en):

   • Inserir o botão <button type="button" id="c2f-code-btn" title="Código da página"> ao lado do botão Assistente IA (#c2f-ai-btn).

   • Ícone representativo de código (</>) com rótulo "Código" (PT-BR) / "Code" (EN).

2. Ponte de Comunicação (dashboard.iframe-toolbar.js):

   • Listener de clique no #c2f-code-btn disparando window.parent.postMessage({ type: 'c2f-toolbar:edit-code', x: r.left, y: r.bottom }, origin).

3. Painel Flutuante de Código (c2f-code-panel em dashboard.toolbar.js):

   • Montar o painel na página hospedeira (mesmo padrão do #c2f-page-config-panel e #c2f-ai-panel).

   • Blindagem e Isolamento: Registrado no isEditorOwned() de html-editor.js, com barreiras de evento de clique para não vazar seleção para a página atrás, e fechamento integrado em dismissHostPanels().

   • 4 Sub-abas com CodeMirror (tema 'tomorrow-night-bright', indentUnit 4, refresh dinâmico ao alternar abas):

     • Aba HTML: Exibe o HTML limpo do corpo (html), sincronizado com o DOM vivo do c2fEditor.

     • Aba HTML Extra Head: Exibe/edita o cabeçalho extra (html_extra_head).

     • Aba CSS: Exibe/edita o CSS autoral da página (css).

     • Aba CSS Compilado: Exibe o CSS utilitário gerado em tempo real pelo @tailwindcss/browser (css_compiled).

4. Sincronização Bidirecional:

   • Ao abrir o painel, o CodeMirror carrega o estado exato e atual do DOM em edição.

   • Alterações no CodeMirror de HTML/CSS aplicam ao vivo no DOM da página hospedeira e re-disparam a compilação do Tailwind Browser.

   • No salvamento (performSave), as alterações de html, css, html_extra_head e css_compiled são unificadas no payload do site-toolbar-save.

Módulo 4: Testes Automatizados e Paridade de Ambientes (Vitest)

1. Cobrir a detecção de regras em @layer utilities com objetos CSSOM simulados.

2. Testar o fluxo de extração em html-editor-interface.js e em dashboard.toolbar.js.

3. Testar a abertura, sincronização e persistência do painel de Código da Editbar.

4. Garantir que node --check e a suíte completa de testes passem com 100% de sucesso.

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

1. Edição Clássica (Admin-Páginas): Ao salvar no Editor HTML, o campo CodeMirrorCssCompiled recebe todas as classes utilitárias da página dentro de @layer utilities { ... }.

2. Edição ao Vivo (Editbar): Ao editar diretamente na página pública, novas classes digitadas ou selecionadas no Styler têm efeito visual imediato na tela.

3. Persistência Completa na Editbar: Salvar via Editbar atualiza html, css, html_extra_head e css_compiled no banco de dados (paginas), garantindo fidelidade visual pública após o recarregamento.

4. Painel de Código na Editbar: Clicar no botão "Código" abre o painel flutuante com as 4 abas e editores CodeMirror funcionais, sem vazamento de clique para o elemento de trás.

5. Sincronia de Código: Alterações no CodeMirror do painel de código atualizam o DOM da página hospedeira e vice-versa.

6. Sem Race Conditions: Nenhuma extração encerra prematuramente com @layer utilities; vazio quando há classes utilitárias no HTML.

7. Testes Unitários: Testes do Vitest (npx vitest run) e node --check 100% verdes sem regressão.