@pyreon/runtime-dom 0.13.1 → 0.15.0

package/lib/transition-entry.js

@@ -0,0 +1,168 @@
+import { Fragment, createRef, h, nativeCompat, onUnmount } from "@pyreon/core";
+import { effect, runUntracked, signal } from "@pyreon/reactivity";
+
+//#region src/transition.ts
+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.
+*
+* Class lifecycle:
+*   Enter: {name}-enter-from  → (next frame) → {name}-enter-active + {name}-enter-to → cleanup
+*   Leave: {name}-leave-from  → (next frame) → {name}-leave-active + {name}-leave-to → unmount
+*
+* The child element stays in the DOM during the leave animation and is removed only
+* after the CSS transition / animation completes.
+*
+* @example
+* const visible = signal(false)
+*
+* h(Transition, { name: "fade", show: () => visible() },
+*   h("div", { class: "modal" }, "content")
+* )
+*
+* // CSS:
+* // .fade-enter-from, .fade-leave-to  { opacity: 0; }
+* // .fade-enter-active, .fade-leave-active { transition: opacity 300ms ease; }
+*/
+function Transition(props) {
+	const n = props.name ?? "pyreon";
+	const cls = {
+		ef: props.enterFrom ?? `${n}-enter-from`,
+		ea: props.enterActive ?? `${n}-enter-active`,
+		et: props.enterTo ?? `${n}-enter-to`,
+		lf: props.leaveFrom ?? `${n}-leave-from`,
+		la: props.leaveActive ?? `${n}-leave-active`,
+		lt: props.leaveTo ?? `${n}-leave-to`
+	};
+	const ref = createRef();
+	const isMounted = signal(runUntracked(props.show));
+	let pendingEnterCancel = null;
+	let pendingLeaveCancel = null;
+	let initialized = false;
+	const applyEnter = (el) => {
+		pendingLeaveCancel?.();
+		pendingLeaveCancel = null;
+		pendingEnterCancel?.();
+		pendingEnterCancel = null;
+		props.onBeforeEnter?.(el);
+		el.classList.remove(cls.lf, cls.la, cls.lt);
+		el.classList.add(cls.ef, cls.ea);
+		requestAnimationFrame(() => {
+			el.classList.remove(cls.ef);
+			el.classList.add(cls.et);
+			let safetyTimer = null;
+			const done = () => {
+				el.removeEventListener("transitionend", done);
+				el.removeEventListener("animationend", done);
+				if (safetyTimer !== null) {
+					clearTimeout(safetyTimer);
+					safetyTimer = null;
+				}
+				pendingEnterCancel = null;
+				el.classList.remove(cls.ea, cls.et);
+				props.onAfterEnter?.(el);
+			};
+			pendingEnterCancel = () => {
+				el.removeEventListener("transitionend", done);
+				el.removeEventListener("animationend", done);
+				if (safetyTimer !== null) {
+					clearTimeout(safetyTimer);
+					safetyTimer = null;
+				}
+				el.classList.remove(cls.ef, cls.ea, cls.et);
+			};
+			el.addEventListener("transitionend", done, { once: true });
+			el.addEventListener("animationend", done, { once: true });
+			safetyTimer = setTimeout(done, 5e3);
+		});
+	};
+	const applyLeave = (el) => {
+		pendingEnterCancel?.();
+		pendingEnterCancel = null;
+		props.onBeforeLeave?.(el);
+		el.classList.remove(cls.ef, cls.ea, cls.et);
+		el.classList.add(cls.lf, cls.la);
+		requestAnimationFrame(() => {
+			el.classList.remove(cls.lf);
+			el.classList.add(cls.lt);
+			let safetyTimer = null;
+			const done = () => {
+				el.removeEventListener("transitionend", done);
+				el.removeEventListener("animationend", done);
+				if (safetyTimer !== null) {
+					clearTimeout(safetyTimer);
+					safetyTimer = null;
+				}
+				el.classList.remove(cls.la, cls.lt);
+				pendingLeaveCancel = null;
+				isMounted.set(false);
+				props.onAfterLeave?.(el);
+			};
+			pendingLeaveCancel = () => {
+				el.removeEventListener("transitionend", done);
+				el.removeEventListener("animationend", done);
+				if (safetyTimer !== null) {
+					clearTimeout(safetyTimer);
+					safetyTimer = null;
+				}
+				el.classList.remove(cls.lf, cls.la, cls.lt);
+			};
+			el.addEventListener("transitionend", done, { once: true });
+			el.addEventListener("animationend", done, { once: true });
+			safetyTimer = setTimeout(done, 5e3);
+		});
+	};
+	const handleVisibilityChange = (visible) => {
+		if (visible) {
+			if (!isMounted.peek()) isMounted.set(true);
+			queueMicrotask(() => applyEnter(ref.current));
+			return;
+		}
+		if (!isMounted.peek()) return;
+		const el = ref.current;
+		if (!el) {
+			isMounted.set(false);
+			return;
+		}
+		applyLeave(el);
+	};
+	effect(() => {
+		const visible = props.show();
+		if (!initialized) {
+			initialized = true;
+			if (visible && props.appear) queueMicrotask(() => applyEnter(ref.current));
+			return;
+		}
+		handleVisibilityChange(visible);
+	});
+	onUnmount(() => {
+		pendingEnterCancel?.();
+		pendingEnterCancel = null;
+		pendingLeaveCancel?.();
+		pendingLeaveCancel = null;
+	});
+	const rawChild = props.children;
+	const emptyFragment = h(Fragment, null);
+	return (() => {
+		if (!isMounted()) return emptyFragment;
+		if (!rawChild || typeof rawChild !== "object" || Array.isArray(rawChild)) return rawChild ?? null;
+		const vnode = rawChild;
+		if (typeof vnode.type !== "string") {
+			if (__DEV__) console.warn("[Pyreon] Transition child is a component. Wrap it in a DOM element for enter/leave animations to work.");
+			return vnode;
+		}
+		return {
+			...vnode,
+			props: {
+				...vnode.props,
+				ref
+			}
+		};
+	});
+}
+nativeCompat(Transition);
+
+//#endregion
+export { Transition };
+//# sourceMappingURL=transition-entry.js.map

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/lib/types/keep-alive-entry.d.ts

