req-125: Enriquecimento Semântico Leve e Extrator de Tokens do Tailwind para o Assistente de IA no Editor HTML

• Status do intake: ready-for-intake

• Data: 2026-08-24

• Origem: solicitação do usuário para capacitar o Assistente de IA com o contexto visual de temas de projetos (Tailwind CSS v4) com compressão inteligente de tokens

• Classificação: inteligência artificial, otimização de tokens, editor HTML, tailwind css v4

• Batch candidato: BATCH-127

1. Contexto e Objetivos

O Assistente de IA integrado ao Editor HTML (html-editor.php e dashboard.toolbar.js) permite que operadores e desenvolvedores criem ou modifiquem páginas, seções e componentes usando inteligência artificial (Gemini).

O Problema Atual:

1. Ausência de Contexto de Marca/Projeto: O backend enviava para a IA apenas {{html}}, {{framework_css}} ("tailwindcss") e {{css}} (CSS autoral vazio). A IA não tinha acesso às cores personalizadas (ex.: bg-mp-red, text-photon-cyan) nem aos componentes utilitários definidos no @theme static do projeto;

2. Risco de Sobrecarga de Tokens: Arquivos de contrato de tema como contents/tailwindcss/browser-contract.css podem atingir mais de 78KB (2.200+ linhas) devido a SVGs embutidos, máscaras e regras detalhadas de @layer components. Enviar o arquivo bruto consumiria mais de 20.000 tokens desnecessários por interação.

Objetivos:

1. Implementar um Extrator Semântico Leve de Tokens em PHP (html_editor_ia_extrair_tokens_tema()), que filtra estritamente declarações de variáveis (--color-*, --font-*, --spacing-*) do bloco @theme e sumários de classes @layer components, descartando data URIs/SVGs e comentários;

2. Limitar o payload injetado a menos de 1.5KB (~350 tokens), alcançando 98% de redução de custo em relação ao CSS bruto;

3. Injetar a variável {{theme_tokens}} nos modos de IA do sistema (ModosIaData.json), garantindo que o Gemini utilize com precisão a paleta e os componentes do projeto.

2. Escopo Técnico Requerido

Módulo 1: Extrator Semântico de Tokens (gestor/bibliotecas/html-editor.php)

• Função html_editor_ia_extrair_tokens_tema(?string $caminhoContrato = null): string:

  • Localiza o arquivo de contrato (contents/tailwindcss/browser-contract.css ou assets/tailwindcss/browser-contract.css);

  • Extrai as variáveis CSS dentro de @theme ou @theme static (ex.: --color-mp-coral: #ff8f70;);

  • Descarta valores com data:image/svg+xml, url(...) extensos e comentários multilinha;

  • Extrai os seletores principais dentro de @layer components (apenas os nomes das classes, ex: .tm-shell, .tm-nav-link);

  • Retorna um bloco compacto e limpo pronto para o prompt do sistema.

Módulo 2: Enriquecimento do Payload AJAX (html_editor_ajax_ia_requests)

• No endpoint html-editor-ia-requests em html-editor.php:

  • Executar o extrator de tokens e substituir a tag {{theme_tokens}} no modo IA ativo;

  • Se a página possuir css_compiled gerado pelo Live Editor, permitir inclusão concisa se solicitado;

  • Tratar escopos de edição (tudo, sessao, editbar-element).

Módulo 3: Atualização dos Modos de IA (gestor/db/data/ModosIaData.json)

• Atualizar os prompts padrão dos modos paginas, paginas-editbar e componentes (em pt-br e en) para incluir a diretriz:

  "Utilize prioritariamente as classes e tokens de tema do projeto listados abaixo quando estilizar elementos:\ncss\n{{theme_tokens}}\n"

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

1. O payload enviado para a API de IA contém as variáveis e classes canônicas do tema do projeto ativo.

2. O tamanho dos tokens de tema extraídos nunca ultrapassa 2KB, mesmo contra arquivos browser-contract.css de 80KB+.

3. A IA passa a gerar código HTML utilizando as cores nativas do projeto (ex.: bg-mp-red, text-mp-gold, color-photon-cyan) sem alucinar cores arbitrárias.

4. Testes unitários PHP e Vitest cobrindo o extrator de tokens 100% verdes.