Named references are easy to read for a small common set. Numeric references cover Unicode code points uniformly. EntityCodec makes the fallback explicit rather than inventing names.
Named with decimal fallback
Common characters such as © and — become © and —. A selected non-ASCII character outside the common map becomes a decimal reference.
Astral characters stay whole
Numeric encoding iterates Unicode code points, not UTF-16 halves. An emoji therefore produces one numeric reference rather than two surrogate references.
Verify the exact destination
Character-reference encoding changes text representation, not the trust level of the data. Keep the output as text until the receiving system applies the correct context-specific escaping or sanitization. Compare the complete result after pasting it into that system. For a repeatable check, keep one literal fixture beside its expected encoded form, run the same selected profile twice, and compare every ampersand, semicolon, code point, space, and line break. Then test the receiving text binding with harmless representative characters. If the destination rewrites, normalizes, repeatedly decodes, or renders the value, document that later behavior separately because it is outside EntityCodec.