Technical Specification: HTML Entity Decoder & Safelist Filter

1. Overview

A high-performance, single-file browser utility designed to help developers and content creators clean, decode, and sanitize HTML strings. This tool operates entirely client-side, ensuring data privacy and instant processing.

2. Core Feature Set

• Dual-Mode Processing:
  • Decoder Mode: Automatically identifies and converts HTML entities (e.g., <, ", {) into raw text characters.
  • Sanitizer (Safelist) Mode: Uses an allow-list approach to strip dangerous tags (e.g., <script>, <iframe>, <object>) and potentially malicious attributes while preserving safe structural HTML (e.g., <p>, <b>, <ul>).
• Real-Time Transformation: Input fields trigger processing on every keystroke, with an optional toggle for manual trigger if performance lags on large text blocks.
• Content Controls:
  • Instant Copy: Single-click button to copy processed output to the system clipboard.
  • Format/Clean Toggle: Buttons to switch between decoding and sanitizing.
  • Counter: Live character and word count statistics for input and output.
• UI Feedback: Custom toast notifications for "Copied to clipboard" (No browser alert() allowed).

3. UI/UX Specifications

• Layout:
  • Header: Clean, centered title with a brief description.
  • Main Area: A split-screen layout (stacked on mobile) containing an Input area and an Output area.
  • Control Strip: Located between the text areas, featuring radio buttons or toggles for the processing mode, and clear buttons.
• Design Aesthetic:
  • Style: Modern, clean "SaaS" aesthetic. High readability with ample whitespace.
  • Typography: Sans-serif, stack-based font (e.g., Inter, system-ui).
  • Shadows/Borders: Subtle, soft box-shadows on input containers; thin, gray-300 borders for structural elements.

4. Technical Constraints & Directives

• Architecture: All HTML, CSS, and JavaScript must reside within a single file.
• Sandboxing:
  • NO Storage: Strictly no localStorage, sessionStorage, or cookies. Do not attempt to save user data.
  • NO Popups: Do not use alert(), confirm(), or prompt(). All UI interactions must use custom DOM elements (e.g., hidden <div>s that toggle to visible for notifications).
• Library Usage: Use Tailwind CSS via CDN for styling. Use standard DOM APIs for sanitization (e.g., DOMParser for creating a document fragment, then iterating nodes to filter against a safe-list array).
• Responsive Behavior: Ensure mobile screens stack the input/output containers vertically; desktop screens display them side-by-side.

5. Color Palette

• Primary: Indigo-600 (#4f46e5) for active buttons and accents.
• Background: White (#ffffff) for page body; Slate-50 (#f8fafc) for input/output panel backgrounds.
• Text: Slate-900 (#0f172a) for headings; Slate-600 (#475569) for body text.
• Border: Slate-200 (#e2e8f0).

6. Implementation Notes for Developer

• Sanitization Logic: Implement a helper function sanitizeHTML(input) that parses the string into a temporary document, identifies unsafe nodes based on an array const allowedTags = ['p', 'b', 'strong', 'i', 'em', 'ul', 'ol', 'li', 'a'], and removes everything else.
• Accessibility: Ensure all buttons have aria-label attributes and the layout respects contrast ratios (WCAG AAA).
• Performance: Debounce the input event listener to ensure smooth interaction on larger text blocks.