@pyreon/core 0.1.0

package/lib/types/index.d.ts

@@ -0,0 +1,381 @@
+//#region src/types.d.ts
+type VNodeChildAtom = VNode | VNode[] | string | number | boolean | null | undefined;
+type VNodeChild = VNodeChildAtom | (() => VNodeChildAtom);
+interface VNode {
+  /** Tag name, component function, or special symbol (Fragment) */
+  type: string | ComponentFn | symbol;
+  props: Props;
+  children: VNodeChild[];
+  key: string | number | null;
+}
+type Props = Record<string, unknown>;
+/**
+ * A component is a plain function that runs ONCE.
+ * It returns a VNode (or null) and may call lifecycle hooks during setup.
+ */
+type ComponentFn<P extends Props = Props> = (props: P) => VNode | null;
+/**
+ * Internal runtime handle created by the renderer for each mounted component.
+ */
+interface ComponentInstance {
+  vnode: VNode | null;
+  /** Trigger a re-check / patch cycle (called by the renderer) */
+  update(): void;
+  unmount(): void;
+}
+type CleanupFn = () => void;
+/**
+ * Result of createTemplate() — a pre-cloned DOM element with its cleanup.
+ * Handled directly by mountFor without going through the VNode reconciler,
+ * saving 2 allocations per row vs the VNode wrapper path.
+ */
+interface NativeItem {
+  readonly __isNative: true;
+  el: HTMLElement;
+  cleanup: (() => void) | null;
+}
+interface LifecycleHooks {
+  mount: (() => CleanupFn | undefined)[];
+  unmount: (() => void)[];
+  update: (() => void)[];
+  /** Error handlers — return true to mark the error as handled (stops propagation). */
+  error: ((err: unknown) => boolean | undefined)[];
+}
+//#endregion
+//#region src/component.d.ts
+/**
+ * Identity wrapper — marks a function as a Pyreon component and preserves its type.
+ * Useful for IDE tooling and future compiler optimisations.
+ */
+declare function defineComponent<P extends Props>(fn: ComponentFn<P>): ComponentFn<P>;
+/**
+ * Run a component function in a tracked context so that lifecycle hooks
+ * registered inside it (onMount, onUnmount, onErrorCaptured, etc.) are captured.
+ *
+ * Called by the renderer — not intended for user code.
+ */
+declare function runWithHooks<P extends Props>(fn: ComponentFn<P>, props: P): {
+  vnode: VNode | null;
+  hooks: LifecycleHooks;
+};
+/**
+ * Walk up error handlers collected during component rendering.
+ * Returns true if any handler marked the error as handled.
+ */
+declare function propagateError(err: unknown, hooks: LifecycleHooks): boolean;
+/**
+ * Dispatch an error to the nearest active ErrorBoundary.
+ * Returns true if the boundary handled it, false if none was registered.
+ */
+declare function dispatchToErrorBoundary(err: unknown): boolean;
+//#endregion
+//#region src/context.d.ts
+/**
+ * Provide / inject — like React context or Vue provide/inject.
+ *
+ * Values flow down the component tree without prop-drilling.
+ * The renderer maintains the context stack as it walks the VNode tree.
+ */
+interface Context<T> {
+  readonly id: symbol;
+  readonly defaultValue: T;
+}
+declare function createContext<T>(defaultValue: T): Context<T>;
+/**
+ * Override the context stack provider. Called by @pyreon/runtime-server to
+ * inject an AsyncLocalStorage-backed stack that isolates concurrent SSR requests.
+ * Has no effect in the browser (CSR always uses the default module-level stack).
+ */
+declare function setContextStackProvider(fn: () => Map<symbol, unknown>[]): void;
+declare function pushContext(values: Map<symbol, unknown>): void;
+declare function popContext(): void;
+/**
+ * Read the nearest provided value for a context.
+ * Falls back to `context.defaultValue` if none found.
+ */
+declare function useContext<T>(context: Context<T>): T;
+/**
+ * Provide a value for `context` during `fn()`.
+ * Used by the renderer when it encounters a `<Provider>` component.
+ */
+declare function withContext<T>(context: Context<T>, value: T, fn: () => void): void;
+//#endregion
+//#region src/dynamic.d.ts
+interface DynamicProps extends Props {
+  component: ComponentFn | string;
+}
+declare function Dynamic(props: DynamicProps): VNode | null;
+//#endregion
+//#region src/error-boundary.d.ts
+/**
+ * ErrorBoundary — catches errors thrown by child components and renders a
+ * fallback UI instead of crashing the whole tree.
+ *
+ * Also reports caught errors to any registered telemetry handlers.
+ *
+ * How error propagation works:
+ * ErrorBoundary pushes a handler onto the module-level boundary stack
+ * synchronously during its own setup (before children are mounted).
+ * When mountComponent catches a child error, it calls dispatchToErrorBoundary()
+ * which invokes the innermost boundary's handler.
+ *
+ * Usage:
+ *   h(ErrorBoundary, {
+ *     fallback: (err) => h("p", null, `Error: ${err}`),
+ *     children: h(MyComponent, null),
+ *   })
+ *
+ *   // or with JSX:
+ *   <ErrorBoundary fallback={(err) => <p>Error: {String(err)}</p>}>
+ *     <MyComponent />
+ *   </ErrorBoundary>
+ */
+declare function ErrorBoundary(props: {
+  /**
+   * Rendered when a child throws. Receives the caught error and a `reset`
+   * function — calling `reset()` clears the error and re-renders children.
+   */
+  fallback: (err: unknown, reset: () => void) => VNodeChild;
+  children?: VNodeChild;
+}): VNodeChild;
+//#endregion
+//#region src/for.d.ts
+/**
+ * Symbol used as the VNode type for a For list — runtime-dom handles it
+ * via mountFor, bypassing the generic VNode reconciler.
+ */
+declare const ForSymbol: unique symbol;
+interface ForProps<T> {
+  each: () => T[];
+  by: (item: T) => string | number;
+  children: (item: T) => VNode | NativeItem;
+}
+/**
+ * Efficient reactive list rendering.
+ *
+ * Unlike a plain `() => items().map(item => h(...))`, For never re-creates
+ * VNodes for existing keys — only new keys invoke `children()`. Structural
+ * mutations (swap, sort, filter) are O(n) key scan + O(k) DOM moves where k
+ * is the number of actually displaced entries.
+ *
+ * Usage:
+ *   <For each={items} by={r => r.id}>{r => <li>...</li>}</For>
+ */
+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;
+/**
+ * Hyperscript function — the compiled output of JSX.
+ * `<div class="x">hello</div>` → `h("div", { class: "x" }, "hello")`
+ *
+ * Generic on P so TypeScript validates props match the component's signature
+ * at the call site, then stores the result in the loosely-typed VNode.
+ */
+/** Shared empty props sentinel — identity-checked in mountElement to skip applyProps. */
+declare const EMPTY_PROPS: Props;
+declare function h<P extends Props>(type: string | ComponentFn<P> | symbol, props: P | null, ...children: VNodeChild[]): VNode;
+//#endregion
+//#region src/suspense.d.ts
+/** Internal marker attached to lazy()-wrapped components */
+type LazyComponent<P extends Props = Props> = ((props: P) => VNode | null) & {
+  __loading: () => boolean;
+};
+/**
+ * Suspense — shows `fallback` while a lazy child component is still loading.
+ *
+ * Works in tandem with `lazy()` from `@pyreon/react-compat` (or `@pyreon/core/lazy`).
+ * The child VNode's `.type.__loading()` signal drives the switch.
+ *
+ * Usage:
+ *   const Page = lazy(() => import("./Page"))
+ *
+ *   h(Suspense, { fallback: h(Spinner, null) }, h(Page, null))
+ *   // or with JSX:
+ *   <Suspense fallback={<Spinner />}><Page /></Suspense>
+ */
+declare function Suspense(props: {
+  fallback: VNodeChild;
+  children?: VNodeChild;
+}): VNode;
+//#endregion
+//#region src/lazy.d.ts
+declare function lazy<P extends Props>(load: () => Promise<{
+  default: ComponentFn<P>;
+}>): LazyComponent<P>;
+//#endregion
+//#region src/lifecycle.d.ts
+/**
+ * Register a callback to run after the component is mounted to the DOM.
+ * Optionally return a cleanup function — it will run on unmount.
+ */
+declare function onMount(fn: () => CleanupFn | undefined): void;
+/**
+ * Register a callback to run when the component is removed from the DOM.
+ */
+declare function onUnmount(fn: () => void): void;
+/**
+ * Register a callback to run after each reactive update.
+ */
+declare function onUpdate(fn: () => void): void;
+/**
+ * Register an error handler for this component subtree.
+ *
+ * When an error is thrown during rendering or in a child component,
+ * the nearest `onErrorCaptured` handler is called with the error.
+ * Return `true` to mark the error as handled and stop propagation.
+ *
+ * @example
+ * onErrorCaptured((err) => {
+ *   setError(String(err))
+ *   return true // handled — don't propagate
+ * })
+ */
+declare function onErrorCaptured(fn: (err: unknown) => boolean | undefined): void;
+//#endregion
+//#region src/map-array.d.ts
+/**
+ * mapArray — keyed reactive list mapping.
+ *
+ * Creates each mapped item exactly once per key, then reuses it across
+ * updates. When the source array is reordered or partially changed, only
+ * new keys invoke `map()`; existing entries return the cached result.
+ *
+ * This makes structural list operations (swap, sort, filter) O(k) in
+ * allocations where k is the number of new/removed keys, not O(n).
+ *
+ * The returned accessor reads `source()` reactively, so it can be passed
+ * directly to the keyed-list reconciler.
+ */
+declare function mapArray<T, U>(source: () => T[], getKey: (item: T) => string | number, map: (item: T) => U): () => U[];
+//#endregion
+//#region src/portal.d.ts
+/**
+ * Symbol used as the VNode type for a Portal — runtime-dom mounts the
+ * children into `target` instead of the normal parent.
+ */
+declare const PortalSymbol: unique symbol;
+interface PortalProps {
+  /** DOM element to render children into (e.g. document.body). */
+  target: Element;
+  children: VNodeChild;
+}
+/**
+ * Portal — renders `children` into a different DOM node than the
+ * current parent tree.
+ *
+ * Useful for modals, tooltips, dropdowns, and any overlay that needs to
+ * escape CSS overflow/stacking context restrictions.
+ *
+ * @example
+ * // Render a modal at document.body level regardless of where in the
+ * // component tree <Modal> is used:
+ * Portal({ target: document.body, children: h(Modal, { onClose }) })
+ *
+ * // JSX:
+ * <Portal target={document.body}>
+ *   <Modal onClose={close} />
+ * </Portal>
+ */
+declare function Portal(props: PortalProps): VNode;
+//#endregion
+//#region src/ref.d.ts
+/**
+ * createRef — mutable container for a DOM element or component value.
+ *
+ * Usage:
+ *   const inputRef = createRef<HTMLInputElement>()
+ *   onMount(() => { inputRef.current?.focus() })
+ *   return <input ref={inputRef} />
+ *
+ * The runtime sets `ref.current` after the element is inserted into the DOM
+ * and clears it to `null` when the element is removed.
+ */
+interface Ref<T = unknown> {
+  current: T | null;
+}
+declare function createRef<T = unknown>(): Ref<T>;
+//#endregion
+//#region src/show.d.ts
+interface ShowProps extends Props {
+  /** Accessor — children render when truthy, fallback when falsy. */
+  when: () => unknown;
+  fallback?: VNodeChild;
+  children?: VNodeChild;
+}
+/**
+ * Conditionally render children based on a reactive condition.
+ *
+ * @example
+ * h(Show, { when: () => isLoggedIn() },
+ *   h(Dashboard, null)
+ * )
+ *
+ * // With fallback:
+ * h(Show, { when: () => user(), fallback: h(Login, null) },
+ *   h(Dashboard, null)
+ * )
+ */
+declare function Show(props: ShowProps): VNode | null;
+interface MatchProps extends Props {
+  /** Accessor — this branch renders when truthy. */
+  when: () => unknown;
+  children?: VNodeChild;
+}
+/**
+ * A branch inside `<Switch>`. Renders when `when()` is truthy.
+ * Must be used as a direct child of `Switch`.
+ *
+ * `Match` acts as a pure type/identity marker — Switch identifies it by checking
+ * `vnode.type === Match` rather than by the runtime return value.
+ */
+declare function Match(_props: MatchProps): VNode | null;
+interface SwitchProps extends Props {
+  /** Rendered when no Match branch is truthy. */
+  fallback?: VNodeChild;
+  children?: VNodeChild | VNodeChild[];
+}
+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.
+ *
+ * @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, or "Anonymous" */
+  component: string;
+  /** Lifecycle phase where the error occurred */
+  phase: "setup" | "render" | "mount" | "unmount" | "effect";
+  /** The thrown value */
+  error: unknown;
+  /** Unix timestamp (ms) */
+  timestamp: number;
+  /** Component props at the time of the error */
+  props?: Record<string, unknown>;
+}
+type ErrorHandler = (ctx: ErrorContext) => void;
+/**
+ * Register a global error handler. Called whenever a component throws in any
+ * lifecycle phase. Returns an unregister function.
+ */
+declare function registerErrorHandler(handler: ErrorHandler): () => void;
+/**
+ * Internal — called by the runtime whenever a component error is caught.
+ * Existing console.error calls are preserved; this is additive.
+ */
+declare function reportError(ctx: ErrorContext): void;
+//#endregion
+export { type CleanupFn, type ComponentFn, type ComponentInstance, type Context, Dynamic, type DynamicProps, EMPTY_PROPS, ErrorBoundary, type ErrorContext, type ErrorHandler, For, type ForProps, ForSymbol, Fragment, type LazyComponent, type LifecycleHooks, Match, type MatchProps, MatchSymbol, type NativeItem, Portal, type PortalProps, PortalSymbol, type Props, type Ref, Show, type ShowProps, Suspense, Switch, type SwitchProps, type VNode, type VNodeChild, type VNodeChildAtom, createContext, createRef, defineComponent, dispatchToErrorBoundary, h, lazy, mapArray, onErrorCaptured, onMount, onUnmount, onUpdate, popContext, propagateError, pushContext, registerErrorHandler, reportError, runWithHooks, setContextStackProvider, useContext, withContext };
+//# sourceMappingURL=index2.d.ts.map

