@pyreon/runtime-dom 0.14.0 → 0.15.0

package/src/hydration-debug.ts

@@ -1,18 +1,42 @@
 /**
- * Hydration mismatch warnings.
+ * Hydration mismatch warnings + telemetry hook.
  *
- * Enabled automatically in development (NODE_ENV !== "production").
- * Can be toggled manually for testing or verbose production debugging.
+ * Two complementary surfaces:
  *
- * @example
+ * 1. **Dev-mode console.warn** — enabled automatically when
+ *    `NODE_ENV !== "production"` (and silent otherwise, matching React /
+ *    Vue / Solid). Toggle manually with `enableHydrationWarnings()` /
+ *    `disableHydrationWarnings()` if you need verbose production debugging.
+ *
+ * 2. **Telemetry callback** — register a handler with
+ *    `onHydrationMismatch(handler)` to forward every mismatch into your
+ *    error-tracking pipeline (Sentry, Datadog, etc.). Fires on EVERY
+ *    mismatch, in development AND production, regardless of the warn
+ *    toggle. Returns an unregister function.
+ *
+ * The dev warn and the telemetry callback are independent: a production
+ * deployment can install Sentry forwarding via `onHydrationMismatch`
+ * WITHOUT enabling the noisy console output.
+ *
+ * @example — dev console
  * import { enableHydrationWarnings } from "@pyreon/runtime-dom"
  * enableHydrationWarnings()
+ *
+ * @example — production telemetry
+ * import { onHydrationMismatch } from "@pyreon/runtime-dom"
+ * import * as Sentry from "@sentry/browser"
+ *
+ * onHydrationMismatch(ctx => {
+ *   Sentry.captureMessage(`Hydration mismatch (${ctx.type})`, {
+ *     extra: { expected: ctx.expected, actual: ctx.actual, path: ctx.path },
+ *     level: 'warning',
+ *   })
+ * })
  */
 
 // Dev-mode gate: see `pyreon/no-process-dev-gate` lint rule for why this
 // uses `import.meta.env.DEV` instead of `typeof process !== 'undefined'`.
-// @ts-ignore — `import.meta.env.DEV` is provided by Vite/Rolldown at build time
-const __DEV__ = import.meta.env?.DEV === true
+const __DEV__ = process.env.NODE_ENV !== 'production'
 
 let _enabled = __DEV__
 
@@ -24,6 +48,43 @@ export function disableHydrationWarnings(): void {
   _enabled = false
 }
 
