"""Display sanitization utilities for HTML render contexts.

All user-supplied values echoed in error messages or other HTML-rendered
output MUST be sanitized first. This module provides the canonical
sanitize_for_display() function.
"""

from __future__ import annotations

import html


def sanitize_for_display(value: str) -> str:
    """Escape HTML special characters in user-supplied strings.

    Use this before interpolating user input into any string that will be
    rendered in an HTML context (e.g. error messages, admin UI, email).

    Does NOT over-escape: JSON responses are not HTML contexts and do not
    need this treatment. Apply sanitization only at HTML render boundaries.

    Args:
        value: Raw user-supplied string.

    Returns:
        The string with HTML special characters escaped.
    """
    return html.escape(value, quote=True)