devtools-unicode-escaping

# Unicode Escaping and User-Controlled Data Guidelines When displaying inspected data, user-controlled strings, or untrusted input in the DevTools UI (e.g., console messages, object properties, DOM tree nodes, or UI titles/descriptions), you must ensure they are properly escaped to prevent layout bleed-through (such as Right-to-Left leaks) or security vulnerabilities. DevTools provides two primary Unicode escaping functions in `Platform.StringUtilities`: ## 1. Escaping for Text Representation (`escapeUnicodeAsText`) Use `Platform.StringUtilities.escapeUnicodeAsText(content)` when rendering values that developers need to inspect (e.g. string values inside the Console or the Object properties view) where hidden, invisible, or formatting characters should be made explicitly visible. * **Behavior**: Escapes all formatting and surrogate characters into literal Unicode escape sequences (e.g., `\u202E`, `\u200B`). * **Example Usage**: ```typescript const text = Platform.StringUtilities.escapeUnicodeAsText(JSON.stringify(description)); ``` ## 2. Escaping for UI Rendering (`safeEscapeUnicode`) Use `Platform.StringUtilities.safeEscapeUnicode(content)` when rendering content inside templates or HTML markup where you want safe layout-critical zero-width formatting characters to function normally for word wrapping or rendering layout, but want to escape dangerous layout-disrupting characters (like bidi overrides). * **Behavior**: Escapes dangerous formatting and surrogate characters (like `\u202E`), but leaves safe formatting characters untouched: * Zero Width Space (`\u200B`) * Zero Width Non-Joiner (`\u200C`) * Zero Width Joiner (`\u200D`) * **Example Usage**: Used automatically by the global Lit template wrapper. --- ## 3. Global Lit Template Wrapper DevTools wraps Lit's default `html` function inside `front_end/ui/lit/strip-whitespace.ts` (re-exported via `ui/lit/lit.js`). This wrapper automatically intercepts and escapes standard string values using `Platform.StringUtilities.safeEscapeUnicode(val)` at runtime. * **What is escaped automatically**: Any standard string interpolated directly in a template (e.g., `html`<span>${myString}</span>``). * **Array items**: Array values are traversed recursively, and string elements inside arrays are escaped automatically. * **Lit directives**: Directives (like `ifDefined`, `live`, `repeat`, `classMap`, etc.) are automatically traversed, and any string arguments inside their `values` array are escaped recursively. ### Directives Rule: Because the wrapper automatically processes directive arguments, you **do not** need to manually escape strings passed to standard Lit directives. They will be handled safely at runtime. ### Correct Example: ```typescript title=${ifDefined(tooLong ? undefined : description)} // Automatically escaped! ``` --- ## 4. Manual DOM Assignments & Non-Lit Rendering Any manual assignments that bypass Lit entirely (e.g., setting `element.textContent`, `element.title`, or constructing DOM elements imperatively) will also bypass the Lit wrapper. * Always wrap user-controlled strings in these contexts with the appropriate escaping helper: * Use `escapeUnicodeAsText` if you want hidden characters to display as text (e.g., showing `\\u202E`). * Use `safeEscapeUnicode` if you want zero-width spaces to function but other dangerous characters to be escaped. ### Correct Example: ```typescript nameElement.textContent = Platform.StringUtilities.escapeUnicodeAsText(name); ```