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

---
 client/app/app.vue                            | 81 ++++++++++++++++++-
 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.ts                               |  9 ++-
 src/module.ts                                 | 10 +--
 src/runtime/core/rpc-types.ts                 | 20 +++++
 src/runtime/core/server/rpc-bridge.ts         | 32 ++++++++
 src/runtime/core/server/sse.ts                | 23 ------
 src/runtime/core/server/types.ts              |  8 +-
 .../handlers/nitro-handlers.plugin.ts         | 22 -----
 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                        |  3 -
 test/unit/core/rpc-bridge.test.ts             | 69 ++++++++++++++++
 test/unit/core/sse.test.ts                    | 53 ------------
 20 files changed, 213 insertions(+), 344 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/runtime/core/rpc-types.ts
 create mode 100644 src/runtime/core/server/rpc-bridge.ts
 delete mode 100644 src/runtime/core/server/sse.ts
 create mode 100644 test/unit/core/rpc-bridge.test.ts
 delete mode 100644 test/unit/core/sse.test.ts

diff --git a/client/app/app.vue b/client/app/app.vue
index f60578f..45c0118 100644
--- a/client/app/app.vue
+++ b/client/app/app.vue
@@ -1,7 +1,86 @@
 <script setup lang="ts">
-import { useDevtoolsClient } from '@nuxt/devtools-kit/iframe-client'
+import { useDevtoolsClient, onDevtoolsClientConnected } from '@nuxt/devtools-kit/iframe-client'
+import type { HintsServerFunctions, HintsClientFunctions } from '../../src/runtime/core/rpc-types'
+import { RPC_NAMESPACE } from '../../src/runtime/core/rpc-types'
+import type { HydrationMismatchPayload, HydrationMismatchResponse, 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'
+import { HYDRATION_ROUTE, LAZY_LOAD_ROUTE, HTML_VALIDATE_ROUTE } from './utils/routes'
 
 const client = useDevtoolsClient()
+
+const hydrationMismatches = ref<(HydrationMismatchPayload | LocalHydrationMismatch)[]>([])
+const lazyLoadHints = ref<ComponentLazyLoadData[]>([])
+const htmlValidateReports = ref<HtmlValidateReport[]>([])
+
+const nuxtApp = useNuxtApp()
+
+onDevtoolsClientConnected((client) => {
+  // Hydration: seed from host payload and fetch from server
+  if (useHintsFeature('hydration')) {
+    hydrationMismatches.value = [...client.host.nuxt.payload.__hints.hydration]
+    $fetch<HydrationMismatchResponse>(new URL(HYDRATION_ROUTE, window.location.origin).href).then((data) => {
+      hydrationMismatches.value = [
+        ...hydrationMismatches.value,
+        ...data.mismatches.filter(m => !hydrationMismatches.value.some(existing => existing.id === m.id)),
+      ]
+    })
+  }
+
+  // Lazy load: fetch from server
+  if (useHintsFeature('lazyLoad')) {
+    $fetch<ComponentLazyLoadData[]>(new URL(LAZY_LOAD_ROUTE, window.location.origin).href).then((data) => {
+      lazyLoadHints.value = data ?? []
+    })
+  }
+
+  // HTML validate: fetch from server
+  if (useHintsFeature('htmlValidate')) {
+    $fetch<HtmlValidateReport[]>(new URL(HTML_VALIDATE_ROUTE, window.location.origin).href).then((data) => {
+      htmlValidateReports.value = data ?? []
+    })
+  }
+
+  // Register client RPC functions for real-time push notifications
+  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)
+    },
+  })
+
+  nuxtApp.provide('hydrationMismatches', hydrationMismatches)
+  nuxtApp.provide('lazyLoadHints', lazyLoadHints)
+  nuxtApp.provide('htmlValidateReports', htmlValidateReports)
+})
 </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.ts b/src/devtools.ts
index ecb44da..9b44843 100644
--- a/src/devtools.ts
+++ b/src/devtools.ts
@@ -1,8 +1,10 @@
-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'
 
 const DEVTOOLS_UI_ROUTE = '/__nuxt-hints'
 const DEVTOOLS_UI_LOCAL_PORT = 3300
