@pyreon/core 0.14.0 → 0.15.0

package/src/compat-marker.ts

@@ -0,0 +1,79 @@
+/**
+ * Compat-mode native-component marker.
+ *
+ * Pyreon ships compat layers (`@pyreon/{react,preact,vue,solid}-compat`) that
+ * wrap every JSX-called component function to emulate that source framework's
+ * render-on-state-change semantics. That wrapping is correct for user code
+ * (the whole point of compat mode) but corrupts Pyreon framework components
+ * — those manage their own reactivity via `provide()` / signals / lifecycle
+ * hooks, and wrapping them runs their setup body inside the compat layer's
+ * render context instead of Pyreon's, breaking `provide()` and
+ * `onMount()` / `onUnmount()` calls.
+ *
+ * Framework components opt out of compat wrapping by setting a well-known
+ * registry symbol (`Symbol.for('pyreon:native-compat')`) on the function.
+ * The compat layer reads that symbol and routes marked components straight
+ * through Pyreon's `h()` mount path. The symbol is registry-shared, so no
+ * import direction between framework and compat is implied — both sides
+ * reference the same global symbol via the helpers exported here.
+ *
+ * Audience: framework-package authors writing JSX components in `@pyreon/*`
+ * packages whose setup body uses `provide()` / lifecycle hooks / signal
+ * subscriptions. Wrap exported components with `nativeCompat()`. One line
+ * per export site; zero runtime cost beyond a single property write at
+ * module load.
+ */
+
+/**
+ * The well-known registry symbol that marks a component as a Pyreon native
+ * framework component. Compat layers check this symbol to decide whether to
+ * skip their `wrapCompatComponent` call.
+ *
+ * Exported for advanced cases where a caller needs to test the marker
+ * directly (most callers should use `isNativeCompat()`).
+ */
+export const NATIVE_COMPAT_MARKER: symbol = Symbol.for('pyreon:native-compat')
+
+/**
+ * Mark a Pyreon framework component as "self-managing" — compat layers will
+ * skip their React/Vue/Solid/Preact-style wrapping and route the component
+ * directly through Pyreon's mount path. Use on every `@pyreon/*` JSX
+ * component whose setup body uses `provide()`, lifecycle hooks
+ * (`onMount` / `onUnmount`), signal-driven reactivity, or any other Pyreon
+ * native pattern that depends on the active component-setup frame.
+ *
+ * Idempotent: re-applying the marker is a no-op. Non-function inputs pass
+ * through unchanged so callers don't have to typecheck before wrapping.
+ *
+ * @example
+ *   import { nativeCompat, provide } from '@pyreon/core'
+ *
+ *   export const RouterView = nativeCompat(function RouterView(props) {
+ *     provide(RouterContext, ...)
+ *     return <div data-pyreon-router-view>{children}</div>
+ *   })
+ */
+export function nativeCompat<T>(fn: T): T {
+  if (typeof fn === 'function') {
+    ;(fn as unknown as Record<symbol, boolean>)[NATIVE_COMPAT_MARKER] = true
+  }
+  return fn
+}
+
+/**
+ * Read whether a component has been marked as a Pyreon native framework
+ * component. Compat-layer code calls this from its `jsx()` to decide whether
+ * to wrap or pass through.
+ *
+ * @example
+ *   import { isNativeCompat } from '@pyreon/core'
+ *
+ *   if (isNativeCompat(type)) return h(type, props)
+ *   return wrapCompatComponent(type)(props)
+ */
+export function isNativeCompat(fn: unknown): boolean {
+  return (
+    typeof fn === 'function' &&
+    (fn as unknown as Record<symbol, boolean>)[NATIVE_COMPAT_MARKER] === true
+  )
+}

package/src/context.ts

@@ -5,6 +5,7 @@
  * The renderer maintains the context stack as it walks the VNode tree.
  */
 
