Stop Broken DOM: Why HTML Escape Utilities Fail Silently

312 milliseconds — the time it took to break our production environment

Our comment system served 2.4 million requests per day without incident. Then one Tuesday afternoon, a single user submission containing <script>alert(1)</script> rendered inline on a product page. The browser executed it in 312 milliseconds. That was all it took — not to compromise our database, but to expose a gap in how our team handled HTML text escaping across a multi-stage rendering pipeline.

I lead frontend infrastructure at a platform that processes user-generated reviews for e-commerce merchants. Every review passes through three systems: a moderation dashboard built in React, a legacy PHP admin panel, and a public-facing storefront rendered via server-side templates. Each layer made different assumptions about whether HTML text was already escaped. That afternoon taught me that developer utilities for escaping and unescaping HTML text are not interchangeable conveniences — they are load-bearing components that demand the same rigor as authentication or payment logic.

The 6 characters that cost us 4 hours of debugging

The offending submission was six characters: <img>. Not even a valid payload — just a malformed tag fragment. But it revealed that our React moderation dashboard was double-escaping text that our PHP backend had already escaped once. The result? Moderators saw <img> on their screens, assumed the content was safe, approved it, and the storefront template — which expected pre-escaped strings — rendered the raw entity codes as visible text to shoppers.

Here is the calculation that matters: we had 47,000 reviews in the queue that day. Each one had been escaped at the PHP layer using htmlspecialchars(), then passed to React props, where a junior developer had added a defensive escapeHtml() utility "just to be safe." Two escapes, applied sequentially, produced < — a string no browser would ever interpret correctly. The fix took four hours. The root cause took longer to internalize.

Why double-escaping is worse than no escaping

No escaping is an obvious vulnerability. Double-escaping is a subtle corruption. The first produces a security alert. The second produces a slow erosion of data integrity that nobody notices until a merchant screenshots their product page and asks why customer reviews look like broken markup. Developer utilities that handle HTML text encoding must be applied exactly once, at exactly the right boundary — and every team member must know which boundary that is.

1 utility function, 47,000 submissions, zero incidents — the architecture that worked

After the incident, we consolidated every escaping and unescaping operation into a single shared library. Not a collection of ad-hoc functions scattered across repositories, but one versioned package imported by all three systems. The contract was simple:

• Store raw. User input enters the database unescaped. Always.
• Escape at render. Each rendering layer applies escaping exactly once, using the shared utility, at the point where text transitions from data to display.
• Unescape only for editing. When loading content into a rich-text editor for moderation, the utility reverses entities back to raw characters — and only in that context.

The library exported two functions: escapeHtml(text) and unescapeHtml(text). The escape function handled the five characters that matter: &, <, >, ", '. The unescape function reversed the standard named entities — &, <, >, ", ' — plus numeric character references in both decimal (') and hexadecimal (') form. That last detail mattered more than I expected: our PHP layer produced hex entities, our React layer produced decimal ones, and the unescape utility needed to handle both transparently.

The performance number nobody measured

Before consolidation, we profiled the escaping overhead across a typical page load serving 120 reviews. The scattered implementations — some using regex, some using DOM manipulation, one using a hand-rolled switch statement — collectively consumed 8.4 milliseconds per render. The unified utility, built on a lookup table with direct string replacement, brought that down to 0.9 milliseconds. On a page serving 500 reviews during a flash sale, the difference was 35 milliseconds versus 4. That is the gap between a page that feels instant and one that feels sluggish under load.

The 3-layer escaping strategy that handles 99.7% of edge cases

During the post-incident review, we catalogued every context in which user text could appear in our system. There were three, and each required different treatment. A single escapeHtml() function was necessary but not sufficient.

Layer 1: HTML body context

Text placed between tags — <p>{userText}</p> — needs the standard five-character escape. This covers the vast majority of cases. Our reviews, review titles, and author names all fall here. The shared utility handles it with a straightforward replacement map.

Layer 2: Attribute context

Text placed inside an attribute value — <a href="{userUrl}"> or <input value="{userName}"> — requires escaping quotes in addition to the standard five characters. More critically, it requires validation for URL contexts. Escaping alone does not prevent javascript: protocol injection. We added a dedicated escapeAttribute() function that wraps the base escape with quote handling and delegates URL validation to a separate sanitizer.

Layer 3: JavaScript string context

When user text is injected into a <script> block or an inline event handler — a pattern we still had in our legacy PHP admin panel — HTML escaping is the wrong tool entirely. The danger is not < but </script>, which terminates the script block regardless of string context. We eliminated this pattern entirely by moving all dynamic data to data- attributes read by external scripts. Where inline injection was unavoidable, we used JSON.stringify() with additional escaping of </ sequences.

The 0.3% of cases not covered by these three layers? They involved CSS context — style attributes with user-provided values — which we banned outright. No user-generated CSS. The risk-to-value ratio was indefensible.

0.02 seconds: the cost of proper unescaping at scale — and why it matters

Unescaping is the operation developers think about last, and it shows. Our moderation dashboard loads 50 reviews at a time into a rich-text editor so moderators can annotate before approval. Each review averages 340 characters of escaped text. Unescaping 50 reviews — 17,000 characters — through our utility takes 0.02 seconds. Through the regex-based approach we had before, it took 0.11 seconds. On its own, negligible. Across a moderator's 200-review daily workload, the difference accumulates to nearly 18 seconds of wasted interaction time per person per day.

But performance was not the real lesson. The real lesson was that unescape HTML operations must be explicit, logged, and reversible. Every call to unescapeHtml() in our codebase now passes through a wrapper that records the context — which editor, which field, which user session. When a moderator reports that a review "looks wrong," we can trace exactly where the unescaping occurred and whether the output was fed back into an escape function downstream. That traceability turned a four-hour debugging session into a five-minute log query.

What I would tell any team building developer tools for HTML text

If you are building or selecting utilities for escaping and unescaping HTML text in web development, three principles will save you the incident we lived through. First, treat escaping as a rendering concern, not a storage concern — raw data in the database, escaped data at the boundary where it becomes markup. Second, unify the utility across every system that touches the same data; inconsistent escaping across layers is not a minor inconsistency, it is a data corruption vector. Third, measure the cost. Profile your escape and unescape functions under realistic load with realistic payload sizes. The numbers will surprise you — and they will tell you whether your utilities are production-grade or prototyping-grade.

The 312 milliseconds that broke our environment were not a security failure. They were an architecture failure disguised as one. The right developer utilities, applied consistently at the right boundaries, would have made those milliseconds impossible.