package/lib/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index2.d.ts","names":[],"sources":["../../src/types.ts","../../src/component.ts","../../src/context.ts","../../src/dynamic.ts","../../src/error-boundary.ts","../../src/for.ts","../../src/h.ts","../../src/suspense.ts","../../src/lazy.ts","../../src/lifecycle.ts","../../src/map-array.ts","../../src/portal.ts","../../src/ref.ts","../../src/show.ts","../../src/telemetry.ts"],"mappings":"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"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@pyreon/core",
+  "version": "0.1.0",
+  "description": "Core component model and lifecycle for Pyreon",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pyreon/pyreon.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/pyreon/pyreon/issues"
+  },
+  "files": [
+    "lib",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "main": "./lib/index.js",
+  "module": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./lib/index.js",
+      "types": "./lib/types/index.d.ts"
+    },
+    "./jsx-runtime": {
+      "bun": "./src/jsx-runtime.ts",
+      "import": "./lib/jsx-runtime.js",
+      "types": "./lib/types/jsx-runtime.d.ts"
+    },
+    "./jsx-dev-runtime": {
+      "bun": "./src/jsx-dev-runtime.ts",
+      "import": "./lib/jsx-dev-runtime.js",
+      "types": "./lib/types/jsx-dev-runtime.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "vl_rolldown_build",
+    "dev": "vl_rolldown_build-watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@pyreon/reactivity": "workspace:*"
+  }
+}

