# Codificador y Decodificador de Entidades HTML: Arquitectura Técnica y Guía Exhaustiva

HTML establece la base estructural de la web bajo el estándar WHATWG HTML Living Standard y la W3C. Reserva delimitadores sintácticos —ampersands (&), corchetes angulares (<, >) y comillas (", ')— para separar etiquetas de nodos de texto (PCDATA).

Al procesar texto con estos caracteres, los analizadores confunden datos con marcado, generando fallos de diseño, atributos truncados y ataques Cross-Site Scripting (XSS). Para renderizarlos fielmente, se convierten en entidades HTML (referencias de caracteres).

El Codificador y Decodificador de Entidades HTML de ToolsAA provee un codificador de entidades html, desescapador bidireccional y saneamiento para escapar caracteres html y desescapar html con precisión. Con arquitectura cliente ("use client"), la tokenización y conversiones Unicode ocurren en memoria del navegador: cero paquetes de red salen del equipo, garantizando privacidad total.

# Visión General y Casos de Uso en Producción

Las entidades HTML reemplazan caracteres reservados, invisibles o no ASCII por secuencias estandarizadas conformes a SGML y XML. Toda entidad inicia con un ampersand (&) y concluye con un punto y coma (;). Entre ambos se sitúa un mnemónico alfanumérico (referencia con nombre) o un punto de código Unicode (referencia numérica de caracteres, o NCR).

+---------------------------------------------------------------------------------------------------+
|                             Anatomía de las Entidades de Caracteres HTML                          |
|  Con nombre:   &        amp          ;    --> Resuelve a: '&' (U+0026)                            |
|               [Prefijo] [Mnemónico]  [Terminador]                                                 |
|  Decimal:      &#       38           ;    --> Resuelve a: '&' (Unicode Base 10)                   |
|               [Prefijo] [Punto Dec]                                                               |
|  Hexadecimal:  &#x      26           ;    --> Resuelve a: '&' (Unicode Base 16)                   |
|               [Prefijo] [Punto Hex]                                                               |
+---------------------------------------------------------------------------------------------------+

# Casos de Uso Críticos en Entornos Empresariales

• Mitigación de XSS: Escapar < a < y > a > fuerza al navegador a interpretar datos como texto (PCDATA), neutralizando nodos DOM ejecutables.
• Código en Documentación: Muestra HTML y JSX literal en bloques <code>, convirtiendo <div class="hero"> en <div class="hero">.
• Atributos en Formularios: Evita rupturas de atributos en <input value="..."> al escapar comillas (" a ", ' a ').
• Consistencia Tipográfica: Usa  , “/”, — y © para renderizado fiel multiplataforma.
• Feeds XML y SVG: Asegura que las cargas cumplan XML 1.0 estricto, donde ampersands sin escapar detienen el parser.

# Privacidad Absoluta: Procesamiento en el Cliente

Utilidades online que envían datos a servidores externos generan riesgos de fuga. Los textos procesados contienen código propietario, esquemas, datos personales o tokens.

Transmitir datos expone cadenas confidenciales a registros y cachés, violando RGPD, HIPAA y SOC 2. ToolsAA opera con Arquitectura de Cliente Puro: tokenización, regex y conversiones se ejecutan localmente en el navegador sin peticiones de red.

# Arquitectura Técnica y Funcionamiento Interno

El manejo de entidades integra convenciones SGML, rigor XML, normas WHATWG y la memoria de JavaScript.

# 1. El Continuo de los Estándares: HTML 4.01, XML 1.0 y WHATWG Living Standard

El análisis de entidades abarca tres estándares clave:

• XML 1.0 (W3C): Exige cinco entidades base (&, <, >, ", '). Otras requieren DTD; las numéricas (NCRs) son universales.
• HTML 4.01 (RFC 1866 / W3C): Estandarizó 252 entidades con nombre, omitiendo ' y provocando fallos en clientes antiguos.
• WHATWG HTML Living Standard: Cataloga 2.231 referencias con nombre y fija reglas de recuperación ante entidades sin cerrar.

# 2. Mecánica a Nivel de Bytes: Unicode y Pares Sustitutos UTF-16

JavaScript usa unidades UTF-16 (16 bits). Glifos del Plano Multilingüe Básico (BMP, U+0000 a U+FFFF) ocupan una unidad; símbolos astrales como emojis (🚀, U+1F680) requieren pares sustitutos (0xD800–0xDBFF superior, 0xDC00–0xDFFF inferior). Métodos como charCodeAt() dividen caracteres astrales en entidades rotas (��). ToolsAA calcula valores escalares con codePointAt():

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

Generar referencias numéricas produce una entidad unificada: 🚀 o 🚀.

# 3. Formatos de Entidades: Con Nombre vs. Decimales vs. Hexadecimales

• Referencias con Nombre (&nombre;): Mnemónicos (&, €) resueltos mediante diccionarios del navegador.
• NCRs Decimales (&#[0-9]+;): Valores Unicode en base 10 (&, €), procesados universalmente sin requerir esquemas.
• NCRs Hexadecimales (&#x[0-9a-fA-F]+;): Valores Unicode en base 16 (&, €), estándar de preferencia en canales de datos.

# 4. DOMParser y Aislamiento Léxico: Por Qué innerHTML es un Antipatrón

Desescapar texto asignándolo a innerHTML introduce riesgos graves:

• DOM-Based XSS: Payloads inyectados (<img src=x onerror=alert(1)>) se ejecutan de inmediato al asignarse.
• Pérdida de Etiquetas: Mezclar entidades con HTML (<code>&lt;div&gt;</code>) parsea elementos DOM, eliminando etiquetas al extraer textContent.
• Peticiones de Red Imprevistas: Recursos multimedia embebidos disparan peticiones HTTP externas.

ToolsAA aplica Aislamiento Léxico por Expresiones Regulares (/&(#(?:[xX][0-9a-fA-F]+|[0-9]+)|[a-zA-Z0-9]+);/g), sustituyendo tokens vía diccionarios inmutables sin tocar el árbol DOM.

# 5. Web APIs Nativas, Rendimiento y Concurrencia

• Concurrencia en React: La entrada usa useDeferredValue(), preservando 60 FPS mientras las transformaciones se computan en diferido.
• Fragmentación en Memoria: Fragmentos procesados se acumulan en arreglos y se combinan con chunks.join("") en $O(N)$.
• Canvas Fuera de Pantalla: Las métricas se renderizan en <canvas> offscreen para eliminar reflujos en el DOM.
• Web Crypto y WASM: Cargas >1 MB usan verificación SHA-256 local y tokenizadores WebAssembly (WASM) con latencia cero.

# Guía Práctica de Uso Paso a Paso

# Paso 1: Carga de Datos y Preajustes

Pegue texto o código en el editor o seleccione preajustes (Defensa XSS, Limpieza XML/SVG, Tipografía). También puede importar archivos con la API nativa FileReader.

# Paso 2: Selección de Alcance y Formato

• Solo Esenciales (Seguro XML): Codifica cinco delimitadores clave (&, <, >, ", ').
• Caracteres No ASCII: Mantiene ASCII estándar y convierte puntos de código >127 (U+007F).
• Todos los Caracteres: Codifica cada carácter a referencias numéricas.
• Alterne entre Entidades con Nombre (&), NCRs Decimales (&) y Hexadecimales (&).

# Paso 3: Configuración Granular de Escape

• Ajuste comillas de forma aislada (' por defecto a ').
• Convierta espacios no separables (\u00A0) en  .
• Transforme saltos de línea en <br /> para emails y foros.

# Paso 4: Decodificación Segura Bidireccional

Decodifique texto HTML con garantías:

• Extracción Unificada: Procesa entidades mnemónicas, decimales y hexadecimales en un solo pase.
• Resolución Heredada: Resuelve entidades antiguas sin punto y coma como &copy 2026.
• Normalización de Saltos: Revierte etiquetas <br /> a saltos de línea estándar (\n).

# Paso 5: Auditoría y Exportación

Revise conteo de caracteres, tamaño en bytes UTF-8 e inflación. Copie el resultado con un clic o descárguelo como archivo plano.

# Implementaciones de Código en Producción

# 1. Implementación en TypeScript / JavaScript Moderno

Códec tipado que soporta formatos configurables, pares sustitutos de 32 bits y decodificación no destructiva:

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

export class HtmlEntityCodec {
  private static readonly NAMED: Record<string, string> = {
    "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;",
    " ": "&nbsp;", "©": "&copy;", "®": "&reg;", "™": "&trade;", "€": "&euro;",
  };

  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;
    }
    return out.join("");
  }

  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. Implementación en Python 3.11+ Moderno

Implementación tipada en Python con conversión numérica determinista, validación de sustitutos y saneamiento:

from typing import Literal
import html, re

class HtmlEntityCodec:
    _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:
        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)

# Errores Comunes, Casos Límite y Solución de Problemas

# 1. Doble Codificación (&)

Al codificar texto ya procesado, & pasa a &, transformando < en < y rompiendo la salida visual.

• Solución: Codifique solo en la frontera de renderizado. Valide idempotencia comprobando si decode(str) !== str.

# 2. Codificación Dependiente del Contexto

El escape de entidades protege nodos de texto y atributos, pero resulta inútil dentro de <script> o parámetros de URL.

• Solución: Use JSON.stringify() con escape \u003C en scripts y codificación porcentual en URLs.

# 3. Incompatibilidad de ' en HTML 4

Omitida en W3C HTML 4.01, ' provoca errores de renderizado en motores de correo antiguos.

• Solución: Estandarice en la referencia decimal ', soportada universalmente en HTML y XML.

# 4. Entidades Sin Cerrar en Modo Quirks

WHATWG tolera entidades sin punto y coma (&copy 2026), pero analizadores estrictos de XML arrojan error de sintaxis.

• Solución: Finalice siempre toda referencia de entidad con punto y coma (;).

# 5. Pares Sustitutos UTF-16 Truncados (Emojis Rotos)

Dividir cadenas con charAt() corta caracteres astrales de 32 bits (🚀, U+1F680) en mitades corruptas (��).

• Solución: Itere con codePointAt() y avance punteros 2 unidades en símbolos astrales.

# 6. Destrucción de Etiquetas con innerHTML

Desescapar vía innerHTML descarta etiquetas válidas y expone a vulnerabilidades de inyección (<img src=x onerror=alert(1)>).

• Solución: Decodifique mediante sustitución léxica con expresiones regulares en lugar de interactuar con el DOM.

# Preguntas Frecuentes (FAQ)

# Q1: ¿Cuál es la diferencia entre entidades con nombre, decimales y hexadecimales?

Respuesta: Las entidades con nombre usan mnemónicos (©). Las decimales usan Unicode base 10 (©) y las hexadecimales base 16 (©). Renderizan igual en navegadores, pero las numéricas operan en XML y SVG sin requerir esquemas DTD.

# Q2: ¿Por qué la codificación de entidades HTML no previene XSS dentro de <script>?

Respuesta: Los navegadores procesan etiquetas <script> con la gramática de JavaScript, donde las entidades no se decodifican. Requieren escape JavaScript (JSON.stringify()) con neutralización de \u003C en vez de entidades HTML.

# Q3: ¿Por qué &apos; falla en clientes de correo antiguos y por qué se prefiere &#39;?

Respuesta: ' se omitió en W3C HTML 4.01. Motores de correo antiguos usan parsers HTML4 que no reconocen '. La referencia decimal ' garantiza compatibilidad universal en HTML, XHTML, XML y SVG.

# Q4: ¿Cómo se comportan los caracteres UTF-8 de 4 bytes y los emojis al convertirse en entidades?

Respuesta: Los emojis (🔥, U+1F525) están fuera del BMP y usan pares sustitutos UTF-16 (\uD83D\uDD25). Codificadores adecuados calculan su valor escalar de 32 bits (128293), emitiendo entidades unificadas (🔥 o 🔥) en vez de fragmentos rotos.

# Q5: ¿Por qué es peligroso usar document.createElement('div').innerHTML para desescapar HTML?

Respuesta: Asignar cadenas a innerHTML ejecuta scripts inyectados (<img src=x onerror=alert(1)>) en memoria, además de suprimir etiquetas legítimas y alterar espacios al extraer textContent.

# Q6: ¿Cómo puedo detectar si una cadena de texto ya ha sido codificada con entidades HTML?

Respuesta: Evalúe la cadena con /&(#(?:[xX][0-9a-fA-F]+|[0-9]+)|[a-zA-Z0-9]+);/. Si decode(str) !== str, la cadena ya contiene entidades codificadas.

# Q7: ¿Mis datos sensibles, código o cadenas privadas se transmiten a servidores al usar ToolsAA?

Respuesta: No. ToolsAA opera con arquitectura cliente pura ("use client"). Tokenización y cálculos Unicode ocurren estrictamente en la memoria del navegador. Cero datos salen de su máquina, cumpliendo RGPD y SOC 2.

# Q8: ¿Cuántas entidades con nombre soporta HTML5 frente a HTML4 y XML?

Respuesta: XML 1.0 define 5 entidades (&, <, >, ", '). HTML 4.01 definió 252. El estándar moderno WHATWG HTML Living Standard reconoce 2.231 referencias cubriendo matemáticas, alfabetos griego y cirílico y símbolos.

# Matriz Técnica Comparativa: Formatos de Entidades HTML y Contextos de Uso

# Conclusión

Comprender los límites entre marcado y texto literal es esencial en la ingeniería web. Sea mitigando XSS, mostrando sintaxis en documentación, preservando tipografía o generando XML, codificar entidades garantiza renderizado determinista sin corrupción sintáctica.

Adoptar buenas prácticas —preferir ' sobre ', unificar pares sustitutos de 32 bits para emojis y aplicar aislamiento léxico por regex frente al DOM— previene doble codificación e inyecciones. El Codificador y Decodificador de Entidades HTML de ToolsAA brinda una solución determinista de alto rendimiento, operando 100% en memoria del navegador con total privacidad.