+// ─── Telemetry callback ─────────────────────────────────────────────────────
+
+export type HydrationMismatchType = 'tag' | 'text' | 'missing'
+
+export interface HydrationMismatchContext {
+  /** Kind of mismatch */
+  type: HydrationMismatchType
+  /** What the VNode expected */
+  expected: unknown
+  /** What the DOM had */
+  actual: unknown
+  /** Human-readable path in the tree, e.g. "root > div > span" */
+  path: string
+  /** Unix timestamp (ms) */
+  timestamp: number
+}
+
+export type HydrationMismatchHandler = (ctx: HydrationMismatchContext) => void
+
+let _handlers: HydrationMismatchHandler[] = []
+
+/**
+ * Register a hydration mismatch handler. Called on every mismatch in BOTH
+ * development and production, independent of the dev-mode warn toggle.
+ *
+ * Mirrors `@pyreon/core`'s `registerErrorHandler` pattern — multiple
+ * handlers can be registered; each is called in registration order;
+ * handler errors are swallowed so they don't propagate into the
+ * framework. Returns an unregister function.
+ */
+export function onHydrationMismatch(handler: HydrationMismatchHandler): () => void {
+  _handlers.push(handler)
+  return () => {
+    _handlers = _handlers.filter((h) => h !== handler)
+  }
+}
+
 /**
  * Emit a hydration mismatch warning.
  * @param type  - Kind of mismatch
@@ -32,13 +93,37 @@ export function disableHydrationWarnings(): void {
  * @param path     - Human-readable path in the tree, e.g. "root > div > span"
  */
 export function warnHydrationMismatch(
-  _type: 'tag' | 'text' | 'missing',
-  _expected: unknown,
-  _actual: unknown,
-  _path: string,
+  type: HydrationMismatchType,
+  expected: unknown,
+  actual: unknown,
+  path: string,
 ): void {
-  if (!_enabled) return
-  console.warn(
-    `[Pyreon] Hydration mismatch (${_type}): expected ${String(_expected)}, got ${String(_actual)} at ${_path}`,
-  )
+  // Dev-mode console.warn — gated on _enabled (default __DEV__).
+  if (_enabled) {
+    // oxlint-disable-next-line no-console
+    console.warn(
+      `[Pyreon] Hydration mismatch (${type}): expected ${String(expected)}, got ${String(actual)} at ${path}`,
+    )
+  }
+
+  // Telemetry callbacks — fire in BOTH dev and prod, independent of the
+  // warn toggle. This is the production observability hook (Sentry,
+  // Datadog, etc.) that pre-fix was missing entirely.
+  if (_handlers.length > 0) {
+    const ctx: HydrationMismatchContext = {
+      type,
+      expected,
+      actual,
+      path,
+      timestamp: Date.now(),
+    }
+    for (const h of _handlers) {
+      try {
+        h(ctx)
+      } catch {
+        // handler errors must never propagate back into the hydration
+        // pipeline — a broken Sentry SDK shouldn't crash the app.
+      }
+    }
+  }
 }

package/src/index.ts

@@ -3,7 +3,16 @@
 export { DELEGATED_EVENTS, delegatedPropName, setupDelegation } from './delegate'
 export type { DevtoolsComponentEntry, PyreonDevtools } from './devtools'
 export { hydrateRoot } from './hydrate'
-export { disableHydrationWarnings, enableHydrationWarnings } from './hydration-debug'
+export type {
+  HydrationMismatchContext,
+  HydrationMismatchHandler,
+  HydrationMismatchType,
+} from './hydration-debug'
+export {
+  disableHydrationWarnings,
+  enableHydrationWarnings,
+  onHydrationMismatch,
+} from './hydration-debug'
 export type { KeepAliveProps } from './keep-alive'
 export { KeepAlive } from './keep-alive'
 export { mountChild } from './mount'
@@ -28,8 +37,7 @@ import { mountChild } from './mount'
 
 // Dev-mode gate: see `pyreon/no-process-dev-gate` lint rule for why this
 // uses `import.meta.env.DEV` instead of `typeof process !== 'undefined'`.
-// @ts-ignore — `import.meta.env.DEV` is provided by Vite/Rolldown at build time
-const __DEV__ = import.meta.env?.DEV === true
+const __DEV__ = process.env.NODE_ENV !== 'production'
 
 // Dev-time counter sink — see packages/internals/perf-harness for contract.
 const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }

package/src/keep-alive.ts

@@ -1,5 +1,5 @@
 import type { Props, VNodeChild } from '@pyreon/core'
-import { createRef, h, onMount } from '@pyreon/core'
+import { createRef, h, nativeCompat, onMount } from '@pyreon/core'
 import { effect } from '@pyreon/reactivity'
 import { mountChild } from './mount'
 
@@ -70,3 +70,7 @@ export function KeepAlive(props: KeepAliveProps): VNodeChild {
   // (children appear as if directly in the parent flow)
   return h('div', { ref: containerRef, style: 'display: contents' })
 }
+
+// Mark as native so compat-mode jsx() runtimes skip wrapCompatComponent —
+// KeepAlive uses onMount + effect + mountChild that need Pyreon's setup frame.
+nativeCompat(KeepAlive)

package/src/mount.ts