package/src/component.ts

@@ -0,0 +1,66 @@
+import { setCurrentHooks } from "./lifecycle"
+import type { ComponentFn, LifecycleHooks, Props, VNode } from "./types"
+
+/**
+ * Identity wrapper — marks a function as a Pyreon component and preserves its type.
+ * Useful for IDE tooling and future compiler optimisations.
+ */
+export function defineComponent<P extends Props>(fn: ComponentFn<P>): ComponentFn<P> {
+  return fn
+}
+
+/**
+ * Run a component function in a tracked context so that lifecycle hooks
+ * registered inside it (onMount, onUnmount, onErrorCaptured, etc.) are captured.
+ *
+ * Called by the renderer — not intended for user code.
+ */
+export function runWithHooks<P extends Props>(
+  fn: ComponentFn<P>,
+  props: P,
+): { vnode: VNode | null; hooks: LifecycleHooks } {
+  const hooks: LifecycleHooks = { mount: [], unmount: [], update: [], error: [] }
+  setCurrentHooks(hooks)
+  let vnode: VNode | null = null
+  try {
+    vnode = fn(props)
+  } finally {
+    setCurrentHooks(null)
+  }
+  return { vnode, hooks }
+}
+
+/**
+ * Walk up error handlers collected during component rendering.
+ * Returns true if any handler marked the error as handled.
+ */
+export function propagateError(err: unknown, hooks: LifecycleHooks): boolean {
+  for (const handler of hooks.error) {
+    if (handler(err) === true) return true
+  }
+  return false
+}
+
+// ─── Error boundary stack ────────────────────────────────────────────────────
+// Module-level stack of active ErrorBoundary handlers (innermost last).
+// ErrorBoundary pushes during its own setup (before children mount) so that
+// any child mountComponent error can dispatch up to the nearest boundary.
+
+const _errorBoundaryStack: ((err: unknown) => boolean)[] = []
+
+export function pushErrorBoundary(handler: (err: unknown) => boolean): void {
+  _errorBoundaryStack.push(handler)
+}
+
+export function popErrorBoundary(): void {
+  _errorBoundaryStack.pop()
+}
+
+/**
+ * Dispatch an error to the nearest active ErrorBoundary.
+ * Returns true if the boundary handled it, false if none was registered.
+ */
+export function dispatchToErrorBoundary(err: unknown): boolean {
+  const handler = _errorBoundaryStack[_errorBoundaryStack.length - 1]
+  return handler ? handler(err) : false
+}

