finish xss section

Author: arthurfiorette

.serena/project.yml

@@ -117,3 +117,12 @@ symbol_info_budget:
 # Note: the backend is fixed at startup. If a project with a different backend
 # is activated post-init, an error will be returned.
 language_backend:
+
+# line ending convention to use when writing source files.
+# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
+# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
+line_ending:
+
+# list of regex patterns which, when matched, mark a memory entry as read‑only.
+# Extends the list from the global configuration, merging the two lists.
+read_only_memory_patterns: []

packages/docs/docs/guide/xss/_meta.json

@@ -1,8 +1,8 @@
 [
   "safe-attribute",
-  "detection",
   "scanner-cli",
   "safety-rules",
   "error-codes",
-  "why-not-auto-escape"
+  "why-not-auto-escape",
+  "detection"
 ]

packages/docs/docs/guide/xss/safe-attribute.md

@@ -26,7 +26,7 @@ rendering the payload as harmless text.
 Place `safe` on the innermost element that holds the untrusted value. Do not add it to a
 parent wrapper, as that would escape the HTML of child components too.
 
-```tsx
+```tsx twoslash kita
 function UserCard({ name, bio }: { name: string; bio: string }) {
   return (
     <div class="card">
@@ -35,6 +35,8 @@ function UserCard({ name, bio }: { name: string; bio: string }) {
     </div>
   )
 }
+// ---cut-after---
+const html = <UserCard name="Name" bio="Bio" />
 ```
 
 ## Component children
@@ -64,13 +66,16 @@ html = <MyComponent>{escapeHtml(userInput)}</MyComponent>
 
 ## Template literal helper
 
-The `e` tagged template escapes interpolated values while preserving literal HTML around
-them.
+The `e` tagged template is an alias to `escapeHtml()` that you can use as interpolated
+content in template literals. It provides a convenient way to escape dynamic values
+outside of JSX.
 
-```tsx
+```tsx twoslash kita
+const userName = '<script>untrusted()</script>' as const
+// ---cut---
 import { e } from '@kitajs/html'
 
-const html = e`<p>Hello, ${userName}!</p>`
+const html = e`Hello, ${userName}!`
 ```
 
 ## Suppression conventions
@@ -111,15 +116,29 @@ const unsafeContent = 'My safe string' as const
 const html = <div>{unsafeContent}</div>
 ```
 
+::: warning
+
+Manual casts and naming conventions are not enforced by the compiler. They rely on
+developer discipline and code reviews to ensure safety. Use them judiciously and document
+the rationale for any exceptions.
+
+:::
+
 Cast the expression to `'safe'` inline. This tells the plugin to skip the check for that
-specific usage.
+specific usage and not warn about possible XSS vulnerabilities.
 
-```tsx
-<div>{content as 'safe'}</div>
+```tsx twoslash kita
+const content: string = '<script>untrusted()</script>'
+// ---cut---
+const html = <div>{content as 'safe'}</div>
 ```
 
 Call `Html.escapeHtml()` directly. The plugin recognizes the return value as escaped.
 
-```tsx
-<div>{Html.escapeHtml(content)}</div>
+```tsx twoslash kita
+const content: string = '<script>untrusted()</script>'
+// ---cut---
+import { Html } from '@kitajs/html'
+
+const html = <div>{Html.escapeHtml(content)}</div>
 ```