From a3a81d908590175a510d7f8fddd67c597b5ff706 Mon Sep 17 00:00:00 2001
From: Julien Huang <julien.h.dev@gmail.com>
Date: Sat, 4 Apr 2026 16:41:10 +0200
Subject: [PATCH 1/5] refactor: move sse to RPC

---
 client/app/app.vue                            |  84 +++++++-
 client/app/plugins/0.sse.ts                   |  19 --
 client/app/plugins/html-validate.ts           |  44 -----
 client/app/plugins/hydration.ts               |  47 -----
 client/app/plugins/lazy-load.ts               |  57 ------
 client/app/utils/routes.ts                    |   1 -
 src/devtools-handlers.ts                      | 184 ++++++++++++++++++
 src/devtools.ts                               |  31 ++-
 src/module.ts                                 |  16 +-
 src/runtime/core/rpc-types.ts                 |  23 +++
 src/runtime/core/server/sse.ts                |  23 ---
 src/runtime/core/server/types.ts              |   8 +-
 src/runtime/html-validate/handlers/delete.ts  |  18 --
 src/runtime/html-validate/handlers/get.ts     |   9 -
 .../handlers/nitro-handlers.plugin.ts         |  22 ---
 src/runtime/html-validate/nitro.plugin.ts     |  10 +-
 src/runtime/html-validate/storage.ts          |   3 -
 src/runtime/hydration/nitro.plugin.ts         |  19 --
 src/runtime/hydration/types.ts                |  19 --
 src/runtime/hydration/utils.ts                |   3 +-
 src/runtime/lazy-load/nitro.plugin.ts         |  18 --
 src/runtime/types.d.ts                        |  21 +-
 test/unit/core/sse.test.ts                    |  53 -----
 23 files changed, 331 insertions(+), 401 deletions(-)
 delete mode 100644 client/app/plugins/0.sse.ts
 delete mode 100644 client/app/plugins/html-validate.ts
 delete mode 100644 client/app/plugins/hydration.ts
 delete mode 100644 client/app/plugins/lazy-load.ts
 create mode 100644 src/devtools-handlers.ts
 create mode 100644 src/runtime/core/rpc-types.ts
 delete mode 100644 src/runtime/core/server/sse.ts
 delete mode 100644 src/runtime/html-validate/handlers/delete.ts
 delete mode 100644 src/runtime/html-validate/handlers/get.ts
 delete mode 100644 src/runtime/html-validate/storage.ts
 delete mode 100644 test/unit/core/sse.test.ts

diff --git a/client/app/app.vue b/client/app/app.vue
index f60578f..d0ce4fd 100644
--- a/client/app/app.vue
+++ b/client/app/app.vue
@@ -1,7 +1,89 @@
 <script setup lang="ts">
-import { useDevtoolsClient } from '@nuxt/devtools-kit/iframe-client'
+import { useDevtoolsClient, onDevtoolsClientConnected } from '@nuxt/devtools-kit/iframe-client'
+import type { HintsClientFunctions, HintsServerFunctions } from '../../src/runtime/core/rpc-types'
+import { RPC_NAMESPACE } from '../../src/runtime/core/rpc-types'
+import type { HydrationMismatchPayload, LocalHydrationMismatch } from '../../src/runtime/hydration/types'
+import type { ComponentLazyLoadData } from '../../src/runtime/lazy-load/schema'
+import { ComponentLazyLoadDataSchema } from '../../src/runtime/lazy-load/schema'
+import type { HtmlValidateReport } from '../../src/runtime/html-validate/types'
+import { parse } from 'valibot'
 
 const client = useDevtoolsClient()
+
+const hydrationMismatches = ref<(HydrationMismatchPayload | LocalHydrationMismatch)[]>([])
+const lazyLoadHints = ref<ComponentLazyLoadData[]>([])
+const htmlValidateReports = ref<HtmlValidateReport[]>([])
+
+const nuxtApp = useNuxtApp()
+nuxtApp.provide('hydrationMismatches', hydrationMismatches)
+nuxtApp.provide('lazyLoadHints', lazyLoadHints)
+nuxtApp.provide('htmlValidateReports', htmlValidateReports)
+
+onDevtoolsClientConnected((client) => {
+  const rpc = client.devtools.extendClientRpc<HintsServerFunctions, HintsClientFunctions>(RPC_NAMESPACE, {
+    onHydrationMismatch(mismatch: HydrationMismatchPayload) {
+      if (!hydrationMismatches.value.some(existing => existing.id === mismatch.id)) {
+        hydrationMismatches.value.push(mismatch)
+      }
+    },
+    onHydrationCleared(ids: string[]) {
+      hydrationMismatches.value = hydrationMismatches.value.filter(m => !ids.includes(m.id))
+    },
+    onLazyLoadReport(data: ComponentLazyLoadData) {
+      try {
+        const validated = parse(ComponentLazyLoadDataSchema, data)
+        if (!lazyLoadHints.value.some(existing => existing.id === validated.id)) {
+          lazyLoadHints.value.push(validated)
+        }
+      }
+      catch {
+        console.warn('[hints] Ignoring malformed lazy-load report', data)
+      }
+    },
+    onLazyLoadCleared(id: string) {
+      lazyLoadHints.value = lazyLoadHints.value.filter(entry => entry.id !== id)
+    },
+    onHtmlValidateReport(report: HtmlValidateReport) {
+      if (!htmlValidateReports.value.some(existing => existing.id === report.id)) {
+        htmlValidateReports.value = [...htmlValidateReports.value, report]
+      }
+    },
+    onHtmlValidateDeleted(id: string) {
+      htmlValidateReports.value = htmlValidateReports.value.filter(report => report.id !== id)
+    },
+  })
+
+  // Hydration: seed from host payload and fetch from server via RPC
+  if (useHintsFeature('hydration')) {
+    hydrationMismatches.value = [...client.host.nuxt.payload.__hints.hydration]
+    rpc.getHydrationMismatches().then((data) => {
+      hydrationMismatches.value = [
+        ...hydrationMismatches.value,
+        ...data.mismatches.filter(m => !hydrationMismatches.value.some(existing => existing.id === m.id)),
+      ]
+    })
+  }
+
+  // Lazy load: fetch from server via RPC
+  if (useHintsFeature('lazyLoad')) {
+    rpc.getLazyLoadHints().then((data) => {
+      lazyLoadHints.value = [
+        ...lazyLoadHints.value,
+        ...(data ?? []).filter(d => !lazyLoadHints.value.some(existing => existing.id === d.id)),
+      ]
+    })
+  }
+
+  // HTML validate: fetch from server via RPC
+  if (useHintsFeature('htmlValidate')) {
+    rpc.getHtmlValidateReports().then((data) => {
+      htmlValidateReports.value = [
+        ...htmlValidateReports.value,
+        ...(data ?? []).filter(d => !htmlValidateReports.value.some(existing => existing.id === d.id)),
+      ]
+    })
+  }
+})
 </script>
 
 <template>
diff --git a/client/app/plugins/0.sse.ts b/client/app/plugins/0.sse.ts
deleted file mode 100644
index d996efb..0000000
--- a/client/app/plugins/0.sse.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-import { HINTS_SSE_ROUTE } from '../utils/routes'
-
-export default defineNuxtPlugin(() => {
-  if (import.meta.test) return
-  const eventSource = useEventSource(HINTS_SSE_ROUTE, undefined, {
-    autoReconnect: {
-      retries: 5,
-      onFailed() {
-        console.error(new Error('[@nuxt/hints] Failed to connect to hints SSE after 5 attempts.'))
-      },
-    },
-  })
-
-  return {
-    provide: {
-      sse: eventSource,
-    },
-  }
-})
diff --git a/client/app/plugins/html-validate.ts b/client/app/plugins/html-validate.ts
deleted file mode 100644
index 2506aad..0000000
--- a/client/app/plugins/html-validate.ts
+++ /dev/null
@@ -1,44 +0,0 @@
-import type { HtmlValidateReport } from '../../../src/runtime/html-validate/types'
-import { defineNuxtPlugin } from '#imports'
-import { HTML_VALIDATE_ROUTE } from '../utils/routes'
-
-export default defineNuxtPlugin(() => {
-  if (import.meta.test || !useHintsFeature('htmlValidate')) return
-  const nuxtApp = useNuxtApp()
-
-  const { data: htmlValidateReports } = useLazyFetch<HtmlValidateReport[]>(new URL(HTML_VALIDATE_ROUTE, window.location.origin).href, {
-    default: () => [],
-    deep: true,
-  })
-
-  function htmlValidateReportHandler(event: MessageEvent) {
-    try {
-      const payload: HtmlValidateReport = JSON.parse(event.data)
-      if (!htmlValidateReports.value.some(existing => existing.id === payload.id)) {
-        htmlValidateReports.value = [...htmlValidateReports.value, payload]
-      }
-    }
-    catch {
-      console.warn('[hints] Ignoring malformed hints:html-validate:report event', event.data)
-    }
-  }
-
-  function htmlValidateDeletedHandler(event: MessageEvent) {
-    try {
-      const deletedId = JSON.parse(event.data)
-      htmlValidateReports.value = htmlValidateReports.value.filter(report => report.id !== deletedId)
-    }
-    catch {
-      console.warn('[hints] Ignoring malformed hints:html-validate:deleted event', event.data)
-    }
-  }
-
-  useEventListener(nuxtApp.$sse.eventSource, 'hints:html-validate:report', htmlValidateReportHandler)
-  useEventListener(nuxtApp.$sse.eventSource, 'hints:html-validate:deleted', htmlValidateDeletedHandler)
-
-  return {
-    provide: {
-      htmlValidateReports,
-    },
-  }
-})
diff --git a/client/app/plugins/hydration.ts b/client/app/plugins/hydration.ts
deleted file mode 100644
index af0e0f0..0000000
--- a/client/app/plugins/hydration.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import type { HydrationMismatchPayload, HydrationMismatchResponse, LocalHydrationMismatch } from '../../../src/runtime/hydration/types'
-import { defineNuxtPlugin, useHostNuxt, ref } from '#imports'
-import { HYDRATION_ROUTE } from '../utils/routes'
-
-export default defineNuxtPlugin(() => {
-  if (import.meta.test || !useHintsFeature('hydration')) return
-  const host = useHostNuxt()
-  const nuxtApp = useNuxtApp()
-  const hydrationMismatches = ref<(HydrationMismatchPayload | LocalHydrationMismatch)[]>([])
-
-  hydrationMismatches.value = [...host.payload.__hints.hydration]
-
-  $fetch<HydrationMismatchResponse>(new URL(HYDRATION_ROUTE, window.location.origin).href).then((data: { mismatches: HydrationMismatchPayload[] }) => {
-    hydrationMismatches.value = [...hydrationMismatches.value, ...data.mismatches.filter(m => !hydrationMismatches.value.some(existing => existing.id === m.id))]
-  })
-
-  const hydrationMismatchHandler = (event: MessageEvent) => {
-    const mismatch: HydrationMismatchPayload = JSON.parse(event.data)
-    if (!hydrationMismatches.value.some(existing => existing.id === mismatch.id)) {
-      hydrationMismatches.value.push(mismatch)
-    }
-  }
-
-  const hydrationClearedHandler = (event: MessageEvent) => {
-    const clearedIds: string[] = JSON.parse(event.data)
-    hydrationMismatches.value = hydrationMismatches.value.filter(m => !clearedIds.includes(m.id))
-  }
-
-  watch(nuxtApp.$sse.eventSource, (newEventSource, oldEventSource) => {
-    if (newEventSource) {
-      newEventSource.addEventListener('hints:hydration:mismatch', hydrationMismatchHandler)
-      newEventSource.addEventListener('hints:hydration:cleared', hydrationClearedHandler)
-    }
-    if (oldEventSource) {
-      oldEventSource.removeEventListener('hints:hydration:mismatch', hydrationMismatchHandler)
-      oldEventSource.removeEventListener('hints:hydration:cleared', hydrationClearedHandler)
-    }
-  }, {
-    immediate: true,
-  })
-
-  return {
-    provide: {
-      hydrationMismatches,
-    },
-  }
-})
diff --git a/client/app/plugins/lazy-load.ts b/client/app/plugins/lazy-load.ts
deleted file mode 100644
index cc459d1..0000000
--- a/client/app/plugins/lazy-load.ts
+++ /dev/null
@@ -1,57 +0,0 @@
-import type { ComponentLazyLoadData } from '../../../src/runtime/lazy-load/schema'
-import { parse } from 'valibot'
-import { defineNuxtPlugin } from '#imports'
-import { ComponentLazyLoadDataSchema } from '../../../src/runtime/lazy-load/schema'
-import { LAZY_LOAD_ROUTE } from '../utils/routes'
-
-export default defineNuxtPlugin(() => {
-  if (import.meta.test || !useHintsFeature('lazyLoad')) return
-  const nuxtApp = useNuxtApp()
-
-  const { data: lazyLoadHints } = useLazyFetch<ComponentLazyLoadData[]>(new URL(LAZY_LOAD_ROUTE, window.location.origin).href, {
-    default: () => [],
-    deep: true,
-  })
-
-  const lazyLoadReportHandler = (event: MessageEvent) => {
-    try {
-      const payload = parse(ComponentLazyLoadDataSchema, JSON.parse(event.data))
-      if (!lazyLoadHints.value.some(existing => existing.id === payload.id)) {
-        lazyLoadHints.value.push(payload)
-      }
-    }
-    catch {
-      console.warn('[hints] Ignoring malformed hints:lazy-load:report event', event.data)
-      return
-    }
-  }
-
-  const lazyLoadClearedHandler = (event: MessageEvent) => {
-    try {
-      const clearedId = JSON.parse(event.data)
-      lazyLoadHints.value = lazyLoadHints.value.filter(entry => entry.id !== clearedId)
-    }
-    catch {
-      return
-    }
-  }
-
-  watch(nuxtApp.$sse.eventSource, (newEventSource, oldEventSource) => {
-    if (newEventSource) {
-      newEventSource.addEventListener('hints:lazy-load:report', lazyLoadReportHandler)
-      newEventSource.addEventListener('hints:lazy-load:cleared', lazyLoadClearedHandler)
-    }
-    if (oldEventSource) {
-      oldEventSource.removeEventListener('hints:lazy-load:report', lazyLoadReportHandler)
-      oldEventSource.removeEventListener('hints:lazy-load:cleared', lazyLoadClearedHandler)
-    }
-  }, {
-    immediate: true,
-  })
-
-  return {
-    provide: {
-      lazyLoadHints,
-    },
-  }
-})
diff --git a/client/app/utils/routes.ts b/client/app/utils/routes.ts
index f05e287..bb5c345 100644
--- a/client/app/utils/routes.ts
+++ b/client/app/utils/routes.ts
@@ -5,7 +5,6 @@
  */
 
 export const HINTS_ROUTE = '/__nuxt_hints'
