req-111: Desativação do Sanitize HTML para Administradores no Live Editor e Mapeamento de Widgets

Descrição do Problema / Contexto

No BATCH-134 (req-132.md), foi introduzida a higienização automática do HTML (gestor_html_higienizar()), controlada por HTML_SANITIZE no .env.

Essa rotina remove comentários de HTML, CSS, JavaScript e indentação do código-fonte servido ao navegador. Porém, essa higienização estava sendo executada de forma cega para todas as requisições de página, inclusive quando um administrador com a Editbar/Live Editor ativa estava acessando o site.

Consequências do comportamento atual:

1. Quebra dos Marcadores do Live Editor: Ao apagar comentários <!-- widgets#... -->, a Editbar no navegador (dashboard.toolbar.js) perde as referências de início e fim dos widgets e não desenha a seleção amarela/roxa.

2. Perda de Contexto e Raciocínio para Agentes e Desenvolvedores: Agentes de IA e desenvolvedores humanos que inspecionam páginas autenticados dependem dos comentários originais de arquitetura, notas técnicas e indentação no HTML/CSS/JS para depurar e entender a estrutura do layout. Quando o sanitize roda para o administrador logado, esses comentários somem do DOM, gerando ambiguidade e falhas de inspeção.

A premissa correta de segurança é: o visitante público não deve ver nenhum comentário ou marcador interno, mas o administrador autenticado no Live Editor deve receber o HTML original completo, sem qualquer corte ou higienização.

Proposta de Alterações Detalhada

1. Gate Condicional Absoluto em gestor_pagina_higienizar_ativo() (gestor/bibliotecas/gestor.php)

• Em gestor/bibliotecas/gestor.php, na função gestor_pagina_higienizar_ativo():

  • Adicionar a checagem do Live Editor/Editbar ativa no início da função:

    // Se a Editbar estiver ativa (administrador logado com permissão de edição),
    // o sanitize é 100% desativado para entregar o HTML original com todos os comentários intactos.
    if(function_exists('gestor_dashboard_toolbar_ativo') && gestor_dashboard_toolbar_ativo()){
    return false;
    }

  • Resultado:

  • Administrador com Live Editor ativo: Recebe o HTML puro, com todos os comentários de widgets (<!-- widgets#... -->), comentários de desenvolvimento, CSS original, JS original e indentação intactos.

  • Visitante público / Anônimo: O gestor_pagina_widgets() já remove os comentários de widgets, e o gestor_html_higienizar() remove todos os demais comentários HTML/CSS/JS e indentação. Segurança e privacidade totais.

2. Suporte a Widgets Vazios em dashboard.toolbar.js

• Em gestor/modulos/dashboard/dashboard.toolbar.js, na função mapTree():

  • Quando lOpen e lClose forem encontrados, mas rootEls.length === 0 (0 elementos filhas entre o comentário de abertura e fechamento):

  • Atribuir ao contêiner pai liveParent os atributos do widget: data-c2f-widget-id, data-c2f-widget-parent="1", data-c2f-widget-root="1", data-c2f-marker, data-widget-type e data-widget-slug.

  • Permitir que a Editbar selecione e edite contêineres de widgets mesmo que estejam vazios ou sem registros no banco de dados.

3. Ajuste de Mapeamento de Widgets na Raiz do Layout

• Em dashboard.toolbar.js:

  • Permitir a marcação de widgets posicionados diretamente no #c2f-layout-root quando estiver em modo de edição do layout (editingLayout).

Validação e Testes

1. Testes Automatizados (PHPUnit & Vitest):

   • Testar gestor_pagina_higienizar_ativo() simulando $editMode = true (deve retornar false) e $editMode = false em produção (deve retornar true).

   • Testar o mapeamento de widgets vazios no dashboard.toolbar.test.js.

   • Executar composer test e npx vitest run.

2. Validação Manual:

   • Acessar como Administrador com Editbar ativa -> Inspecionar código-fonte e confirmar que todos os comentários e marcadores de widgets estão visíveis e a seleção funciona 100%.

   • Acessar como Visitante anônimo (aba anônima) -> Inspecionar código-fonte e confirmar que o HTML sai 100% limpo, sem nenhum comentário ou marcador de widget.