1. Technical Overview: Beyond Simple Character Substitution

At its surface, an HTML Entity Encoder appears to be a straightforward text transformation tool, replacing characters like <, >, &, ", and ' with their corresponding HTML entities (<, >, &, ", '). However, this simplistic view belies a complex system deeply intertwined with character encoding theory, browser parsing models, and security paradigms. The core function is to ensure that text is treated as literal data content rather than executable markup by the HTML parser, a fundamental requirement for both displaying special characters correctly and preventing injection attacks. The encoder must navigate the entire Unicode spectrum, which contains over 140,000 characters, not all of which have predefined named entities. This necessitates a dual-mode operation: using named entities for a well-known subset (like © for ©) and numeric character references (decimal like © or hexadecimal like ©) for the vast majority of characters, particularly those outside the ASCII range.

1.1. The Unicode and Encoding Foundation

The encoder's behavior is fundamentally governed by the document's character encoding declaration, typically UTF-8 in modern web development. UTF-8's variable-length encoding (1 to 4 bytes) complicates the encoder's logic when dealing with code points beyond the Basic Multilingual Plane (BMP). An encoder must decide whether to encode a multi-byte UTF-8 sequence as a single numeric entity for the entire code point or, in flawed implementations, incorrectly encode individual bytes. Furthermore, the distinction between numeric decimal references (&#nnnn;) and hexadecimal references (&#xhhhh;) is more than syntactic; hexadecimal references can be more efficient for developers reading the code, as Unicode code points are conventionally expressed in hex.

1.2. Context-Aware Encoding: A Critical Distinction

A sophisticated encoder is not context-agnostic. The encoding rules differ drastically based on the syntactic context within the HTML document. Text content within an element body (e.g., inside a