-export const HINTS_SSE_ROUTE = '/__nuxt_hints/sse'
 export const HYDRATION_ROUTE = `${HINTS_ROUTE}/hydration`
 export const LAZY_LOAD_ROUTE = `${HINTS_ROUTE}/lazy-load`
 export const HTML_VALIDATE_ROUTE = `${HINTS_ROUTE}/html-validate`
diff --git a/src/devtools-handlers.ts b/src/devtools-handlers.ts
new file mode 100644
index 0000000..b7fc2b0
--- /dev/null
+++ b/src/devtools-handlers.ts
@@ -0,0 +1,184 @@
+import { createError, createRouter, defineEventHandler, readBody, setResponseStatus } from 'h3'
+import type { HydrationMismatchPayload } from './runtime/hydration/types'
+import type { ComponentLazyLoadData } from './runtime/lazy-load/schema'
+import { ComponentLazyLoadDataSchema } from './runtime/lazy-load/schema'
+import type { HtmlValidateReport } from './runtime/html-validate/types'
+import type { HintsClientFunctions } from './runtime/core/rpc-types'
+import { parse, ValiError } from 'valibot'
+
+const hydrationMismatches: HydrationMismatchPayload[] = []
+const lazyLoadData: ComponentLazyLoadData[] = []
+const htmlValidateReports: HtmlValidateReport[] = []
+
+let broadcast: HintsClientFunctions | undefined
+
+/**
+ * Set broadcast object from module. 
+ */
+export function setBroadcast(b: HintsClientFunctions) {
+  broadcast = b
+}
+ 
+
+export function getHydrationMismatches() {
+  return { mismatches: hydrationMismatches }
+}
+
+export function clearHydrationMismatches(ids: string[]) {
+  for (const id of ids) {
+    const index = hydrationMismatches.findIndex(m => m.id === id)
+    if (index !== -1) {
+      hydrationMismatches.splice(index, 1)
+    }
+  }
+  broadcast?.onHydrationCleared(ids)
+}
+
+export function getLazyLoadHints() {
+  return lazyLoadData
+}
+
+export function clearLazyLoadHint(id: string) {
+  const index = lazyLoadData.findIndex(item => item.id === id)
+  if (index !== -1) {
+    lazyLoadData.splice(index, 1)
+  }
+  broadcast?.onLazyLoadCleared(id)
+}
+
+export function getHtmlValidateReports() {
+  return htmlValidateReports
+}
+
+export function clearHtmlValidateReport(id: string) {
+  const index = htmlValidateReports.findIndex(r => r.id === id)
+  if (index !== -1) {
+    htmlValidateReports.splice(index, 1)
+  }
+  broadcast?.onHtmlValidateDeleted(id)
+}
+
+// --- H3 Router ---
+
+export const hintsRouter = createRouter()
+
+// Hydration handlers
+hintsRouter.get('/hydration', defineEventHandler(() => {
+  return { mismatches: hydrationMismatches }
+}))
+
+hintsRouter.post('/hydration', defineEventHandler(async (event) => {
+  const body = await readBody<Omit<HydrationMismatchPayload, 'id'>>(event)
+  assertHydrationPayload(body)
+  const payload: HydrationMismatchPayload = {
+    id: crypto.randomUUID(),
+    htmlPreHydration: body.htmlPreHydration,
+    htmlPostHydration: body.htmlPostHydration,
+    componentName: body.componentName,
+    fileLocation: body.fileLocation,
+  }
+  hydrationMismatches.push(payload)
+  if (hydrationMismatches.length > 20) {
+    hydrationMismatches.shift()
+  }
+  broadcast?.onHydrationMismatch(payload)
+  setResponseStatus(event, 201)
+  return payload
+}))
+
+hintsRouter.delete('/hydration', defineEventHandler(async (event) => {
+  const body = await readBody<{ id: string[] }>(event)
+  if (!body || !Array.isArray(body.id)) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid payload' })
+  }
+  for (const id of body.id) {
+    const index = hydrationMismatches.findIndex(m => m.id === id)
+    if (index !== -1) {
+      hydrationMismatches.splice(index, 1)
+    }
+  }
+  broadcast?.onHydrationCleared(body.id)
+  setResponseStatus(event, 204)
+}))
+
+// Lazy-load handlers
+hintsRouter.get('/lazy-load', defineEventHandler(() => {
+  return lazyLoadData
+}))
+
+hintsRouter.post('/lazy-load', defineEventHandler(async (event) => {
+  const body = await readBody(event)
+  let parsed: ComponentLazyLoadData
+  try {
+    parsed = parse(ComponentLazyLoadDataSchema, body)
+  }
+  catch (error) {
+    if (error instanceof ValiError) {
+      setResponseStatus(event, 400)
+      return { error: 'Validation failed', message: error.message }
+    }
+    throw error
+  }
+  lazyLoadData.push(parsed)
+  broadcast?.onLazyLoadReport(parsed)
+  setResponseStatus(event, 201)
+}))
+
+hintsRouter.delete('/lazy-load/:id', defineEventHandler(async (event) => {
+  const id = event.context.params?.id
+  if (!id) {
+    throw createError({ statusCode: 400, message: 'ID is required' })
+  }
+  const index = lazyLoadData.findIndex(item => item.id === id)
+  if (index !== -1) {
+    lazyLoadData.splice(index, 1)
+  }
+  else {
+    throw createError({ statusCode: 404, message: 'Entry not found' })
+  }
+  broadcast?.onLazyLoadCleared(id)
+  setResponseStatus(event, 204)
+}))
+
+// HTML validate handlers
+hintsRouter.get('/html-validate', defineEventHandler(() => {
+  return htmlValidateReports
+}))
+
+hintsRouter.post('/html-validate', defineEventHandler(async (event) => {
+  const body = await readBody<HtmlValidateReport>(event)
+  if (!body || typeof body.id !== 'string') {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid payload' })
+  }
+  if (!htmlValidateReports.some(r => r.id === body.id)) {
+    htmlValidateReports.push(body)
+    broadcast?.onHtmlValidateReport(body)
+  }
+  setResponseStatus(event, 201)
+}))
+
+hintsRouter.delete('/html-validate/:id', defineEventHandler(async (event) => {
+  const id = event.context.params?.id
+  if (typeof id !== 'string') {
+    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
+  }
+  const index = htmlValidateReports.findIndex(r => r.id === id)
+  if (index !== -1) {
+    htmlValidateReports.splice(index, 1)
+  }
+  broadcast?.onHtmlValidateDeleted(id)
+  setResponseStatus(event, 204)
+}))
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function assertHydrationPayload(body: any): asserts body is Omit<HydrationMismatchPayload, 'id'> {
+  if (
+    typeof body !== 'object'
+    || (body.htmlPreHydration !== undefined && typeof body.htmlPreHydration !== 'string')
+    || (body.htmlPostHydration !== undefined && typeof body.htmlPostHydration !== 'string')
+    || typeof body.componentName !== 'string'
+    || typeof body.fileLocation !== 'string'
+  ) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid payload' })
+  }
+}
diff --git a/src/devtools.ts b/src/devtools.ts
index ecb44da..a382576 100644
--- a/src/devtools.ts
+++ b/src/devtools.ts
@@ -1,8 +1,20 @@
-import { addCustomTab } from '@nuxt/devtools-kit'
+import { addCustomTab, extendServerRpc, onDevToolsInitialized } from '@nuxt/devtools-kit'
 import { existsSync } from 'node:fs'
 import type { Nuxt } from '@nuxt/schema'
 import { addDevServerHandler, type Resolver } from '@nuxt/kit'
 import { proxyRequest, eventHandler } from 'h3'
+import type { HintsClientFunctions, HintsServerFunctions } from './runtime/core/rpc-types'
+import { RPC_NAMESPACE } from './runtime/core/rpc-types'
+import {
+  hintsRouter,
+  setBroadcast,
+  getHydrationMismatches,
+  clearHydrationMismatches,
+  getLazyLoadHints,
+  clearLazyLoadHint,
+  getHtmlValidateReports,
+  clearHtmlValidateReport,
+} from './devtools-handlers'
 
 const DEVTOOLS_UI_ROUTE = '/__nuxt-hints'
 const DEVTOOLS_UI_LOCAL_PORT = 3300
@@ -41,4 +53,21 @@ export function setupDevToolsUI(nuxt: Nuxt, resolver: Resolver) {
       src: DEVTOOLS_UI_ROUTE,
     },
   }, nuxt)
+
+  addDevServerHandler({
+    route: '/__nuxt_hints',
+    handler: hintsRouter.handler,
+  })
+
+  onDevToolsInitialized(() => {
+    const rpc = extendServerRpc<HintsClientFunctions, HintsServerFunctions>(RPC_NAMESPACE, {
+      getHydrationMismatches,
+      clearHydrationMismatches,
+      getLazyLoadHints,
+      clearLazyLoadHint,
+      getHtmlValidateReports,
+      clearHtmlValidateReport,
+    })
+    setBroadcast(rpc.broadcast)
+  }, nuxt)
 }
diff --git a/src/module.ts b/src/module.ts
index caf94c7..691b3c4 100644
--- a/src/module.ts
+++ b/src/module.ts
@@ -1,5 +1,4 @@
-import { defineNuxtModule, addPlugin, createResolver, addBuildPlugin, addComponent, addServerPlugin, addServerHandler, addTemplate } from '@nuxt/kit'
-import { HINTS_SSE_ROUTE } from './runtime/core/server/types'
+import { defineNuxtModule, addPlugin, createResolver, addBuildPlugin, addComponent, addServerPlugin, addTemplate } from '@nuxt/kit'
 import { setupDevToolsUI } from './devtools'
 import { InjectHydrationPlugin } from './plugins/hydration'
 import { LazyLoadHintPlugin } from './plugins/lazy-load'
@@ -55,12 +54,6 @@ export default defineNuxtModule<ModuleOptions>({
       priority: 1000,
     })
 