+import { setSnapshotCapture } from '@pyreon/reactivity'
 import { onUnmount } from './lifecycle'
 
 export interface Context<T> {
@@ -66,8 +67,7 @@ function getStack(): Map<symbol, unknown>[] {
 
 // 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'
 
 export function pushContext(values: Map<symbol, unknown>) {
   getStack().push(values)
@@ -149,13 +149,22 @@ export function captureContextStack(): ContextSnapshot {
 
 /**
  * Execute `fn()` with a previously captured context stack active.
- * Restores the original stack after `fn()` completes (even on throw).
+ *
+ * After `fn()` returns, removes ONLY the snapshot frames this call pushed
+ * — anything `fn()` itself pushed (typically provider frames from
+ * `provide()` calls during component mount) stays on the stack so
+ * subsequent reactive re-runs (e.g. `_bind` text bindings,
+ * `renderEffect` callbacks) can still find ancestor providers via
+ * `useContext`. Pre-fix this method was `stack.length = savedLength`,
+ * which destructively truncated provider frames pushed during mount —
+ * silently breaking `useMode()` / `useTheme()` / `useRouter()` etc. on
+ * every signal-driven update under a `mountReactive` boundary.
  */
 export function restoreContextStack<T>(snapshot: ContextSnapshot, fn: () => T): T {
   const stack = getStack()
-  const savedLength = stack.length
+  const insertIndex = stack.length
 
-  // Push all captured frames onto the current stack
+  // Push captured snapshot frames at the END of the current stack.
   for (const frame of snapshot) {
     stack.push(frame)
   }
@@ -163,7 +172,29 @@ export function restoreContextStack<T>(snapshot: ContextSnapshot, fn: () => T):
   try {
     return fn()
   } finally {
-    // Remove only the frames we pushed (preserve anything added by fn)
-    stack.length = savedLength
+    // Splice out exactly the snapshot frames we pushed (they sit at
+    // [insertIndex, insertIndex + snapshot.length)). Any frames `fn()`
+    // pushed AFTER our snapshot (provider frames) get shifted down by
+    // `snapshot.length` positions but remain on the stack. Their owning
+    // components' `onUnmount(popContext)` handlers will pop them in
+    // LIFO order on subtree teardown — splice preserves that ordering
+    // because it doesn't touch frames at indices >= insertIndex +
+    // snapshot.length until the splice operation itself.
+    stack.splice(insertIndex, snapshot.length)
   }
 }
+
+// ─── Reactivity-layer DI: install context capture/restore for effects ────────
+//
+// `_bind` / `renderEffect` / `effect` (in `@pyreon/reactivity`) capture this
+// snapshot at setup and restore it on every subsequent re-run. Without this,
+// signal-driven re-runs after the synchronous mount see whatever the GLOBAL
+// context stack looks like at that moment — which may be missing provider
+// frames for any number of reasons (sibling subtree mounts/unmounts mutating
+// the stack, async re-render cycles, etc.). Defense-in-depth alongside the
+// `restoreContextStack` splice fix above.
+setSnapshotCapture({
+  capture: () => captureContextStack(),
+  restore: <T>(snap: unknown, fn: () => T): T =>
+    restoreContextStack(snap as ContextSnapshot, fn),
+})

package/src/dynamic.ts

@@ -1,21 +1,32 @@
 import { h } from './h'
-import type { ComponentFn, Props, VNode } from './types'
+import type { ComponentFn, Props, VNode, VNodeChild } from './types'
 
 // 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'
 
 export interface DynamicProps extends Props {
   component: ComponentFn | string
 }
 
 export function Dynamic(props: DynamicProps): VNode | null {
-  const { component, ...rest } = props
+  const { component, children, ...rest } = props as DynamicProps & { children?: unknown }
   if (__DEV__ && !component) {
     // oxlint-disable-next-line no-console
     console.warn('[Pyreon] <Dynamic> received a falsy `component` prop. Nothing will be rendered.')
   }
   if (!component) return null
-  return h(component as string | ComponentFn, rest as Props)
+  // Children must NOT remain in props. When `component` is a string tag
+  // (e.g. <Dynamic component="h3">x</Dynamic>), runtime-dom's prop applier
+  // forwards every prop key to setAttribute, so a leaked `children` prop
+  // crashes with `setAttribute('children', ...)`. Re-emit them as h() rest
+  // args so they land in vnode.children, which is where both string-tag
+  // mounts and component-merge expect them.
+  if (children === undefined) {
+    return h(component as string | ComponentFn, rest as Props)
+  }
+  if (Array.isArray(children)) {
+    return h(component as string | ComponentFn, rest as Props, ...(children as VNodeChild[]))
+  }
+  return h(component as string | ComponentFn, rest as Props, children as VNodeChild)
 }

package/src/error-boundary.ts

@@ -1,4 +1,5 @@
 import { signal } from '@pyreon/reactivity'
+import { nativeCompat } from './compat-marker'
 import { popErrorBoundary, pushErrorBoundary } from './component'
 import { onUnmount } from './lifecycle'
 import { reportError } from './telemetry'
@@ -6,8 +7,7 @@ import type { VNodeChild, VNodeChildAtom } from './types'
 
 // 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'
 
 /**
  * ErrorBoundary — catches errors thrown by child components and renders a
@@ -53,6 +53,14 @@ export function ErrorBoundary(props: {
 
   const handler = (err: unknown): boolean => {
     if (error.peek() !== null) return false // already in error state — let outer boundary catch it
+    // Synchronous signal write. The handler fires from inside mountComponent's
+    // catch, which is itself inside the boundary's own mountReactive effect
+    // run (the run that mounted the throwing child). The batch system's
+    // two-tier flush handles this correctly: this `error.set(err)` enqueues
+    // the boundary's run into the effects queue's nextPass (since the run is
+    // currently being visited), and the next pass fires it to swap to the
+    // fallback subtree. See packages/core/reactivity/src/batch.ts for the
+    // multi-pass effect drain contract.
     error.set(err)
     reportError({ component: 'ErrorBoundary', phase: 'render', error: err, timestamp: Date.now() })
     return true
@@ -69,3 +77,8 @@ export function ErrorBoundary(props: {
     return (typeof ch === 'function' ? ch() : ch) as VNodeChildAtom
   }
 }
+
+// Mark as native so compat-mode jsx() runtimes (react/preact/vue/solid-compat)
+// skip wrapCompatComponent — ErrorBoundary uses pushErrorBoundary/onUnmount,
+// which need Pyreon's setup frame (compat wrapping breaks dispatchToErrorBoundary).
+nativeCompat(ErrorBoundary)

package/src/index.ts

@@ -1,6 +1,7 @@
 // @pyreon/core — component model, VNode types, lifecycle hooks
 
 export { defineComponent, dispatchToErrorBoundary, propagateError, runWithHooks } from './component'
+export { isNativeCompat, NATIVE_COMPAT_MARKER, nativeCompat } from './compat-marker'
 export type { Context, ContextSnapshot, ReactiveContext } from './context'
 export {
   captureContextStack,

package/src/jsx-runtime.ts

@@ -1,9 +1,17 @@
+/// <reference lib="dom" />
 /**
  * JSX automatic runtime.
  *
  * When tsconfig has `"jsxImportSource": "@pyreon/core"`, the TS/bundler compiler
  * rewrites JSX to imports from this file automatically:
  *   <div class="x" />  →  jsx("div", { class: "x" })
+ *
+ * The triple-slash reference above makes this file self-declare its DOM-lib
+ * dependency. Without it, any consumer whose tsconfig has `lib: ["ESNext"]`
+ * (no DOM) — e.g. backend-only packages like @pyreon/cli — fails to typecheck
+ * once `@pyreon/core` becomes resolvable from their dependency graph (e.g. via
+ * a transitive devDep), because tsc auto-resolves jsxImportSource and pulls
+ * jsx-runtime.ts into the consumer's compilation unit.
  */
 import { Fragment, h } from './h'
 import type { RefProp } from './ref'
@@ -132,6 +140,8 @@ export interface PyreonHTMLAttributes<E extends Element = HTMLElement> {
   // Events — typed currentTarget via generic E
   onClick?: ((e: TargetedEvent<E, MouseEvent>) => void) | undefined
   onDblClick?: ((e: TargetedEvent<E, MouseEvent>) => void) | undefined
+  // React-compat alias for onDblClick — compiler maps to `dblclick` DOM event.
+  onDoubleClick?: ((e: TargetedEvent<E, MouseEvent>) => void) | undefined
   onMouseDown?: ((e: TargetedEvent<E, MouseEvent>) => void) | undefined
   onMouseUp?: ((e: TargetedEvent<E, MouseEvent>) => void) | undefined
   onMouseEnter?: ((e: TargetedEvent<E, MouseEvent>) => void) | undefined
@@ -197,7 +207,11 @@ export interface InputAttributes extends PyreonHTMLAttributes<HTMLInputElement>
   defaultChecked?: boolean | undefined
   placeholder?: string | (() => string) | undefined
   disabled?: boolean | (() => boolean) | undefined
-  readOnly?: boolean | undefined
+  // `readOnly` is paired with `disabled` semantically — both accept a
+  // reactive callable so consumers can spread `useForm.register()`'s
+  // return value (which produces `readOnly: Accessor<boolean>`) directly
+  // onto `<input>` / `<textarea>` without losing reactivity.
+  readOnly?: boolean | (() => boolean) | undefined
   required?: boolean | (() => boolean) | undefined
   min?: string | number | undefined
   max?: string | number | undefined
@@ -249,7 +263,11 @@ export interface TextareaAttributes extends PyreonHTMLAttributes<HTMLTextAreaEle
   defaultValue?: string | undefined
   placeholder?: string | (() => string) | undefined
   disabled?: boolean | (() => boolean) | undefined
-  readOnly?: boolean | undefined
+  // `readOnly` is paired with `disabled` semantically — both accept a
+  // reactive callable so consumers can spread `useForm.register()`'s
+  // return value (which produces `readOnly: Accessor<boolean>`) directly
+  // onto `<input>` / `<textarea>` without losing reactivity.
+  readOnly?: boolean | (() => boolean) | undefined
   required?: boolean | (() => boolean) | undefined
   rows?: number | undefined
   cols?: number | undefined

package/src/lifecycle.ts

@@ -2,8 +2,7 @@ import type { CleanupFn, LifecycleHooks } from './types'
 
 // 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'
 
 // The currently-executing component's hook storage, set by the renderer
 // before calling the component function, cleared immediately after.

package/src/manifest.ts

@@ -249,14 +249,14 @@ const getMode = useContext(ModeCtx)    // reactive: returns () => T`,
       kind: 'component',
       signature: '<Show when={condition} fallback={alternative}>{children}</Show>',
       summary:
-        'Reactive conditional rendering. Mounts children when `when` is truthy, unmounts and shows `fallback` when falsy. More efficient than ternary for signal-driven conditions because it avoids re-evaluating the entire branch expression on every signal change — `Show` only transitions between mounted/unmounted when the boolean flips.',
+        'Reactive conditional rendering. Mounts children when `when` is truthy, unmounts and shows `fallback` when falsy. More efficient than ternary for signal-driven conditions because it avoids re-evaluating the entire branch expression on every signal change — `Show` only transitions between mounted/unmounted when the boolean flips. `when` accepts BOTH a value (`when={true}`, `when={signal()}`) and an accessor (`when={() => signal()}`) — the framework normalizes via `typeof === "function"`. The accessor form is required for true reactivity (the framework re-evaluates it on signal change); a bare `when={signal}` reference works because the compiler\'s signal auto-call rewrites it to `when={signal()}`.',
       example: `<Show when={isLoggedIn()} fallback={<LoginForm />}>
   <Dashboard />
 </Show>`,
       mistakes: [
         '`{cond() ? <A /> : <B />}` — works but less efficient than `<Show>` for signal-driven conditions',
         '`<Show when={items().length}>` — works (truthy check), but be explicit: `<Show when={items().length > 0}>`',
-        '`<Show when={user}>` without calling the signal — must call: `<Show when={user()}>`',
+        '`<Show when={signal}>` (bare reference) — relies on the compiler\'s signal auto-call to rewrite to `when={signal()}`. Works defensively but use `when={() => signal()}` for explicit accessor semantics across the entire reactive lifecycle.',
       ],
       seeAlso: ['Switch', 'Match', 'For'],
     },
@@ -284,7 +284,7 @@ const getMode = useContext(ModeCtx)    // reactive: returns () => T`,
       kind: 'component',
       signature: '<Match when={condition}>{children}</Match>',
       summary:
-        'A branch inside a `<Switch>`. Renders its children when `when` is truthy and it is the first truthy `<Match>` in the parent `<Switch>`. Must be a direct child of `<Switch>`.',
+        'A branch inside a `<Switch>`. Renders its children when `when` is truthy and it is the first truthy `<Match>` in the parent `<Switch>`. Must be a direct child of `<Switch>`. `when` accepts both a value and an accessor (same normalization as `<Show>`).',
       example: `<Switch>
   <Match when={tab() === "home"}><Home /></Match>
   <Match when={tab() === "settings"}><Settings /></Match>
@@ -481,6 +481,46 @@ return <input ref={inputRef} />`,
 })`,
       seeAlso: ['@pyreon/reactivity'],
     },
+    {
+      name: 'nativeCompat',
+      kind: 'function',
+      signature: '<T>(fn: T) => T',
+      summary:
+        'Mark a Pyreon framework component as "self-managing" so compat layers (`@pyreon/{react,preact,vue,solid}-compat`) skip their wrapping and route the component through Pyreon\'s mount path. Use on every `@pyreon/*` JSX component whose setup body uses `provide()` / lifecycle hooks / signal subscriptions — wrapping breaks those by running the body inside the compat layer\'s render context instead of Pyreon\'s. Idempotent; non-function inputs pass through unchanged. The marker is a registry symbol (`Symbol.for("pyreon:native-compat")`), so framework and compat sides share it without an import dependency between them.',
+      example: `// In a framework package:
+export const RouterView = nativeCompat(function RouterView(props) {
+  provide(RouterContext, ...)
+  return <div>{children}</div>
+})`,
+      seeAlso: ['isNativeCompat', 'NATIVE_COMPAT_MARKER'],
+      mistakes: [
+        'Forgetting to mark a new framework JSX export — under compat mode, the component\'s `provide()` / `onMount()` calls fail with "called outside component setup" warnings and the rendered DOM silently breaks.',
+        'Marking user-app components — only `@pyreon/*` framework components that already manage their own reactivity should be marked. User components in compat mode are SUPPOSED to be wrapped (that\'s how they get re-render-on-state-change semantics).',
+      ],
+    },
+    {
+      name: 'isNativeCompat',
+      kind: 'function',
+      signature: '(fn: unknown) => boolean',
+      summary:
+        'Compat-layer-side: read whether a function has been marked as a Pyreon native framework component via `nativeCompat()`. Compat `jsx()` calls this to decide whether to skip the React/Vue/Solid/Preact-style wrapping. Always returns `false` for non-function inputs.',
+      example: `// In a compat layer's jsx-runtime:
+if (isNativeCompat(type)) return h(type, props)
+return wrapCompatComponent(type)(props)`,
+      seeAlso: ['nativeCompat', 'NATIVE_COMPAT_MARKER'],
+    },
+    {
+      name: 'NATIVE_COMPAT_MARKER',
+      kind: 'constant',
+      signature: 'symbol',
+      summary:
+        'The well-known registry symbol (`Symbol.for("pyreon:native-compat")`) used to mark a component as a Pyreon native framework component. Most callers should use `nativeCompat()` / `isNativeCompat()` instead of touching the symbol directly; exported for advanced cases (e.g., a compat layer that wants to inspect the property without going through the helper).',
+      example: `import { NATIVE_COMPAT_MARKER } from '@pyreon/core'
+
+// Equivalent to nativeCompat(MyComponent):
+;(MyComponent as Record<symbol, boolean>)[NATIVE_COMPAT_MARKER] = true`,
+      seeAlso: ['nativeCompat', 'isNativeCompat'],
+    },
     {
       name: 'ExtractProps',
       kind: 'type',

package/src/show.ts

@@ -3,12 +3,25 @@ import type { Props, VNode, VNodeChild, VNodeChildAtom } from './types'
 // ─── Show ─────────────────────────────────────────────────────────────────────
 
 export interface ShowProps extends Props {
-  /** Accessor — children render when truthy, fallback when falsy. */
-  when: () => unknown
+  /**
+   * Truthy condition. Accepts a value or an accessor.
+   *
+   * Use an accessor (`() => signal()`) for reactive conditions.
+   * Bare values are accepted for static cases and as a defensive normalization
+   * for cases where the compiler's signal auto-call has already invoked
+   * a signal at the prop site (e.g. `when={mySignal}` becomes `when={mySignal()}`).
+   */
+  when: unknown | (() => unknown)
   fallback?: VNodeChild
   children?: VNodeChild
 }
 
+// Normalize a value-or-accessor `when` into a single accessor.
+// Same shape used by Match — kept inline (one branch) to stay zero-cost.
+function callWhen(when: unknown): unknown {
+  return typeof when === 'function' ? (when as () => unknown)() : when
+}
+
 /**
  * Conditionally render children based on a reactive condition.
  *
@@ -25,7 +38,7 @@ export interface ShowProps extends Props {
 export function Show(props: ShowProps): VNode | null {
   // Returns a reactive accessor; the renderer unwraps it at mount time.
   return ((): VNodeChildAtom =>
-    (props.when()
+    (callWhen(props.when)
       ? (props.children ?? null)
       : (props.fallback ?? null)) as VNodeChildAtom) as unknown as VNode
 }
@@ -33,8 +46,8 @@ export function Show(props: ShowProps): VNode | null {
 // ─── Switch / Match ───────────────────────────────────────────────────────────
 
 export interface MatchProps extends Props {
-  /** Accessor — this branch renders when truthy. */
-  when: () => unknown
+  /** Truthy condition. Accepts a value or an accessor — see {@link ShowProps.when}. */
+  when: unknown | (() => unknown)
   children?: VNodeChild
 }
 