@@ -0,0 +1,41 @@
+import { Props, VNodeChild } from "@pyreon/core";
+
+//#region src/keep-alive.d.ts
+interface KeepAliveProps extends Props {
+  /**
+   * Accessor that returns true when this slot's children should be visible.
+   * When false, children are CSS-hidden but remain mounted — effects and
+   * signals stay alive.
+   * Defaults to true (always visible / always mounted).
+   */
+  active?: () => boolean;
+  children?: VNodeChild;
+}
+/**
+ * KeepAlive — mounts its children once and keeps them alive even when hidden.
+ *
+ * Unlike conditional rendering (which destroys and recreates component state),
+ * KeepAlive CSS-hides the children while preserving all reactive state,
+ * scroll position, form values, and in-flight async operations.
+ *
+ * Children are mounted imperatively on first activation and are never unmounted
+ * while the KeepAlive itself is mounted.
+ *
+ * Multi-slot pattern (one KeepAlive per route):
+ * @example
+ * h(Fragment, null, [
+ *   h(KeepAlive, { active: () => route() === "/a" }, h(RouteA, null)),
+ *   h(KeepAlive, { active: () => route() === "/b" }, h(RouteB, null)),
+ * ])
+ *
+ * With JSX:
+ * @example
+ * <>
+ *   <KeepAlive active={() => route() === "/a"}><RouteA /></KeepAlive>
+ *   <KeepAlive active={() => route() === "/b"}><RouteB /></KeepAlive>
+ * </>
+ */
+declare function KeepAlive(props: KeepAliveProps): VNodeChild;
+//#endregion
+export { KeepAlive, KeepAliveProps };
+//# sourceMappingURL=keep-alive-entry2.d.ts.map

package/lib/types/transition-entry.d.ts

