@pyreon/core 0.13.1 → 0.15.0

package/lib/types/index.d.ts

@@ -1,6 +1,8 @@
 //#region src/types.d.ts
 type VNodeChildAtom = VNode | string | number | boolean | null | undefined;
-type VNodeChild = VNodeChildAtom | VNodeChildAtom[] | (() => VNodeChildAtom | VNodeChildAtom[]);
+/** Reactive accessor — TS checks this arm FIRST so `{() => cond && <X />}` resolves correctly */
+type VNodeChildAccessor = () => VNodeChildAtom | VNodeChildAtom[];
+type VNodeChild = VNodeChildAccessor | VNodeChildAtom | VNodeChildAtom[];
 interface VNode {
   /** Tag name, component function, or special symbol (Fragment) */
   type: string | ComponentFn | symbol;
@@ -39,11 +41,11 @@ interface NativeItem {
   cleanup: (() => void) | null;
 }
 interface LifecycleHooks {
-  mount: (() => CleanupFn | void | undefined)[];
-  unmount: (() => void)[];
-  update: (() => void)[];
+  mount: (() => CleanupFn | void | undefined)[] | null;
+  unmount: (() => void)[] | null;
+  update: (() => void)[] | null;
   /** Error handlers — return true to mark the error as handled (stops propagation). */
-  error: ((err: unknown) => boolean | undefined)[];
+  error: ((err: unknown) => boolean | undefined)[] | null;
 }
 //#endregion
 //#region src/component.d.ts
@@ -73,6 +75,74 @@ declare function propagateError(err: unknown, hooks: LifecycleHooks): boolean;
  */
 declare function dispatchToErrorBoundary(err: unknown): boolean;
 //#endregion
+//#region src/compat-marker.d.ts
+/**
+ * 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()`).
+ */
+declare const NATIVE_COMPAT_MARKER: symbol;
+/**
+ * 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>
+ *   })
+ */
+declare function nativeCompat<T>(fn: T): T;
+/**
+ * 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)
+ */
+declare function isNativeCompat(fn: unknown): boolean;
+//#endregion
 //#region src/context.d.ts
 /**
  * Provide / inject — like React context or Vue provide/inject.
@@ -153,7 +223,16 @@ type ContextSnapshot = Map<symbol, unknown>[];
 declare 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.
  */
 declare function restoreContextStack<T>(snapshot: ContextSnapshot, fn: () => T): T;
 //#endregion
@@ -363,6 +442,7 @@ interface PyreonHTMLAttributes<E extends Element = HTMLElement> {
   } | undefined;
   onClick?: ((e: TargetedEvent<E, MouseEvent>) => void) | undefined;
   onDblClick?: ((e: TargetedEvent<E, MouseEvent>) => void) | undefined;
+  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;
@@ -426,7 +506,7 @@ interface InputAttributes extends PyreonHTMLAttributes<HTMLInputElement> {
   defaultChecked?: boolean | undefined;
   placeholder?: string | (() => string) | undefined;
   disabled?: boolean | (() => boolean) | undefined;
-  readOnly?: boolean | undefined;
+  readOnly?: boolean | (() => boolean) | undefined;
   required?: boolean | (() => boolean) | undefined;
   min?: string | number | undefined;
   max?: string | number | undefined;
@@ -475,7 +555,7 @@ interface TextareaAttributes extends PyreonHTMLAttributes<HTMLTextAreaElement> {
   defaultValue?: string | undefined;
   placeholder?: string | (() => string) | undefined;
   disabled?: boolean | (() => boolean) | undefined;
-  readOnly?: boolean | undefined;
+  readOnly?: boolean | (() => boolean) | undefined;
   required?: boolean | (() => boolean) | undefined;
   rows?: number | undefined;
   cols?: number | undefined;
@@ -1029,8 +1109,15 @@ declare function createUniqueId(): string;
 //#endregion
 //#region src/show.d.ts
 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;
 }
@@ -1049,8 +1136,8 @@ interface ShowProps extends Props {
  */
 declare function Show(props: ShowProps): VNode | null;
 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;
 }
 /**
@@ -1073,6 +1160,10 @@ declare const MatchSymbol: unique symbol;
 /**
  * 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"
@@ -1084,7 +1175,7 @@ declare const MatchSymbol: unique symbol;
  * })
  */
 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';
@@ -1098,7 +1189,13 @@ interface ErrorContext {
 type ErrorHandler = (ctx: ErrorContext) => void;
 /**
  * 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.
  */
 declare function registerErrorHandler(handler: ErrorHandler): () => void;
 /**
@@ -1107,5 +1204,5 @@ declare function registerErrorHandler(handler: ErrorHandler): () => void;
  */
 declare function reportError(ctx: ErrorContext): void;
 //#endregion
-export { type AnchorAttributes, type ButtonAttributes, type CSSProperties, CSS_UNITLESS, type ClassValue, type CleanupFn, type ComponentFn, type ComponentInstance, type Context, type ContextSnapshot, Dynamic, type DynamicProps, EMPTY_PROPS, ErrorBoundary, type ErrorContext, type ErrorHandler, type ExtractProps, For, type ForProps, ForSymbol, type FormAttributes, Fragment, type HigherOrderComponent, type ImgAttributes, type InputAttributes, type LazyComponent, type LifecycleHooks, Match, type MatchProps, MatchSymbol, type NativeItem, Portal, type PortalProps, PortalSymbol, type Props, type PyreonHTMLAttributes, REACTIVE_PROP, type ReactiveContext, type Ref, type RefCallback, type RefProp, type SelectAttributes, Show, type ShowProps, type StyleValue, Suspense, type SvgAttributes, Switch, type SwitchProps, type TargetedEvent, type TextareaAttributes, type VNode, type VNodeChild, type VNodeChildAtom, _rp, captureContextStack, createContext, createReactiveContext, createRef, createUniqueId, cx, defineComponent, dispatchToErrorBoundary, h, lazy, makeReactiveProps, mapArray, mergeProps, normalizeStyleValue, onErrorCaptured, onMount, onUnmount, onUpdate, popContext, propagateError, provide, pushContext, registerErrorHandler, reportError, restoreContextStack, runWithHooks, setContextStackProvider, splitProps, toKebabCase, useContext, withContext };
+export { type AnchorAttributes, type ButtonAttributes, type CSSProperties, CSS_UNITLESS, type ClassValue, type CleanupFn, type ComponentFn, type ComponentInstance, type Context, type ContextSnapshot, Dynamic, type DynamicProps, EMPTY_PROPS, ErrorBoundary, type ErrorContext, type ErrorHandler, type ExtractProps, For, type ForProps, ForSymbol, type FormAttributes, Fragment, type HigherOrderComponent, type ImgAttributes, type InputAttributes, type LazyComponent, type LifecycleHooks, Match, type MatchProps, MatchSymbol, NATIVE_COMPAT_MARKER, type NativeItem, Portal, type PortalProps, PortalSymbol, type Props, type PyreonHTMLAttributes, REACTIVE_PROP, type ReactiveContext, type Ref, type RefCallback, type RefProp, type SelectAttributes, Show, type ShowProps, type StyleValue, Suspense, type SvgAttributes, Switch, type SwitchProps, type TargetedEvent, type TextareaAttributes, type VNode, type VNodeChild, type VNodeChildAccessor, type VNodeChildAtom, _rp, captureContextStack, createContext, createReactiveContext, createRef, createUniqueId, cx, defineComponent, dispatchToErrorBoundary, h, isNativeCompat, lazy, makeReactiveProps, mapArray, mergeProps, nativeCompat, normalizeStyleValue, onErrorCaptured, onMount, onUnmount, onUpdate, popContext, propagateError, provide, pushContext, registerErrorHandler, reportError, restoreContextStack, runWithHooks, setContextStackProvider, splitProps, toKebabCase, useContext, withContext };
 //# sourceMappingURL=index2.d.ts.map

package/lib/types/jsx-dev-runtime.d.ts

@@ -1,6 +1,8 @@
 //#region src/types.d.ts
 type VNodeChildAtom = VNode | string | number | boolean | null | undefined;
-type VNodeChild = VNodeChildAtom | VNodeChildAtom[] | (() => VNodeChildAtom | VNodeChildAtom[]);
+/** Reactive accessor — TS checks this arm FIRST so `{() => cond && <X />}` resolves correctly */
+type VNodeChildAccessor = () => VNodeChildAtom | VNodeChildAtom[];
+type VNodeChild = VNodeChildAccessor | VNodeChildAtom | VNodeChildAtom[];
 interface VNode {
   /** Tag name, component function, or special symbol (Fragment) */
   type: string | ComponentFn | symbol;
@@ -133,6 +135,7 @@ interface PyreonHTMLAttributes<E extends Element = HTMLElement> {
   } | undefined;
   onClick?: ((e: TargetedEvent<E, MouseEvent>) => void) | undefined;
   onDblClick?: ((e: TargetedEvent<E, MouseEvent>) => void) | undefined;
+  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;
@@ -196,7 +199,7 @@ interface InputAttributes extends PyreonHTMLAttributes<HTMLInputElement> {
   defaultChecked?: boolean | undefined;
   placeholder?: string | (() => string) | undefined;
   disabled?: boolean | (() => boolean) | undefined;
-  readOnly?: boolean | undefined;
+  readOnly?: boolean | (() => boolean) | undefined;
   required?: boolean | (() => boolean) | undefined;
   min?: string | number | undefined;
   max?: string | number | undefined;
@@ -245,7 +248,7 @@ interface TextareaAttributes extends PyreonHTMLAttributes<HTMLTextAreaElement> {
   defaultValue?: string | undefined;
   placeholder?: string | (() => string) | undefined;
   disabled?: boolean | (() => boolean) | undefined;
-  readOnly?: boolean | undefined;
+  readOnly?: boolean | (() => boolean) | undefined;
   required?: boolean | (() => boolean) | undefined;
   rows?: number | undefined;
   cols?: number | undefined;

package/lib/types/jsx-runtime.d.ts

@@ -1,6 +1,8 @@
 //#region src/types.d.ts
 type VNodeChildAtom = VNode | string | number | boolean | null | undefined;
-type VNodeChild = VNodeChildAtom | VNodeChildAtom[] | (() => VNodeChildAtom | VNodeChildAtom[]);
+/** Reactive accessor — TS checks this arm FIRST so `{() => cond && <X />}` resolves correctly */
+type VNodeChildAccessor = () => VNodeChildAtom | VNodeChildAtom[];
+type VNodeChild = VNodeChildAccessor | VNodeChildAtom | VNodeChildAtom[];
 interface VNode {
   /** Tag name, component function, or special symbol (Fragment) */
   type: string | ComponentFn | symbol;
@@ -133,6 +135,7 @@ interface PyreonHTMLAttributes<E extends Element = HTMLElement> {
   } | undefined;
   onClick?: ((e: TargetedEvent<E, MouseEvent>) => void) | undefined;
   onDblClick?: ((e: TargetedEvent<E, MouseEvent>) => void) | undefined;
+  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;
@@ -196,7 +199,7 @@ interface InputAttributes extends PyreonHTMLAttributes<HTMLInputElement> {
   defaultChecked?: boolean | undefined;
   placeholder?: string | (() => string) | undefined;
   disabled?: boolean | (() => boolean) | undefined;
-  readOnly?: boolean | undefined;
+  readOnly?: boolean | (() => boolean) | undefined;
   required?: boolean | (() => boolean) | undefined;
   min?: string | number | undefined;
   max?: string | number | undefined;
@@ -245,7 +248,7 @@ interface TextareaAttributes extends PyreonHTMLAttributes<HTMLTextAreaElement> {
   defaultValue?: string | undefined;
   placeholder?: string | (() => string) | undefined;
   disabled?: boolean | (() => boolean) | undefined;
-  readOnly?: boolean | undefined;
+  readOnly?: boolean | (() => boolean) | undefined;
   required?: boolean | (() => boolean) | undefined;
   rows?: number | undefined;
   cols?: number | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/core",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description": "Core component model and lifecycle for Pyreon",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/core#readme",
   "bugs": {
@@ -14,6 +14,7 @@
   },
   "files": [
     "lib",
+    "!lib/**/*.map",
     "src",
     "README.md",
     "LICENSE"
@@ -52,7 +53,7 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@pyreon/reactivity": "^0.13.1"
+    "@pyreon/reactivity": "^0.15.0"
   },
   "devDependencies": {
     "@pyreon/manifest": "0.13.1"

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/component.ts

@@ -19,7 +19,7 @@ export function runWithHooks<P extends Props>(
   fn: ComponentFn<P>,
   props: P,
 ): { vnode: VNodeChild; hooks: LifecycleHooks } {
-  const hooks: LifecycleHooks = { mount: [], unmount: [], update: [], error: [] }
+  const hooks: LifecycleHooks = { mount: null, unmount: null, update: null, error: null }
   setCurrentHooks(hooks)
   let vnode: VNodeChild = null
   try {
@@ -35,6 +35,7 @@ export function runWithHooks<P extends Props>(
  * Returns true if any handler marked the error as handled.
  */
 export function propagateError(err: unknown, hooks: LifecycleHooks): boolean {
+  if (!hooks.error) return false
   for (const handler of hooks.error) {
     if (handler(err) === true) return 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,
@@ -61,5 +62,6 @@ export type {
   Props,
   VNode,
   VNodeChild,
+  VNodeChildAccessor,
   VNodeChildAtom,
 } from './types'

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