@pyreon/core 0.15.0 → 0.18.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>;
 /**
@@ -282,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;
@@ -306,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")`
@@ -952,6 +1011,89 @@ declare global {
   }
 } //# sourceMappingURL=jsx-runtime.d.ts.map
 //#endregion
+//#region src/defer.d.ts
+/**
+ * Module shape `<Defer>` accepts from `chunk()`. Mirrors `lazy()`'s
+ * contract — either an ES module with `default` export, OR a raw
+ * `ComponentFn` returned directly (rare; covers re-export patterns).
+ */
+type ChunkResult<P extends Props> = {
+  default: ComponentFn<P>;
+} | ComponentFn<P>;
+/**
+ * Trigger discriminant. Exactly ONE shape is provided:
+ *   - `when={() => signal()}` — load when the accessor becomes truthy
+ *   - `on="visible"`         — load when the wrapper enters the viewport
+ *   - `on="idle"`            — load during browser idle time
+ */
+type DeferTrigger = {
+  when: () => boolean;
+} | {
+  on: 'visible' | 'idle';
+};
+/**
+ * Set up the `on="idle"` trigger. Returns a teardown function the
+ * caller must invoke on unmount. Browser-API access is gated by
+ * `typeof` checks so SSR / jsdom environments fall back to a
+ * `setTimeout(1)` shim. Extracted as a standalone helper so it's
+ * directly testable without going through `onMount` (core tests
+ * don't run in happy-dom; runtime-dom is where the lifecycle hooks
+ * live).
+ *
+ * @internal Exported for tests; not part of the stable public API.
+ */
+type DeferProps<P extends Props> = DeferTrigger & {
+  /**
+   * Dynamic import to lazy-load. The literal `import('./X')` is what
+   * Rolldown / Vite see when emitting chunks — using a variable here
+   * defeats code splitting.
+   */
+  chunk: () => Promise<ChunkResult<P>>;
+  /**
+   * Render-prop for the loaded component. Receives the resolved component
+   * and returns its JSX with whatever props the parent needs to pass.
+   * Optional — omitting it renders `<Comp />` with no props.
+   */
+  children?: (Component: ComponentFn<P>) => VNodeChild; /** Shown while the chunk is loading. Default: `null`. */
+  fallback?: VNodeChild;
+  /**
+   * IntersectionObserver `rootMargin` for `on="visible"` mode. Default
+   * `'200px'` — start loading the chunk before the wrapper is fully in
+   * view so it's typically ready by the time the user scrolls to it.
+   */
+  rootMargin?: string;
+};
+/**
+ * Lazy-load a chunk when a trigger condition is met.
+ *
+ * Three trigger modes:
+ *   - `when={() => signal()}` — load when condition flips truthy (modal pattern)
+ *   - `on="visible"`         — load when the wrapper scrolls into view
+ *   - `on="idle"`            — load during browser idle time
+ *
+ * The chunk fetch is fired exactly once per `Defer` instance — repeated
+ * trigger firings after the chunk loads are no-ops.
+ *
+ * @example
+ * // Signal-driven (modal):
+ * <Defer chunk={() => import('./ConfirmDeleteModal')} when={open}>
+ *   {Modal => <Modal onClose={() => setOpen(false)} />}
+ * </Defer>
+ *
+ * @example
+ * // Viewport-driven (below-fold):
+ * <Defer chunk={() => import('./Comments')} on="visible">
+ *   {Comments => <Comments postId={id} />}
+ * </Defer>
+ *
+ * @example
+ * // Idle-driven (non-critical):
+ * <Defer chunk={() => import('./Analytics')} on="idle">
+ *   {Dashboard => <Dashboard />}
+ * </Defer>
+ */
+declare function Defer<P extends Props>(props: DeferProps<P>): VNode;
+//#endregion
 //#region src/suspense.d.ts
 /** Internal marker attached to lazy()-wrapped components */
 type LazyComponent<P extends Props = Props> = ((props: P) => VNodeChild) & {
@@ -1085,6 +1227,34 @@ declare const REACTIVE_PROP: unique symbol;
  * Called by the compiler for component prop expressions containing signal reads.
  */
 declare function _rp<T>(fn: () => T): () => T;
+/**
+ * Wrap a JSX spread source so its getter-shaped reactive props survive
+ * the JS-level object spread that esbuild's automatic JSX runtime emits
+ * for `<Comp {...source}>`.
+ *
+ * Without this wrapper, esbuild compiles `<Comp {...source}>` to
+ * `jsx(Comp, { ...source })` — and JS spread fires every getter on
+ * `source`, storing the resolved values as plain data properties. Any
+ * compiler-emitted reactive prop (`_rp(() => signal())` converted to a
+ * getter by `makeReactiveProps`) on `source` is collapsed to its
+ * initial value before the receiving component ever sees it.
+ *
+ * `_wrapSpread(source)` walks `source`'s own keys via `Reflect.ownKeys`
+ * (no getter firing) and returns a new object whose values are
+ * `_rp`-branded thunks `() => source[key]`. When `{ ..._wrapSpread(s) }`
+ * is spread by esbuild, the thunks are stored as plain data property
+ * values (no getters to fire), then `makeReactiveProps` in `mount.ts`
+ * converts the brands back into getters that lazily read from the
+ * original `source` — preserving the reactive subscription end-to-end.
+ *
+ * Fast path: when `source` has no getter descriptors, return the
+ * source object unchanged. JS spread will work correctly in that case
+ * because there's nothing reactive to preserve. Saves N thunk
+ * allocations per component render in the 99% case.
+ *
+ * Emitted by the compiler — not generally meant for hand-written code.
+ */
+declare function _wrapSpread(source: Record<string, unknown> | null | undefined): Record<string, unknown> | null | undefined;
 /**
  * Convert compiler-emitted `_rp(() => expr)` prop values into getter properties.
  *
@@ -1204,5 +1374,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, 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 };
+export { type AnchorAttributes, type ButtonAttributes, type CSSProperties, CSS_UNITLESS, type ClassValue, type CleanupFn, type ComponentFn, type ComponentInstance, type Context, type ContextSnapshot, Defer, type DeferProps, 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, _wrapSpread, 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
 /**

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
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/core",
-  "version": "0.15.0",
+  "version": "0.18.0",
   "description": "Core component model and lifecycle for Pyreon",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/core#readme",
   "bugs": {
@@ -53,7 +53,7 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@pyreon/reactivity": "^0.15.0"
+    "@pyreon/reactivity": "^0.18.0"
   },
   "devDependencies": {
     "@pyreon/manifest": "0.13.1"

package/src/defer.ts

@@ -0,0 +1,241 @@
+import { effect, signal } from '@pyreon/reactivity'
+import { Fragment, h } from './h'
+import { onMount } from './lifecycle'
+import { createRef } from './ref'
+import type { ComponentFn, Props, VNode, VNodeChild, VNodeChildAccessor } from './types'
+
+// Dev-mode gate (bundler-agnostic, see pyreon/no-process-dev-gate).
+const __DEV__ = process.env.NODE_ENV !== 'production'
+
+/**
+ * Module shape `<Defer>` accepts from `chunk()`. Mirrors `lazy()`'s
+ * contract — either an ES module with `default` export, OR a raw
+ * `ComponentFn` returned directly (rare; covers re-export patterns).
+ */
+type ChunkResult<P extends Props> = { default: ComponentFn<P> } | ComponentFn<P>
+
+/**
+ * Trigger discriminant. Exactly ONE shape is provided:
+ *   - `when={() => signal()}` — load when the accessor becomes truthy
+ *   - `on="visible"`         — load when the wrapper enters the viewport
+ *   - `on="idle"`            — load during browser idle time
+ */
+type DeferTrigger = { when: () => boolean } | { on: 'visible' | 'idle' }
+
+/**
+ * Set up the `on="idle"` trigger. Returns a teardown function the
+ * caller must invoke on unmount. Browser-API access is gated by
+ * `typeof` checks so SSR / jsdom environments fall back to a
+ * `setTimeout(1)` shim. Extracted as a standalone helper so it's
+ * directly testable without going through `onMount` (core tests
+ * don't run in happy-dom; runtime-dom is where the lifecycle hooks
+ * live).
+ *
+ * @internal Exported for tests; not part of the stable public API.
+ */
+export function _setupIdleTrigger(startLoad: () => void): () => void {
+  const ric = (
+    globalThis as { requestIdleCallback?: (cb: () => void) => number }
+  ).requestIdleCallback
+  const cic = (
+    globalThis as { cancelIdleCallback?: (id: number) => void }
+  ).cancelIdleCallback
+  if (typeof ric === 'function') {
+    const id = ric(startLoad)
+    return () => cic?.(id)
+  }
+  const t = setTimeout(startLoad, 1)
+  return () => clearTimeout(t)
+}
+
+/**
+ * Set up the `on="visible"` trigger. Observes `el` via an
+ * `IntersectionObserver` and fires `startLoad` once on the first
+ * intersection. If `IntersectionObserver` is unavailable (jsdom)
+ * or `el` is null (SSR), falls back to loading immediately.
+ *
+ * Returns a teardown function — call to disconnect the observer.
+ *
+ * @internal Exported for tests; not part of the stable public API.
+ */
+export function _setupVisibleTrigger(
+  el: HTMLElement | null,
+  startLoad: () => void,
+  rootMargin: string,
+): () => void {
+  if (!el || typeof IntersectionObserver === 'undefined') {
+    // Observer unavailable or no DOM target — load eagerly so the
+    // user still sees the component in environments where the
+    // viewport-detection mechanism can't run.
+    startLoad()
+    return () => {}
+  }
+  const obs = new IntersectionObserver(
+    (entries) => {
+      if (entries.some((e) => e.isIntersecting)) {
+        startLoad()
+        obs.disconnect()
+      }
+    },
+    { rootMargin },
+  )
+  obs.observe(el)
+  return () => obs.disconnect()
+}
+
+export type DeferProps<P extends Props> = DeferTrigger & {
+  /**
+   * Dynamic import to lazy-load. The literal `import('./X')` is what
+   * Rolldown / Vite see when emitting chunks — using a variable here
+   * defeats code splitting.
+   */
+  chunk: () => Promise<ChunkResult<P>>
+  /**
+   * Render-prop for the loaded component. Receives the resolved component
+   * and returns its JSX with whatever props the parent needs to pass.
+   * Optional — omitting it renders `<Comp />` with no props.
+   */
+  children?: (Component: ComponentFn<P>) => VNodeChild
+  /** Shown while the chunk is loading. Default: `null`. */
+  fallback?: VNodeChild
+  /**
+   * IntersectionObserver `rootMargin` for `on="visible"` mode. Default
+   * `'200px'` — start loading the chunk before the wrapper is fully in
+   * view so it's typically ready by the time the user scrolls to it.
+   */
+  rootMargin?: string
+}
+
+/**
+ * Lazy-load a chunk when a trigger condition is met.
+ *
+ * Three trigger modes:
+ *   - `when={() => signal()}` — load when condition flips truthy (modal pattern)
+ *   - `on="visible"`         — load when the wrapper scrolls into view
+ *   - `on="idle"`            — load during browser idle time
+ *
+ * The chunk fetch is fired exactly once per `Defer` instance — repeated
+ * trigger firings after the chunk loads are no-ops.
+ *
+ * @example
+ * // Signal-driven (modal):
+ * <Defer chunk={() => import('./ConfirmDeleteModal')} when={open}>
+ *   {Modal => <Modal onClose={() => setOpen(false)} />}
+ * </Defer>
+ *
+ * @example
+ * // Viewport-driven (below-fold):
+ * <Defer chunk={() => import('./Comments')} on="visible">
+ *   {Comments => <Comments postId={id} />}
+ * </Defer>
+ *
+ * @example
+ * // Idle-driven (non-critical):
+ * <Defer chunk={() => import('./Analytics')} on="idle">
+ *   {Dashboard => <Dashboard />}
+ * </Defer>
+ */
+export function Defer<P extends Props>(props: DeferProps<P>): VNode {
+  const Loaded = signal<ComponentFn<P> | null>(null)
+  const Failed = signal<Error | null>(null)
+  // Module-scope flag prevents repeat fetches when the trigger condition
+  // oscillates (e.g. modal opens / closes / opens again). The chunk only
+  // loads once per Defer mount.
+  let loadStarted = false
+
+  const startLoad = (): void => {
+    if (loadStarted) return
+    loadStarted = true
+    props
+      .chunk()
+      .then((mod) => {
+        // Accept both ES-module-default and bare ComponentFn shapes.
+        const Comp =
+          typeof mod === 'function'
+            ? mod
+            : (mod as { default: ComponentFn<P> }).default
+        if (__DEV__ && typeof Comp !== 'function') {
+          // oxlint-disable-next-line no-console
+          console.warn(
+            '[Pyreon] <Defer> chunk() resolved without a default-exported component. Make sure your module exports default.',
+          )
+          return
+        }
+        Loaded.set(Comp)
+      })
+      .catch((err) => {
+        const wrapped = err instanceof Error ? err : new Error(String(err))
+        if (__DEV__) {
+          // oxlint-disable-next-line no-console
+          console.error('[Pyreon] <Defer> chunk() rejected:', wrapped)
+        }
+        Failed.set(wrapped)
+      })
+  }
+
+  // Trigger wiring — exactly one branch fires per instance.
+  if ('when' in props) {
+    // Signal-driven. Subscribe to the accessor; load when it transitions
+    // to truthy. Repeat truthy emissions are no-ops via `loadStarted`.
+    effect(() => {
+      if (props.when() && !loadStarted) startLoad()
+    })
+  } else if (props.on === 'idle') {
+    // Idle-driven. Delegated to `_setupIdleTrigger` so the browser-API
+    // branching is testable as a pure function. Wrapped in onMount so
+    // SSR / non-browser environments don't fire the callback at all.
+    onMount(() => _setupIdleTrigger(startLoad))
+  }
+  // Note: `on === 'visible'` is wired below alongside the wrapper element
+  // because it needs a DOM target to observe.
+
+  // Inline accessor — type annotation deliberately omitted so the
+  // inferred return type narrows to `VNodeChildAtom | VNodeChildAtom[]`
+  // (what `h()`'s rest-args expect). Annotating as `VNodeChild` widens
+  // to include `VNodeChildAccessor`, which can't be returned from another
+  // accessor.
+  const renderContent = () => {
+    const err = Failed()
+    if (err) throw err
+    const Comp = Loaded()
+    if (!Comp) return props.fallback ?? null
+    return props.children ? props.children(Comp) : h(Comp as ComponentFn, {})
+  }
+
+  if ('on' in props && props.on === 'visible') {
+    // Visible-mode needs a DOM target for IntersectionObserver. A
+    // wrapper `<div data-pyreon-defer="visible">` carries the ref and
+    // styles `display: contents` so it's transparent to layout (the
+    // fallback / loaded component render as direct children of Defer's
+    // parent).
+    const containerRef = createRef<HTMLElement>()
+    // Visible-mode trigger is wired via `_setupVisibleTrigger` so the
+    // observer-construction + intersection-detection logic is
+    // independently testable. onMount keeps the browser-API access
+    // out of the SSR path.
+    onMount(() =>
+      _setupVisibleTrigger(
+        containerRef.current,
+        startLoad,
+        props.rootMargin ?? '200px',
+      ),
+    )
+    // Cast renderContent to VNodeChildAccessor — its inferred return type
+    // is `VNodeChild` (broader than the accessor's `atom | atom[]`) because
+    // `props.children` itself may return any VNodeChild. The runtime
+    // unwraps nested accessors via the same mountChild path that handles
+    // <Show>'s thunk shape; the type system doesn't model the unwrap so
+    // the cast bridges. See <Show>'s `as unknown as VNode` for prior art.
+    return h(
+      'div',
+      {
+        'data-pyreon-defer': 'visible',
+        ref: containerRef,
+        style: 'display: contents',
+      },
+      renderContent as VNodeChildAccessor,
+    )
+  }
+
+  return h(Fragment, null, renderContent as VNodeChildAccessor)
+}

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

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

@@ -35,12 +35,22 @@ export type {
   TargetedEvent,
   TextareaAttributes,
 } from './jsx-runtime'
+export type { DeferProps } from './defer'
+export { Defer } from './defer'
 export { lazy } from './lazy'
 export { onErrorCaptured, onMount, onUnmount, onUpdate } from './lifecycle'
 export { mapArray } from './map-array'
 export type { PortalProps } from './portal'
 export { Portal, PortalSymbol } from './portal'
-export { _rp, createUniqueId, makeReactiveProps, mergeProps, REACTIVE_PROP, splitProps } from './props'
+export {
+  _rp,
+  _wrapSpread,
+  createUniqueId,
+  makeReactiveProps,
+  mergeProps,
+  REACTIVE_PROP,
+  splitProps,
+} from './props'
 export type { Ref, RefCallback, RefProp } from './ref'
 export { createRef } from './ref'
 export type { MatchProps, ShowProps, SwitchProps } from './show'

package/src/jsx-runtime.ts

@@ -25,19 +25,57 @@ export function jsx(
   props: Props & { children?: VNodeChild | VNodeChild[] },
   key?: string | number | null,
 ): VNode {
-  const { children, ...rest } = props
-  const propsWithKey = (key != null ? { ...rest, key } : rest) as Props
+  // Build the destructured props object by copying own property
+  // DESCRIPTORS, not values. Compiler-emitted reactive props (`_rp(() =>
+  // signal())` wrappers converted to getter properties by
+  // `makeReactiveProps` in mount.ts) MUST survive the destructure with
+  // their getters intact. A plain `{ children, ...rest } = props`
+  // destructure fires every getter on `props` and stores the resolved
+  // value, breaking signal-driven reactivity for any downstream
+  // consumer that reads `props.x` in a tracking scope.
+  //
+  // Fast path: if `props` has no own property descriptors with `get`
+  // accessors, we can use the original value-copy shape (cheap object
+  // literal allocation). This is the 99% case — only framework wrappers
+  // (rocketstyle attrs HOC, Wrapper, styled) and direct signal props
+  // produce getter-shaped descriptors.
+  const descriptors = Object.getOwnPropertyDescriptors(props)
+  let hasGetter = false
+  for (const k in descriptors) {
+    if (descriptors[k]!.get) {
+      hasGetter = true
+      break
+    }
+  }
+  const children = props.children
+
+  if (!hasGetter) {
+    const { children: _ignored, ...rest } = props
+    const propsWithKey = (key != null ? { ...rest, key } : rest) as Props
+    if (typeof type === 'function') {
+      const componentProps = children !== undefined ? { ...propsWithKey, children } : propsWithKey
+      return h(type, componentProps)
+    }
+    const childArray = children === undefined ? [] : Array.isArray(children) ? children : [children]
+    return h(type, propsWithKey, ...(childArray as VNodeChild[]))
+  }
+
+  // Slow path: at least one getter descriptor present — preserve
+  // descriptors during the destructure.
+  const propsWithKey: Record<string, unknown> = {}
+  for (const k in descriptors) {
+    if (k === 'children') continue
+    Object.defineProperty(propsWithKey, k, descriptors[k]!)
+  }
+  if (key != null) propsWithKey.key = key as unknown
 
   if (typeof type === 'function') {
-    // Component: keep children in props.children so the component function can access them.
-    // Children must NOT be spread as h() rest args because mountComponent only passes vnode.props.
-    const componentProps = children !== undefined ? { ...propsWithKey, children } : propsWithKey
-    return h(type, componentProps)
+    if (children !== undefined) propsWithKey.children = children
+    return h(type, propsWithKey as Props)
   }
 
-  // DOM element or symbol (Fragment, ForSymbol): children go in vnode.children
   const childArray = children === undefined ? [] : Array.isArray(children) ? children : [children]
-  return h(type, propsWithKey, ...(childArray as VNodeChild[]))
+  return h(type, propsWithKey as Props, ...(childArray as VNodeChild[]))
 }
 
 // jsxs is called when there are multiple static children — same signature