@@ -25,8 +25,7 @@ import { applyProps } from './props'
 
 // Dev-mode gate: see `pyreon/no-process-dev-gate` lint rule for why this
 // uses `import.meta.env.DEV` instead of `typeof process !== 'undefined'`.
-// @ts-ignore — `import.meta.env.DEV` is provided by Vite/Rolldown at build time
-const __DEV__ = import.meta.env?.DEV === true
+const __DEV__ = process.env.NODE_ENV !== 'production'
 
 // Dev-time counter sink — see packages/internals/perf-harness for contract.
 const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }

package/src/nodes.ts

@@ -7,8 +7,7 @@ import { effect, runUntracked } from '@pyreon/reactivity'
 
 // Dev-mode gate: see `pyreon/no-process-dev-gate` lint rule for why this
 // uses `import.meta.env.DEV` instead of `typeof process !== 'undefined'`.
-// @ts-ignore — `import.meta.env.DEV` is provided by Vite/Rolldown at build time
-const __DEV__ = import.meta.env?.DEV === true
+const __DEV__ = process.env.NODE_ENV !== 'production'
 
 // Dev-time counter sink — see packages/internals/perf-harness for contract.
 const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }

package/src/props.ts

@@ -8,8 +8,7 @@ type Cleanup = () => void
 
 // Dev-mode gate: see `pyreon/no-process-dev-gate` lint rule for why this
 // uses `import.meta.env.DEV` instead of `typeof process !== 'undefined'`.
-// @ts-ignore — `import.meta.env.DEV` is provided by Vite/Rolldown at build time
-const __DEV__ = import.meta.env?.DEV === true
+const __DEV__ = process.env.NODE_ENV !== 'production'
 
 // ─── Configurable sanitizer ──────────────────────────────────────────────────
 

package/src/template.ts

@@ -4,8 +4,7 @@ import { mountChild } from './mount'
 
 // Dev-mode gate: see `pyreon/no-process-dev-gate` lint rule for why this
 // uses `import.meta.env.DEV` instead of `typeof process !== 'undefined'`.
-// @ts-ignore — `import.meta.env.DEV` is provided by Vite/Rolldown at build time
-const __DEV__ = import.meta.env?.DEV === true
+const __DEV__ = process.env.NODE_ENV !== 'production'
 
 // Dev-time counter sink — see packages/internals/perf-harness for contract.
 const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }
