@pyreon/core 0.14.0 → 0.16.0

package/lib/types/index.d.ts

@@ -16,8 +16,41 @@ type Props = Record<string, unknown>;
  * It returns any renderable content and may call lifecycle hooks during setup.
  */
 type ComponentFn<P extends Props = Props> = (props: P) => VNodeChild;
-/** Extract the props type from a component function, or pass through if already a props type. */
-type ExtractProps<T> = T extends ComponentFn<infer P> ? P : T;
+/**
+ * Extract the props type from a component function, or pass through if already
+ * a props type. **Multi-overload aware** — matches up to 4 call signatures and
+ * produces the UNION of their first-argument types. A single-overload function
+ * still works (the union of 4 copies of the same props type dedupes back to
+ * the single shape).
+ *
+ * **Why this shape**. `T extends (props: infer P) => any ? P : never` only
+ * captures the LAST overload of a multi-overload function — TS's overload-
+ * resolution-against-conditional-types semantics. Multi-overload primitives
+ * (Iterator, List, Element, etc.) need the union of every overload's props
+ * to survive HOC wrapping (`rocketstyle()`, `attrs()`) without silently
+ * downgrading the public prop surface to the loosest overload. Mirrors
+ * vitus-labs PR #222.
+ *
+ * @example
+ * function Iterator<T extends SimpleValue>(p: { data: T[]; valueName?: string }): VNodeChild
+ * function Iterator<T extends ObjectValue>(p: { data: T[]; component: ComponentFn<T> }): VNodeChild
+ * type Props = ExtractProps<typeof Iterator>
+ * // → { data: SimpleValue[]; valueName?: string }
+ * //  | { data: ObjectValue[]; component: ComponentFn<ObjectValue> }
+ */
+type ExtractProps<T> = T extends {
+  (props: infer P1, ...args: any): any;
+  (props: infer P2, ...args: any): any;
+  (props: infer P3, ...args: any): any;
+  (props: infer P4, ...args: any): any;
+} ? P1 | P2 | P3 | P4 : T extends {
+  (props: infer P1, ...args: any): any;
+  (props: infer P2, ...args: any): any;
+  (props: infer P3, ...args: any): any;
+} ? P1 | P2 | P3 : T extends {
+  (props: infer P1, ...args: any): any;
+  (props: infer P2, ...args: any): any;
+} ? P1 | P2 : T extends ComponentFn<infer P> ? P : T;
 /** A higher-order component that wraps a component, optionally transforming its props. */
 type HigherOrderComponent<HOP extends Props, P extends Props | undefined = undefined> = (Component: ComponentFn<HOP>) => ComponentFn<P extends undefined ? HOP : P>;
 /**
@@ -75,6 +108,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.
@@ -155,7 +256,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
@@ -205,7 +315,19 @@ declare function ErrorBoundary(props: {
  */
 declare const ForSymbol: unique symbol;
 interface ForProps<T> {
-  each: () => T[];
+  /**
+   * The list to iterate. Accepts EITHER a function returning the array
+   * (preferred — keeps reactivity intact when the array comes from a
+   * signal accessor) OR the array directly (convenient for static lists
+   * or already-resolved arrays). The runtime in `runtime-dom/src/mount.ts`
+   * normalizes both shapes; this type matches the runtime so users aren't
+   * forced to write `each={() => items}` for a plain array.
+   *
+   * @example
+   * <For each={items}>{r => <li>{r.label}</li>}</For>           // static
+   * <For each={() => store.items()}>{r => <li>...</li>}</For>   // reactive
+   */
+  each: T[] | (() => T[]);
   /** Keying function — use `by` not `key` (JSX extracts `key` for VNode reconciliation). */
   by: (item: T) => string | number;
   children: (item: T) => VNode | NativeItem;
@@ -229,8 +351,22 @@ interface ForProps<T> {
 declare function For<T>(props: ForProps<T>): VNode;
 //#endregion
 //#region src/h.d.ts
-/** Marker for fragment nodes — renders children without a wrapper element */
-declare const Fragment: unique symbol;
+/**
+ * Marker for fragment nodes — renders children without a wrapper element.
+ *
+ * MUST use `Symbol.for(...)` (global registry, keyed by string), NOT
+ * `Symbol(...)` (fresh per evaluation). `h.ts` is inlined into BOTH the
+ * main `lib/index.js` and the `lib/jsx-runtime.js` published bundles —
+ * each bundle's evaluation of a bare `Symbol(...)` would produce a
+ * DISTINCT Symbol identity. JSX `<>` compiles to `jsx(Fragment, ...)` and
+ * resolves to jsx-runtime's identity; `runtime-server` checks
+ * `vnode.type === Fragment` against the main-entry identity. Mismatch
+ * fell through to `renderElement` and crashed SSG with
+ * `TypeError: Cannot convert a Symbol value to a string`.
+ * `Symbol.for()` keys by string in a global registry shared across all
+ * bundle evaluations — same identity everywhere.
+ */
+declare const Fragment: symbol;
 /**
  * Hyperscript function — the compiled output of JSX.
  * `<div class="x">hello</div>` → `h("div", { class: "x" }, "hello")`
@@ -365,6 +501,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;
@@ -428,7 +565,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;
@@ -477,7 +614,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;
@@ -1031,8 +1168,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;
 }
@@ -1051,8 +1195,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;
 }
 /**
@@ -1075,6 +1219,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"
@@ -1086,7 +1234,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';
@@ -1100,7 +1248,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;
 /**
@@ -1109,5 +1263,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 VNodeChildAccessor, 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

@@ -18,8 +18,22 @@ type Props = Record<string, unknown>;
 type ComponentFn<P extends Props = Props> = (props: P) => VNodeChild;
 //#endregion
 //#region src/h.d.ts
-/** Marker for fragment nodes — renders children without a wrapper element */
-declare const Fragment: unique symbol;
+/**
+ * Marker for fragment nodes — renders children without a wrapper element.
+ *
+ * MUST use `Symbol.for(...)` (global registry, keyed by string), NOT
+ * `Symbol(...)` (fresh per evaluation). `h.ts` is inlined into BOTH the
+ * main `lib/index.js` and the `lib/jsx-runtime.js` published bundles —
+ * each bundle's evaluation of a bare `Symbol(...)` would produce a
+ * DISTINCT Symbol identity. JSX `<>` compiles to `jsx(Fragment, ...)` and
+ * resolves to jsx-runtime's identity; `runtime-server` checks
+ * `vnode.type === Fragment` against the main-entry identity. Mismatch
+ * fell through to `renderElement` and crashed SSG with
+ * `TypeError: Cannot convert a Symbol value to a string`.
+ * `Symbol.for()` keys by string in a global registry shared across all
+ * bundle evaluations — same identity everywhere.
+ */
+declare const Fragment: symbol;
 //#endregion
 //#region src/ref.d.ts
 /**
@@ -135,6 +149,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;
@@ -198,7 +213,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;
@@ -247,7 +262,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

@@ -18,8 +18,22 @@ type Props = Record<string, unknown>;
 type ComponentFn<P extends Props = Props> = (props: P) => VNodeChild;
 //#endregion
 //#region src/h.d.ts
-/** Marker for fragment nodes — renders children without a wrapper element */
-declare const Fragment: unique symbol;
+/**
+ * Marker for fragment nodes — renders children without a wrapper element.
+ *
+ * MUST use `Symbol.for(...)` (global registry, keyed by string), NOT
+ * `Symbol(...)` (fresh per evaluation). `h.ts` is inlined into BOTH the
+ * main `lib/index.js` and the `lib/jsx-runtime.js` published bundles —
+ * each bundle's evaluation of a bare `Symbol(...)` would produce a
+ * DISTINCT Symbol identity. JSX `<>` compiles to `jsx(Fragment, ...)` and
+ * resolves to jsx-runtime's identity; `runtime-server` checks
+ * `vnode.type === Fragment` against the main-entry identity. Mismatch
+ * fell through to `renderElement` and crashed SSG with
+ * `TypeError: Cannot convert a Symbol value to a string`.
+ * `Symbol.for()` keys by string in a global registry shared across all
+ * bundle evaluations — same identity everywhere.
+ */
+declare const Fragment: symbol;
 //#endregion
 //#region src/ref.d.ts
 /**
@@ -135,6 +149,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;
@@ -198,7 +213,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;
@@ -247,7 +262,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.14.0",
+  "version": "0.16.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.14.0"
+    "@pyreon/reactivity": "^0.16.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/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/for.ts

@@ -7,7 +7,19 @@ import type { NativeItem, Props, VNode } from './types'
 export const ForSymbol: unique symbol = Symbol('pyreon.For')
 
 export interface ForProps<T> {
-  each: () => T[]
+  /**
+   * The list to iterate. Accepts EITHER a function returning the array
+   * (preferred — keeps reactivity intact when the array comes from a
+   * signal accessor) OR the array directly (convenient for static lists
+   * or already-resolved arrays). The runtime in `runtime-dom/src/mount.ts`
+   * normalizes both shapes; this type matches the runtime so users aren't
+   * forced to write `each={() => items}` for a plain array.
+   *
+   * @example
+   * <For each={items}>{r => <li>{r.label}</li>}</For>           // static
+   * <For each={() => store.items()}>{r => <li>...</li>}</For>   // reactive
+   */
+  each: T[] | (() => T[])
   /** Keying function — use `by` not `key` (JSX extracts `key` for VNode reconciliation). */
   by: (item: T) => string | number
   children: (item: T) => VNode | NativeItem