package/src/context.ts

@@ -0,0 +1,79 @@
+/**
+ * Provide / inject — like React context or Vue provide/inject.
+ *
+ * Values flow down the component tree without prop-drilling.
+ * The renderer maintains the context stack as it walks the VNode tree.
+ */
+
+export interface Context<T> {
+  readonly id: symbol
+  readonly defaultValue: T
+}
+
+export function createContext<T>(defaultValue: T): Context<T> {
+  return { id: Symbol("PyreonContext"), defaultValue }
+}
+
+// ─── Runtime context stack (managed by the renderer) ─────────────────────────
+
+// Default stack — used for CSR and single-threaded SSR.
+// On Node.js with concurrent requests, @pyreon/runtime-server replaces this with
+// an AsyncLocalStorage-backed provider via setContextStackProvider().
+const _defaultStack: Map<symbol, unknown>[] = []
+let _stackProvider: () => Map<symbol, unknown>[] = () => _defaultStack
+
+/**
+ * Override the context stack provider. Called by @pyreon/runtime-server to
+ * inject an AsyncLocalStorage-backed stack that isolates concurrent SSR requests.
+ * Has no effect in the browser (CSR always uses the default module-level stack).
+ */
+export function setContextStackProvider(fn: () => Map<symbol, unknown>[]): void {
+  _stackProvider = fn
+}
+
+function getStack(): Map<symbol, unknown>[] {
+  return _stackProvider()
+}
+
+const __DEV__ = typeof process !== "undefined" && process.env.NODE_ENV !== "production"
+
+export function pushContext(values: Map<symbol, unknown>) {
+  getStack().push(values)
+}
+
+export function popContext() {
+  const stack = getStack()
+  if (__DEV__ && stack.length === 0) {
+    return
+  }
+  stack.pop()
+}
+
+/**
+ * Read the nearest provided value for a context.
+ * Falls back to `context.defaultValue` if none found.
+ */
+export function useContext<T>(context: Context<T>): T {
+  const stack = getStack()
+  for (let i = stack.length - 1; i >= 0; i--) {
+    const frame = stack[i]
+    if (frame?.has(context.id)) {
+      return frame.get(context.id) as T
+    }
+  }
+  return context.defaultValue
+}
+
+/**
+ * Provide a value for `context` during `fn()`.
+ * Used by the renderer when it encounters a `<Provider>` component.
+ */
+export function withContext<T>(context: Context<T>, value: T, fn: () => void) {
+  const frame = new Map<symbol, unknown>([[context.id, value]])
+  pushContext(frame)
+  try {
+    fn()
+  } finally {
+    popContext()
+  }
+}

