@pyreon/runtime-dom 0.14.0 → 0.16.0

package/lib/keep-alive-entry.js

@@ -1,4 +1,4 @@
-import { EMPTY_PROPS, ForSymbol, Fragment, PortalSymbol, captureContextStack, createRef, cx, dispatchToErrorBoundary, h, makeReactiveProps, normalizeStyleValue, onMount, propagateError, reportError, restoreContextStack, runWithHooks, toKebabCase } from "@pyreon/core";
+import { EMPTY_PROPS, ForSymbol, Fragment, PortalSymbol, captureContextStack, createRef, cx, dispatchToErrorBoundary, h, makeReactiveProps, nativeCompat, normalizeStyleValue, onMount, propagateError, reportError, restoreContextStack, runWithHooks, toKebabCase } from "@pyreon/core";
 import { batch, effect, effectScope, renderEffect, runUntracked, setCurrentScope } from "@pyreon/reactivity";
 
 //#region src/devtools.ts
@@ -33,8 +33,8 @@ function unregisterComponent(id) {
 
 //#endregion
 //#region src/nodes.ts
-const __DEV__$2 = import.meta.env?.DEV === true;
-const _countSink$1 = globalThis;
+const __DEV__$2 = process.env.NODE_ENV !== "production";
+const _countSink$2 = globalThis;
 /**
 * Move all nodes strictly between `start` and `end` into a throwaway
 * DocumentFragment, detaching them from the live DOM in O(n) top-level moves.
@@ -56,6 +56,10 @@ function clearBetween(start, end) {
 		cur = next;
 	}
 }
+/** Emit `runtime.cleanup` once per registered mount cleanup that actually runs. */
+function _emitCleanup() {
+	if (__DEV__$2) _countSink$2.__pyreon_count__?.("runtime.cleanup");
+}
 /**
 * Mount a reactive node whose content changes over time.
 *
@@ -63,24 +67,34 @@ function clearBetween(start, end) {
 * On each change: old nodes are removed, new ones inserted before the anchor.
 */
 function mountReactive(accessor, parent, anchor, mount) {
+	if (__DEV__$2) _countSink$2.__pyreon_count__?.("runtime.mountReactive");
 	const marker = document.createComment("pyreon");
 	parent.insertBefore(marker, anchor);
 	const contextSnapshot = captureContextStack();
 	let currentCleanup = () => {};
+	let hasCleanup = false;
 	let generation = 0;
 	const e = effect(() => {
 		const myGen = ++generation;
+		if (hasCleanup) _emitCleanup();
 		runUntracked(() => currentCleanup());
 		currentCleanup = () => {};
+		hasCleanup = false;
 		const value = accessor();
 		if (value != null && value !== false) {
 			const cleanup = runUntracked(() => restoreContextStack(contextSnapshot, () => mount(value, parent, marker)));
-			if (myGen === generation) currentCleanup = cleanup;
-			else cleanup();
+			if (myGen === generation) {
+				currentCleanup = cleanup;
+				hasCleanup = true;
+			} else {
+				_emitCleanup();
+				cleanup();
+			}
 		}
 	});
 	return () => {
 		e.dispose();
+		if (hasCleanup) _emitCleanup();
 		currentCleanup();
 		marker.parentNode?.removeChild(marker);
 	};
@@ -117,7 +131,7 @@ function computeKeyedLis(lis, n, newKeyOrder, curPos) {
 		if (lo > 0) pred[i] = tailIdx[lo - 1];
 		if (lo === lisLen) lisLen++;
 	}
-	if (__DEV__$2 && ops > 0) _countSink$1.__pyreon_count__?.("runtime.mountFor.lisOps", ops);
+	if (__DEV__$2 && ops > 0) _countSink$2.__pyreon_count__?.("runtime.mountFor.lisOps", ops);
 	return lisLen;
 }
 function markStayingEntries(lis, lisLen) {
@@ -180,6 +194,7 @@ function mountKeyedList(accessor, parent, listAnchor, mountVNode) {
 	const removeStaleEntries = (newKeySet) => {
 		for (const [key, entry] of cache) {
 			if (newKeySet.has(key)) continue;
+			_emitCleanup();
 			entry.cleanup();
 			entry.anchor.parentNode?.removeChild(entry.anchor);
 			cache.delete(key);
@@ -204,28 +219,34 @@ function mountKeyedList(accessor, parent, listAnchor, mountVNode) {
 	const e = effect(() => {
 		const newList = accessor();
 		const n = newList.length;
-		if (n === 0 && cache.size > 0) {
-			for (const entry of cache.values()) entry.cleanup();
-			cache.clear();
+		runUntracked(() => {
+			if (n === 0 && cache.size > 0) {
+				for (const entry of cache.values()) {
+					_emitCleanup();
+					entry.cleanup();
+				}
+				cache.clear();
+				curPos.clear();
+				currentKeyOrder = [];
+				clearBetween(startMarker, tailMarker);
+				return;
+			}
+			const { newKeyOrder, newKeySet } = collectKeyOrder(newList);
+			removeStaleEntries(newKeySet);
+			mountNewEntries(newList);
+			if (currentKeyOrder.length > 0 && n > 0) lis = keyedListReorder(lis, n, newKeyOrder, curPos, cache, parent, tailMarker);
 			curPos.clear();
-			currentKeyOrder = [];
-			clearBetween(startMarker, tailMarker);
-			return;
-		}
-		const { newKeyOrder, newKeySet } = collectKeyOrder(newList);
-		removeStaleEntries(newKeySet);
-		mountNewEntries(newList);
-		if (currentKeyOrder.length > 0 && n > 0) lis = keyedListReorder(lis, n, newKeyOrder, curPos, cache, parent, tailMarker);
-		curPos.clear();
-		for (let i = 0; i < newKeyOrder.length; i++) {
-			const k = newKeyOrder[i];
-			if (k !== void 0) curPos.set(k, i);
-		}
-		currentKeyOrder = newKeyOrder;
+			for (let i = 0; i < newKeyOrder.length; i++) {
+				const k = newKeyOrder[i];
+				if (k !== void 0) curPos.set(k, i);
+			}
+			currentKeyOrder = newKeyOrder;
+		});
 	});
 	return () => {
 		e.dispose();
 		for (const entry of cache.values()) {
+			_emitCleanup();
 			entry.cleanup();
 			entry.anchor.parentNode?.removeChild(entry.anchor);
 		}
@@ -284,7 +305,7 @@ function computeForLis(lis, n, newKeys, cache) {
 		tailIdx[lo] = i;
 		if (lo > 0) pred[i] = tailIdx[lo - 1];
 	}
-	if (__DEV__$2 && ops > 0) _countSink$1.__pyreon_count__?.("runtime.mountFor.lisOps", ops);
+	if (__DEV__$2 && ops > 0) _countSink$2.__pyreon_count__?.("runtime.mountFor.lisOps", ops);
 	return lisLen;
 }
 function applyForMoves(n, newKeys, stay, cache, liveParent, tailMarker) {
@@ -402,7 +423,10 @@ function mountFor(source, getKey, renderItem, parent, anchor, mountChild) {
 	};
 	const handleReplaceAll = (items, n, newKeys, liveParent) => {
 		if (cleanupCount > 0) {
-			for (const entry of cache.values()) if (entry.cleanup) entry.cleanup();
+			for (const entry of cache.values()) if (entry.cleanup) {
+				_emitCleanup();
+				entry.cleanup();
+			}
 		}
 		cache = /* @__PURE__ */ new Map();
 		cleanupCount = 0;
@@ -427,6 +451,7 @@ function mountFor(source, getKey, renderItem, parent, anchor, mountChild) {
 		for (const [key, entry] of cache) {
 			if (newKeySet.has(key)) continue;
 			if (entry.cleanup) {
+				_emitCleanup();
 				entry.cleanup();
 				cleanupCount--;
 			}
@@ -446,7 +471,10 @@ function mountFor(source, getKey, renderItem, parent, anchor, mountChild) {
 	const handleFastClear = (liveParent) => {
 		if (cache.size === 0) return;
 		if (cleanupCount > 0) {
-			for (const entry of cache.values()) if (entry.cleanup) entry.cleanup();
+			for (const entry of cache.values()) if (entry.cleanup) {
+				_emitCleanup();
+				entry.cleanup();
+			}
 		}
 		const pp = liveParent.parentNode;
 		if (pp && liveParent.firstChild === startMarker && liveParent.lastChild === tailMarker) {
@@ -484,25 +512,30 @@ function mountFor(source, getKey, renderItem, parent, anchor, mountChild) {
 		if (!liveParent) return;
 		const items = source();
 		const n = items.length;
-		if (n === 0) {
-			handleFastClear(liveParent);
-			return;
-		}
-		if (currentKeys.length === 0) {
-			handleFreshRender(items, n, liveParent);
-			return;
-		}
-		const newKeys = collectNewKeys(items, n);
-		if (!hasAnyKeptKey(n, newKeys)) {
-			handleReplaceAll(items, n, newKeys, liveParent);
-			return;
-		}
-		handleIncrementalUpdate(items, n, newKeys, liveParent);
+		runUntracked(() => {
+			if (n === 0) {
+				handleFastClear(liveParent);
+				return;
+			}
+			if (currentKeys.length === 0) {
+				handleFreshRender(items, n, liveParent);
+				return;
+			}
+			const newKeys = collectNewKeys(items, n);
+			if (!hasAnyKeptKey(n, newKeys)) {
+				handleReplaceAll(items, n, newKeys, liveParent);
+				return;
+			}
+			handleIncrementalUpdate(items, n, newKeys, liveParent);
+		});
 	});
 	return () => {
 		e.dispose();
 		for (const entry of cache.values()) {
-			if (cleanupCount > 0 && entry.cleanup) entry.cleanup();
+			if (cleanupCount > 0 && entry.cleanup) {
+				_emitCleanup();
+				entry.cleanup();
+			}
 			entry.anchor.parentNode?.removeChild(entry.anchor);
 		}
 		cache = /* @__PURE__ */ new Map();
@@ -605,7 +638,8 @@ function delegatedPropName(eventName) {
 
 //#endregion
 //#region src/props.ts
-const __DEV__$1 = import.meta.env?.DEV === true;
+const __DEV__$1 = process.env.NODE_ENV !== "production";
+const _countSink$1 = globalThis;
 let _customSanitizer = null;
 const SAFE_TAGS = new Set([
 	"a",
@@ -750,6 +784,7 @@ function applyProps(el, props) {
 * Bind an event handler (onClick → "click") with batching + delegation support.
 */
 function applyEventProp(el, key, value) {
+	if (__DEV__$1) _countSink$1.__pyreon_count__?.("runtime.applyEvent");
 	if (typeof value !== "function") {
 		if (__DEV__$1 && value != null) console.warn(`[Pyreon] Event handler "${key}" received a non-function value (${typeof value}). Expected a function. Did you mean ${key}={() => ...}?`);
 		return null;
@@ -796,6 +831,7 @@ function applyStaticProp(el, key, value) {
 	setStaticProp(el, key, value);
 }
 function applyProp(el, key, value) {
+	if (__DEV__$1) _countSink$1.__pyreon_count__?.("runtime.applyProp");
 	if (EVENT_RE.test(key)) return applyEventProp(el, key, value);
 	if (typeof value === "function") return renderEffect(() => applyStaticProp(el, key, value()));
 	applyStaticProp(el, key, value);
@@ -886,7 +922,7 @@ function setStaticProp(el, key, value) {
 
 //#endregion
 //#region src/mount.ts
-const __DEV__ = import.meta.env?.DEV === true;
+const __DEV__ = process.env.NODE_ENV !== "production";
 const _countSink = globalThis;
 const noop = () => {};
 let _elementDepth = 0;
@@ -1320,7 +1356,7 @@ function KeepAlive(props) {
 		const e = effect(() => {
 			const isActive = props.active?.() ?? true;
 			if (!childMounted) {
-				childCleanup = mountChild(props.children ?? null, container, null);
+				childCleanup = runUntracked(() => mountChild(props.children ?? null, container, null));
 				childMounted = true;
 			}
 			container.style.display = isActive ? "" : "none";
@@ -1335,6 +1371,7 @@ function KeepAlive(props) {
 		style: "display: contents"
 	});
 }
+nativeCompat(KeepAlive);
 
 //#endregion
 export { KeepAlive };

package/lib/transition-entry.js

@@ -1,8 +1,8 @@
-import { Fragment, createRef, h, onUnmount } from "@pyreon/core";
+import { Fragment, createRef, h, nativeCompat, onUnmount } from "@pyreon/core";
 import { effect, runUntracked, signal } from "@pyreon/reactivity";
 
 //#region src/transition.ts
-const __DEV__ = import.meta.env?.DEV === true;
+const __DEV__ = process.env.NODE_ENV !== "production";
 /**
 * Transition — adds CSS enter/leave animation classes to a single child element,
 * controlled by the reactive `show` prop.
@@ -161,6 +161,7 @@ function Transition(props) {
 		};
 	});
 }
+nativeCompat(Transition);
 
 //#endregion
 export { Transition };

package/lib/types/index.d.ts

@@ -85,17 +85,66 @@ declare function hydrateRoot(container: Element, vnode: VNodeChild): () => void;
 //#endregion
 //#region src/hydration-debug.d.ts
 /**
- * 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',
+ *   })
+ * })
  */
 declare function enableHydrationWarnings(): void;
 declare function disableHydrationWarnings(): void;
+type HydrationMismatchType = 'tag' | 'text' | 'missing';
+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;
+}
+type HydrationMismatchHandler = (ctx: HydrationMismatchContext) => void;
+/**
+ * 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.
+ */
+declare function onHydrationMismatch(handler: HydrationMismatchHandler): () => void;
 //#endregion
 //#region src/keep-alive.d.ts
 interface KeepAliveProps extends Props {
@@ -410,5 +459,5 @@ declare function mount(root: VNodeChild, container: Element): () => void;
 /** Alias for `mount` */
 declare const render: typeof mount;
 //#endregion
-export { DELEGATED_EVENTS, type DevtoolsComponentEntry, KeepAlive, type KeepAliveProps, type PyreonDevtools, type SanitizeFn, Transition, TransitionGroup, type TransitionGroupProps, type TransitionProps, applyProps as _applyProps, applyProps, _bindDirect, _bindText, _mountSlot, _tpl, applyProp, createTemplate, delegatedPropName, disableHydrationWarnings, enableHydrationWarnings, hydrateRoot, mount, mountChild, render, sanitizeHtml, setSanitizer, setupDelegation };
+export { DELEGATED_EVENTS, type DevtoolsComponentEntry, type HydrationMismatchContext, type HydrationMismatchHandler, type HydrationMismatchType, KeepAlive, type KeepAliveProps, type PyreonDevtools, type SanitizeFn, Transition, TransitionGroup, type TransitionGroupProps, type TransitionProps, applyProps as _applyProps, applyProps, _bindDirect, _bindText, _mountSlot, _tpl, applyProp, createTemplate, delegatedPropName, disableHydrationWarnings, enableHydrationWarnings, hydrateRoot, mount, mountChild, onHydrationMismatch, render, sanitizeHtml, setSanitizer, setupDelegation };
 //# sourceMappingURL=index2.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/runtime-dom",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "DOM renderer for Pyreon",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/runtime-dom#readme",
   "bugs": {
@@ -14,6 +14,7 @@
   },
   "files": [
     "lib",
+    "!lib/**/*.map",
     "src",
     "README.md",
     "LICENSE"
@@ -53,15 +54,15 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@pyreon/core": "^0.14.0",
-    "@pyreon/reactivity": "^0.14.0"
+    "@pyreon/core": "^0.16.0",
+    "@pyreon/reactivity": "^0.16.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.9",
-    "@pyreon/compiler": "^0.14.0",
+    "@pyreon/compiler": "^0.16.0",
     "@pyreon/manifest": "0.13.1",
-    "@pyreon/runtime-server": "^0.14.0",
-    "@pyreon/test-utils": "^0.13.2",
+    "@pyreon/runtime-server": "^0.16.0",
+    "@pyreon/test-utils": "^0.13.3",
     "@vitest/browser-playwright": "^4.1.4",
     "esbuild": "^0.28.0",
     "happy-dom": "^20.8.3",

package/src/delegate.ts

@@ -70,6 +70,22 @@ export function setupDelegation(container: Element): void {
       while (el && el !== container) {
         const handler = el[prop]
         if (typeof handler === 'function') {
+          // Per-handler `currentTarget` patch: native event delegation leaves
+          // `e.currentTarget` as the container (the listener root). Without
+          // this override, `ev.currentTarget.value` in user code reads from
+          // the container — silently `undefined` for inputs, the wrong tag
+          // type, etc. Pyreon's `TargetedEvent<E>` type *promises* the
+          // matched element; this override makes the runtime keep that
+          // promise, matching what React, Vue, and Solid all do for
+          // delegated events.
+          //
+          // `currentTarget` is a read-only accessor on native Event types,
+          // so direct assignment is silently ignored — `Object.defineProperty`
+          // with `configurable: true` is the only portable override.
+          Object.defineProperty(e, 'currentTarget', {
+            value: el,
+            configurable: true,
+          })
           batch(() => handler(e))
           // Don't break — allow ancestor handlers too (consistent with addEventListener)
           // But if stopPropagation was called, stop walking

package/src/hydrate.ts

@@ -21,6 +21,7 @@ import {
   dispatchToErrorBoundary,
   ForSymbol,
   Fragment,
+  makeReactiveProps,
   PortalSymbol,
   reportError,
   runWithHooks,
@@ -349,7 +350,7 @@ function hydrateComponent(
 
   // Function.name is always a string per spec; || handles empty string, avoids uncoverable ?? branch
   const componentName = ((vnode.type as ComponentFn).name || 'Anonymous') as string
-  const mergedProps =
+  const rawProps =
     (vnode.children ?? []).length > 0 &&
     (vnode.props as Record<string, unknown>).children === undefined
       ? {
@@ -359,7 +360,13 @@ function hydrateComponent(
               ? (vnode.children ?? [])[0]
               : (vnode.children ?? []),
         }
-      : vnode.props
+      : (vnode.props as Record<string, unknown>)
+  // Convert compiler-emitted `_rp(() => expr)` wrappers into getter properties —
+  // mirrors mount.ts so component code can read `props.x` and get the resolved
+  // value (not the raw `_rp` function). Without this, hydration set up reactive
+  // bindings against the wrong values and any signal-driven re-render would
+  // diverge from the SSR HTML.
+  const mergedProps = makeReactiveProps(rawProps as Record<string, unknown>)
 
   let result: ReturnType<typeof runWithHooks>
   try {

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,6 +1,6 @@
 import type { Props, VNodeChild } from '@pyreon/core'
-import { createRef, h, onMount } from '@pyreon/core'
-import { effect } from '@pyreon/reactivity'
+import { createRef, h, nativeCompat, onMount } from '@pyreon/core'
+import { effect, runUntracked } from '@pyreon/reactivity'
 import { mountChild } from './mount'
 
 export interface KeepAliveProps extends Props {
@@ -51,8 +51,15 @@ export function KeepAlive(props: KeepAliveProps): VNodeChild {
       const isActive = props.active?.() ?? true
 
       if (!childMounted) {
-        // Mount children into the container div exactly once
-        childCleanup = mountChild(props.children ?? null, container, null)
+        // Mount children UNTRACKED — child component setup must not
+        // subscribe this effect. Otherwise an unrelated signal flip in
+        // the children would re-run KeepAlive's effect, runCleanup()
+        // would dispose the children's inner effects (because they were
+        // collected as inner effects of this run via _innerEffectCollector),
+        // and the `if (!childMounted)` guard would skip re-mount → the
+        // children become permanently un-reactive while still rendered.
+        // Same shape as the mountFor / mountKeyedList fix in nodes.ts.
+        childCleanup = runUntracked(() => mountChild(props.children ?? null, container, null))
         childMounted = true
       }
 
@@ -70,3 +77,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 }