@pyreon/core 0.16.0 → 0.19.0

package/lib/types/index.d.ts

@@ -1,3 +1,5 @@
+import { ReactiveTraceEntry } from "@pyreon/reactivity";
+
 //#region src/types.d.ts
 type VNodeChildAtom = VNode | string | number | boolean | null | undefined;
 /** Reactive accessor — TS checks this arm FIRST so `{() => cond && <X />}` resolves correctly */
@@ -176,6 +178,34 @@ declare function nativeCompat<T>(fn: T): T;
  */
 declare function isNativeCompat(fn: unknown): boolean;
 //#endregion
+//#region src/compat-shared.d.ts
+/**
+ * Code shared by the framework-compat JSX runtimes
+ * (`@pyreon/react-compat`, `@pyreon/preact-compat`).
+ *
+ * These helpers were previously copy-pasted byte-for-byte into both
+ * packages. `@pyreon/core` is the correct single home — it's already a
+ * dependency of every compat package and already hosts the sibling
+ * cross-compat module `compat-marker.ts` (`nativeCompat` / `isNativeCompat`).
+ */
+/**
+ * Shallow props comparison used by compat `memo()` / `useState` bailout.
+ * Same-length key sets with `Object.is`-equal values → equal.
+ */
+declare function shallowEqualProps<P extends Record<string, unknown>>(a: P, b: P): boolean;
+/**
+ * Map React/Preact-style DOM attributes to standard HTML attributes,
+ * mutating `props` in place. No-op when `type` is not a host string
+ * (component vnodes keep their props untouched).
+ *
+ * The React and Preact variants were identical apart from React also
+ * stripping `suppressContentEditableWarning`. Both keys are React/Preact
+ * authoring-only and never valid DOM attributes, so always stripping
+ * both is behavior-preserving for Preact (the key is never set there;
+ * `delete` of an absent key is a no-op) and removes the only divergence.
+ */
+declare function mapCompatDomProps(props: Record<string, unknown>, type: unknown): void;
+//#endregion
 //#region src/context.d.ts
 /**
  * Provide / inject — like React context or Vue provide/inject.
@@ -1011,6 +1041,102 @@ 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.
+   *
+   * Typed as optional ONLY because the compiler-driven inline form
+   * (`<Defer when={x}><Modal /></Defer>`) doesn't include a `chunk`
+   * prop at source level — `@pyreon/compiler`'s `transformDeferInline`
+   * synthesizes it before runtime. Authors using the explicit form
+   * must pass `chunk` — runtime throws a clear dev-mode error when
+   * the trigger fires and `chunk` is missing.
+   */
+  chunk?: () => Promise<ChunkResult<P>>;
+  /**
+   * Children accept TWO shapes:
+   *   1. Render-prop `(Component) => VNodeChild` — the explicit form.
+   *      Receives the loaded component, lets the author pass props.
+   *   2. Inline JSX (`<Defer when={x}><Modal /></Defer>`) — the compiler-
+   *      driven form. The compiler extracts the subtree into a chunk
+   *      and rewrites this to the render-prop form before runtime.
+   *
+   * Type widening is necessary because TypeScript checks the raw source
+   * BEFORE the compiler pass runs — both shapes must typecheck.
+   */
+  children?: ((Component: ComponentFn<P>) => VNodeChild) | 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) & {
@@ -1144,6 +1270,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.
  *
@@ -1216,23 +1370,6 @@ declare function Switch(props: SwitchProps): VNode | null;
 declare const MatchSymbol: unique symbol;
 //#endregion
 //#region src/telemetry.d.ts
-/**
- * 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"
- *
- * registerErrorHandler(ctx => {
- *   Sentry.captureException(ctx.error, {
- *     extra: { component: ctx.component, phase: ctx.phase },
- *   })
- * })
- */
 interface ErrorContext {
   /** Component function name, "Anonymous", or "Effect" for reactive effects */
   component: string;
@@ -1244,6 +1381,22 @@ interface ErrorContext {
   timestamp: number;
   /** Component props at the time of the error */
   props?: Record<string, unknown>;
+  /**
+   * The last N signal writes (chronological, oldest → newest) leading
+   * up to the error — the causal sequence of reactive state changes,
+   * not a point-in-time snapshot. Each entry is `{ name, prev, next,
+   * timestamp }` with `prev` / `next` as bounded string previews.
+   *
+   * Populated automatically in development from `@pyreon/reactivity`'s
+   * dev-only ring buffer. **`undefined` in production** — the recorder
+   * feeding the buffer tree-shakes out of prod bundles, so the cost is
+   * zero and the field is simply absent.
+   *
+   * For a signal framework this answers the first question a crash
+   * raises — "what reactive state changed in the run-up?" — that the
+   * thrown value + stack alone can't.
+   */
+  reactiveTrace?: ReactiveTraceEntry[];
 }
 type ErrorHandler = (ctx: ErrorContext) => void;
 /**
@@ -1263,5 +1416,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 ReactiveTraceEntry, 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, mapCompatDomProps, mergeProps, nativeCompat, normalizeStyleValue, onErrorCaptured, onMount, onUnmount, onUpdate, popContext, propagateError, provide, pushContext, registerErrorHandler, reportError, restoreContextStack, runWithHooks, setContextStackProvider, shallowEqualProps, splitProps, toKebabCase, useContext, withContext };
 //# sourceMappingURL=index2.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/core",
-  "version": "0.16.0",
+  "version": "0.19.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.16.0"
+    "@pyreon/reactivity": "^0.19.0"
   },
   "devDependencies": {
     "@pyreon/manifest": "0.13.1"

package/src/compat-shared.ts

@@ -0,0 +1,80 @@
+/**
+ * Code shared by the framework-compat JSX runtimes
+ * (`@pyreon/react-compat`, `@pyreon/preact-compat`).
+ *
+ * These helpers were previously copy-pasted byte-for-byte into both
+ * packages. `@pyreon/core` is the correct single home — it's already a
+ * dependency of every compat package and already hosts the sibling
+ * cross-compat module `compat-marker.ts` (`nativeCompat` / `isNativeCompat`).
+ */
+
+/**
+ * Shallow props comparison used by compat `memo()` / `useState` bailout.
+ * Same-length key sets with `Object.is`-equal values → equal.
+ */
+export function shallowEqualProps<P extends Record<string, unknown>>(a: P, b: P): boolean {
+  const keysA = Object.keys(a)
+  const keysB = Object.keys(b)
+  if (keysA.length !== keysB.length) return false
+  for (const k of keysA) {
+    if (!Object.is(a[k], b[k])) return false
+  }
+  return true
+}
+
+/**
+ * Map React/Preact-style DOM attributes to standard HTML attributes,
+ * mutating `props` in place. No-op when `type` is not a host string
+ * (component vnodes keep their props untouched).
+ *
+ * The React and Preact variants were identical apart from React also
+ * stripping `suppressContentEditableWarning`. Both keys are React/Preact
+ * authoring-only and never valid DOM attributes, so always stripping
+ * both is behavior-preserving for Preact (the key is never set there;
+ * `delete` of an absent key is a no-op) and removes the only divergence.
+ */
+export function mapCompatDomProps(props: Record<string, unknown>, type: unknown): void {
+  if (typeof type !== 'string') return
+
+  if (props.className !== undefined) {
+    props.class = props.className
+    delete props.className
+  }
+  if (props.htmlFor !== undefined) {
+    props.for = props.htmlFor
+    delete props.htmlFor
+  }
+
+  // React/Preact onChange fires on every keystroke for form elements (like onInput)
+  if (
+    (type === 'input' || type === 'textarea' || type === 'select') &&
+    props.onChange !== undefined
+  ) {
+    if (props.onInput === undefined) {
+      props.onInput = props.onChange
+    }
+    delete props.onChange
+  }
+
+  // autoFocus → autofocus
+  if (props.autoFocus !== undefined) {
+    props.autofocus = props.autoFocus
+    delete props.autoFocus
+  }
+
+  // defaultValue / defaultChecked → value / checked when no controlled value
+  if (type === 'input' || type === 'textarea') {
+    if (props.defaultValue !== undefined && props.value === undefined) {
+      props.value = props.defaultValue
+      delete props.defaultValue
+    }
+    if (props.defaultChecked !== undefined && props.checked === undefined) {
+      props.checked = props.defaultChecked
+      delete props.defaultChecked
+    }
+  }
+
+  // Strip authoring-only props that have no DOM equivalent
+  delete props.suppressHydrationWarning
+  delete props.suppressContentEditableWarning
+}

package/src/defer.ts

@@ -0,0 +1,279 @@
+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.
+   *
+   * Typed as optional ONLY because the compiler-driven inline form
+   * (`<Defer when={x}><Modal /></Defer>`) doesn't include a `chunk`
+   * prop at source level — `@pyreon/compiler`'s `transformDeferInline`
+   * synthesizes it before runtime. Authors using the explicit form
+   * must pass `chunk` — runtime throws a clear dev-mode error when
+   * the trigger fires and `chunk` is missing.
+   */
+  chunk?: () => Promise<ChunkResult<P>>
+  /**
+   * Children accept TWO shapes:
+   *   1. Render-prop `(Component) => VNodeChild` — the explicit form.
+   *      Receives the loaded component, lets the author pass props.
+   *   2. Inline JSX (`<Defer when={x}><Modal /></Defer>`) — the compiler-
+   *      driven form. The compiler extracts the subtree into a chunk
+   *      and rewrites this to the render-prop form before runtime.
+   *
+   * Type widening is necessary because TypeScript checks the raw source
+   * BEFORE the compiler pass runs — both shapes must typecheck.
+   */
+  children?: ((Component: ComponentFn<P>) => VNodeChild) | 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
+    if (!props.chunk) {
+      // Missing chunk = either the user is hand-writing the inline form
+      // without the compiler pass running, or they wrote the explicit
+      // form and forgot to pass chunk. Either way, error early with an
+      // actionable message instead of crashing later inside the `.then`.
+      const err = new Error(
+        '[Pyreon] <Defer> has no `chunk` prop. Either pass `chunk={() => import("...")}` ' +
+          '(explicit form), or use the inline form `<Defer when={...}><Component /></Defer>` ' +
+          'with `@pyreon/vite-plugin` enabled — the compiler rewrites inline JSX to ' +
+          'an explicit chunk-prop call.',
+      )
+      Failed.set(err)
+      return
+    }
+    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
+    // children is widened to `VNodeChild | render-prop` so the compiler-
+    // driven inline form (where author writes `<Defer ...><Modal /></Defer>`)
+    // typechecks at source level. At RUNTIME children is always either
+    // undefined OR the render-prop — the compiler rewrites the inline
+    // form's JSX children to a render-prop before this code runs.
+    // A non-function children at runtime means the user is invoking the
+    // inline form without the compiler pass (e.g. running tests through
+    // a bundler that doesn't include `@pyreon/vite-plugin`) — in that
+    // case we render `<Comp />` with no props as a best-effort fallback.
+    const ch = props.children
+    if (typeof ch === 'function') return ch(Comp)
+    return 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/index.ts

@@ -2,6 +2,7 @@
 
 export { defineComponent, dispatchToErrorBoundary, propagateError, runWithHooks } from './component'
 export { isNativeCompat, NATIVE_COMPAT_MARKER, nativeCompat } from './compat-marker'
+export { mapCompatDomProps, shallowEqualProps } from './compat-shared'
 export type { Context, ContextSnapshot, ReactiveContext } from './context'
 export {
   captureContextStack,
@@ -35,12 +36,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'
@@ -49,7 +60,7 @@ export type { ClassValue } from './style'
 export { CSS_UNITLESS, cx, normalizeStyleValue, toKebabCase } from './style'
 export type { LazyComponent } from './suspense'
 export { Suspense } from './suspense'
-export type { ErrorContext, ErrorHandler } from './telemetry'
+export type { ErrorContext, ErrorHandler, ReactiveTraceEntry } from './telemetry'
 export { registerErrorHandler, reportError } from './telemetry'
 export type {
   CleanupFn,