@@ -126,6 +125,22 @@ export function _bindDirect(
 // ─── Compiler-facing template API ─────────────────────────────────────────────
 
 // Cache parsed <template> elements by HTML string — parse once, clone many.
+//
+// LRU bound (audit bug #5): typical apps emit a small bounded set of unique
+// HTML strings (one per JSX element tree the compiler hoists), so the cache
+// stays in the dozens-to-hundreds in practice. But an app that constructs
+// JSX from user input (or compiles many large dynamic templates) could grow
+// this unbounded — every unique string holds a parsed <template> alive.
+//
+// Map preserves insertion order; on overflow we evict the OLDEST entry (the
+// least-recently-inserted). Common HTML strings hit the cache before
+// eviction; pathological inputs cycle through the cap without leaking.
+//
+// 1024 chosen as a balance: ~1024 unique templates × ~1KB parsed = ~1MB
+// worst case — well within memory budget for any realistic app, and
+// generous enough that no real codebase will hit the cap. Apps that
+// genuinely need a different cap can swap their own _tpl wrapper.
+const TPL_CACHE_MAX = 1024
 const _tplCache = new Map<string, HTMLTemplateElement>()
 
 /**
@@ -157,6 +172,18 @@ export function _tpl(html: string, bind: (el: HTMLElement) => (() => void) | nul
   if (!tpl) {
     tpl = document.createElement('template')
     tpl.innerHTML = html
+    // LRU eviction — drop the oldest entry once we hit the cap. Map
+    // iteration is insertion-order so the first key is always the
+    // oldest. delete() is O(1).
+    if (_tplCache.size >= TPL_CACHE_MAX) {
+      const oldest = _tplCache.keys().next().value
+      if (oldest !== undefined) _tplCache.delete(oldest)
+    }
+    _tplCache.set(html, tpl)
+  } else {
+    // LRU touch — re-insert moves to most-recent position so frequently
+    // used templates survive eviction.
+    _tplCache.delete(html)
     _tplCache.set(html, tpl)
   }
   const el = tpl.content.firstElementChild?.cloneNode(true) as HTMLElement
@@ -164,6 +191,23 @@ export function _tpl(html: string, bind: (el: HTMLElement) => (() => void) | nul
   return { __isNative: true, el, cleanup }
 }
 
+/**
+ * Test-only: clear the template cache. Used by tests that assert on
+ * cache size; never called by runtime code. Not exported from the
+ * package's public index.
+ */
+export function _clearTplCache(): void {
+  _tplCache.clear()
+}
+
+/**
+ * Test-only: read current cache size. Used by tests that assert
+ * eviction. Not exported from the package's public index.
+ */
+export function _tplCacheSize(): number {
+  return _tplCache.size
+}
+
 /**
  * Mount a children slot inside a template.
  *

package/src/tests/dev-gate-pattern.test.ts

@@ -8,22 +8,27 @@ const SRC = path.resolve(here, '..')
 
 // Source-pattern regression test for the dev-mode warning gate. Pairs with
 // the browser test in `runtime-dom.browser.test.ts` (which proves the gate
-// fires in dev) — this asserts the gate is written using the pattern that
-// Vite/Rolldown can literal-replace at build time, NOT the broken
-// `typeof process` pattern that PR #200 cleaned up.
+// fires in dev) — this asserts the gate is written using the bundler-agnostic
+// pattern (`process.env.NODE_ENV !== 'production'`) that every modern bundler
+// (Vite, Webpack/Next.js, esbuild, Rollup, Parcel, Bun) literal-replaces at
+// consumer build time. The two previously-shipped broken patterns must not
+// appear:
+//   1. `typeof process !== 'undefined' && process.env.NODE_ENV !== 'production'`
+//      — dead in Vite browser bundles.
+//   2. `import.meta.env.DEV` — Vite/Rolldown-only; undefined and silent in
+//      Webpack/Next.js, esbuild, Rollup, Parcel, Bun.
 //
 // Same shape as `flow/src/tests/integration.test.ts:warnIgnoredOptions`.
 //
-// The lint rule `pyreon/no-process-dev-gate` (introduced in PR #220) is the
-// CI-wide enforcement for this. This test is the narrow, package-local
-// safety net so a regression in runtime-dom is caught even if the lint
-// configuration drifts.
+// The lint rule `pyreon/no-process-dev-gate` is the CI-wide enforcement for
+// this. This test is the narrow, package-local safety net so a regression in
+// runtime-dom is caught even if the lint configuration drifts.
 
 const FILES_WITH_DEV_GATE = ['nodes.ts', 'hydration-debug.ts']
 
 describe('runtime-dom dev-warning gate (source pattern)', () => {
   for (const file of FILES_WITH_DEV_GATE) {
-    it(`${file} uses import.meta.env.DEV, not typeof process`, async () => {
+    it(`${file} uses bundler-agnostic process.env.NODE_ENV`, async () => {
       const source = await readFile(path.join(SRC, file), 'utf8')
       // Strip line + block comments so referencing the broken pattern in
       // documentation doesn't false-positive.
@@ -31,10 +36,11 @@ describe('runtime-dom dev-warning gate (source pattern)', () => {
         .replace(/\/\*[\s\S]*?\*\//g, '')
         .replace(/(^|[^:])\/\/.*$/gm, '$1')
 
-      // The gate constant must exist, defined via Vite's literal-replaced env.
-      expect(code).toMatch(/const\s+__DEV__\s*=\s*import\.meta\.env\??\.DEV/)
-      // The broken pattern must not appear anywhere in executable code.
+      // The bundler-agnostic gate must appear (bare `process.env.NODE_ENV`).
+      expect(code).toMatch(/process\.env\.NODE_ENV/)
+      // Neither broken pattern may appear in executable code.
       expect(code).not.toMatch(/typeof\s+process\s*!==?\s*['"]undefined['"]/)
+      expect(code).not.toMatch(/import\.meta\.env\??\.DEV/)
     })
   }
 })

package/src/tests/dev-gate-treeshake.test.ts

@@ -8,28 +8,24 @@ import { build } from 'vite'
 const here = path.dirname(fileURLToPath(import.meta.url))
 const SRC = path.resolve(here, '..')
 
-// Bundle-level regression test for the T1.1 C-2 finding.
+// Bundle-level regression test for the dev-warning gate.
 //
-// Background — the shape of the problem from PR #227 bring-up:
-//   Raw `esbuild --minify` preserves chained `__DEV__ && cond &&
-//   console.warn(...)` patterns even when `import.meta.env.DEV` is
-//   defined to `false`. That tempted a pattern-rewrite across all
-//   Pyreon sources.
+// runtime-dom uses bundler-agnostic `process.env.NODE_ENV !== 'production'`
+// for dev gates — the cross-bundler library convention used by React, Vue,
+// Preact, Solid, MobX, Redux. Every modern bundler (Vite, Webpack/Next.js,
+// esbuild, Rollup, Parcel, Bun) auto-replaces `process.env.NODE_ENV` at
+// consumer build time. This test bundles each representative runtime-dom
+// file through Vite's production build and asserts dev-warning strings
+// are GONE from the output — proving literal-replacement + dead-code
+// elimination work end-to-end.
 //
-// What the C-2 investigation actually found:
-//   Pyreon's real consumer path is Vite (which uses Rolldown under the
-//   hood plus its own import.meta.env replacement + tree-shake passes).
-//   Vite's production build DOES eliminate the chained patterns
-//   correctly — the raw esbuild baseline was misleading. Raw Rolldown
-//   alone also doesn't replicate Vite's behavior because Rolldown's
-//   `define` doesn't rewrite optional-chain access paths.
+// The test uses Vite because that's Pyreon's reference consumer pipeline
+// today; the same files under Webpack / esbuild / Rollup etc. tree-shake
+// equivalently because they all replace `process.env.NODE_ENV`. Vite is
+// just the most-tested path.
 //
-// This test bundles a runtime-dom entry through Vite's production
-// build and asserts dev-warning strings are GONE. If Vite's handling
-// ever regresses, this catches it.
-//
-// Scope note: the existing `dev-gate-pattern.test.ts` is the cheap
-// source-level guard (grep for `typeof process`, require `import.meta.env.DEV`).
+// Scope note: `dev-gate-pattern.test.ts` is the cheap source-level guard
+// (grep for the broken patterns, require bare `process.env.NODE_ENV`).
 // This test is the expensive end-to-end guard for the bundle path.
 
 interface FileContract {
@@ -84,19 +80,17 @@ const FILES_UNDER_TEST: FileContract[] = [
 async function bundleWithVite(entry: string, dev: boolean): Promise<string> {
   const outDir = mkdtempSync(path.join(tmpdir(), 'pyreon-vite-treeshake-'))
   try {
-    // Vite library-mode build with explicit minify. `define` on
-    // `import.meta.env` isn't usually needed (Vite sets it automatically
-    // based on mode), but `mode: 'production'` flips DEV to false.
+    // Vite library-mode build with explicit minify. The bundler-agnostic
+    // gate uses `process.env.NODE_ENV` — Vite's library mode doesn't apply
+    // the default replacement automatically, so we set it ourselves to
+    // match what every modern bundler does at consumer build time.
     await build({
       mode: dev ? 'development' : 'production',
       logLevel: 'error',
       configFile: false,
       resolve: { conditions: ['bun'] },
-      // Explicit define — Vite in lib mode doesn't always apply the
-      // default production env replacement, so we set it ourselves.
       define: {
-        'import.meta.env.DEV': JSON.stringify(dev),
-        'import.meta.env': JSON.stringify({ DEV: dev, PROD: !dev, MODE: dev ? 'development' : 'production' }),
+        'process.env.NODE_ENV': JSON.stringify(dev ? 'development' : 'production'),
       },
       build: {
         // PINNED minifier: 'esbuild' is what Pyreon's reference consumers

package/src/tests/hydration-integration.test.tsx

@@ -5,7 +5,7 @@
  * hydrate on client, verify signals work and DOM is reused.
  */
 import type { VNodeChild } from '@pyreon/core'
-import { For, Fragment, h, Show } from '@pyreon/core'
+import { _rp, For, Fragment, h, Show } from '@pyreon/core'
 import { signal } from '@pyreon/reactivity'
 import { renderToString } from '@pyreon/runtime-server'
 import { disableHydrationWarnings, enableHydrationWarnings, hydrateRoot } from '../index'
@@ -373,3 +373,168 @@ describe('hydration integration — mismatch recovery', () => {
     cleanup()
   })
 })