-    // core handlers
-    addServerHandler({
-      route: HINTS_SSE_ROUTE,
-      handler: resolver.resolve('./runtime/core/server/sse'),
-    })
-
     // performances
     if (isFeatureEnabled(options, 'webVitals')) {
       addPlugin(resolver.resolve('./runtime/web-vitals/plugin.client'))
@@ -70,15 +63,11 @@ export default defineNuxtModule<ModuleOptions>({
     if (isFeatureEnabled(options, 'hydration')) {
       addPlugin(resolver.resolve('./runtime/hydration/plugin.client'))
       addBuildPlugin(InjectHydrationPlugin)
-      addServerPlugin(resolver.resolve('./runtime/hydration/nitro.plugin'))
     }
 
     // lazy-load suggestions
     if (isFeatureEnabled(options, 'lazyLoad')) {
       addPlugin(resolver.resolve('./runtime/lazy-load/plugin.client'))
-      if (isFeatureDevtoolsEnabled(options, 'lazyLoad')) {
-        addServerPlugin(resolver.resolve('./runtime/lazy-load/nitro.plugin'))
-      }
       nuxt.hook('modules:done', () => {
         // hack to ensure the plugins runs after everything else. But before vite:import-analysis
         addBuildPlugin(LazyLoadHintPlugin, { client: false })
@@ -98,9 +87,6 @@ export default defineNuxtModule<ModuleOptions>({
     if (isFeatureEnabled(options, 'htmlValidate')) {
       addPlugin(resolver.resolve('./runtime/html-validate/plugin.client'))
       addServerPlugin(resolver.resolve('./runtime/html-validate/nitro.plugin'))
-      if (isFeatureDevtoolsEnabled(options, 'htmlValidate')) {
-        addServerPlugin(resolver.resolve('./runtime/html-validate/handlers/nitro-handlers.plugin'))
-      }
     }
 
     nuxt.hook('prepare:types', ({ references }) => {
diff --git a/src/runtime/core/rpc-types.ts b/src/runtime/core/rpc-types.ts
new file mode 100644
index 0000000..fd541b8
--- /dev/null
+++ b/src/runtime/core/rpc-types.ts
@@ -0,0 +1,23 @@
+import type { HydrationMismatchPayload, HydrationMismatchResponse } from '../hydration/types'
+import type { ComponentLazyLoadData } from '../lazy-load/schema'
+import type { HtmlValidateReport } from '../html-validate/types'
+
+export interface HintsClientFunctions {
+  onHydrationMismatch: (mismatch: HydrationMismatchPayload) => void
+  onHydrationCleared: (ids: string[]) => void
+  onLazyLoadReport: (data: ComponentLazyLoadData) => void
+  onLazyLoadCleared: (id: string) => void
+  onHtmlValidateReport: (report: HtmlValidateReport) => void
+  onHtmlValidateDeleted: (id: string) => void
+}
+
+export interface HintsServerFunctions {
+  getHydrationMismatches: () => HydrationMismatchResponse
+  clearHydrationMismatches: (ids: string[]) => void
+  getLazyLoadHints: () => ComponentLazyLoadData[]
+  clearLazyLoadHint: (id: string) => void
+  getHtmlValidateReports: () => HtmlValidateReport[]
+  clearHtmlValidateReport: (id: string) => void
+}
+
+export const RPC_NAMESPACE = 'nuxt-hints'
diff --git a/src/runtime/core/server/sse.ts b/src/runtime/core/server/sse.ts
deleted file mode 100644
index f17a185..0000000
--- a/src/runtime/core/server/sse.ts
+++ /dev/null
@@ -1,23 +0,0 @@
-import { createEventStream, defineEventHandler } from 'h3'
-import { useNitroApp } from 'nitropack/runtime'
-import type { HintsSseContext } from './types'
-
-export default defineEventHandler((event) => {
-  const nitro = useNitroApp()
-  const eventStream = createEventStream(event)
-
-  const context: HintsSseContext = {
-    eventStream,
-    unsubscribers: [],
-  }
-
-  // Allow features to register their SSE event handlers
-  nitro.hooks.callHook('hints:sse:setup', context)
-
-  eventStream.onClosed(async () => {
-    context.unsubscribers.forEach(unsub => unsub())
-    await eventStream.close()
-  })
-
-  return eventStream.send()
-})
diff --git a/src/runtime/core/server/types.ts b/src/runtime/core/server/types.ts
index 6f3e30a..1bc6f72 100644
--- a/src/runtime/core/server/types.ts
+++ b/src/runtime/core/server/types.ts
@@ -1,4 +1,4 @@
-import type { EventHandler, EventStream, H3Event } from 'h3'
+import type { EventHandler, H3Event } from 'h3'
 
 export interface HintsApiContext {
   event: H3Event
@@ -6,10 +6,4 @@ export interface HintsApiContext {
   handler?: EventHandler
 }
 
-export interface HintsSseContext {
-  eventStream: EventStream
-  unsubscribers: (() => void)[]
-}
-
 export const HINTS_ROUTE = '/__nuxt_hints'
-export const HINTS_SSE_ROUTE = '/__nuxt_hints/sse'
diff --git a/src/runtime/html-validate/handlers/delete.ts b/src/runtime/html-validate/handlers/delete.ts
deleted file mode 100644
index e45439b..0000000
--- a/src/runtime/html-validate/handlers/delete.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-import { createError, defineEventHandler, setResponseStatus } from 'h3'
-import { storage } from '../storage'
-import { useNitroApp } from 'nitropack/runtime'
-
-export const deleteHandler = defineEventHandler(async (event) => {
-  const nitro = useNitroApp()
-  const id = event.context.params?.id
-  if (typeof id === 'string') {
-    await storage.removeItem(id)
-    setResponseStatus(event, 204)
-    nitro.hooks.callHook('hints:html-validate:deleted', id)
-    return {}
-  }
-  throw createError({
-    statusCode: 404,
-    statusMessage: 'Not Found',
-  })
-})
diff --git a/src/runtime/html-validate/handlers/get.ts b/src/runtime/html-validate/handlers/get.ts
deleted file mode 100644
index 2e36fd2..0000000
--- a/src/runtime/html-validate/handlers/get.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-import { defineEventHandler } from 'h3'
-import { storage } from '../storage'
-import type { HtmlValidateReport } from '../types'
-
-export const getAllHandler = defineEventHandler(() => {
-  return storage.getKeys()
-    .then(keys => Promise.all(keys.map(key => storage.getItem<HtmlValidateReport>(key))))
-    .then(items => items.filter((item): item is HtmlValidateReport => item !== null))
-})
diff --git a/src/runtime/html-validate/handlers/nitro-handlers.plugin.ts b/src/runtime/html-validate/handlers/nitro-handlers.plugin.ts
index 0f6d42b..c38a3fd 100644
--- a/src/runtime/html-validate/handlers/nitro-handlers.plugin.ts
+++ b/src/runtime/html-validate/handlers/nitro-handlers.plugin.ts
@@ -16,26 +16,4 @@ export default <NitroAppPlugin> function (nitro) {
     deleteHandler,
     'delete',
   )
-
-  // sse
-  nitro.hooks.hook('hints:sse:setup', (context) => {
-    context.unsubscribers.push(
-      nitro.hooks.hook('hints:html-validate:report', (report) => {
-        context.eventStream.push(
-          {
-            data: JSON.stringify(report),
-            event: 'hints:html-validate:report',
-          },
-        )
-      }),
-      nitro.hooks.hook('hints:html-validate:deleted', (id) => {
-        context.eventStream.push(
-          {
-            data: id,
-            event: 'hints:html-validate:deleted',
-          },
-        )
-      }),
-    )
-  })
 }
diff --git a/src/runtime/html-validate/nitro.plugin.ts b/src/runtime/html-validate/nitro.plugin.ts
index 4c2a93f..70c8777 100644
--- a/src/runtime/html-validate/nitro.plugin.ts
+++ b/src/runtime/html-validate/nitro.plugin.ts
@@ -1,7 +1,6 @@
 import type { NitroAppPlugin } from 'nitropack/types'
 import { HtmlValidate, type ConfigData, type RuleConfig } from 'html-validate'
 import { addBeforeBodyEndTag } from './utils'
-import { storage } from './storage'
 import { randomUUID } from 'crypto'
 import { stringify } from 'devalue'
 import type { HtmlValidateReport } from './types'
@@ -9,6 +8,7 @@ import { format } from 'prettier/standalone'
 import html from 'prettier/parser-html'
 import { getFeatureOptions } from '../core/features'
 import { defu } from 'defu'
+import { getRequestURL } from 'h3'
 
 const DEFAULT_EXTENDS = [
   'html-validate:standard',
@@ -50,12 +50,16 @@ export default <NitroAppPlugin> function (nitro) {
           html: formattedBody,
           results: results.results,
         }
-        storage.setItem(id, data)
         response.body = addBeforeBodyEndTag(
           response.body,
           `<script id="hints-html-validate" type="application/json">${stringify(data)}</script>`,
         )
-        nitro.hooks.callHook('hints:html-validate:report', data)
+        const origin = getRequestURL(event).origin
+        globalThis.fetch(`${origin}/__nuxt_hints/html-validate`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(data),
+        }).catch(() => {})
       }
     }
   })
diff --git a/src/runtime/html-validate/storage.ts b/src/runtime/html-validate/storage.ts
deleted file mode 100644
index 0225eca..0000000
--- a/src/runtime/html-validate/storage.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-import { createStorage } from 'unstorage'
-
-export const storage = createStorage()
diff --git a/src/runtime/hydration/nitro.plugin.ts b/src/runtime/hydration/nitro.plugin.ts
index b4e8737..a0a112f 100644
--- a/src/runtime/hydration/nitro.plugin.ts
+++ b/src/runtime/hydration/nitro.plugin.ts
@@ -1,7 +1,6 @@
 import { createError, defineEventHandler, readBody, setResponseStatus } from 'h3'
 import type { NitroApp } from 'nitropack/types'
 import type { HydrationMismatchPayload } from './types'
-import type { HintsSseContext } from '../core/server/types'
 
 const hydrationMismatches: HydrationMismatchPayload[] = []
 
@@ -53,24 +52,6 @@ export default function (nitroApp: NitroApp) {
   nitroApp.router.add('/__nuxt_hints/hydration', postHandler, 'post')
   nitroApp.router.add('/__nuxt_hints/hydration', deleteHandler, 'delete')
 
-  // Register SSE event handlers for hydration
-  nitroApp.hooks.hook('hints:sse:setup', (context: HintsSseContext) => {
-    context.unsubscribers.push(
-      nitroApp.hooks.hook('hints:hydration:mismatch', (mismatch) => {
-        context.eventStream.push({
-          data: JSON.stringify(mismatch),
-          event: 'hints:hydration:mismatch',
-        })
-      }),
-      nitroApp.hooks.hook('hints:hydration:cleared', (payload) => {
-        context.eventStream.push({
-          data: JSON.stringify(payload.id),
-          event: 'hints:hydration:cleared',
-        })
-      }),
-    )
-  })
-
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   function assertPayload(body: any): asserts body is Omit<HydrationMismatchPayload, 'id'> {
     if (
diff --git a/src/runtime/hydration/types.ts b/src/runtime/hydration/types.ts
index a422268..9e53e18 100644
--- a/src/runtime/hydration/types.ts
+++ b/src/runtime/hydration/types.ts
@@ -1,4 +1,3 @@
-import type { EventStreamMessage } from 'h3'
 import type { ComponentInternalInstance, VNode } from 'vue'
 
 export interface HydrationMismatchPayload {
@@ -14,24 +13,6 @@ export interface LocalHydrationMismatch extends HydrationMismatchPayload {
   vnode: VNode
 }
 
-// prefer interface for extensibility
 export interface HydrationMismatchResponse {
   mismatches: HydrationMismatchPayload[]
 }
-
-export interface HydrationDeleteSSE extends EventStreamMessage {
-  event: 'hydration:cleared'
-  // array of ids
-  data: string
-}
-
-export interface HydrationNewSSE extends EventStreamMessage {
-  event: 'hydration:mismatch'
-  /**
-   * Stringified HydrationMismatchPayload
-   * @see HydrationMismatchPayload
-   */
-  data: string
-}
-
-export type HydrationSSEPayload = HydrationDeleteSSE | HydrationNewSSE
diff --git a/src/runtime/hydration/utils.ts b/src/runtime/hydration/utils.ts
index 91d8f26..cf382df 100644
--- a/src/runtime/hydration/utils.ts
+++ b/src/runtime/hydration/utils.ts
@@ -1,10 +1,9 @@
-import { HINTS_ROUTE, HINTS_SSE_ROUTE } from '../core/server/types'
+import { HINTS_ROUTE } from '../core/server/types'
 import { createHintsLogger } from '../logger'
 
 export const logger = createHintsLogger('hydration')
 
 export const HYDRATION_ROUTE = `${HINTS_ROUTE}/hydration`
-export const HYDRATION_SSE_ROUTE = HINTS_SSE_ROUTE
 
 export function formatHTML(html: string | undefined): string {
   if (!html) return ''
diff --git a/src/runtime/lazy-load/nitro.plugin.ts b/src/runtime/lazy-load/nitro.plugin.ts
index d214b75..0c4a172 100644
--- a/src/runtime/lazy-load/nitro.plugin.ts
+++ b/src/runtime/lazy-load/nitro.plugin.ts
@@ -3,7 +3,6 @@ import type { NitroApp } from 'nitropack/types'
 import type { ComponentLazyLoadData } from './schema'
 import { ComponentLazyLoadDataSchema } from './schema'
 import { parse, ValiError } from 'valibot'
-import type { HintsSseContext } from '../core/server/types'
 import { LAZY_LOAD_ROUTE } from './utils'
 
 const data: ComponentLazyLoadData[] = []
@@ -51,21 +50,4 @@ export default function (nitroApp: NitroApp) {
   nitroApp.router.add(LAZY_LOAD_ROUTE, getHandler, 'get')
   nitroApp.router.add(LAZY_LOAD_ROUTE, postHandler, 'post')
   nitroApp.router.add(`${LAZY_LOAD_ROUTE}/:id`, deleteHandler, 'delete')
-
-  nitroApp.hooks.hook('hints:sse:setup', (context: HintsSseContext) => {
-    context.unsubscribers.push(
-      nitroApp.hooks.hook('hints:lazy-load:report', (payload) => {
-        context.eventStream.push({
-          data: JSON.stringify(payload),
-          event: 'hints:lazy-load:report',
-        })
-      }),
-      nitroApp.hooks.hook('hints:lazy-load:cleared', (payload) => {
-        context.eventStream.push({
-          data: JSON.stringify(payload.id),
-          event: 'hints:lazy-load:cleared',
-        })
-      }),
-    )
-  })
 }
diff --git a/src/runtime/types.d.ts b/src/runtime/types.d.ts
index 96d1377..c44d8a9 100644
--- a/src/runtime/types.d.ts
+++ b/src/runtime/types.d.ts
@@ -1,6 +1,6 @@
 import type { VNode, Ref } from 'vue'
 import type { LCPMetricWithAttribution, INPMetricWithAttribution, CLSMetricWithAttribution } from 'web-vitals/attribution'
-import type { HydrationMismatchPayload, LocalHydrationMismatch } from './hydration/types'
+import type { LocalHydrationMismatch } from './hydration/types'
 import type { DirectImportInfo, LazyHydrationState } from './lazy-load/composables'
 import type { Features } from './core/types'
 
@@ -64,23 +64,4 @@ declare module '#app' {
   }
 }
 
-declare module 'nitropack' {
-  interface NitroRuntimeHooks {
-    // Core hints hooks
-    'hints:sse:setup': (context: import('./core/server/types').HintsSseContext) => void
-
-    // html-validate hooks
-    'hints:html-validate:report': (report: import('./html-validate/types').HtmlValidateReport) => void
-    'hints:html-validate:deleted': (id: string) => void
-
-    // Hydration hooks
-    'hints:hydration:mismatch': (payload: HydrationMismatchPayload) => void
-    'hints:hydration:cleared': (payload: { id: string[] }) => void
-
-    // Lazy-load hooks
-    'hints:lazy-load:report': (payload: import('./lazy-load/schema').ComponentLazyLoadData) => void
-    'hints:lazy-load:cleared': (payload: { id: string }) => void
-  }
-}
-
 export {}
diff --git a/test/unit/core/sse.test.ts b/test/unit/core/sse.test.ts
deleted file mode 100644
index 71b79c9..0000000
--- a/test/unit/core/sse.test.ts
+++ /dev/null
@@ -1,53 +0,0 @@
-import { describe, expect, it, vi, beforeEach, afterAll, beforeAll } from 'vitest'
-import { createApp, toWebHandler, toNodeListener } from 'h3'
-import sseEndpoint from '../../../src/runtime/core/server/sse'
-import type { Hookable } from 'hookable'
-import { createHooks } from 'hookable'
-import { useNitroApp } from 'nitropack/runtime'
-import type { NitroRuntimeHooks } from 'nitropack/types'
-import { createServer } from 'node:http'
-
-import {
-  getRandomPort,
-} from 'get-port-please'
-
-vi.mock('nitropack/runtime', async () => ({
-  useNitroApp: vi.fn(),
-}))
-
-const app = createApp()
-
-app.use('/', sseEndpoint)
-const handler = toWebHandler(app)
-const server = createServer(toNodeListener(app))
-
-describe('sseEndpoint', () => {
-  let hooks: Hookable<NitroRuntimeHooks>
-  let port: number
-
-  beforeAll(async () => {
-    port = await getRandomPort()
-    server.listen(port, () => {
-      console.log(`Test server running on http://localhost:${port}`)
-    })
-  })
-
-  beforeEach(() => {
-    hooks = createHooks()
-    vi.mocked(useNitroApp).mockReturnValue({ hooks } as unknown as ReturnType<typeof useNitroApp>)
-  })
-
-  afterAll(() => {
-    server.close()
-  })
-
-  it('should call registered SSE handlers on setup', async () => {
-    const mockHandler = vi.fn()
-
-    hooks.hook('hints:sse:setup', mockHandler)
-    const response = await handler(new Request(new URL('/', `http://localhost:${port}`)))
-    expect(mockHandler).toHaveBeenCalled()
-    expect(response.status).toBe(200)
-    expect(response.headers.get('Content-Type')).toBe('text/event-stream')
-  })
-})

From d79edc56ba3b54980a8860148c882068e82b9cd7 Mon Sep 17 00:00:00 2001
From: Julien Huang <julien.h.dev@gmail.com>
Date: Sat, 4 Apr 2026 17:59:29 +0200
Subject: [PATCH 2/5] refactor: move SSE to devtools RPC

---
 src/devtools-handlers.ts                      | 232 +++++-------------
 src/devtools.ts                               |   4 +-
 src/runtime/core/server/rpc-bridge.ts         |  32 +++
 src/runtime/html-validate/api-handlers.ts     |  50 ++++
 .../handlers/nitro-handlers.plugin.ts         |  19 --
 src/runtime/hydration/handlers.ts             |  72 ++++++
 src/runtime/hydration/nitro.plugin.ts         |  67 -----
 src/runtime/lazy-load/handlers.ts             |  63 +++++
 src/runtime/lazy-load/nitro.plugin.ts         |  53 ----
 9 files changed, 277 insertions(+), 315 deletions(-)
 create mode 100644 src/runtime/core/server/rpc-bridge.ts
 create mode 100644 src/runtime/html-validate/api-handlers.ts
 delete mode 100644 src/runtime/html-validate/handlers/nitro-handlers.plugin.ts
 create mode 100644 src/runtime/hydration/handlers.ts
 delete mode 100644 src/runtime/hydration/nitro.plugin.ts
 create mode 100644 src/runtime/lazy-load/handlers.ts
 delete mode 100644 src/runtime/lazy-load/nitro.plugin.ts

diff --git a/src/devtools-handlers.ts b/src/devtools-handlers.ts
index b7fc2b0..f3c9190 100644
--- a/src/devtools-handlers.ts
+++ b/src/devtools-handlers.ts
@@ -1,184 +1,68 @@
-import { createError, createRouter, defineEventHandler, readBody, setResponseStatus } from 'h3'
-import type { HydrationMismatchPayload } from './runtime/hydration/types'
-import type { ComponentLazyLoadData } from './runtime/lazy-load/schema'
-import { ComponentLazyLoadDataSchema } from './runtime/lazy-load/schema'
-import type { HtmlValidateReport } from './runtime/html-validate/types'
+import { createRouter } from 'h3'
 import type { HintsClientFunctions } from './runtime/core/rpc-types'
-import { parse, ValiError } from 'valibot'
-
-const hydrationMismatches: HydrationMismatchPayload[] = []
-const lazyLoadData: ComponentLazyLoadData[] = []
-const htmlValidateReports: HtmlValidateReport[] = []
-
-let broadcast: HintsClientFunctions | undefined
-
-/**
- * Set broadcast object from module. 
- */
-export function setBroadcast(b: HintsClientFunctions) {
-  broadcast = b
-}
- 
-
-export function getHydrationMismatches() {
-  return { mismatches: hydrationMismatches }
-}
-
-export function clearHydrationMismatches(ids: string[]) {
-  for (const id of ids) {
-    const index = hydrationMismatches.findIndex(m => m.id === id)
-    if (index !== -1) {
-      hydrationMismatches.splice(index, 1)
-    }
-  }
-  broadcast?.onHydrationCleared(ids)
-}
-
-export function getLazyLoadHints() {
-  return lazyLoadData
-}
-
-export function clearLazyLoadHint(id: string) {
-  const index = lazyLoadData.findIndex(item => item.id === id)
-  if (index !== -1) {
-    lazyLoadData.splice(index, 1)
-  }
-  broadcast?.onLazyLoadCleared(id)
-}
-
-export function getHtmlValidateReports() {
-  return htmlValidateReports
+import {
+  getHydrationMismatches,
+  clearHydrationMismatches,
+  setHydrationNotify,
+  getHandler as hydrationGet,
+  postHandler as hydrationPost,
+  deleteHandler as hydrationDelete,
+} from './runtime/hydration/handlers'
+import {
+  getLazyLoadHints,
+  clearLazyLoadHint,
+  setLazyLoadNotify,
+  getHandler as lazyLoadGet,
+  postHandler as lazyLoadPost,
+  deleteHandler as lazyLoadDelete,
+} from './runtime/lazy-load/handlers'
+import {
+  getHtmlValidateReports,
+  clearHtmlValidateReport,
+  setHtmlValidateNotify,
+  getHandler as htmlValidateGet,
+  postHandler as htmlValidatePost,
+  deleteHandler as htmlValidateDelete,
+} from './runtime/html-validate/api-handlers'
+
+export {
+  getHydrationMismatches,
+  clearHydrationMismatches,
+  getLazyLoadHints,
+  clearLazyLoadHint,
+  getHtmlValidateReports,
+  clearHtmlValidateReport,
 }
 
-export function clearHtmlValidateReport(id: string) {
-  const index = htmlValidateReports.findIndex(r => r.id === id)
-  if (index !== -1) {
-    htmlValidateReports.splice(index, 1)
-  }
-  broadcast?.onHtmlValidateDeleted(id)
+export function setBroadcast(b: HintsClientFunctions) {
+  setHydrationNotify({
+    onMismatch: p => b.onHydrationMismatch(p),
+    onCleared: ids => b.onHydrationCleared(ids),
+  })
+  setLazyLoadNotify({
+    onReport: d => b.onLazyLoadReport(d),
+    onCleared: id => b.onLazyLoadCleared(id),
+  })
+  setHtmlValidateNotify({
+    onReport: r => b.onHtmlValidateReport(r),
+    onDeleted: id => b.onHtmlValidateDeleted(id),
+  })
 }
 
-// --- H3 Router ---
-
-export const hintsRouter = createRouter()
-
-// Hydration handlers
-hintsRouter.get('/hydration', defineEventHandler(() => {
-  return { mismatches: hydrationMismatches }
-}))
-
-hintsRouter.post('/hydration', defineEventHandler(async (event) => {
-  const body = await readBody<Omit<HydrationMismatchPayload, 'id'>>(event)
-  assertHydrationPayload(body)
-  const payload: HydrationMismatchPayload = {
-    id: crypto.randomUUID(),
-    htmlPreHydration: body.htmlPreHydration,
-    htmlPostHydration: body.htmlPostHydration,
-    componentName: body.componentName,
-    fileLocation: body.fileLocation,
-  }
-  hydrationMismatches.push(payload)
-  if (hydrationMismatches.length > 20) {
-    hydrationMismatches.shift()
-  }
-  broadcast?.onHydrationMismatch(payload)
-  setResponseStatus(event, 201)
-  return payload
-}))
-
-hintsRouter.delete('/hydration', defineEventHandler(async (event) => {
-  const body = await readBody<{ id: string[] }>(event)
-  if (!body || !Array.isArray(body.id)) {
-    throw createError({ statusCode: 400, statusMessage: 'Invalid payload' })
-  }
-  for (const id of body.id) {
-    const index = hydrationMismatches.findIndex(m => m.id === id)
-    if (index !== -1) {
-      hydrationMismatches.splice(index, 1)
-    }
-  }
-  broadcast?.onHydrationCleared(body.id)
-  setResponseStatus(event, 204)
-}))
-
-// Lazy-load handlers
-hintsRouter.get('/lazy-load', defineEventHandler(() => {
-  return lazyLoadData
-}))
-
-hintsRouter.post('/lazy-load', defineEventHandler(async (event) => {
-  const body = await readBody(event)
-  let parsed: ComponentLazyLoadData
-  try {
-    parsed = parse(ComponentLazyLoadDataSchema, body)
-  }
-  catch (error) {
-    if (error instanceof ValiError) {
-      setResponseStatus(event, 400)
-      return { error: 'Validation failed', message: error.message }
-    }
-    throw error
-  }
-  lazyLoadData.push(parsed)
-  broadcast?.onLazyLoadReport(parsed)
-  setResponseStatus(event, 201)
-}))
-
-hintsRouter.delete('/lazy-load/:id', defineEventHandler(async (event) => {
-  const id = event.context.params?.id
-  if (!id) {
-    throw createError({ statusCode: 400, message: 'ID is required' })
-  }
-  const index = lazyLoadData.findIndex(item => item.id === id)
-  if (index !== -1) {
-    lazyLoadData.splice(index, 1)
-  }
-  else {
-    throw createError({ statusCode: 404, message: 'Entry not found' })
-  }
-  broadcast?.onLazyLoadCleared(id)
-  setResponseStatus(event, 204)
-}))
+export function createHintsRouter() {
+  const router = createRouter()
 
-// HTML validate handlers
-hintsRouter.get('/html-validate', defineEventHandler(() => {
-  return htmlValidateReports
-}))
+  router.get('/hydration', hydrationGet)
+  router.post('/hydration', hydrationPost)
+  router.delete('/hydration', hydrationDelete)
 
-hintsRouter.post('/html-validate', defineEventHandler(async (event) => {
-  const body = await readBody<HtmlValidateReport>(event)
-  if (!body || typeof body.id !== 'string') {
-    throw createError({ statusCode: 400, statusMessage: 'Invalid payload' })
-  }
-  if (!htmlValidateReports.some(r => r.id === body.id)) {
-    htmlValidateReports.push(body)
-    broadcast?.onHtmlValidateReport(body)
-  }
-  setResponseStatus(event, 201)
-}))
+  router.get('/lazy-load', lazyLoadGet)
+  router.post('/lazy-load', lazyLoadPost)
+  router.delete('/lazy-load/:id', lazyLoadDelete)
 
-hintsRouter.delete('/html-validate/:id', defineEventHandler(async (event) => {
-  const id = event.context.params?.id
-  if (typeof id !== 'string') {
-    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
-  }
-  const index = htmlValidateReports.findIndex(r => r.id === id)
-  if (index !== -1) {
-    htmlValidateReports.splice(index, 1)
-  }
-  broadcast?.onHtmlValidateDeleted(id)
-  setResponseStatus(event, 204)
-}))
+  router.get('/html-validate', htmlValidateGet)
+  router.post('/html-validate', htmlValidatePost)
+  router.delete('/html-validate/:id', htmlValidateDelete)
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function assertHydrationPayload(body: any): asserts body is Omit<HydrationMismatchPayload, 'id'> {
-  if (
-    typeof body !== 'object'
-    || (body.htmlPreHydration !== undefined && typeof body.htmlPreHydration !== 'string')
-    || (body.htmlPostHydration !== undefined && typeof body.htmlPostHydration !== 'string')
-    || typeof body.componentName !== 'string'
-    || typeof body.fileLocation !== 'string'
-  ) {
-    throw createError({ statusCode: 400, statusMessage: 'Invalid payload' })
-  }
+  return router
 }
diff --git a/src/devtools.ts b/src/devtools.ts
index a382576..c3e2e95 100644
--- a/src/devtools.ts
+++ b/src/devtools.ts
@@ -6,7 +6,7 @@ import { proxyRequest, eventHandler } from 'h3'
 import type { HintsClientFunctions, HintsServerFunctions } from './runtime/core/rpc-types'
 import { RPC_NAMESPACE } from './runtime/core/rpc-types'
 import {
-  hintsRouter,
+  createHintsRouter,
   setBroadcast,
   getHydrationMismatches,
   clearHydrationMismatches,
@@ -56,7 +56,7 @@ export function setupDevToolsUI(nuxt: Nuxt, resolver: Resolver) {
 
   addDevServerHandler({
     route: '/__nuxt_hints',
-    handler: hintsRouter.handler,
+    handler: createHintsRouter().handler,
   })
 
   onDevToolsInitialized(() => {
diff --git a/src/runtime/core/server/rpc-bridge.ts b/src/runtime/core/server/rpc-bridge.ts
new file mode 100644
index 0000000..e00f390
--- /dev/null
+++ b/src/runtime/core/server/rpc-bridge.ts
@@ -0,0 +1,32 @@
+import type { NitroApp } from 'nitropack/types'
+import type { HintsClientFunctions } from '../rpc-types'
+
+function getRpcBroadcast(): HintsClientFunctions | undefined {
+  return globalThis.__nuxtHintsRpcBroadcast
+}
+
+export default function (nitroApp: NitroApp) {
+  nitroApp.hooks.hook('hints:hydration:mismatch', (mismatch) => {
+    getRpcBroadcast()?.onHydrationMismatch(mismatch)
+  })
+
+  nitroApp.hooks.hook('hints:hydration:cleared', (payload) => {
+    getRpcBroadcast()?.onHydrationCleared(payload.id)
+  })
+
+  nitroApp.hooks.hook('hints:lazy-load:report', (data) => {
+    getRpcBroadcast()?.onLazyLoadReport(data)
+  })
+
+  nitroApp.hooks.hook('hints:lazy-load:cleared', (payload) => {
+    getRpcBroadcast()?.onLazyLoadCleared(payload.id)
+  })
+
+  nitroApp.hooks.hook('hints:html-validate:report', (report) => {
+    getRpcBroadcast()?.onHtmlValidateReport(report)
+  })
+
+  nitroApp.hooks.hook('hints:html-validate:deleted', (id) => {
+    getRpcBroadcast()?.onHtmlValidateDeleted(id)
+  })
+}
diff --git a/src/runtime/html-validate/api-handlers.ts b/src/runtime/html-validate/api-handlers.ts
new file mode 100644
index 0000000..786d7ea
--- /dev/null
+++ b/src/runtime/html-validate/api-handlers.ts
@@ -0,0 +1,50 @@
+import { createError, defineEventHandler, readBody, setResponseStatus } from 'h3'
+import type { HtmlValidateReport } from './types'
+
+export const htmlValidateReports: HtmlValidateReport[] = []
+
+let onReport: ((report: HtmlValidateReport) => void) | undefined
+let onDeleted: ((id: string) => void) | undefined
+
+export function setHtmlValidateNotify(callbacks: {
+  onReport: (report: HtmlValidateReport) => void
+  onDeleted: (id: string) => void
+}) {
+  onReport = callbacks.onReport
+  onDeleted = callbacks.onDeleted
+}
+
+export function getHtmlValidateReports() {
+  return htmlValidateReports
+}
+
+export function clearHtmlValidateReport(id: string) {
+  const index = htmlValidateReports.findIndex(r => r.id === id)
+  if (index !== -1) {
+    htmlValidateReports.splice(index, 1)
+  }
+  onDeleted?.(id)
+}
+
+export const getHandler = defineEventHandler(() => getHtmlValidateReports())
+
+export const postHandler = defineEventHandler(async (event) => {
+  const body = await readBody<HtmlValidateReport>(event)
+  if (!body || typeof body.id !== 'string') {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid payload' })
+  }
+  if (!htmlValidateReports.some(r => r.id === body.id)) {
+    htmlValidateReports.push(body)
+    onReport?.(body)
+  }
+  setResponseStatus(event, 201)
+})
+
+export const deleteHandler = defineEventHandler(async (event) => {
+  const id = event.context.params?.id
+  if (typeof id !== 'string') {
+    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
+  }
+  clearHtmlValidateReport(id)
+  setResponseStatus(event, 204)
+})
diff --git a/src/runtime/html-validate/handlers/nitro-handlers.plugin.ts b/src/runtime/html-validate/handlers/nitro-handlers.plugin.ts
deleted file mode 100644
index c38a3fd..0000000
--- a/src/runtime/html-validate/handlers/nitro-handlers.plugin.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-import type { NitroAppPlugin } from 'nitropack/types'
-import { join } from 'pathe'
-import { HTMLVALIDATE_ROUTE } from '../utils'
-import { getAllHandler } from './get'
-import { deleteHandler } from './delete'
-
-export default <NitroAppPlugin> function (nitro) {
-  nitro.router.add(
-    HTMLVALIDATE_ROUTE,
-    getAllHandler,
-    'get',
-  )
-
-  nitro.router.add(
-    join(HTMLVALIDATE_ROUTE, ':id'),
-    deleteHandler,
-    'delete',
-  )
-}
diff --git a/src/runtime/hydration/handlers.ts b/src/runtime/hydration/handlers.ts
new file mode 100644
index 0000000..ae64156
--- /dev/null
+++ b/src/runtime/hydration/handlers.ts
@@ -0,0 +1,72 @@
+import { createError, defineEventHandler, readBody, setResponseStatus } from 'h3'
+import type { HydrationMismatchPayload } from './types'
+
+export const hydrationMismatches: HydrationMismatchPayload[] = []
+
+let onMismatch: ((payload: HydrationMismatchPayload) => void) | undefined
+let onCleared: ((ids: string[]) => void) | undefined
+
+export function setHydrationNotify(callbacks: {
+  onMismatch: (payload: HydrationMismatchPayload) => void
+  onCleared: (ids: string[]) => void
+}) {
+  onMismatch = callbacks.onMismatch
+  onCleared = callbacks.onCleared
+}
+
+export function getHydrationMismatches() {
+  return { mismatches: hydrationMismatches }
+}
+
+export function clearHydrationMismatches(ids: string[]) {
+  for (const id of ids) {
+    const index = hydrationMismatches.findIndex(m => m.id === id)
+    if (index !== -1) {
+      hydrationMismatches.splice(index, 1)
+    }
+  }
+  onCleared?.(ids)
+}
+
+export const getHandler = defineEventHandler(() => getHydrationMismatches())
+
+export const postHandler = defineEventHandler(async (event) => {
+  const body = await readBody<Omit<HydrationMismatchPayload, 'id'>>(event)
+  assertPayload(body)
+  const payload: HydrationMismatchPayload = {
+    id: crypto.randomUUID(),
+    htmlPreHydration: body.htmlPreHydration,
+    htmlPostHydration: body.htmlPostHydration,
+    componentName: body.componentName,
+    fileLocation: body.fileLocation,
+  }
+  hydrationMismatches.push(payload)
+  if (hydrationMismatches.length > 20) {
+    hydrationMismatches.shift()
+  }
+  onMismatch?.(payload)
+  setResponseStatus(event, 201)
+  return payload
+})
+
+export const deleteHandler = defineEventHandler(async (event) => {
+  const body = await readBody<{ id: string[] }>(event)
+  if (!body || !Array.isArray(body.id)) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid payload' })
+  }
+  clearHydrationMismatches(body.id)
+  setResponseStatus(event, 204)
+})
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function assertPayload(body: any): asserts body is Omit<HydrationMismatchPayload, 'id'> {
+  if (
+    typeof body !== 'object'
+    || (body.htmlPreHydration !== undefined && typeof body.htmlPreHydration !== 'string')
+    || (body.htmlPostHydration !== undefined && typeof body.htmlPostHydration !== 'string')
+    || typeof body.componentName !== 'string'
+    || typeof body.fileLocation !== 'string'
+  ) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid payload' })
+  }
+}
diff --git a/src/runtime/hydration/nitro.plugin.ts b/src/runtime/hydration/nitro.plugin.ts
deleted file mode 100644
index a0a112f..0000000
--- a/src/runtime/hydration/nitro.plugin.ts
+++ /dev/null
@@ -1,67 +0,0 @@
-import { createError, defineEventHandler, readBody, setResponseStatus } from 'h3'
-import type { NitroApp } from 'nitropack/types'
-import type { HydrationMismatchPayload } from './types'
-
-const hydrationMismatches: HydrationMismatchPayload[] = []
-
-export default function (nitroApp: NitroApp) {
-  const getHandler = defineEventHandler(() => {
-    return {
-      mismatches: hydrationMismatches,
-    }
-  })
-
-  const postHandler = defineEventHandler(async (event) => {
-    const body = await readBody<Omit<HydrationMismatchPayload, 'id'>>(event)
-    assertPayload(body)
-    const payload: HydrationMismatchPayload = {
-      id: crypto.randomUUID(),
-      htmlPreHydration: body.htmlPreHydration,
-      htmlPostHydration: body.htmlPostHydration,
-      componentName: body.componentName,
-      fileLocation: body.fileLocation,
-    }
-    hydrationMismatches.push(payload)
-    if (hydrationMismatches.length > 20) {
-      hydrationMismatches.shift()
-    }
-    nitroApp.hooks.callHook('hints:hydration:mismatch', payload)
-    setResponseStatus(event, 201)
-    return payload
-  })
-
-  const deleteHandler = defineEventHandler(async (event) => {
-    const body = await readBody<{ id: string[] }>(event)
-
-    if (!body || !Array.isArray(body.id)) {
-      throw createError({ statusCode: 400, statusMessage: 'Invalid payload' })
-    }
-
-    for (const id of body.id) {
-      const index = hydrationMismatches.findIndex(m => m.id === id)
-      if (index !== -1) {
-        hydrationMismatches.splice(index, 1)
-      }
-    }
-
-    nitroApp.hooks.callHook('hints:hydration:cleared', { id: body.id })
-    setResponseStatus(event, 204)
-  })
-
-  nitroApp.router.add('/__nuxt_hints/hydration', getHandler, 'get')
-  nitroApp.router.add('/__nuxt_hints/hydration', postHandler, 'post')
-  nitroApp.router.add('/__nuxt_hints/hydration', deleteHandler, 'delete')
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  function assertPayload(body: any): asserts body is Omit<HydrationMismatchPayload, 'id'> {
-    if (
-      typeof body !== 'object'
-      || (body.htmlPreHydration !== undefined && typeof body.htmlPreHydration !== 'string')
-      || (body.htmlPostHydration !== undefined && typeof body.htmlPostHydration !== 'string')
-      || typeof body.componentName !== 'string'
-      || typeof body.fileLocation !== 'string'
-    ) {
-      throw createError({ statusCode: 400, statusMessage: 'Invalid payload' })
-    }
-  }
-}
diff --git a/src/runtime/lazy-load/handlers.ts b/src/runtime/lazy-load/handlers.ts
new file mode 100644
index 0000000..68dfe97
--- /dev/null
+++ b/src/runtime/lazy-load/handlers.ts
@@ -0,0 +1,63 @@
+import { createError, defineEventHandler, readBody, setResponseStatus } from 'h3'
+import type { ComponentLazyLoadData } from './schema'
+import { ComponentLazyLoadDataSchema } from './schema'
+import { parse, ValiError } from 'valibot'
+
+export const lazyLoadData: ComponentLazyLoadData[] = []
+
+let onReport: ((data: ComponentLazyLoadData) => void) | undefined
+let onCleared: ((id: string) => void) | undefined
+
+export function setLazyLoadNotify(callbacks: {
+  onReport: (data: ComponentLazyLoadData) => void
+  onCleared: (id: string) => void
+}) {
+  onReport = callbacks.onReport
+  onCleared = callbacks.onCleared
+}
+
+export function getLazyLoadHints() {
+  return lazyLoadData
+}
+
+export function clearLazyLoadHint(id: string) {
+  const index = lazyLoadData.findIndex(item => item.id === id)
+  if (index !== -1) {
+    lazyLoadData.splice(index, 1)
+  }
+  onCleared?.(id)
+}
+
+export const getHandler = defineEventHandler(() => getLazyLoadHints())
+
+export const postHandler = defineEventHandler(async (event) => {
+  const body = await readBody(event)
+  let parsed: ComponentLazyLoadData
+  try {
+    parsed = parse(ComponentLazyLoadDataSchema, body)
+  }
+  catch (error) {
+    if (error instanceof ValiError) {
+      setResponseStatus(event, 400)
+      return { error: 'Validation failed', message: error.message }
+    }
+    throw error
+  }
+  lazyLoadData.push(parsed)
+  onReport?.(parsed)
+  setResponseStatus(event, 201)
+})
+
+export const deleteHandler = defineEventHandler(async (event) => {
+  const id = event.context.params?.id
+  if (!id) {
+    throw createError({ statusCode: 400, message: 'ID is required' })
+  }
+  const index = lazyLoadData.findIndex(item => item.id === id)
+  if (index === -1) {
+    throw createError({ statusCode: 404, message: 'Entry not found' })
+  }
+  lazyLoadData.splice(index, 1)
+  onCleared?.(id)
+  setResponseStatus(event, 204)
+})
diff --git a/src/runtime/lazy-load/nitro.plugin.ts b/src/runtime/lazy-load/nitro.plugin.ts
deleted file mode 100644
index 0c4a172..0000000
--- a/src/runtime/lazy-load/nitro.plugin.ts
+++ /dev/null
@@ -1,53 +0,0 @@
-import { createError, defineEventHandler, setResponseStatus, readBody } from 'h3'
-import type { NitroApp } from 'nitropack/types'
-import type { ComponentLazyLoadData } from './schema'
-import { ComponentLazyLoadDataSchema } from './schema'
-import { parse, ValiError } from 'valibot'
-import { LAZY_LOAD_ROUTE } from './utils'
-
-const data: ComponentLazyLoadData[] = []
-
-export default function (nitroApp: NitroApp) {
-  const getHandler = defineEventHandler(() => {
-    return data
-  })
-
-  const postHandler = defineEventHandler(async (event) => {
-    const body = await readBody(event)
-    let parsed: ComponentLazyLoadData
-    try {
-      parsed = parse(ComponentLazyLoadDataSchema, body)
-    }
-    catch (error) {
-      if (error instanceof ValiError) {
-        setResponseStatus(event, 400)
-        return { error: 'Validation failed', message: error.message }
-      }
-      throw error
-    }
-    data.push(parsed)
-    nitroApp.hooks.callHook('hints:lazy-load:report', parsed)
-    setResponseStatus(event, 201)
-  })
-
-  const deleteHandler = defineEventHandler(async (event) => {
-    const id = event.context.params?.id
-    if (!id) {
-      throw createError({ statusCode: 400, message: 'ID is required' })
-    }
-
-    const index = data.findIndex(item => item.id === id)
-    if (index !== -1) {
-      data.splice(index, 1)
-    }
-    else {
-      throw createError({ statusCode: 404, message: 'Entry not found' })
-    }
-    nitroApp.hooks.callHook('hints:lazy-load:cleared', { id })
-    setResponseStatus(event, 204)
-  })
-
-  nitroApp.router.add(LAZY_LOAD_ROUTE, getHandler, 'get')
-  nitroApp.router.add(LAZY_LOAD_ROUTE, postHandler, 'post')
-  nitroApp.router.add(`${LAZY_LOAD_ROUTE}/:id`, deleteHandler, 'delete')
-}

From 34bc29d8b688e459f94d5f22777b859674f8d760 Mon Sep 17 00:00:00 2001
From: Julien Huang <julien.h.dev@gmail.com>
Date: Wed, 8 Apr 2026 23:43:25 +0200
Subject: [PATCH 3/5] feedbacks

---
 client/app/app.vue                        | 104 ++++++++++++++++++----
 client/app/composables/features.ts        |   7 ++
 client/app/composables/host.ts            |   4 +-
 src/devtools-handlers.ts                  |  19 ----
 src/devtools.ts                           |   3 +-
 src/runtime/core/rpc.ts                   |   5 ++
 src/runtime/core/server/rpc-bridge.ts     |  32 -------
 src/runtime/html-validate/api-handlers.ts |  16 +---
 src/runtime/hydration/handlers.ts         |  24 ++---
 src/runtime/lazy-load/handlers.ts         |  38 ++++----
 src/runtime/types.d.ts                    |   3 +
 11 files changed, 131 insertions(+), 124 deletions(-)
 create mode 100644 src/runtime/core/rpc.ts
 delete mode 100644 src/runtime/core/server/rpc-bridge.ts

diff --git a/client/app/app.vue b/client/app/app.vue
index d0ce4fd..16adbd8 100644
--- a/client/app/app.vue
+++ b/client/app/app.vue
@@ -20,67 +20,133 @@ nuxtApp.provide('lazyLoadHints', lazyLoadHints)
 nuxtApp.provide('htmlValidateReports', htmlValidateReports)
 
 onDevtoolsClientConnected((client) => {
+  const hydrationTombstones = new Set<string>()
+  const lazyLoadTombstones = new Set<string>()
+  const htmlValidateTombstones = new Set<string>()
+
+  let hydrationInitialSyncDone = !useHintsFeature('hydration')
+  let lazyLoadInitialSyncDone = !useHintsFeature('lazyLoad')
+  let htmlValidateInitialSyncDone = !useHintsFeature('htmlValidate')
+
+  const bufferedHydrationMismatches: HydrationMismatchPayload[] = []
+  const bufferedLazyLoadHints: ComponentLazyLoadData[] = []
+  const bufferedHtmlValidateReports: HtmlValidateReport[] = []
+
+  const applyHydrationMismatch = (mismatch: HydrationMismatchPayload | LocalHydrationMismatch) => {
+    if (hydrationTombstones.has(mismatch.id)) {
+      return
+    }
+    if (!hydrationMismatches.value.some(existing => existing.id === mismatch.id)) {
+      hydrationMismatches.value.push(mismatch)
+    }
+  }
+
+  const applyLazyLoadHint = (entry: ComponentLazyLoadData) => {
+    if (lazyLoadTombstones.has(entry.id)) {
+      return
+    }
+    if (!lazyLoadHints.value.some(existing => existing.id === entry.id)) {
+      lazyLoadHints.value.push(entry)
+    }
+  }
+
+  const applyHtmlValidateReport = (report: HtmlValidateReport) => {
+    if (htmlValidateTombstones.has(report.id)) {
+      return
+    }
+    if (!htmlValidateReports.value.some(existing => existing.id === report.id)) {
+      htmlValidateReports.value = [...htmlValidateReports.value, report]
+    }
+  }
+
   const rpc = client.devtools.extendClientRpc<HintsServerFunctions, HintsClientFunctions>(RPC_NAMESPACE, {
     onHydrationMismatch(mismatch: HydrationMismatchPayload) {
-      if (!hydrationMismatches.value.some(existing => existing.id === mismatch.id)) {
-        hydrationMismatches.value.push(mismatch)
+      if (!hydrationInitialSyncDone) {
+        bufferedHydrationMismatches.push(mismatch)
+        return
       }
+      applyHydrationMismatch(mismatch)
     },
     onHydrationCleared(ids: string[]) {
+      ids.forEach(id => hydrationTombstones.add(id))
       hydrationMismatches.value = hydrationMismatches.value.filter(m => !ids.includes(m.id))
     },
     onLazyLoadReport(data: ComponentLazyLoadData) {
       try {
         const validated = parse(ComponentLazyLoadDataSchema, data)
-        if (!lazyLoadHints.value.some(existing => existing.id === validated.id)) {
-          lazyLoadHints.value.push(validated)
+        if (!lazyLoadInitialSyncDone) {
+          bufferedLazyLoadHints.push(validated)
+          return
         }
+        applyLazyLoadHint(validated)
       }
       catch {
         console.warn('[hints] Ignoring malformed lazy-load report', data)
       }
     },
     onLazyLoadCleared(id: string) {
+      lazyLoadTombstones.add(id)
       lazyLoadHints.value = lazyLoadHints.value.filter(entry => entry.id !== id)
     },
     onHtmlValidateReport(report: HtmlValidateReport) {
-      if (!htmlValidateReports.value.some(existing => existing.id === report.id)) {
-        htmlValidateReports.value = [...htmlValidateReports.value, report]
+      if (!htmlValidateInitialSyncDone) {
+        bufferedHtmlValidateReports.push(report)
+        return
       }
+      applyHtmlValidateReport(report)
     },
     onHtmlValidateDeleted(id: string) {
+      htmlValidateTombstones.add(id)
       htmlValidateReports.value = htmlValidateReports.value.filter(report => report.id !== id)
     },
   })
 
   // Hydration: seed from host payload and fetch from server via RPC
   if (useHintsFeature('hydration')) {
-    hydrationMismatches.value = [...client.host.nuxt.payload.__hints.hydration]
+    if (client.host?.nuxt?.payload?.__hints?.hydration) {
+      hydrationMismatches.value = client.host.nuxt.payload.__hints.hydration
+        .filter(mismatch => !hydrationTombstones.has(mismatch.id))
+    }
     rpc.getHydrationMismatches().then((data) => {
-      hydrationMismatches.value = [
-        ...hydrationMismatches.value,
-        ...data.mismatches.filter(m => !hydrationMismatches.value.some(existing => existing.id === m.id)),
-      ]
+      data.mismatches
+        .filter(mismatch => !hydrationTombstones.has(mismatch.id))
+        .forEach(mismatch => applyHydrationMismatch(mismatch))
+    }).catch((error) => {
+      console.warn('[hints] Failed to fetch hydration mismatches', error)
+    }).finally(() => {
+      hydrationInitialSyncDone = true
+      bufferedHydrationMismatches.forEach(mismatch => applyHydrationMismatch(mismatch))
+      bufferedHydrationMismatches.length = 0
     })
   }
 
   // Lazy load: fetch from server via RPC
   if (useHintsFeature('lazyLoad')) {
     rpc.getLazyLoadHints().then((data) => {
-      lazyLoadHints.value = [
-        ...lazyLoadHints.value,
-        ...(data ?? []).filter(d => !lazyLoadHints.value.some(existing => existing.id === d.id)),
-      ]
+      ;(data ?? [])
+        .filter(entry => !lazyLoadTombstones.has(entry.id))
+        .forEach(entry => applyLazyLoadHint(entry))
+    }).catch((error) => {
+      console.warn('[hints] Failed to fetch lazy-load hints', error)
+    }).finally(() => {
+      lazyLoadInitialSyncDone = true
+      bufferedLazyLoadHints.forEach(entry => applyLazyLoadHint(entry))
+      bufferedLazyLoadHints.length = 0
     })
   }
 
   // HTML validate: fetch from server via RPC
   if (useHintsFeature('htmlValidate')) {
     rpc.getHtmlValidateReports().then((data) => {
-      htmlValidateReports.value = [
-        ...htmlValidateReports.value,
-        ...(data ?? []).filter(d => !htmlValidateReports.value.some(existing => existing.id === d.id)),
-      ]
+      ;(data ?? [])
+        .filter(report => !htmlValidateTombstones.has(report.id))
+        .forEach(report => applyHtmlValidateReport(report))
+    }).catch((error) => {
+      console.warn('[hints] Failed to fetch html-validate reports', error)
+    }).finally(() => {
+      htmlValidateInitialSyncDone = true
+      bufferedHtmlValidateReports.forEach(report => applyHtmlValidateReport(report))
+      bufferedHtmlValidateReports.length = 0
     })
   }
 })
diff --git a/client/app/composables/features.ts b/client/app/composables/features.ts
index b4f4cd2..2ceb29f 100644
--- a/client/app/composables/features.ts
+++ b/client/app/composables/features.ts
@@ -1,4 +1,5 @@
 import type { FeaturesName } from '../../../src/runtime/core/types'
+import { useDevtoolsClient } from '@nuxt/devtools-kit/iframe-client'
 
 export function useHintsConfig() {
   const hostNuxt = useHostNuxt()
@@ -7,6 +8,10 @@ export function useHintsConfig() {
 }
 
 export function useEnabledHintsFeatures(): Record<FeaturesName, boolean> {
+  const client = useDevtoolsClient().value
+  if (!client?.host?.nuxt) {
+    return { hydration: true, lazyLoad: true, webVitals: false, thirdPartyScripts: false, htmlValidate: true }
+  }
   const config = useHintsConfig()
   return Object.fromEntries<boolean>(
     Object.entries(config.features).map(([feature, flags]) => [
@@ -17,6 +22,8 @@ export function useEnabledHintsFeatures(): Record<FeaturesName, boolean> {
 }
 
 export function useHintsFeature(feature: FeaturesName): boolean {
+  const client = useDevtoolsClient().value
+  if (!client?.host?.nuxt) return true
   const config = useHintsConfig()
   return typeof config.features[feature] === 'object' ? config.features[feature].devtools !== false : Boolean(config.features[feature])
 }
diff --git a/client/app/composables/host.ts b/client/app/composables/host.ts
index 7e05066..9412098 100644
--- a/client/app/composables/host.ts
+++ b/client/app/composables/host.ts
@@ -53,8 +53,8 @@ export function useHostHydration() {
 export function useHostNuxt() {
   const client = useDevtoolsClient().value
 
-  if (!client) {
-    throw new Error('`useHostNuxt` must be used when the devtools client is connected')
+  if (!client?.host?.nuxt) {
+    throw new Error('`useHostNuxt` must be used when the devtools client is connected to a host app')
   }
 
   return client.host.nuxt
diff --git a/src/devtools-handlers.ts b/src/devtools-handlers.ts
index f3c9190..27b9665 100644
--- a/src/devtools-handlers.ts
+++ b/src/devtools-handlers.ts
@@ -1,9 +1,7 @@
 import { createRouter } from 'h3'
-import type { HintsClientFunctions } from './runtime/core/rpc-types'
 import {
   getHydrationMismatches,
   clearHydrationMismatches,
-  setHydrationNotify,
   getHandler as hydrationGet,
   postHandler as hydrationPost,
   deleteHandler as hydrationDelete,
@@ -11,7 +9,6 @@ import {
 import {
   getLazyLoadHints,
   clearLazyLoadHint,
-  setLazyLoadNotify,
   getHandler as lazyLoadGet,
   postHandler as lazyLoadPost,
   deleteHandler as lazyLoadDelete,
@@ -19,7 +16,6 @@ import {
 import {
   getHtmlValidateReports,
   clearHtmlValidateReport,
-  setHtmlValidateNotify,
   getHandler as htmlValidateGet,
   postHandler as htmlValidatePost,
   deleteHandler as htmlValidateDelete,
@@ -34,21 +30,6 @@ export {
   clearHtmlValidateReport,
 }
 
-export function setBroadcast(b: HintsClientFunctions) {
-  setHydrationNotify({
-    onMismatch: p => b.onHydrationMismatch(p),
-    onCleared: ids => b.onHydrationCleared(ids),
-  })
-  setLazyLoadNotify({
-    onReport: d => b.onLazyLoadReport(d),
-    onCleared: id => b.onLazyLoadCleared(id),
-  })
-  setHtmlValidateNotify({
-    onReport: r => b.onHtmlValidateReport(r),
-    onDeleted: id => b.onHtmlValidateDeleted(id),
-  })
-}
-
 export function createHintsRouter() {
   const router = createRouter()
 
diff --git a/src/devtools.ts b/src/devtools.ts
index c3e2e95..1eb0638 100644
--- a/src/devtools.ts
+++ b/src/devtools.ts
@@ -7,7 +7,6 @@ import type { HintsClientFunctions, HintsServerFunctions } from './runtime/core/
 import { RPC_NAMESPACE } from './runtime/core/rpc-types'
 import {
   createHintsRouter,
-  setBroadcast,
   getHydrationMismatches,
   clearHydrationMismatches,
   getLazyLoadHints,
@@ -68,6 +67,6 @@ export function setupDevToolsUI(nuxt: Nuxt, resolver: Resolver) {
       getHtmlValidateReports,
       clearHtmlValidateReport,
     })
-    setBroadcast(rpc.broadcast)
+    globalThis.__nuxtHintsRpcBroadcast = rpc.broadcast
   }, nuxt)
 }
diff --git a/src/runtime/core/rpc.ts b/src/runtime/core/rpc.ts
new file mode 100644
index 0000000..588e28c
--- /dev/null
+++ b/src/runtime/core/rpc.ts
@@ -0,0 +1,5 @@
+import type { HintsClientFunctions } from './rpc-types'
+
+export function getRPC(): HintsClientFunctions | undefined {
+  return globalThis.__nuxtHintsRpcBroadcast
+}
\ No newline at end of file
diff --git a/src/runtime/core/server/rpc-bridge.ts b/src/runtime/core/server/rpc-bridge.ts
deleted file mode 100644
index e00f390..0000000
--- a/src/runtime/core/server/rpc-bridge.ts
+++ /dev/null
@@ -1,32 +0,0 @@
-import type { NitroApp } from 'nitropack/types'
-import type { HintsClientFunctions } from '../rpc-types'
-
-function getRpcBroadcast(): HintsClientFunctions | undefined {
-  return globalThis.__nuxtHintsRpcBroadcast
-}
-
-export default function (nitroApp: NitroApp) {
-  nitroApp.hooks.hook('hints:hydration:mismatch', (mismatch) => {
-    getRpcBroadcast()?.onHydrationMismatch(mismatch)
-  })
-
-  nitroApp.hooks.hook('hints:hydration:cleared', (payload) => {
-    getRpcBroadcast()?.onHydrationCleared(payload.id)
-  })
-
-  nitroApp.hooks.hook('hints:lazy-load:report', (data) => {
-    getRpcBroadcast()?.onLazyLoadReport(data)
-  })
-
-  nitroApp.hooks.hook('hints:lazy-load:cleared', (payload) => {
-    getRpcBroadcast()?.onLazyLoadCleared(payload.id)
-  })
-
-  nitroApp.hooks.hook('hints:html-validate:report', (report) => {
-    getRpcBroadcast()?.onHtmlValidateReport(report)
-  })
-
-  nitroApp.hooks.hook('hints:html-validate:deleted', (id) => {
-    getRpcBroadcast()?.onHtmlValidateDeleted(id)
-  })
-}
diff --git a/src/runtime/html-validate/api-handlers.ts b/src/runtime/html-validate/api-handlers.ts
index 786d7ea..4c68e8e 100644
--- a/src/runtime/html-validate/api-handlers.ts
+++ b/src/runtime/html-validate/api-handlers.ts
@@ -1,19 +1,9 @@
 import { createError, defineEventHandler, readBody, setResponseStatus } from 'h3'
 import type { HtmlValidateReport } from './types'
+import { getRPC } from '../core/rpc'
 
 export const htmlValidateReports: HtmlValidateReport[] = []
 
-let onReport: ((report: HtmlValidateReport) => void) | undefined
-let onDeleted: ((id: string) => void) | undefined
-
-export function setHtmlValidateNotify(callbacks: {
-  onReport: (report: HtmlValidateReport) => void
-  onDeleted: (id: string) => void
-}) {
-  onReport = callbacks.onReport
-  onDeleted = callbacks.onDeleted
-}
-
 export function getHtmlValidateReports() {
   return htmlValidateReports
 }
@@ -23,7 +13,7 @@ export function clearHtmlValidateReport(id: string) {
   if (index !== -1) {
     htmlValidateReports.splice(index, 1)
   }
-  onDeleted?.(id)
+  getRPC()?.onHtmlValidateDeleted(id)
 }
 
 export const getHandler = defineEventHandler(() => getHtmlValidateReports())
@@ -35,7 +25,7 @@ export const postHandler = defineEventHandler(async (event) => {
   }
   if (!htmlValidateReports.some(r => r.id === body.id)) {
     htmlValidateReports.push(body)
-    onReport?.(body)
+    getRPC()?.onHtmlValidateReport(body)
   }
   setResponseStatus(event, 201)
 })
diff --git a/src/runtime/hydration/handlers.ts b/src/runtime/hydration/handlers.ts
index ae64156..4ce9ecb 100644
--- a/src/runtime/hydration/handlers.ts
+++ b/src/runtime/hydration/handlers.ts
@@ -1,19 +1,9 @@
 import { createError, defineEventHandler, readBody, setResponseStatus } from 'h3'
 import type { HydrationMismatchPayload } from './types'
+import { getRPC } from '../core/rpc'
 
 export const hydrationMismatches: HydrationMismatchPayload[] = []
 
-let onMismatch: ((payload: HydrationMismatchPayload) => void) | undefined
-let onCleared: ((ids: string[]) => void) | undefined
-
-export function setHydrationNotify(callbacks: {
-  onMismatch: (payload: HydrationMismatchPayload) => void
-  onCleared: (ids: string[]) => void
-}) {
-  onMismatch = callbacks.onMismatch
-  onCleared = callbacks.onCleared
-}
-
 export function getHydrationMismatches() {
   return { mismatches: hydrationMismatches }
 }
@@ -25,7 +15,7 @@ export function clearHydrationMismatches(ids: string[]) {
       hydrationMismatches.splice(index, 1)
     }
   }
-  onCleared?.(ids)
+  getRPC()?.onHydrationCleared(ids)
 }
 
 export const getHandler = defineEventHandler(() => getHydrationMismatches())
@@ -42,9 +32,12 @@ export const postHandler = defineEventHandler(async (event) => {
   }
   hydrationMismatches.push(payload)
   if (hydrationMismatches.length > 20) {
-    hydrationMismatches.shift()
+    const evicted = hydrationMismatches.shift()
+    if (evicted) {
+      getRPC()?.onHydrationCleared([evicted.id])
+    }
   }
-  onMismatch?.(payload)
+  getRPC()?.onHydrationMismatch(payload)
   setResponseStatus(event, 201)
   return payload
 })
@@ -61,7 +54,8 @@ export const deleteHandler = defineEventHandler(async (event) => {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function assertPayload(body: any): asserts body is Omit<HydrationMismatchPayload, 'id'> {
   if (
-    typeof body !== 'object'
+    !body
+    || typeof body !== 'object'
     || (body.htmlPreHydration !== undefined && typeof body.htmlPreHydration !== 'string')
     || (body.htmlPostHydration !== undefined && typeof body.htmlPostHydration !== 'string')
     || typeof body.componentName !== 'string'
diff --git a/src/runtime/lazy-load/handlers.ts b/src/runtime/lazy-load/handlers.ts
index 68dfe97..aed46a3 100644
--- a/src/runtime/lazy-load/handlers.ts
+++ b/src/runtime/lazy-load/handlers.ts
@@ -2,30 +2,19 @@ import { createError, defineEventHandler, readBody, setResponseStatus } from 'h3
 import type { ComponentLazyLoadData } from './schema'
 import { ComponentLazyLoadDataSchema } from './schema'
 import { parse, ValiError } from 'valibot'
+import { getRPC } from '../core/rpc'
 
 export const lazyLoadData: ComponentLazyLoadData[] = []
 
-let onReport: ((data: ComponentLazyLoadData) => void) | undefined
-let onCleared: ((id: string) => void) | undefined
-
-export function setLazyLoadNotify(callbacks: {
-  onReport: (data: ComponentLazyLoadData) => void
-  onCleared: (id: string) => void
-}) {
-  onReport = callbacks.onReport
-  onCleared = callbacks.onCleared
-}
-
 export function getLazyLoadHints() {
   return lazyLoadData
 }
 
 export function clearLazyLoadHint(id: string) {
-  const index = lazyLoadData.findIndex(item => item.id === id)
-  if (index !== -1) {
-    lazyLoadData.splice(index, 1)
-  }
-  onCleared?.(id)
+  const next = lazyLoadData.filter(item => item.id !== id)
+  lazyLoadData.length = 0
+  lazyLoadData.push(...next)
+  getRPC()?.onLazyLoadCleared(id)
 }
 
 export const getHandler = defineEventHandler(() => getLazyLoadHints())
@@ -43,8 +32,11 @@ export const postHandler = defineEventHandler(async (event) => {
     }
     throw error
   }
-  lazyLoadData.push(parsed)
-  onReport?.(parsed)
+  const index = lazyLoadData.findIndex(item => item.id === parsed.id)
+  if (index === -1) {
+    lazyLoadData.push(parsed)
+    getRPC()?.onLazyLoadReport(parsed)
+  }
   setResponseStatus(event, 201)
 })
 
@@ -53,11 +45,13 @@ export const deleteHandler = defineEventHandler(async (event) => {
   if (!id) {
     throw createError({ statusCode: 400, message: 'ID is required' })
   }
-  const index = lazyLoadData.findIndex(item => item.id === id)
-  if (index === -1) {
+  const hasEntry = lazyLoadData.some(item => item.id === id)
+  if (!hasEntry) {
     throw createError({ statusCode: 404, message: 'Entry not found' })
   }
-  lazyLoadData.splice(index, 1)
-  onCleared?.(id)
+  const next = lazyLoadData.filter(item => item.id !== id)
+  lazyLoadData.length = 0
+  lazyLoadData.push(...next)
+  getRPC()?.onLazyLoadCleared(id)
   setResponseStatus(event, 204)
 })
diff --git a/src/runtime/types.d.ts b/src/runtime/types.d.ts
index c44d8a9..c0ffda1 100644
--- a/src/runtime/types.d.ts
+++ b/src/runtime/types.d.ts
@@ -3,8 +3,11 @@ import type { LCPMetricWithAttribution, INPMetricWithAttribution, CLSMetricWithA
 import type { LocalHydrationMismatch } from './hydration/types'
 import type { DirectImportInfo, LazyHydrationState } from './lazy-load/composables'
 import type { Features } from './core/types'
+import type { HintsClientFunctions } from './core/rpc-types'
 
 declare global {
+  var __nuxtHintsRpcBroadcast: HintsClientFunctions | undefined
+
   interface Window {
     __hints_TPC_start_time: number
     __hints_TPC_saveTime: (script: HTMLScriptElement, startTime?: number) => void

From 4976be992f21f6aef03c1a4af20700867d446cf0 Mon Sep 17 00:00:00 2001
From: Julien Huang <julien.h.dev@gmail.com>
Date: Thu, 9 Apr 2026 23:15:55 +0200
Subject: [PATCH 4/5] refactor: use nitro hook

---
 src/runtime/core/rpc.ts                      |   2 +-
 src/runtime/html-validate/api-handlers.ts    |  16 ++-
 src/runtime/html-validate/nitro.plugin.ts    |  15 ++-
 src/runtime/nitro.d.ts                       |   7 +
 test/unit/html-validate/nitro-plugin.test.ts | 135 +++++++++++++++++++
 5 files changed, 163 insertions(+), 12 deletions(-)
 create mode 100644 src/runtime/nitro.d.ts
 create mode 100644 test/unit/html-validate/nitro-plugin.test.ts

diff --git a/src/runtime/core/rpc.ts b/src/runtime/core/rpc.ts
index 588e28c..15edabe 100644
--- a/src/runtime/core/rpc.ts
+++ b/src/runtime/core/rpc.ts
@@ -2,4 +2,4 @@ import type { HintsClientFunctions } from './rpc-types'
 
 export function getRPC(): HintsClientFunctions | undefined {
   return globalThis.__nuxtHintsRpcBroadcast
-}
\ No newline at end of file
+}
diff --git a/src/runtime/html-validate/api-handlers.ts b/src/runtime/html-validate/api-handlers.ts
index 4c68e8e..37986a5 100644
--- a/src/runtime/html-validate/api-handlers.ts
+++ b/src/runtime/html-validate/api-handlers.ts
@@ -4,6 +4,17 @@ import { getRPC } from '../core/rpc'
 
 export const htmlValidateReports: HtmlValidateReport[] = []
 
+export function storeHtmlValidateReport(report: HtmlValidateReport) {
+  if (htmlValidateReports.some(existing => existing.id === report.id)) {
+    return false
+  }
+
+  htmlValidateReports.push(report)
+  getRPC()?.onHtmlValidateReport(report)
+
+  return true
+}
+
 export function getHtmlValidateReports() {
   return htmlValidateReports
 }
@@ -23,10 +34,7 @@ export const postHandler = defineEventHandler(async (event) => {
   if (!body || typeof body.id !== 'string') {
     throw createError({ statusCode: 400, statusMessage: 'Invalid payload' })
   }
-  if (!htmlValidateReports.some(r => r.id === body.id)) {
-    htmlValidateReports.push(body)
-    getRPC()?.onHtmlValidateReport(body)
-  }
+  storeHtmlValidateReport(body)
   setResponseStatus(event, 201)
 })
 
diff --git a/src/runtime/html-validate/nitro.plugin.ts b/src/runtime/html-validate/nitro.plugin.ts
index 70c8777..bb391be 100644
--- a/src/runtime/html-validate/nitro.plugin.ts
+++ b/src/runtime/html-validate/nitro.plugin.ts
@@ -1,6 +1,7 @@
 import type { NitroAppPlugin } from 'nitropack/types'
 import { HtmlValidate, type ConfigData, type RuleConfig } from 'html-validate'
 import { addBeforeBodyEndTag } from './utils'
+import { storeHtmlValidateReport } from './api-handlers'
 import { randomUUID } from 'crypto'
 import { stringify } from 'devalue'
 import type { HtmlValidateReport } from './types'
@@ -8,7 +9,8 @@ import { format } from 'prettier/standalone'
 import html from 'prettier/parser-html'
 import { getFeatureOptions } from '../core/features'
 import { defu } from 'defu'
-import { getRequestURL } from 'h3'
+
+const HTML_VALIDATE_REPORT_HOOK = 'hints:html-validate:report' as const
 
 const DEFAULT_EXTENDS = [
   'html-validate:standard',
@@ -37,6 +39,8 @@ export default <NitroAppPlugin> function (nitro) {
 
   const validator = new HtmlValidate(opts)
 
+  nitro.hooks.hook(HTML_VALIDATE_REPORT_HOOK, storeHtmlValidateReport)
+
   nitro.hooks.hook('render:response', async (response, { event }) => {
     if (typeof response.body === 'string' && (response.headers?.['Content-Type'] || response.headers?.['content-type'])?.includes('html')) {
       const formattedBody = await format(response.body, { plugins: [html], parser: 'html' })
@@ -54,12 +58,9 @@ export default <NitroAppPlugin> function (nitro) {
           response.body,
           `<script id="hints-html-validate" type="application/json">${stringify(data)}</script>`,
         )
-        const origin = getRequestURL(event).origin
-        globalThis.fetch(`${origin}/__nuxt_hints/html-validate`, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify(data),
-        }).catch(() => {})
+        nitro.hooks.callHook(HTML_VALIDATE_REPORT_HOOK, data).catch((error) => {
+          nitro.captureError(error instanceof Error ? error : new Error(String(error)), { event })
+        })
       }
     }
   })
diff --git a/src/runtime/nitro.d.ts b/src/runtime/nitro.d.ts
new file mode 100644
index 0000000..65b71ab
--- /dev/null
+++ b/src/runtime/nitro.d.ts
@@ -0,0 +1,7 @@
+import type { HtmlValidateReport } from './html-validate/types'
+
+declare module 'nitropack/types' {
+  interface NitroRuntimeHooks {
+    'hints:html-validate:report': (report: HtmlValidateReport) => void
+  }
+}
\ No newline at end of file
diff --git a/test/unit/html-validate/nitro-plugin.test.ts b/test/unit/html-validate/nitro-plugin.test.ts
new file mode 100644
index 0000000..b5f700d
--- /dev/null
+++ b/test/unit/html-validate/nitro-plugin.test.ts
@@ -0,0 +1,135 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import plugin from '../../../src/runtime/html-validate/nitro.plugin'
+import { htmlValidateReports } from '../../../src/runtime/html-validate/api-handlers'
+
+const reportResults = [
+  {
+    filePath: '/demo',
+    messages: [
+      {
+        ruleId: 'no-unknown-elements',
+        message: 'Unknown element',
+        line: 1,
+        column: 1,
+        offset: 0,
+        size: 1,
+        selector: 'body',
+      },
+    ],
+    errorCount: 1,
+    warningCount: 0,
+    source: '<html><body></body></html>',
+  },
+]
+
+const rpcMock = vi.hoisted(() => ({
+  onHtmlValidateReport: vi.fn(),
+  onHtmlValidateDeleted: vi.fn(),
+}))
+
+vi.mock('../../../src/runtime/core/rpc', () => ({
+  getRPC: () => rpcMock,
+}))
+
+vi.mock('crypto', () => ({
+  randomUUID: () => 'report-1',
+}))
+
+vi.mock('devalue', () => ({
+  stringify: () => '{"id":"report-1"}',
+}))
+
+vi.mock('prettier/standalone', () => ({
+  format: vi.fn(async (value: string) => value),
+}))
+
+vi.mock('prettier/parser-html', () => ({
+  default: {},
+}))
+
+vi.mock('html-validate', () => ({
+  HtmlValidate: class {
+    async validateString() {
+      return {
+        errorCount: 1,
+        results: reportResults,
+      }
+    }
+  },
+}))
+
+vi.mock('../../../src/runtime/core/features', () => ({
+  getFeatureOptions: () => undefined,
+}))
+
+vi.mock('../../../src/runtime/html-validate/utils', () => ({
+  addBeforeBodyEndTag: (body: string, tag: string) => body.replace('</body>', `${tag}</body>`),
+}))
+
+describe('html-validate nitro plugin', () => {
+  beforeEach(() => {
+    htmlValidateReports.length = 0
+    rpcMock.onHtmlValidateReport.mockClear()
+    rpcMock.onHtmlValidateDeleted.mockClear()
+    vi.stubGlobal('fetch', vi.fn())
+  })
+
+  it('dispatches reports through a nitro hook without a loopback fetch', async () => {
+    const hookHandlers = new Map<string, Function>()
+    const hook = vi.fn((name: string, handler: Function) => {
+      hookHandlers.set(name, handler)
+    })
+    const callHook = vi.fn(async (name: string, payload: unknown) => {
+      const handler = hookHandlers.get(name)
+      await handler?.(payload)
+    })
+    const captureError = vi.fn()
+
+    plugin({
+      captureError,
+      hooks: {
+        hook,
+        callHook,
+      },
+    } as never)
+
+    const renderResponse = hookHandlers.get('render:response')
+    const reportHook = hookHandlers.get('hints:html-validate:report')
+
+    expect(renderResponse).toBeTypeOf('function')
+    expect(reportHook).toBeTypeOf('function')
+
+    const event = {
+      path: '/demo',
+      context: {},
+    }
+    const response = {
+      body: '<html><body></body></html>',
+      headers: {
+        'content-type': 'text/html',
+      },
+    }
+
+    await renderResponse?.(response, { event })
+
+    expect(response.body).toContain('hints-html-validate')
+    expect(globalThis.fetch).not.toHaveBeenCalled()
+    expect(htmlValidateReports).toHaveLength(1)
+    expect(htmlValidateReports[0]).toMatchObject({
+      id: 'report-1',
+      path: '/demo',
+      html: '<html><body></body></html>',
+      results: reportResults,
+    })
+    expect(callHook).toHaveBeenCalledTimes(1)
+    expect(callHook).toHaveBeenCalledWith('hints:html-validate:report', expect.objectContaining({ id: 'report-1' }))
+    expect(rpcMock.onHtmlValidateReport).toHaveBeenCalledTimes(1)
+    expect(rpcMock.onHtmlValidateReport).toHaveBeenCalledWith(expect.objectContaining({ id: 'report-1' }))
+    expect(captureError).not.toHaveBeenCalled()
+
+    await reportHook?.(htmlValidateReports[0])
+
+    expect(htmlValidateReports).toHaveLength(1)
+    expect(rpcMock.onHtmlValidateReport).toHaveBeenCalledTimes(1)
+  })
+})

From 65a0be9cc7151d36b8d61e4832bdb03c1c6a285f Mon Sep 17 00:00:00 2001
From: Julien Huang <julien.h.dev@gmail.com>
Date: Thu, 9 Apr 2026 23:26:10 +0200
Subject: [PATCH 5/5] lint

---
 src/runtime/nitro.d.ts                       | 2 +-
 test/unit/html-validate/nitro-plugin.test.ts | 2 ++
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/runtime/nitro.d.ts b/src/runtime/nitro.d.ts
index 65b71ab..fa1b760 100644
--- a/src/runtime/nitro.d.ts
+++ b/src/runtime/nitro.d.ts
@@ -4,4 +4,4 @@ declare module 'nitropack/types' {
   interface NitroRuntimeHooks {
     'hints:html-validate:report': (report: HtmlValidateReport) => void
   }
-}
\ No newline at end of file
+}
diff --git a/test/unit/html-validate/nitro-plugin.test.ts b/test/unit/html-validate/nitro-plugin.test.ts
index b5f700d..4d86b82 100644
--- a/test/unit/html-validate/nitro-plugin.test.ts
+++ b/test/unit/html-validate/nitro-plugin.test.ts
@@ -75,7 +75,9 @@ describe('html-validate nitro plugin', () => {
   })
 
   it('dispatches reports through a nitro hook without a loopback fetch', async () => {
+    // eslint-disable-next-line  @typescript-eslint/no-unsafe-function-type
     const hookHandlers = new Map<string, Function>()
+    // eslint-disable-next-line  @typescript-eslint/no-unsafe-function-type
     const hook = vi.fn((name: string, handler: Function) => {
       hookHandlers.set(name, handler)
     })