From 69a473c32a55ed94ea93af9af503b583ab2466d7 Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Sun, 22 Feb 2026 08:30:45 +0000
Subject: [PATCH 1/5] perf: move html entity decoding to server side

---
 app/components/Package/Playgrounds.vue     |  5 ++---
 app/components/ReadmeTocDropdown.vue       |  7 +++----
 app/composables/useMarkdown.ts             |  2 +-
 app/utils/formatters.ts                    | 14 --------------
 server/api/registry/readme/[...pkg].get.ts |  2 +-
 server/utils/readme.ts                     | 10 ++++++----
 shared/utils/html.ts                       | 13 +++++++++++++
 7 files changed, 26 insertions(+), 27 deletions(-)
 create mode 100644 shared/utils/html.ts

diff --git a/app/components/Package/Playgrounds.vue b/app/components/Package/Playgrounds.vue
index a79488f1a..6a38f6b1e 100644
--- a/app/components/Package/Playgrounds.vue
+++ b/app/components/Package/Playgrounds.vue
@@ -1,6 +1,5 @@
 <script setup lang="ts">
 import type { PlaygroundLink } from '#shared/types'
-import { decodeHtmlEntities } from '~/utils/formatters'
 
 const props = defineProps<{
   links: PlaygroundLink[]
@@ -130,7 +129,7 @@ function focusMenuItem(index: number) {
             :class="[getIcon(firstLink.provider), getColor(firstLink.provider), 'w-4 h-4 shrink-0']"
             aria-hidden="true"
           />
-          <span class="truncate text-fg-muted">{{ decodeHtmlEntities(firstLink.label) }}</span>
+          <span class="truncate text-fg-muted">{{ firstLink.label }}</span>
         </a>
       </TooltipApp>
 
@@ -186,7 +185,7 @@ function focusMenuItem(index: number) {
                 :class="[getIcon(link.provider), getColor(link.provider), 'w-4 h-4 shrink-0']"
                 aria-hidden="true"
               />
-              <span class="truncate">{{ decodeHtmlEntities(link.label) }}</span>
+              <span class="truncate">{{ link.label }}</span>
             </a>
           </TooltipApp>
         </div>
diff --git a/app/components/ReadmeTocDropdown.vue b/app/components/ReadmeTocDropdown.vue
index f80edce0b..66f92d08e 100644
--- a/app/components/ReadmeTocDropdown.vue
+++ b/app/components/ReadmeTocDropdown.vue
@@ -1,7 +1,6 @@
 <script setup lang="ts">
 import type { TocItem } from '#shared/types/readme'
 import { onClickOutside, useEventListener } from '@vueuse/core'
-import { decodeHtmlEntities } from '~/utils/formatters'
 
 const props = defineProps<{
   toc: TocItem[]
@@ -202,7 +201,7 @@ function handleKeydown(event: KeyboardEvent) {
             @click="select()"
             @mouseenter="highlightedIndex = getIndex(node.id)"
           >
-            <span class="truncate">{{ decodeHtmlEntities(node.text) }}</span>
+            <span class="truncate">{{ node.text }}</span>
           </NuxtLink>
 
           <template v-for="child in node.children" :key="child.id">
@@ -220,7 +219,7 @@ function handleKeydown(event: KeyboardEvent) {
               @click="select()"
               @mouseenter="highlightedIndex = getIndex(child.id)"
             >
-              <span class="truncate">{{ decodeHtmlEntities(child.text) }}</span>
+              <span class="truncate">{{ child.text }}</span>
             </NuxtLink>
 
             <NuxtLink
@@ -241,7 +240,7 @@ function handleKeydown(event: KeyboardEvent) {
               @click="select()"
               @mouseenter="highlightedIndex = getIndex(grandchild.id)"
             >
-              <span class="truncate">{{ decodeHtmlEntities(grandchild.text) }}</span>
+              <span class="truncate">{{ grandchild.text }}</span>
             </NuxtLink>
           </template>
         </template>
diff --git a/app/composables/useMarkdown.ts b/app/composables/useMarkdown.ts
index 4f3cfe730..a7a86f6fb 100644
--- a/app/composables/useMarkdown.ts
+++ b/app/composables/useMarkdown.ts
@@ -1,4 +1,4 @@
-import { decodeHtmlEntities } from '~/utils/formatters'
+import { decodeHtmlEntities } from '#shared/utils/html'
 
 interface UseMarkdownOptions {
   text: string
diff --git a/app/utils/formatters.ts b/app/utils/formatters.ts
index 570a9a462..c135506d7 100644
--- a/app/utils/formatters.ts
+++ b/app/utils/formatters.ts
@@ -4,17 +4,3 @@ export function toIsoDateString(date: Date): string {
   const day = String(date.getUTCDate()).padStart(2, '0')
   return `${year}-${month}-${day}`
 }
-
-const htmlEntities: Record<string, string> = {
-  '&amp;': '&',
-  '&lt;': '<',
-  '&gt;': '>',
-  '&quot;': '"',
-  '&#39;': "'",
-  '&apos;': "'",
-  '&nbsp;': ' ',
-}
-
-export function decodeHtmlEntities(text: string): string {
-  return text.replace(/&(?:amp|lt|gt|quot|apos|nbsp|#39);/g, match => htmlEntities[match] || match)
-}
diff --git a/server/api/registry/readme/[...pkg].get.ts b/server/api/registry/readme/[...pkg].get.ts
index c6f8e4ebd..771f04035 100644
--- a/server/api/registry/readme/[...pkg].get.ts
+++ b/server/api/registry/readme/[...pkg].get.ts
@@ -33,7 +33,7 @@ export default defineCachedEventHandler(
     swr: true,
     getKey: event => {
       const pkg = getRouterParam(event, 'pkg') ?? ''
-      return `readme:v8:${pkg.replace(/\/+$/, '').trim()}`
+      return `readme:v9:${pkg.replace(/\/+$/, '').trim()}`
     },
   },
 )
diff --git a/server/utils/readme.ts b/server/utils/readme.ts
index fff2cea28..e54c42418 100644
--- a/server/utils/readme.ts
+++ b/server/utils/readme.ts
@@ -3,9 +3,11 @@ import sanitizeHtml from 'sanitize-html'
 import { hasProtocol } from 'ufo'
 import type { ReadmeResponse, TocItem } from '#shared/types/readme'
 import { convertBlobOrFileToRawUrl, type RepositoryInfo } from '#shared/utils/git-providers'
-import { highlightCodeSync } from './shiki'
+import { decodeHtmlEntities } from '#shared/utils/html'
 import { convertToEmoji } from '#shared/utils/emoji'
 
+import { highlightCodeSync } from './shiki'
+
 /**
  * Playground provider configuration
  */
@@ -371,8 +373,8 @@ export async function renderReadmeHtml(
     // (e.g., #install, #dependencies, #versions are used by the package page)
     const id = `user-content-${uniqueSlug}`
 
-    // Collect TOC item with plain text (HTML stripped)
-    const plainText = text.replace(/<[^>]*>/g, '').trim()
+    // Collect TOC item with plain text (HTML stripped, entities decoded)
+    const plainText = decodeHtmlEntities(text.replace(/<[^>]*>/g, '').trim())
     if (plainText) {
       toc.push({ text: plainText, id, depth })
     }
@@ -511,7 +513,7 @@ ${html}
              * provide the text of the element. This will automatically be removed, because there
              * is an allow list for link attributes.
              * */
-            label: attribs['data-title-intermediate'] || provider.name,
+            label: decodeHtmlEntities(attribs['data-title-intermediate'] || provider.name),
           })
         }
 
diff --git a/shared/utils/html.ts b/shared/utils/html.ts
new file mode 100644
index 000000000..944613fc2
--- /dev/null
+++ b/shared/utils/html.ts
@@ -0,0 +1,13 @@
+const htmlEntities: Record<string, string> = {
+  '&amp;': '&',
+  '&lt;': '<',
+  '&gt;': '>',
+  '&quot;': '"',
+  '&#39;': "'",
+  '&apos;': "'",
+  '&nbsp;': ' ',
+}
+
+export function decodeHtmlEntities(text: string): string {
+  return text.replace(/&(?:amp|lt|gt|quot|apos|nbsp|#39);/g, match => htmlEntities[match] || match)
+}

From 6a99a3296b7e1c7d7e16ffc6ea592ddb0ebaa13a Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Sun, 22 Feb 2026 08:40:09 +0000
Subject: [PATCH 2/5] test: move test to shared dir

---
 test/unit/app/utils/formatters.spec.ts | 28 +-------------------------
 test/unit/shared/utils/html.spec.ts    | 28 ++++++++++++++++++++++++++
 2 files changed, 29 insertions(+), 27 deletions(-)
 create mode 100644 test/unit/shared/utils/html.spec.ts

diff --git a/test/unit/app/utils/formatters.spec.ts b/test/unit/app/utils/formatters.spec.ts
index 02415cd46..8c489a915 100644
--- a/test/unit/app/utils/formatters.spec.ts
+++ b/test/unit/app/utils/formatters.spec.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { decodeHtmlEntities, toIsoDateString } from '../../../../app/utils/formatters'
+import { toIsoDateString } from '../../../../app/utils/formatters'
 
 describe('toIsoDateString', () => {
   it('formats a date as YYYY-MM-DD', () => {
@@ -10,29 +10,3 @@ describe('toIsoDateString', () => {
     expect(toIsoDateString(new Date('2024-01-05T00:00:00Z'))).toBe('2024-01-05')
   })
 })
-
-describe('decodeHtmlEntities', () => {
-  it.each([
-    ['&amp;', '&'],
-    ['&lt;', '<'],
-    ['&gt;', '>'],
-    ['&quot;', '"'],
-    ['&#39;', "'"],
-    ['&apos;', "'"],
-    ['&nbsp;', ' '],
-  ] as const)('%s → %s', (input, expected) => {
-    expect(decodeHtmlEntities(input)).toBe(expected)
-  })
-
-  it('decodes multiple entities in one string', () => {
-    expect(decodeHtmlEntities('a &amp; b &lt; c')).toBe('a & b < c')
-  })
-
-  it('leaves plain text unchanged', () => {
-    expect(decodeHtmlEntities('say no to bloat')).toBe('say no to bloat')
-  })
-
-  it('leaves unknown entities unchanged', () => {
-    expect(decodeHtmlEntities('&unknown;')).toBe('&unknown;')
-  })
-})
diff --git a/test/unit/shared/utils/html.spec.ts b/test/unit/shared/utils/html.spec.ts
new file mode 100644
index 000000000..0b52392f8
--- /dev/null
+++ b/test/unit/shared/utils/html.spec.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import { decodeHtmlEntities } from '../../../../shared/utils/html'
+
+describe('decodeHtmlEntities', () => {
+  it.each([
+    ['&amp;', '&'],
+    ['&lt;', '<'],
+    ['&gt;', '>'],
+    ['&quot;', '"'],
+    ['&#39;', "'"],
+    ['&apos;', "'"],
+    ['&nbsp;', ' '],
+  ] as const)('%s → %s', (input, expected) => {
+    expect(decodeHtmlEntities(input)).toBe(expected)
+  })
+
+  it('decodes multiple entities in one string', () => {
+    expect(decodeHtmlEntities('a &amp; b &lt; c')).toBe('a & b < c')
+  })
+
+  it('leaves plain text unchanged', () => {
+    expect(decodeHtmlEntities('say no to bloat')).toBe('say no to bloat')
+  })
+
+  it('leaves unknown entities unchanged', () => {
+    expect(decodeHtmlEntities('&unknown;')).toBe('&unknown;')
+  })
+})

From 90313e5585fdc2c650a02fc813c70f78c0ddbda6 Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Sun, 22 Feb 2026 09:10:07 +0000
Subject: [PATCH 3/5] fix: improve html tag stripping

---
 server/utils/readme.ts | 26 +++++++++++++++++++-------
 1 file changed, 19 insertions(+), 7 deletions(-)

diff --git a/server/utils/readme.ts b/server/utils/readme.ts
index e54c42418..d7c296117 100644
--- a/server/utils/readme.ts
+++ b/server/utils/readme.ts
@@ -174,8 +174,21 @@ const ALLOWED_ATTR: Record<string, string[]> = {
   'p': ['align'],
 }
 
-// GitHub-style callout types
-// Format: > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION]
+/**
+ * Strip all HTML tags from a string, looping until stable to prevent
+ * incomplete sanitization from nested/interleaved tags
+ * (e.g. `<scr<script>ipt>` → `<script>` after one pass).
+ */
+function stripHtmlTags(text: string): string {
+  const tagPattern = /<[^>]*>/g
+  let result = text
+  let previous: string
+  do {
+    previous = result
+    result = result.replace(tagPattern, '')
+  } while (result !== previous)
+  return result
+}
 
 /**
  * Generate a GitHub-style slug from heading text.
@@ -186,8 +199,7 @@ const ALLOWED_ATTR: Record<string, string[]> = {
  * - Collapse multiple hyphens
  */
 function slugify(text: string): string {
-  return text
-    .replace(/<[^>]*>/g, '') // Strip HTML tags
+  return stripHtmlTags(text)
     .toLowerCase()
     .trim()
     .replace(/\s+/g, '-') // Spaces to hyphens
@@ -374,7 +386,7 @@ export async function renderReadmeHtml(
     const id = `user-content-${uniqueSlug}`
 
     // Collect TOC item with plain text (HTML stripped, entities decoded)
-    const plainText = decodeHtmlEntities(text.replace(/<[^>]*>/g, '').trim())
+    const plainText = decodeHtmlEntities(stripHtmlTags(text).trim())
     if (plainText) {
       toc.push({ text: plainText, id, depth })
     }
@@ -404,11 +416,11 @@ ${html}
     return `<img src="${resolvedHref}"${altAttr}${titleAttr}>`
   }
 
-  // // Resolve link URLs, add security attributes, and collect playground links
+  // Resolve link URLs, add security attributes, and collect playground links
   renderer.link = function ({ href, title, tokens }: Tokens.Link) {
     const text = this.parser.parseInline(tokens)
     const titleAttr = title ? ` title="${title}"` : ''
-    let plainText = text.replace(/<[^>]*>/g, '').trim()
+    let plainText = stripHtmlTags(text).trim()
 
     // If plain text is empty, check if we have an image with alt text
     if (!plainText && tokens.length === 1 && tokens[0]?.type === 'image') {

From 101591174f4b431d4811155d16336fef9573b0a0 Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Sun, 22 Feb 2026 09:16:15 +0000
Subject: [PATCH 4/5] chore: use explicit non-breaking space unicode

---
 shared/utils/html.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/shared/utils/html.ts b/shared/utils/html.ts
index 944613fc2..e4a084d6d 100644
--- a/shared/utils/html.ts
+++ b/shared/utils/html.ts
@@ -5,7 +5,7 @@ const htmlEntities: Record<string, string> = {
   '&quot;': '"',
   '&#39;': "'",
   '&apos;': "'",
-  '&nbsp;': ' ',
+  '&nbsp;': '\u00A0',
 }
 
 export function decodeHtmlEntities(text: string): string {

From a9fb76d7a44ff84dd984d0db1d1746d305b8f0ed Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Sun, 22 Feb 2026 09:24:08 +0000
Subject: [PATCH 5/5] test: update expectation

---
 test/unit/shared/utils/html.spec.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/unit/shared/utils/html.spec.ts b/test/unit/shared/utils/html.spec.ts
index 0b52392f8..12ef1b6bf 100644
--- a/test/unit/shared/utils/html.spec.ts
+++ b/test/unit/shared/utils/html.spec.ts
@@ -9,7 +9,7 @@ describe('decodeHtmlEntities', () => {
     ['&quot;', '"'],
     ['&#39;', "'"],
     ['&apos;', "'"],
-    ['&nbsp;', ' '],
+    ['&nbsp;', '\u00A0'],
   ] as const)('%s → %s', (input, expected) => {
     expect(decodeHtmlEntities(input)).toBe(expected)
   })