+
+// ─── onHydrationMismatch telemetry hook ────────────────────────────────────
+//
+// Pre-fix: runtime-dom emitted hydration mismatches via console.warn ONLY,
+// gated on __DEV__. Production deployments (Sentry, Datadog) had no
+// integration point — mismatches surfaced as silent recovery (text
+// rewritten or DOM remounted) with no telemetry signal. The asymmetry
+// with `@pyreon/core`'s `registerErrorHandler` (which captures component
+// + reactivity errors via the `__pyreon_report_error__` bridge) was the
+// gap.
+//
+// Post-fix: `onHydrationMismatch(handler)` registers a callback fired on
+// EVERY mismatch in dev AND prod, independent of the warn toggle.
+// Mirrors core's `registerErrorHandler` shape.
+describe('hydration integration — onHydrationMismatch telemetry hook', () => {
+  test('handler fires with full mismatch context on tag mismatch', async () => {
+    const { onHydrationMismatch } = await import('../hydration-debug')
+    const captured: Array<{ type: string; expected: unknown; actual: unknown; path: string; timestamp: number }> = []
+    const unsub = onHydrationMismatch((ctx) => {
+      captured.push({
+        type: ctx.type,
+        expected: ctx.expected,
+        actual: ctx.actual,
+        path: ctx.path,
+        timestamp: ctx.timestamp,
+      })
+    })
+
+    const el = container()
+    el.innerHTML = '<div>server content</div>'
+
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const cleanup = hydrateRoot(el, h('span', null, 'client content'))
+
+    expect(captured.length).toBeGreaterThan(0)
+    const tagMismatch = captured.find((c) => c.type === 'tag')
+    expect(tagMismatch).toBeDefined()
+    expect(tagMismatch?.expected).toBe('span')
+    expect(typeof tagMismatch?.path).toBe('string')
+    expect(typeof tagMismatch?.timestamp).toBe('number')
+
+    cleanup()
+    unsub()
+    warnSpy.mockRestore()
+  })
+
+  test('handler fires for tag mismatch in production-style silence (warn disabled)', () => {
+    const el = container()
+    el.innerHTML = '<div>server content</div>'
+
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    disableHydrationWarnings() // simulate production: warns silenced
+
+    return import('../hydration-debug').then(({ onHydrationMismatch }) => {
+      const captured: Array<{ type: string }> = []
+      const unsub = onHydrationMismatch((ctx) => {
+        captured.push({ type: ctx.type })
+      })
+
+      const cleanup = hydrateRoot(el, h('span', null, 'client content'))
+
+      // Telemetry hook fired even with warn disabled — independent.
+      expect(captured.length).toBeGreaterThan(0)
+      expect(captured.some((c) => c.type === 'tag')).toBe(true)
+      // console.warn was NOT called (production-style silence).
+      expect(warnSpy).not.toHaveBeenCalled()
+
+      cleanup()
+      unsub()
+      warnSpy.mockRestore()
+      enableHydrationWarnings()
+    })
+  })
+
+  test('multiple handlers all receive forwarded mismatches; unsub stops one cleanly', async () => {
+    const { onHydrationMismatch } = await import('../hydration-debug')
+    let count1 = 0
+    let count2 = 0
+    const unsub1 = onHydrationMismatch(() => count1++)
+    const unsub2 = onHydrationMismatch(() => count2++)
+
+    const el = container()
+    el.innerHTML = '<div>server</div>'
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    const cleanup = hydrateRoot(el, h('span', null, 'client'))
+
+    expect(count1).toBeGreaterThan(0)
+    expect(count1).toBe(count2)
+
+    // Unsubscribe one — only the other fires next time.
+    unsub1()
+    const before2 = count2
+    const el2 = container()
+    el2.innerHTML = '<p>foo</p>'
+    const cleanup2 = hydrateRoot(el2, h('article', null, 'bar'))
+
+    expect(count2).toBeGreaterThan(before2)
+
+    cleanup()
+    cleanup2()
+    unsub2()
+    warnSpy.mockRestore()
+  })
+
+  test('handler errors do not propagate into hydration', async () => {
+    const { onHydrationMismatch } = await import('../hydration-debug')
+    let goodHandlerFired = false
+    const unsubBad = onHydrationMismatch(() => {
+      throw new Error('telemetry SDK exploded')
+    })
+    const unsubGood = onHydrationMismatch(() => {
+      goodHandlerFired = true
+    })
+
+    const el = container()
+    el.innerHTML = '<div>server</div>'
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    disableHydrationWarnings()
+
+    // Hydration must complete without throwing despite bad handler.
+    const cleanup = hydrateRoot(el, h('span', null, 'client'))
+    expect(goodHandlerFired).toBe(true)
+    // Client content still rendered — recovery worked.
+    expect(el.textContent).toContain('client')
+
+    cleanup()
+    unsubBad()
+    unsubGood()
+    warnSpy.mockRestore()
+    enableHydrationWarnings()
+  })
+})
+
+// ─── _rp prop forwarding through SSR -> hydrate ─────────────────────────────
+
+describe('hydration integration — `_rp`-wrapped component props (regression)', () => {
+  // Pre-fix, hydrate.ts skipped `makeReactiveProps` on the way into a
+  // component, so `props.x` returned the raw `_rp` function instead of the
+  // resolved value. mount.ts already did the right thing, so the failure mode
+  // surfaced only on cold-start SSR/hydrate (the fundamentals NavItem layout
+  // shape — see e2e/fundamentals/playground.spec.ts). Lock in BOTH the SSR
+  // emit and the post-hydration value.
+  test('SSR emits resolved string from `_rp` prop, hydration preserves it', async () => {
+    const Link = (props: { to: string }) =>
+      h('a', { href: `#${props.to}`, id: 'lnk' }, () => props.to)
+
+    const html = await renderToString(
+      h(Link, { to: _rp(() => '/about') as unknown as string }),
+    )
+    expect(html).toBe('<a href="#/about" id="lnk">/about</a>')
+    expect(html).not.toContain('=>')
+
+    const el = container()
+    el.innerHTML = html
+    const cleanup = hydrateRoot(
+      el,
+      h(Link, { to: _rp(() => '/about') as unknown as string }),
+    )
+    const link = el.querySelector<HTMLAnchorElement>('#lnk')!
+    expect(link.getAttribute('href')).toBe('#/about')
+    expect(link.textContent).toBe('/about')
+    cleanup()
+  })
+})