@pyreon/core 0.14.0 → 0.16.0

package/src/h.ts

@@ -1,7 +1,21 @@
 import type { ComponentFn, Props, VNode, VNodeChild } from './types'
 
-/** Marker for fragment nodes — renders children without a wrapper element */
-export const Fragment: unique symbol = Symbol('Pyreon.Fragment')
+/**
+ * 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.
+ */
+export const Fragment: symbol = Symbol.for('Pyreon.Fragment')
 
 /**
  * Hyperscript function — the compiled output of JSX.

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,14 +481,62 @@ 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',
-      signature: 'type ExtractProps<T> = T extends ComponentFn<infer P> ? P : T',
+      signature:
+        'type ExtractProps<T> = /* matches up to 4 overloads, unions the props */ T extends ComponentFn<infer P> ? P : T',
       summary:
-        'Extracts the props type from a `ComponentFn`. Passes through unchanged if `T` is not a `ComponentFn`. Useful for HOC patterns and typed wrappers that need to infer the wrapped component\'s prop interface.',
-      example: `const Greet: ComponentFn<{ name: string }> = ({ name }) => <h1>{name}</h1>
-type Props = ExtractProps<typeof Greet>  // { name: string }`,
+        "Extracts the props type from a `ComponentFn`. Passes through unchanged if `T` is not a `ComponentFn`. **Multi-overload aware** — matches up to 4 call signatures and produces the UNION of their first-argument types. Critical for multi-overload primitives (Iterator, List, Element) whose loosest overload is last; without overload-aware extraction, HOC wrapping (`rocketstyle()`, `attrs()`) silently downgraded their public prop surface. Single-overload functions still work — the union of 4 copies of the same props type dedupes back to the single shape.",
+      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> }`,
+      mistakes: [
+        'Assuming `ExtractProps<T>` returns only the LAST overload — pre-fix it did, post-fix it returns the UNION of up to 4 overloads. Functions with more than 4 overloads still drop the extras.',
+        'Using `T extends (props: infer P) => any ? P : never` directly in user code — that pattern captures only the LAST overload of a multi-overload function. Use `ExtractProps<T>` to get the full union.',
+      ],
       seeAlso: ['HigherOrderComponent'],
     },
     {

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/core.test.ts

@@ -982,7 +982,7 @@ describe('lifecycle hooks', () => {
 
 describe('edge cases', () => {
   test('h() with empty children array', () => {
-    const node = h('div', null, ...[])
+    const node = h('div', null, )
     expect(node.children).toEqual([])
   })
 

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'])
+  })
 })

package/src/tests/extract-props-overloads.types.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Compile-time type tests for `ExtractProps` multi-overload narrowing.
+ *
+ * Regression: pre-fix, `ExtractProps<T>` collapsed multi-overload functions
+ * to the LAST overload's props — TS's overload-resolution-against-conditional-
+ * types semantics. Multi-overload primitives (Iterator / List / Element in
+ * `@pyreon/elements`) silently downgraded their public prop surface to the
+ * loosest overload when wrapped through `rocketstyle()` / `attrs()`. The
+ * fix matches up to 4 call signatures via pattern matching and produces the
+ * UNION of every overload's first-argument type.
+ *
+ * Mirrors vitus-labs PR #222. Kept in sync across the 4 copies in
+ * `@pyreon/core`, `@pyreon/elements`, `@pyreon/attrs`, and `@pyreon/rocketstyle`
+ * — the canonical reference test lives here.
+ */
+
+import { describe, expectTypeOf, it } from 'vitest'
+import type { ComponentFn, ExtractProps, VNodeChild } from '../index'
+
+describe('ExtractProps — single-overload functions still work', () => {
+  it('extracts props from a ComponentFn<P>', () => {
+    type Greet = ComponentFn<{ name: string }>
+    expectTypeOf<ExtractProps<Greet>>().toEqualTypeOf<{ name: string }>()
+  })
+
+  it('extracts props from a bare (props: P) => any signature', () => {
+    type Fn = (props: { count: number }) => string
+    expectTypeOf<ExtractProps<Fn>>().toEqualTypeOf<{ count: number }>()
+  })
+
+  it('passes through a non-function shape unchanged', () => {
+    type Props = { id: string; value: number }
+    expectTypeOf<ExtractProps<Props>>().toEqualTypeOf<Props>()
+  })
+})
+
+describe('ExtractProps — multi-overload narrowing (load-bearing assertions)', () => {
+  it('unions both arms of a 2-overload function', () => {
+    interface TwoOverloads {
+      (props: { kind: 'a'; value: number }): VNodeChild
+      (props: { kind: 'b'; value: string }): VNodeChild
+    }
+    type Props = ExtractProps<TwoOverloads>
+    // Both shapes appear in the extracted union.
+    expectTypeOf<Props>().toEqualTypeOf<
+      { kind: 'a'; value: number } | { kind: 'b'; value: string }
+    >()
+  })
+
+  it('unions all three arms of a 3-overload function (Iterator/List/Element shape)', () => {
+    interface ThreeOverloads {
+      (props: { mode: 'simple'; data: string[] }): VNodeChild
+      (props: { mode: 'object'; data: { id: number }[] }): VNodeChild
+      (props: { mode: 'children'; children: unknown }): VNodeChild
+    }
+    type Props = ExtractProps<ThreeOverloads>
+    expectTypeOf<Props>().toEqualTypeOf<
+      | { mode: 'simple'; data: string[] }
+      | { mode: 'object'; data: { id: number }[] }
+      | { mode: 'children'; children: unknown }
+    >()
+  })
+
+  it('unions all four arms of a 4-overload function', () => {
+    interface FourOverloads {
+      (props: { variant: 'a' }): VNodeChild
+      (props: { variant: 'b' }): VNodeChild
+      (props: { variant: 'c' }): VNodeChild
+      (props: { variant: 'd' }): VNodeChild
+    }
+    type Props = ExtractProps<FourOverloads>
+    expectTypeOf<Props>().toEqualTypeOf<
+      { variant: 'a' } | { variant: 'b' } | { variant: 'c' } | { variant: 'd' }
+    >()
+  })
+})
+
+describe('ExtractProps — bisect-load-bearing: pre-fix shape would FAIL these', () => {
+  /**
+   * If `ExtractProps<T>` were reverted to `T extends ComponentFn<infer P> ? P : T`,
+   * each of these would extract only the LAST overload's props and the
+   * `toEqualTypeOf<union>` check would fail at compile time. This is the
+   * structural anchor — the load-bearing regression guard.
+   */
+
+  it('a 2-overload function MUST extract BOTH arms (not just the last)', () => {
+    interface OverloadedComp {
+      (props: { mode: 'a'; valueA: number }): VNodeChild
+      (props: { mode: 'b'; valueB: string }): VNodeChild
+    }
+    // The first arm `{ mode: 'a'; valueA: number }` must be present in the
+    // union. Pre-fix, the conditional collapsed to just the LAST arm.
+    type Props = ExtractProps<OverloadedComp>
+    // Assignability check: both shapes must be assignable to the extracted type.
+    const a: Props = { mode: 'a', valueA: 1 }
+    const b: Props = { mode: 'b', valueB: 'x' }
+    void a
+    void b
+  })
+
+  it("a 3-overload Iterator-shaped surface MUST surface SimpleProps + ObjectProps + ChildrenProps", () => {
+    // Synthetic Iterator overload-shape — mirrors the real
+    // `@pyreon/elements` Iterator. The structural failure mode pre-fix:
+    // `ExtractProps<typeof Iterator>` returned just `ChildrenProps`, so any
+    // HOC wrapping (rocketstyle, attrs) lost the SimpleProps + ObjectProps
+    // surfaces from the public typed API.
+    type SimpleItem = ComponentFn<{ value: string }>
+    type ObjectItem = ComponentFn<{ id: number }>
+    interface IteratorLike {
+      <T extends string | number>(props: {
+        data: T[]
+        component: SimpleItem
+        valueName?: string
+      }): VNodeChild
+      <T extends { id: number }>(props: {
+        data: T[]
+        component: ObjectItem
+      }): VNodeChild
+      (props: { children: VNodeChild }): VNodeChild
+    }
+    type Props = ExtractProps<IteratorLike>
+
+    const noopSimple: SimpleItem = () => null
+    const noopObject: ObjectItem = () => null
+    // SimpleProps arm assignable:
+    const simple: Props = { data: ['a', 'b'], component: noopSimple, valueName: 'text' }
+    // ObjectProps arm assignable:
+    const obj: Props = { data: [{ id: 1 }], component: noopObject }
+    // ChildrenProps arm assignable:
+    const ch: Props = { children: null }
+    void simple
+    void obj
+    void ch
+  })
+})

package/src/tests/for.test.ts

@@ -91,4 +91,27 @@ describe('For', () => {
     expect((result as VNode).type).toBe('li')
     expect((result as VNode).key).toBe(1)
   })
+
+  // Regression: `ForProps.each` previously typed as `() => T[]` only.
+  // Users writing `<For each={items}>` (with `items: T[]` directly) hit
+  // a confusing TS error: `Type 'T[]' is not assignable to type
+  // '() => T[]'`. The runtime in `runtime-dom/src/mount.ts:144-147`
+  // already accepted both shapes — only the type was forcing the
+  // accessor form. Type now accepts `T[] | (() => T[])` so users with
+  // already-resolved arrays don't need to wrap them in a thunk just to
+  // satisfy the type.
+  test('each accepts T[] directly (not just () => T[])', () => {
+    // TypeScript-level test: this would not compile pre-fix.
+    const items = [1, 2, 3]
+    const childFn = (n: number): VNode => h('li', { key: n }, String(n))
+    const node = For<number>({ each: items, by: (n) => n, children: childFn })
+    expect(node.type).toBe(ForSymbol as unknown as string)
+    // Both shapes still work — function form continues to typecheck.
+    const node2 = For<number>({
+      each: () => items,
+      by: (n) => n,
+      children: childFn,
+    })
+    expect(node2.type).toBe(ForSymbol as unknown as string)
+  })
 })