package/src/dynamic.ts

@@ -0,0 +1,12 @@
+import { h } from "./h"
+import type { ComponentFn, Props, VNode } from "./types"
+
+export interface DynamicProps extends Props {
+  component: ComponentFn | string
+}
+
+export function Dynamic(props: DynamicProps): VNode | null {
+  const { component, ...rest } = props
+  if (!component) return null
+  return h(component as string | ComponentFn, rest as Props)
+}

package/src/error-boundary.ts

@@ -0,0 +1,58 @@
+import { signal } from "@pyreon/reactivity"
+import { popErrorBoundary, pushErrorBoundary } from "./component"
+import { onUnmount } from "./lifecycle"
+import { reportError } from "./telemetry"
+import type { VNodeChild, VNodeChildAtom } from "./types"
+
+/**
+ * ErrorBoundary — catches errors thrown by child components and renders a
+ * fallback UI instead of crashing the whole tree.
+ *
+ * Also reports caught errors to any registered telemetry handlers.
+ *
+ * How error propagation works:
+ * ErrorBoundary pushes a handler onto the module-level boundary stack
+ * synchronously during its own setup (before children are mounted).
+ * When mountComponent catches a child error, it calls dispatchToErrorBoundary()
+ * which invokes the innermost boundary's handler.
+ *
+ * Usage:
+ *   h(ErrorBoundary, {
+ *     fallback: (err) => h("p", null, `Error: ${err}`),
+ *     children: h(MyComponent, null),
+ *   })
+ *
+ *   // or with JSX:
+ *   <ErrorBoundary fallback={(err) => <p>Error: {String(err)}</p>}>
+ *     <MyComponent />
+ *   </ErrorBoundary>
+ */
+export function ErrorBoundary(props: {
+  /**
+   * Rendered when a child throws. Receives the caught error and a `reset`
+   * function — calling `reset()` clears the error and re-renders children.
+   */
+  fallback: (err: unknown, reset: () => void) => VNodeChild
+  children?: VNodeChild
+}): VNodeChild {
+  const error = signal<unknown>(null)
+  const reset = () => error.set(null)
+
+  const handler = (err: unknown): boolean => {
+    if (error.peek() !== null) return false // already in error state — let outer boundary catch it
+    error.set(err)
+    reportError({ component: "ErrorBoundary", phase: "render", error: err, timestamp: Date.now() })
+    return true
+  }
+
+  // Push synchronously — before children are mounted — so child errors see this boundary
+  pushErrorBoundary(handler)
+  onUnmount(() => popErrorBoundary())
+
+  return (): VNodeChildAtom => {
+    const err = error()
+    if (err != null) return props.fallback(err, reset) as VNodeChildAtom
+    const ch = props.children
+    return (typeof ch === "function" ? ch() : ch) as VNodeChildAtom
+  }
+}