# Codificador e Decodificador de Entidades HTML: Arquitetura Técnica e Guia Avançado

A Linguagem de Marcação de Hipertexto (HTML) define a estrutura da Web. Normatizada pelo WHATWG HTML Living Standard e pelo W3C, sua gramática reserva delimitadores sintáticos — como &, <, > e aspas (", ') — para separar tags de nós textuais no DOM.

Entradas não tratadas contendo esses caracteres confundem analisadores, provocando quebra de layout, truncamento de atributos e falhas de Cross-Site Scripting (XSS). Para renderizar literais determinísticamente, convertem-se esses delimitadores em entidades HTML (Character References).

O Codificador e Decodificador de Entidades HTML do ToolsAA combina codificador de entidades html, desescapador bidirecional e módulo de sanitização para escapar caracteres html e desescapar html com precisão. Em arquitetura 100% no cliente ("use client"), tokenização, buscas e conversões Unicode executam na memória local do navegador. Zero dados trafegam pela rede, garantindo privacidade e conformidade com a LGPD e o GDPR.

# Visão Geral Abrangente e Casos de Uso no Mundo Real

Entidades HTML substituem caracteres reservados ou não ASCII por sequências padronizadas segundo normas SGML e XML. Uma entidade inicia-se com & e termina com ;. Entre esses limites situa-se um mnemônico (referência nomeada) ou um ponto Unicode (referência numérica, ou NCR).

+---------------------------------------------------------------------------------------------------+
|                                 Anatomia de uma Entidade HTML                                     |
|  Nomeada:     &        amp          ;    --> Resolve para: '&' (U+0026)                           |
|              [Prefixo] [Mnemônico]  [Delimitador]                                                 |
|  Decimal:     &#       38           ;    --> Resolve para: '&' (Unicode Base-10)                  |
|              [Prefixo] [Ponto Dec]  [Delimitador]                                                 |
|  Hexadecimal: &#x      26           ;    --> Resolve para: '&' (Unicode Base-16)                  |
|              [Prefixo] [Ponto Hex]  [Delimitador]                                                 |
+---------------------------------------------------------------------------------------------------+

# Casos de Uso Críticos em Engenharia de Software

• Mitigação de Cross-Site Scripting (XSS): Escapar < para < e > para > permite que analisadores tratem entradas como texto (PCDATA) em vez de nós executáveis no DOM.
• Exibição de Código em Documentações: Exibe tags literais de HTML e JSX em blocos <code>, convertendo <div class="hero"> em <div class="hero">.
• Atributos de Formulários: Previne quebras em <input value="...">, escapando aspas (" para ", ' para ').
• Consistência Tipográfica: Emprega  , “/”, — e © para manter uniformidade entre plataformas.
• Feeds XML e SVG: Assegura conformidade com o XML 1.0, onde um e comercial isolado interrompe o processamento.

# Por Que o Processamento no Cliente É Inegociável para a Privacidade

Conversores online que enviam dados a servidores geram riscos de vazamento de código proprietário, tokens ou dados pessoais.

O envio expõe dados a logs e proxies, violando LGPD, GDPR e SOC 2. O ToolsAA adota Arquitetura 100% Client-Side: toda a execução ocorre na memória do navegador, sem tráfego de rede ou telemetria.

# Arquitetura Técnica e Funcionamento Interno

A manipulação de entidades conecta normas SGML, XML 1.0, WHATWG e o modelo UTF-16 das engines JavaScript.

# 1. O Contínuo de Padrões: XML 1.0, HTML 4.01 e WHATWG Living Standard

• XML 1.0 (W3C): Impõe cinco entidades canônicas (&, <, >, ", '). Outras entidades exigem DTDs; NCRs são universais.
• HTML 4.01 (W3C): Padronizou 252 entidades nomeadas, omitindo ' e gerando incompatibilidades legadas.
• WHATWG HTML Living Standard: Cataloga 2.231 entidades nomeadas e padroniza recuperação determinística em modo quirks.

# 2. Mecânica em Nível de Bytes de Unicode e Pares Substitutos UTF-16

Strings em JavaScript utilizam unidades UTF-16 de 16 bits. Glifos do BMP (U+0000 a U+FFFF) ocupam uma unidade; caracteres astrais como emojis (🚀, U+1F680) exigem pares substitutos (surrogate pairs: 0xD800–0xDBFF alto, 0xDC00–0xDFFF baixo). Iterar com charCodeAt() fragmenta esses pares em substitutos órfãos (��). O ToolsAA calcula valores escalares via codePointAt():

$$\text{CodePoint} = ((\text{High} - 0\text{xD800}) \times 0\text{x400}) + (\text{Low} - 0\text{xDC00}) + 0\text{x10000}$$

Isso gera referências numéricas atômicas unificadas: 🚀 ou 🚀.

# 3. Formatos de Entidades: Nomeadas vs. Decimais vs. Hexadecimais

• Nomeadas (&nome;): Mnemônicos (&, €) mapeados no navegador.
• NCRs Decimais (&#[0-9]+;): Pontos Unicode em base 10 (&, €), universais sem esquemas.
• NCRs Hexadecimais (&#x[0-9a-fA-F]+;): Pontos Unicode em base 16 (&, €), padrão em feeds e SVG.

# 4. DOMParser e Isolamento de Tokens: Por Que innerHTML é um Anti-Pattern

Decodificar strings via innerHTML introduz riscos graves:

• DOM-Based XSS: Injeções como <img src=x onerror=alert(1)> executam scripts na instanciação do elemento.
• Remoção de Tags: Misturar entidades e marcações expurga tags ao ler textContent.
• Requisições Involuntárias: Elementos de mídia disparam conexões automáticas a servidores.

O ToolsAA adota Isolamento de Tokens via Expressões Regulares (/&(#(?:[xX][0-9a-fA-F]+|[0-9]+)|[a-zA-Z0-9]+);/g), substituindo tokens por dicionário imutável e conversor Unicode sem alterar marcações.

# 5. APIs Web do Navegador, Desempenho e Concorrência

• React 18 Concorrente: Entradas usam useDeferredValue(), mantendo 60 FPS na digitação.
• Bufferização Linear: Fatias unem-se via chunks.join("") em tempo linear $O(N)$.
• Canvas Offscreen: Métricas de densidade renderizam em <canvas> offscreen para eliminar reflows.
• Web Crypto: Cargas extensas usam verificação SHA-256 no cliente para integridade instantânea.

# Guia Prático Passo a Passo

# Passo 1: Ingestão de Dados e Presets

Cole o texto no painel ou selecione presets (XSS Defense, XML/SVG Clean, Tipografia). Arquivos podem ser abertos via FileReader sem rede.

# Passo 2: Seleção de Escopo e Formato

• Apenas Essenciais (XML Safe): Converte os cinco delimitadores canônicos (&, <, >, ", ').
• Caracteres Não ASCII: Preserva a tabela ASCII e converte pontos acima de 127 (U+007F).
• Todos os Caracteres (Ofuscação): Converte todos os caracteres em referências numéricas.
• Alterne entre Entidades Nomeadas (&), NCRs Decimais (&) e NCRs Hexadecimais (&).

# Passo 3: Opções Granulares de Escape

• Padronize apóstrofos (' como ').
• Converta espaços fixos (\u00A0) em  .
• Converta quebras de linha em <br /> para fóruns ou e-mails.

# Passo 4: Decodificação Segura e Bidirecional

Para desenvolvedores que necessitam desescapar html:

• Extração Unificada: Decodifica simultaneamente entidades nomeadas, decimais e hexadecimais.
• Resolução Legada: Normaliza entidades não terminadas como &copy 2026.
• Restauração de Quebras: Reconverte <br /> para quebras de linha (\n).

# Passo 5: Métricas e Exportação

Monitore contagem de caracteres, bytes UTF-8 e expansão. Copie o resultado ou exporte em .txt.

# Implementações de Código para Produção

# 1. Implementação em TypeScript / JavaScript Moderno

Codec corporativo com suporte a escopos configuráveis, pares substitutos de 32 bits e decodificação não destrutiva sem usar o DOM:

export type EntityFormat = "named" | "decimal" | "hex";

export class HtmlEntityCodec {
  // Delimitadores canônicos e caracteres tipográficos frequentes
  private static readonly NAMED: Record<string, string> = {
    "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;",
    "\u00A0": "&nbsp;", "©": "&copy;", "®": "&reg;", "™": "&trade;", "€": "&euro;",
  };

  // Codifica caracteres preservando pares substitutos UTF-16
  public static encode(str: string, format: EntityFormat = "named", nonAscii = false): string {
    const out: string[] = [];
    for (let i = 0; i < str.length; ) {
      const cp = str.codePointAt(i)!;
      const ch = String.fromCodePoint(cp);
      if (this.NAMED[ch]) {
        out.push(format === "named" ? this.NAMED[ch] : format === "decimal" ? `&#${cp};` : `&#x${cp.toString(16).toUpperCase()};`);
      } else if (nonAscii && cp > 127) {
        out.push(format === "hex" ? `&#x${cp.toString(16).toUpperCase()};` : `&#${cp};`);
      } else {
        out.push(ch);
      }
      i += cp > 0xffff ? 2 : 1; // Avança 2 unidades fora do BMP
    }
    return out.join("");
  }

  // Decodifica entidades nomeadas e numéricas sem o DOM
  public static decode(str: string): string {
    const map: Record<string, string> = { "&amp;": "&", "&lt;": "<", "&gt;": ">", "&quot;": '"', "&apos;": "'", "&#39;": "'" };
    return str.replace(/&(#(?:[xX][0-9a-fA-F]+|[0-9]+)|[a-zA-Z0-9]+);/g, (m, ent) => {
      if (ent.startsWith("#x") || ent.startsWith("#X")) {
        const cp = parseInt(ent.slice(2), 16);
        return cp <= 0x10ffff && !(cp >= 0xd800 && cp <= 0xdfff) ? String.fromCodePoint(cp) : m;
      }
      if (ent.startsWith("#")) {
        const cp = parseInt(ent.slice(1), 10);
        return cp <= 0x10ffff && !(cp >= 0xd800 && cp <= 0xdfff) ? String.fromCodePoint(cp) : m;
      }
      return map[m] || m;
    });
  }
}

# 2. Implementação em Python 3.11+

Implementação tipada em Python para conversão numérica determinística, validação de limites Unicode e sanitização:

from typing import Literal
import html, re

class HtmlEntityCodec:
    # Regex para capturar entidades nomeadas e numéricas
    _RE = re.compile(r"&(#(?:[xX][0-9a-fA-F]+|[0-9]+)|[a-zA-Z0-9]+);")
    _CORE = {"&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;"}

    @classmethod
    def encode(cls, text: str, mode: Literal["named", "decimal", "hex"] = "named", non_ascii: bool = False) -> str:
        out = []
        for ch in text:
            cp = ord(ch)
            if ch in cls._CORE:
                out.append(cls._CORE[ch] if mode == "named" else f"&#{cp};" if mode == "decimal" else f"&#x{cp:X};")
            elif non_ascii and cp > 127:
                out.append(f"&#x{cp:X};" if mode == "hex" else f"&#{cp};")
            else:
                out.append(ch)
        return "".join(out)

    @classmethod
    def decode(cls, text: str) -> str:
        # Decodifica entidades com validação Unicode sem o DOM
        def _rep(m: re.Match) -> str:
            raw, ent = m.group(0), m.group(1)
            if ent.startswith(("#x", "#X")):
                try: cp = int(ent[2:], 16); return chr(cp) if 0 <= cp <= 0x10FFFF and not (0xD800 <= cp <= 0xDFFF) else raw
                except ValueError: return raw
            if ent.startswith("#"):
                try: cp = int(ent[1:], 10); return chr(cp) if 0 <= cp <= 0x10FFFF and not (0xD800 <= cp <= 0xDFFF) else raw
                except ValueError: return raw
            return html.unescape(raw)
        return cls._RE.sub(_rep, text)

# Armadilhas Comuns, Casos Limite e Solução de Problemas

# 1. Dupla Codificação (&)

Converter & em & transforma < em <, exibindo texto bruto corrompido na tela.

• Solução: Codifique na camada de apresentação. Valide idempotência antes do escape (decode(str) !== str).

# 2. Escape Dependente de Contexto

A codificação de entidades protege nós de texto e atributos, mas falha dentro de <script> ou em URLs.

• Solução: Use JSON.stringify() com escape de < para \u003C em <script>, e codificação percentual em URLs.

# 3. Incompatibilidade de ' no HTML 4 Legado

Omitida do HTML 4.01, a entidade ' falha em leitores de e-mail legados.

• Solução: Padronize a referência decimal ', reconhecida universalmente em HTML e XML.

# 4. Entidades Nomeadas Não Terminadas no Modo Quirks

O WHATWG recupera entidades sem ponto e vírgula (&copy 2026), mas parsers XML estritos rejeitam com erro fatal.

• Solução: Termine invariavelmente todas as entidades com ponto e vírgula (;).

# 5. Fatiamento de Pares Substitutos UTF-16 (Emojis Quebrados)

Iterar strings com charAt() divide emojis (🚀, U+1F680) em pares órfãos (��).

• Solução: Itere com codePointAt() e avance 2 unidades para caracteres fora do BMP (> 0xFFFF).

# 6. Remoção Destrutiva de Tags com innerHTML

Decodificar via innerHTML descarta marcações legítimas e permite a execução indevida de scripts inline.

• Solução: Decodifique entidades via expressões regulares e tabelas imutáveis sem acionar o DOM.

# Perguntas Frequentes (FAQ)

# Q1: Qual é a diferença entre entidades HTML nomeadas, decimais e hexadecimais?

Resposta: Entidades nomeadas usam mnemônicos (©). NCRs decimais usam base 10 (©). NCRs hexadecimais usam base 16 (©). Todas renderizam identicamente, mas referências numéricas operam em XML e SVG sem DTDs.

# Q2: Por que a codificação de entidades HTML não é suficiente para impedir XSS dentro de <script>?

Resposta: Navegadores analisam <script> com gramática JavaScript, onde entidades HTML não são interpretadas. Contextos de script exigem escape JavaScript (JSON.stringify()) com sanitização de \u003C.

# Q3: Por que &apos; falha em clientes de e-mail antigos e por que &#39; é preferida?

Resposta: ' foi omitida do HTML 4.01. Analisadores legados rejeitam '. A referência decimal ' assegura compatibilidade universal em motores HTML e XML.

# Q4: Como caracteres UTF-8 de 4 bytes e emojis se comportam ao serem convertidos em entidades?

Resposta: Emojis (🔥, U+1F525) residem além do BMP, demandando pares substitutos UTF-16. Codificadores calculam o escalar de 32 bits (128293), gerando entidades unificadas válidas (🔥 ou 🔥).

# Q5: Por que usar document.createElement('div').innerHTML para desescapar HTML é perigoso?

Resposta: Atribuir texto externo a innerHTML executa imediatamente payloads inline (<img src=x onerror=alert(1)>), gerando DOM XSS e removendo tags legítimas.

# Q6: Como posso detectar se uma string já foi codificada com entidades HTML?

Resposta: Valide a cadeia contra a regex /&(#(?:[xX][0-9a-fA-F]+|[0-9]+)|[a-zA-Z0-9]+);/. Para confirmar a idempotência, verifique se decode(str) !== str.

# Q7: Meus códigos-fonte ou dados confidenciais são enviados a algum servidor no ToolsAA?

Resposta: Não. O ToolsAA opera em arquitetura 100% client-side ("use client"). Toda a execução ocorre na memória do navegador. Zero dados trafegam pela rede, garantindo conformidade com a LGPD e o GDPR.

# Q8: Quantas entidades nomeadas o HTML5 suporta em comparação com o HTML4 e o XML?

Resposta: O XML 1.0 define 5 entidades canônicas (&, <, >, ", '). O HTML 4.01 catalogava 252 entidades. O WHATWG HTML Living Standard padroniza 2.231 referências cobrindo operadores matemáticos e glifos internacionais.

# Matriz de Comparação Técnica: Formatos e Contextos de Entidades HTML

# Conclusão

Compreender as fronteiras entre marcações e texto literal é vital na engenharia web. Seja para mitigar Cross-Site Scripting (XSS), exibir códigos em documentações, preservar tipografia ou gerar feeds XML, a codificação de entidades assegura renderização determinística.

Ao adotar boas práticas — preferir ' a ', calcular pares substitutos de 32 bits para emojis e aplicar isolamento de tokens em vez de manipular o DOM —, times eliminam dupla codificação e injeções. O Codificador e Decodificador de Entidades HTML do ToolsAA oferece alta performance bidirecional, operando 100% no cliente com privacidade irrestrita.