@@ -0,0 +1,59 @@
+import { VNodeChild } from "@pyreon/core";
+
+//#region src/transition.d.ts
+interface TransitionProps {
+  /**
+   * CSS class name prefix.
+   * "fade" → fade-enter-from, fade-enter-active, fade-enter-to, fade-leave-from, …
+   * Default: "pyreon"
+   */
+  name?: string;
+  /** Reactive boolean controlling whether the child is shown. */
+  show: () => boolean;
+  /**
+   * If true, runs the enter transition on the initial mount (instead of
+   * appearing immediately). Default: false.
+   */
+  appear?: boolean;
+  enterFrom?: string;
+  enterActive?: string;
+  enterTo?: string;
+  leaveFrom?: string;
+  leaveActive?: string;
+  leaveTo?: string;
+  onBeforeEnter?: (el: HTMLElement) => void;
+  onAfterEnter?: (el: HTMLElement) => void;
+  onBeforeLeave?: (el: HTMLElement) => void;
+  onAfterLeave?: (el: HTMLElement) => void;
+  /**
+   * The single child element to animate.
+   * Must be a direct DOM element VNode (not a component) for class injection to work.
+   */
+  children?: VNodeChild;
+}
+/**
+ * Transition — adds CSS enter/leave animation classes to a single child element,
+ * controlled by the reactive `show` prop.
+ *
+ * Class lifecycle:
+ *   Enter: {name}-enter-from  → (next frame) → {name}-enter-active + {name}-enter-to → cleanup
+ *   Leave: {name}-leave-from  → (next frame) → {name}-leave-active + {name}-leave-to → unmount
+ *
+ * The child element stays in the DOM during the leave animation and is removed only
+ * after the CSS transition / animation completes.
+ *
+ * @example
+ * const visible = signal(false)
+ *
+ * h(Transition, { name: "fade", show: () => visible() },
+ *   h("div", { class: "modal" }, "content")
+ * )
+ *
+ * // CSS:
+ * // .fade-enter-from, .fade-leave-to  { opacity: 0; }
+ * // .fade-enter-active, .fade-leave-active { transition: opacity 300ms ease; }
+ */
+declare function Transition(props: TransitionProps): VNodeChild;
+//#endregion
+export { Transition, TransitionProps };
+//# sourceMappingURL=transition-entry2.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/runtime-dom",
-  "version": "0.13.1",
+  "version": "0.15.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"
@@ -28,6 +29,16 @@
       "bun": "./src/index.ts",
       "import": "./lib/index.js",
       "types": "./lib/types/index.d.ts"
+    },
+    "./transition": {
+      "bun": "./src/transition-entry.ts",
+      "import": "./lib/transition-entry.js",
+      "types": "./lib/types/transition-entry.d.ts"
+    },
+    "./keep-alive": {
+      "bun": "./src/keep-alive-entry.ts",
+      "import": "./lib/keep-alive-entry.js",
+      "types": "./lib/types/keep-alive-entry.d.ts"
     }
   },
   "publishConfig": {
@@ -43,15 +54,15 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@pyreon/core": "^0.13.1",
-    "@pyreon/reactivity": "^0.13.1"
+    "@pyreon/core": "^0.15.0",
+    "@pyreon/reactivity": "^0.15.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.9",
-    "@pyreon/compiler": "^0.13.1",
+    "@pyreon/compiler": "^0.15.0",
     "@pyreon/manifest": "0.13.1",
-    "@pyreon/runtime-server": "^0.13.1",
-    "@pyreon/test-utils": "^0.13.1",
+    "@pyreon/runtime-server": "^0.15.0",
+    "@pyreon/test-utils": "^0.13.2",
     "@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 {
@@ -384,8 +391,8 @@ function hydrateComponent(
   const { vnode: output, hooks } = result
 
   // Register onUpdate hooks with the scope
-  for (const fn of hooks.update) {
-    scope.addUpdateHook(fn)
+  if (hooks.update) {
+    for (const fn of hooks.update) scope.addUpdateHook(fn)
   }
 
   if (output != null) {
@@ -395,22 +402,24 @@ function hydrateComponent(
   }
 
   // Fire onMount hooks; effects created inside are tracked by the scope via runInScope
-  for (const fn of hooks.mount) {
-    try {
-      let c: (() => void) | undefined
-      scope.runInScope(() => {
-        c = fn() as (() => void) | undefined
-      })
-      if (c) mountCleanups.push(c)
-    } catch (err) {
-      reportError({ component: componentName, phase: 'mount', error: err, timestamp: Date.now() })
+  if (hooks.mount) {
+    for (const fn of hooks.mount) {
+      try {
+        let c: (() => void) | undefined
+        scope.runInScope(() => {
+          c = fn() as (() => void) | undefined
+        })
+        if (c) mountCleanups.push(c)
+      } catch (err) {
+        reportError({ component: componentName, phase: 'mount', error: err, timestamp: Date.now() })
+      }
     }
   }
 
   const cleanup: Cleanup = () => {
     scope.stop()
     subtreeCleanup()
-    for (const fn of hooks.unmount) fn()
+    if (hooks.unmount) for (const fn of hooks.unmount) fn()
     for (const fn of mountCleanups) fn()
   }
 

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.
+      }
+    }
+  }
 }