@@ -97,7 +110,7 @@ export function Switch(props: SwitchProps): VNode | null {
     for (const branch of branches) {
       if (!isMatchVNode(branch)) continue
       const matchProps = branch.props as unknown as MatchProps
-      if (matchProps.when()) return resolveMatchChildren(branch)
+      if (callWhen(matchProps.when)) return resolveMatchChildren(branch)
     }
 
     return (props.fallback ?? null) as VNodeChildAtom

package/src/suspense.ts

@@ -3,8 +3,7 @@ import type { Props, VNode, VNodeChild } from './types'
 
 // 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'
 
 /** Internal marker attached to lazy()-wrapped components */
 export type LazyComponent<P extends Props = Props> = ((props: P) => VNodeChild) & {

package/src/telemetry.ts

@@ -1,6 +1,10 @@
 /**
  * Error telemetry — hook into Pyreon's error reporting for Sentry, Datadog, etc.
  *
+ * Captures errors from ALL lifecycle phases including reactive effects.
+ * `effect()` errors thrown by `@pyreon/reactivity` are bridged through a
+ * globalThis sink (no upward import — reactivity doesn't depend on core).
+ *
  * @example
  * import { registerErrorHandler } from "@pyreon/core"
  * import * as Sentry from "@sentry/browser"
@@ -13,7 +17,7 @@
  */
 
 export interface ErrorContext {
-  /** Component function name, or "Anonymous" */
+  /** Component function name, "Anonymous", or "Effect" for reactive effects */
   component: string
   /** Lifecycle phase where the error occurred */
   phase: 'setup' | 'render' | 'mount' | 'unmount' | 'effect'
@@ -31,10 +35,17 @@ let _handlers: ErrorHandler[] = []
 
 /**
  * Register a global error handler. Called whenever a component throws in any
- * lifecycle phase. Returns an unregister function.
+ * lifecycle phase, OR an effect throws in `@pyreon/reactivity`. Returns an
+ * unregister function.
+ *
+ * Also installs a `globalThis.__pyreon_report_error__` bridge so the
+ * reactivity package (which can't depend on core) can forward effect errors
+ * into the same telemetry pipeline. Pre-fix the two surfaces were
+ * disconnected — Sentry/Datadog wiring missed effect-thrown errors.
  */
 export function registerErrorHandler(handler: ErrorHandler): () => void {
   _handlers.push(handler)
+  _installReactivityBridge()
   return () => {
     _handlers = _handlers.filter((h) => h !== handler)
   }
@@ -53,3 +64,20 @@ export function reportError(ctx: ErrorContext): void {
     }
   }
 }
+
+// ─── Reactivity bridge ──────────────────────────────────────────────────────
+// Installs `globalThis.__pyreon_report_error__` so `@pyreon/reactivity`
+// effect-error path can forward into reportError. Idempotent — multiple
+// `registerErrorHandler` calls install once.
+
+interface PyreonErrorBridge {
+  __pyreon_report_error__?: (err: unknown, phase: 'effect') => void
+}
+const _bridgeHost = globalThis as PyreonErrorBridge
+
+function _installReactivityBridge(): void {
+  if (_bridgeHost.__pyreon_report_error__) return
+  _bridgeHost.__pyreon_report_error__ = (err, phase) => {
+    reportError({ component: 'Effect', phase, error: err, timestamp: Date.now() })
+  }
+}

package/src/tests/compat-marker.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest'
+import { isNativeCompat, NATIVE_COMPAT_MARKER, nativeCompat } from '../compat-marker'
+
+describe('NATIVE_COMPAT_MARKER', () => {
+  it('is the same registry symbol regardless of how it is referenced', () => {
+    // Symbol.for(...) registry contract — every consumer that uses the same
+    // string key (compat layers reading it, framework packages writing it)
+    // gets the SAME symbol identity. Changing the string is a breaking
+    // change to the marker contract.
+    expect(NATIVE_COMPAT_MARKER).toBe(Symbol.for('pyreon:native-compat'))
+  })
+
+  it('is a `symbol`-typed value', () => {
+    expect(typeof NATIVE_COMPAT_MARKER).toBe('symbol')
+  })
+})
+
+describe('nativeCompat', () => {
+  it('attaches the marker to a function and returns the same reference', () => {
+    function RouterView() {
+      return null
+    }
+    const marked = nativeCompat(RouterView)
+    expect(marked).toBe(RouterView)
+    expect((RouterView as unknown as Record<symbol, boolean>)[NATIVE_COMPAT_MARKER]).toBe(true)
+  })
+
+  it('is idempotent — applying twice yields the same property state', () => {
+    const Component = () => null
+    nativeCompat(Component)
+    nativeCompat(Component)
+    expect((Component as unknown as Record<symbol, boolean>)[NATIVE_COMPAT_MARKER]).toBe(true)
+  })
+
+  it('passes non-function values through unchanged', () => {
+    // Defensive: callers may pipe variables of unknown shape (e.g. lazy
+    // imports that resolve to objects, or null during HMR boundary
+    // teardown). The helper must be safe regardless.
+    expect(nativeCompat(null as unknown)).toBe(null)
+    expect(nativeCompat(undefined as unknown)).toBe(undefined)
+    const obj = { foo: 'bar' }
+    expect(nativeCompat(obj)).toBe(obj)
+    expect((obj as unknown as Record<symbol, boolean>)[NATIVE_COMPAT_MARKER]).toBeUndefined()
+  })
+
+  it('preserves the function signature for typed callers', () => {
+    // The generic `T` flows through unchanged so framework component
+    // exports keep their typed callable shape after wrapping.
+    const Typed = (props: { name: string }): string => `hello ${props.name}`
+    const marked: typeof Typed = nativeCompat(Typed)
+    expect(marked({ name: 'world' })).toBe('hello world')
+  })
+})
+
+describe('isNativeCompat', () => {
+  it('returns true for a marked function', () => {
+    const Comp = nativeCompat(() => null)
+    expect(isNativeCompat(Comp)).toBe(true)
+  })
+
+  it('returns false for an unmarked function', () => {
+    expect(isNativeCompat(() => null)).toBe(false)
+  })
+
+  it('returns false for non-function inputs', () => {
+    expect(isNativeCompat(null)).toBe(false)
+    expect(isNativeCompat(undefined)).toBe(false)
+    expect(isNativeCompat('string')).toBe(false)
+    expect(isNativeCompat(42)).toBe(false)
+    expect(isNativeCompat({ [NATIVE_COMPAT_MARKER]: true })).toBe(false)
+  })
+
+  it('returns false when the marker is set to a non-true value', () => {
+    // Defensive against accidental shape mismatch — only `=== true` qualifies.
+    function Comp() {
+      return null
+    }
+    ;(Comp as unknown as Record<symbol, unknown>)[NATIVE_COMPAT_MARKER] = 1
+    expect(isNativeCompat(Comp)).toBe(false)
+    ;(Comp as unknown as Record<symbol, unknown>)[NATIVE_COMPAT_MARKER] = 'yes'
+    expect(isNativeCompat(Comp)).toBe(false)
+  })
+
+  it('reads the same registry symbol that nativeCompat writes', () => {
+    // Cross-side contract: a function marked here is detectable by
+    // someone who looked up the symbol via `Symbol.for('pyreon:native-compat')`
+    // independently — without importing NATIVE_COMPAT_MARKER from this module.
+    const Comp = nativeCompat(function Comp() {
+      return null
+    })
+    const externallyDiscoveredSymbol = Symbol.for('pyreon:native-compat')
+    expect(
+      (Comp as unknown as Record<symbol, boolean>)[externallyDiscoveredSymbol],
+    ).toBe(true)
+  })
+})

package/src/tests/dynamic.test.ts

@@ -1,6 +1,6 @@
 import { Dynamic } from '../dynamic'
 import { h } from '../h'
-import type { ComponentFn, VNode } from '../types'
+import type { ComponentFn, VNode, VNodeChild } from '../types'
 
 describe('Dynamic', () => {
   test('renders component function', () => {
@@ -52,4 +52,36 @@ describe('Dynamic', () => {
     expect(result).not.toBeNull()
     expect((result as VNode).type).toBe('br')
   })
+
+  test('does not leak children as a prop on string-tag mount', () => {
+    // Regression: for string `component`, runtime-dom forwards every prop
+    // key to setAttribute. If `children` stayed in props it crashed at
+    // mount with `setAttribute('children', ...)`. The fix re-emits them
+    // as h() rest args, landing them in vnode.children.
+    const result = Dynamic({ component: 'h3', children: 'hello' })
+    expect((result as VNode).type).toBe('h3')
+    expect((result as VNode).props.children).toBeUndefined()
+    expect((result as VNode).children).toEqual(['hello'])
+  })
+
+  test('flattens array children to vnode.children', () => {
+    const a = h('span', null, 'a')
+    const b = h('span', null, 'b')
+    const result = Dynamic({ component: 'div', children: [a, b] })
+    expect((result as VNode).props.children).toBeUndefined()
+    expect((result as VNode).children).toHaveLength(2)
+  })
+
+  test('component children still reach props.children at mount', () => {
+    // For component (not string), the merge happens at mount via
+    // mergeChildrenIntoProps — verified end-to-end by mount tests in
+    // runtime-dom. Here we just confirm the vnode shape is correct so the
+    // merge will fire (children must be on vnode.children, not props).
+    const Comp: ComponentFn = (props) =>
+      h('div', null, (props as { children?: VNodeChild }).children ?? null)
+    const result = Dynamic({ component: Comp, children: 'hi' })
+    expect((result as VNode).type).toBe(Comp)
+    expect((result as VNode).props.children).toBeUndefined()
+    expect((result as VNode).children).toEqual(['hi'])
+  })
 })