@@ -41,4 +43,9 @@ export function setupDevToolsUI(nuxt: Nuxt, resolver: Resolver) {
       src: DEVTOOLS_UI_ROUTE,
     },
   }, nuxt)
+
+  onDevToolsInitialized(() => {
+    const rpc = extendServerRpc<HintsClientFunctions, HintsServerFunctions>(RPC_NAMESPACE, {})
+    globalThis.__nuxtHintsRpcBroadcast = rpc.broadcast
+  }, nuxt)
 }
diff --git a/src/module.ts b/src/module.ts
index caf94c7..da18847 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'))
@@ -112,6 +105,7 @@ export default defineNuxtModule<ModuleOptions>({
     if (options.devtools) {
       setupDevToolsUI(nuxt, resolver)
       addPlugin(resolver.resolve('./runtime/core/plugins/vue-tracer-state.client'))
+      addServerPlugin(resolver.resolve('./runtime/core/server/rpc-bridge'))
     }
 
     nuxt.options.build.transpile.push(moduleName)
diff --git a/src/runtime/core/rpc-types.ts b/src/runtime/core/rpc-types.ts
new file mode 100644
index 0000000..0309d9b
--- /dev/null
+++ b/src/runtime/core/rpc-types.ts
@@ -0,0 +1,20 @@
+import type { HydrationMismatchPayload } 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 {}
+
+export const RPC_NAMESPACE = 'nuxt-hints'
+
+declare global {
+  var __nuxtHintsRpcBroadcast: HintsClientFunctions | undefined
+}
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/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/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/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..0e75f12 100644
--- a/src/runtime/types.d.ts
+++ b/src/runtime/types.d.ts
@@ -66,9 +66,6 @@ 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
diff --git a/test/unit/core/rpc-bridge.test.ts b/test/unit/core/rpc-bridge.test.ts
new file mode 100644
index 0000000..144e20f
--- /dev/null
+++ b/test/unit/core/rpc-bridge.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
+import { createHooks } from 'hookable'
+import type { NitroRuntimeHooks, NitroApp } from 'nitropack/types'
+import type { HintsClientFunctions } from '../../../src/runtime/core/rpc-types'
+import rpcBridge from '../../../src/runtime/core/server/rpc-bridge'
+
+describe('rpcBridge', () => {
+  let hooks: ReturnType<typeof createHooks<NitroRuntimeHooks>>
+  let mockBroadcast: HintsClientFunctions
+
+  beforeEach(() => {
+    hooks = createHooks()
+    mockBroadcast = {
+      onHydrationMismatch: vi.fn(),
+      onHydrationCleared: vi.fn(),
+      onLazyLoadReport: vi.fn(),
+      onLazyLoadCleared: vi.fn(),
+      onHtmlValidateReport: vi.fn(),
+      onHtmlValidateDeleted: vi.fn(),
+    }
+    globalThis.__nuxtHintsRpcBroadcast = mockBroadcast
+
+    rpcBridge({ hooks } as unknown as NitroApp)
+  })
+
+  afterEach(() => {
+    globalThis.__nuxtHintsRpcBroadcast = undefined
+  })
+
+  it('should broadcast hydration mismatch via RPC', async () => {
+    const mismatch = { id: '1', componentName: 'Test', fileLocation: '/test.vue', htmlPreHydration: '<div>', htmlPostHydration: '<span>' }
+    await hooks.callHook('hints:hydration:mismatch', mismatch)
+    expect(mockBroadcast.onHydrationMismatch).toHaveBeenCalledWith(mismatch)
+  })
+
+  it('should broadcast hydration cleared via RPC', async () => {
+    await hooks.callHook('hints:hydration:cleared', { id: ['1', '2'] })
+    expect(mockBroadcast.onHydrationCleared).toHaveBeenCalledWith(['1', '2'])
+  })
+
+  it('should broadcast lazy-load report via RPC', async () => {
+    const data = { id: '1', route: '/', state: { pageLoaded: true, hasReported: true, directImports: [] } }
+    await hooks.callHook('hints:lazy-load:report', data)
+    expect(mockBroadcast.onLazyLoadReport).toHaveBeenCalledWith(data)
+  })
+
+  it('should broadcast lazy-load cleared via RPC', async () => {
+    await hooks.callHook('hints:lazy-load:cleared', { id: 'test-id' })
+    expect(mockBroadcast.onLazyLoadCleared).toHaveBeenCalledWith('test-id')
+  })
+
+  it('should broadcast html-validate report via RPC', async () => {
+    const report = { id: '1', path: '/test', html: '<html></html>', results: [] }
+    await hooks.callHook('hints:html-validate:report', report)
+    expect(mockBroadcast.onHtmlValidateReport).toHaveBeenCalledWith(report)
+  })
+
+  it('should broadcast html-validate deleted via RPC', async () => {
+    await hooks.callHook('hints:html-validate:deleted', 'test-id')
+    expect(mockBroadcast.onHtmlValidateDeleted).toHaveBeenCalledWith('test-id')
+  })
+
+  it('should not throw when RPC broadcast is not available', async () => {
+    globalThis.__nuxtHintsRpcBroadcast = undefined
+    expect(() =>
+      hooks.callHook('hints:hydration:mismatch', { id: '1', componentName: 'Test', fileLocation: '/test.vue', htmlPreHydration: '', htmlPostHydration: '' }),
+    ).not.toThrow()
+  })
+})
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 e60ebaa71108d77799c807fe24a62a531c4cd904 Mon Sep 17 00:00:00 2001
From: Julien Huang <julien.h.dev@gmail.com>
Date: Sat, 4 Apr 2026 00:40:09 +0200
Subject: [PATCH 2/4] fix: types

---
 client/app/app.vue            | 4 ++--
 src/devtools.ts               | 4 ++--
 src/runtime/core/rpc-types.ts | 2 --
 3 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/client/app/app.vue b/client/app/app.vue
index 45c0118..6a38684 100644
--- a/client/app/app.vue
+++ b/client/app/app.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { useDevtoolsClient, onDevtoolsClientConnected } from '@nuxt/devtools-kit/iframe-client'
-import type { HintsServerFunctions, HintsClientFunctions } from '../../src/runtime/core/rpc-types'
+import type { HintsClientFunctions } from '../../src/runtime/core/rpc-types'
 import { RPC_NAMESPACE } from '../../src/runtime/core/rpc-types'
 import type { HydrationMismatchPayload, HydrationMismatchResponse, LocalHydrationMismatch } from '../../src/runtime/hydration/types'
 import type { ComponentLazyLoadData } from '../../src/runtime/lazy-load/schema'
@@ -44,7 +44,7 @@ onDevtoolsClientConnected((client) => {
   }
 
   // Register client RPC functions for real-time push notifications
-  client.devtools.extendClientRpc<HintsServerFunctions, HintsClientFunctions>(RPC_NAMESPACE, {
+  client.devtools.extendClientRpc<undefined, HintsClientFunctions>(RPC_NAMESPACE, {
     onHydrationMismatch(mismatch: HydrationMismatchPayload) {
       if (!hydrationMismatches.value.some(existing => existing.id === mismatch.id)) {
         hydrationMismatches.value.push(mismatch)
diff --git a/src/devtools.ts b/src/devtools.ts
index 9b44843..d29db9e 100644
--- a/src/devtools.ts
+++ b/src/devtools.ts
@@ -3,7 +3,7 @@ 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 type { HintsClientFunctions } from './runtime/core/rpc-types'
 import { RPC_NAMESPACE } from './runtime/core/rpc-types'
 
 const DEVTOOLS_UI_ROUTE = '/__nuxt-hints'
@@ -45,7 +45,7 @@ export function setupDevToolsUI(nuxt: Nuxt, resolver: Resolver) {
   }, nuxt)
 
   onDevToolsInitialized(() => {
-    const rpc = extendServerRpc<HintsClientFunctions, HintsServerFunctions>(RPC_NAMESPACE, {})
+    const rpc = extendServerRpc<HintsClientFunctions>(RPC_NAMESPACE, {})
     globalThis.__nuxtHintsRpcBroadcast = rpc.broadcast
   }, nuxt)
 }
diff --git a/src/runtime/core/rpc-types.ts b/src/runtime/core/rpc-types.ts
index 0309d9b..863830a 100644
--- a/src/runtime/core/rpc-types.ts
+++ b/src/runtime/core/rpc-types.ts
@@ -11,8 +11,6 @@ export interface HintsClientFunctions {
   onHtmlValidateDeleted: (id: string) => void
 }
 
-export interface HintsServerFunctions {}
-
 export const RPC_NAMESPACE = 'nuxt-hints'
 
 declare global {

From 0e19e711ff05f5d4de45f47c598c97be5a1612ed Mon Sep 17 00:00:00 2001
From: Julien Huang <julien.h.dev@gmail.com>
Date: Sat, 4 Apr 2026 14:39:20 +0200
Subject: [PATCH 3/4] fix: review

---
 client/app/app.vue | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/client/app/app.vue b/client/app/app.vue
index 6a38684..b65917a 100644
--- a/client/app/app.vue
+++ b/client/app/app.vue
@@ -16,6 +16,9 @@ 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) => {
   // Hydration: seed from host payload and fetch from server
@@ -32,14 +35,20 @@ onDevtoolsClientConnected((client) => {
   // Lazy load: fetch from server
   if (useHintsFeature('lazyLoad')) {
     $fetch<ComponentLazyLoadData[]>(new URL(LAZY_LOAD_ROUTE, window.location.origin).href).then((data) => {
-      lazyLoadHints.value = data ?? []
+      lazyLoadHints.value = [
+        ...lazyLoadHints.value,
+        ...(data ?? []).filter(d => !lazyLoadHints.value.some(existing => existing.id === d.id)),
+      ]
     })
   }
 
   // HTML validate: fetch from server
   if (useHintsFeature('htmlValidate')) {
     $fetch<HtmlValidateReport[]>(new URL(HTML_VALIDATE_ROUTE, window.location.origin).href).then((data) => {
-      htmlValidateReports.value = data ?? []
+      htmlValidateReports.value = [
+        ...htmlValidateReports.value,
+        ...(data ?? []).filter(d => !htmlValidateReports.value.some(existing => existing.id === d.id)),
+      ]
     })
   }
 
@@ -76,10 +85,6 @@ onDevtoolsClientConnected((client) => {
       htmlValidateReports.value = htmlValidateReports.value.filter(report => report.id !== id)
     },
   })
-
-  nuxtApp.provide('hydrationMismatches', hydrationMismatches)
-  nuxtApp.provide('lazyLoadHints', lazyLoadHints)
-  nuxtApp.provide('htmlValidateReports', htmlValidateReports)
 })
 </script>
 

From 0c8eb45ad1de28ba615b1b9b2f8f5ccc647beabd Mon Sep 17 00:00:00 2001
From: Julien Huang <julien.h.dev@gmail.com>
Date: Sat, 4 Apr 2026 14:40:58 +0200
Subject: [PATCH 4/4] fix: feedbacks

---
 client/app/app.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/client/app/app.vue b/client/app/app.vue
index b65917a..c18ec1e 100644
--- a/client/app/app.vue
+++ b/client/app/app.vue
@@ -53,7 +53,7 @@ onDevtoolsClientConnected((client) => {
   }
 
   // Register client RPC functions for real-time push notifications
-  client.devtools.extendClientRpc<undefined, HintsClientFunctions>(RPC_NAMESPACE, {
+  client.devtools.extendClientRpc<Record<string, unknown>, HintsClientFunctions>(RPC_NAMESPACE, {
     onHydrationMismatch(mismatch: HydrationMismatchPayload) {
       if (!hydrationMismatches.value.some(existing => existing.id === mismatch.id)) {
         hydrationMismatches.value.push(mismatch)