@pyreon/runtime-dom 0.1.0

package/src/hydration-debug.ts

@@ -0,0 +1,39 @@
+/**
+ * Hydration mismatch warnings.
+ *
+ * Enabled automatically in development (NODE_ENV !== "production").
+ * Can be toggled manually for testing or verbose production debugging.
+ *
+ * @example
+ * import { enableHydrationWarnings } from "@pyreon/runtime-dom"
+ * enableHydrationWarnings()
+ */
+
+let _enabled = typeof process !== "undefined" && process.env.NODE_ENV !== "production"
+
+export function enableHydrationWarnings(): void {
+  _enabled = true
+}
+
+export function disableHydrationWarnings(): void {
+  _enabled = false
+}
+
+/**
+ * Emit a hydration mismatch warning.
+ * @param type  - Kind of mismatch
+ * @param expected - What the VNode expected
+ * @param actual   - What the DOM had
+ * @param path     - Human-readable path in the tree, e.g. "root > div > span"
+ */
+export function warnHydrationMismatch(
+  _type: "tag" | "text" | "missing",
+  _expected: unknown,
+  _actual: unknown,
+  _path: string,
+): void {
+  if (!_enabled) return
+  console.warn(
+    `[Pyreon] Hydration mismatch (${_type}): expected ${String(_expected)}, got ${String(_actual)} at ${_path}`,
+  )
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+// @pyreon/runtime-dom — surgical signal-to-DOM renderer (no virtual DOM)
+
+export type { DevtoolsComponentEntry, PyreonDevtools } from "./devtools"
+export { hydrateRoot } from "./hydrate"
+export { disableHydrationWarnings, enableHydrationWarnings } from "./hydration-debug"
+export type { KeepAliveProps } from "./keep-alive"
+export { KeepAlive } from "./keep-alive"
+export { mountChild } from "./mount"
+export type { Directive, SanitizeFn } from "./props"
+export { applyProp, applyProps, sanitizeHtml, setSanitizer } from "./props"
+export { _tpl, createTemplate } from "./template"
+export type { TransitionProps } from "./transition"
+export { Transition } from "./transition"
+export type { TransitionGroupProps } from "./transition-group"
+export { TransitionGroup } from "./transition-group"
+
+import type { VNodeChild } from "@pyreon/core"
+import { installDevTools } from "./devtools"
+import { mountChild } from "./mount"
+
+const __DEV__ = typeof process !== "undefined" && process.env.NODE_ENV !== "production"
+
+/**
+ * Mount a VNode tree into a container element.
+ * Clears the container first, then mounts the given child.
+ * Returns an `unmount` function that removes everything and disposes effects.
+ *
+ * @example
+ * const unmount = mount(h("div", null, "Hello Pyreon"), document.getElementById("app")!)
+ */
+export function mount(root: VNodeChild, container: Element): () => void {
+  if (__DEV__ && container == null) {
+    throw new Error(
+      '[pyreon] mount() called with a null/undefined container. Make sure the element exists in the DOM, e.g. document.getElementById("app")',
+    )
+  }
+  installDevTools()
+  container.innerHTML = ""
+  return mountChild(root, container, null)
+}
+
+/** Alias for `mount` */
+export const render = mount

package/src/keep-alive.ts

@@ -0,0 +1,71 @@
+import type { Props, VNodeChild } from "@pyreon/core"
+import { createRef, h, onMount } from "@pyreon/core"
+import { effect } from "@pyreon/reactivity"
+import { mountChild } from "./mount"
+
+export interface KeepAliveProps extends Props {
+  /**
+   * Accessor that returns true when this slot's children should be visible.
+   * When false, children are CSS-hidden but remain mounted — effects and
+   * signals stay alive.
+   * Defaults to true (always visible / always mounted).
+   */
+  active?: () => boolean
+  children?: VNodeChild
+}
+
+/**
+ * KeepAlive — mounts its children once and keeps them alive even when hidden.
+ *
+ * Unlike conditional rendering (which destroys and recreates component state),
+ * KeepAlive CSS-hides the children while preserving all reactive state,
+ * scroll position, form values, and in-flight async operations.
+ *
+ * Children are mounted imperatively on first activation and are never unmounted
+ * while the KeepAlive itself is mounted.
+ *
+ * Multi-slot pattern (one KeepAlive per route):
+ * @example
+ * h(Fragment, null, [
+ *   h(KeepAlive, { active: () => route() === "/a" }, h(RouteA, null)),
+ *   h(KeepAlive, { active: () => route() === "/b" }, h(RouteB, null)),
+ * ])
+ *
+ * With JSX:
+ * @example
+ * <>
+ *   <KeepAlive active={() => route() === "/a"}><RouteA /></KeepAlive>
+ *   <KeepAlive active={() => route() === "/b"}><RouteB /></KeepAlive>
+ * </>
+ */
+export function KeepAlive(props: KeepAliveProps): VNodeChild {
+  const containerRef = createRef<HTMLElement>()
+  let childCleanup: (() => void) | null = null
+  let childMounted = false
+
+  onMount(() => {
+    const container = containerRef.current as HTMLElement
+
+    const e = effect(() => {
+      const isActive = props.active?.() ?? true
+
+      if (!childMounted) {
+        // Mount children into the container div exactly once
+        childCleanup = mountChild(props.children ?? null, container, null)
+        childMounted = true
+      }
+
+      // Show/hide without unmounting — state is fully preserved
+      container.style.display = isActive ? "" : "none"
+    })
+
+    return () => {
+      e.dispose()
+      childCleanup?.()
+    }
+  })
+
+  // `display: contents` makes the wrapper transparent to layout
+  // (children appear as if directly in the parent flow)
+  return h("div", { ref: containerRef, style: "display: contents" })
+}

package/src/mount.ts

@@ -0,0 +1,367 @@
+import type {
+  ComponentFn,
+  ForProps,
+  NativeItem,
+  PortalProps,
+  Ref,
+  VNode,
+  VNodeChild,
+} from "@pyreon/core"
+import {
+  dispatchToErrorBoundary,
+  EMPTY_PROPS,
+  ForSymbol,
+  Fragment,
+  PortalSymbol,
+  propagateError,
+  reportError,
+  runWithHooks,
+} from "@pyreon/core"
+import { effectScope, renderEffect, runUntracked, setCurrentScope } from "@pyreon/reactivity"
+import { registerComponent, unregisterComponent } from "./devtools"
+import { mountFor, mountKeyedList, mountReactive } from "./nodes"
+import { applyProps } from "./props"
+
+const __DEV__ = typeof process !== "undefined" && process.env.NODE_ENV !== "production"
+
+type Cleanup = () => void
+const noop: Cleanup = () => {
+  /* noop */
+}
+
+// When > 0, we're mounting children inside an element — child cleanups can skip
+// DOM removal (parent element removal handles it). This avoids allocating a
+// removeChild closure for every nested element that has no reactive work.
+let _elementDepth = 0
+
+// Stack tracking which component is currently being mounted (depth-first order).
+// Used to infer parent/child relationships for DevTools.
+const _mountingStack: string[] = []
+
+/**
+ * Mount a single child into `parent`, inserting before `anchor` (null = append).
+ * Returns a cleanup that removes the node(s) and disposes all reactive effects.
+ *
+ * This function is the hot path — all child types are handled inline to avoid
+ * function call overhead in tight render loops (1000+ calls per list render).
+ */
+export function mountChild(
+  child: VNodeChild | VNodeChild[] | (() => VNodeChild | VNodeChild[]),
+  parent: Node,
+  anchor: Node | null = null,
+): Cleanup {
+  // Reactive accessor — function that reads signals
+  if (typeof child === "function") {
+    const sample = runUntracked(() => (child as () => VNodeChild | VNodeChild[])())
+    if (isKeyedArray(sample)) {
+      const prevDepth = _elementDepth
+      _elementDepth = 0
+      const cleanup = mountKeyedList(child as () => VNode[], parent, anchor, (v, p, a) =>
+        mountChild(v, p, a),
+      )
+      _elementDepth = prevDepth
+      return cleanup
+    }
+    // Text fast path: reactive string/number/boolean — update text.data in-place
+    if (typeof sample === "string" || typeof sample === "number" || typeof sample === "boolean") {
+      const text = document.createTextNode(sample == null || sample === false ? "" : String(sample))
+      parent.insertBefore(text, anchor)
+      const dispose = renderEffect(() => {
+        const v = (child as () => unknown)()
+        text.data = v == null || v === false ? "" : String(v as string | number)
+      })
+      if (_elementDepth > 0) return dispose
+      return () => {
+        dispose()
+        const p = text.parentNode
+        if (p && (p as Element).isConnected !== false) p.removeChild(text)
+      }
+    }
+    const prevDepth = _elementDepth
+    _elementDepth = 0
+    const cleanup = mountReactive(child as () => VNodeChild, parent, anchor, mountChild)
+    _elementDepth = prevDepth
+    return cleanup
+  }
+
+  // Array of children (e.g. from .map())
+  if (Array.isArray(child)) return mountChildren(child, parent, anchor)
+
+  // Nothing to render
+  if (child == null || child === false) return noop
+
+  // Primitive — text node (static, no reactive effects to tear down).
+  if (typeof child !== "object") {
+    parent.insertBefore(document.createTextNode(String(child)), anchor)
+    return noop
+  }
+
+  // NativeItem — pre-built DOM element from _tpl() or createTemplate().
+  if ((child as unknown as NativeItem).__isNative) {
+    const native = child as unknown as NativeItem
+    parent.insertBefore(native.el, anchor)
+    if (!native.cleanup) {
+      if (_elementDepth > 0) return noop
+      return () => {
+        const p = native.el.parentNode
+        if (p && (p as Element).isConnected !== false) p.removeChild(native.el)
+      }
+    }
+    if (_elementDepth > 0) return native.cleanup
+    return () => {
+      native.cleanup?.()
+      const p = native.el.parentNode
+      if (p && (p as Element).isConnected !== false) p.removeChild(native.el)
+    }
+  }
+
+  // VNode — element, component, fragment, For, Portal
+  const vnode = child as VNode
+
+  if (vnode.type === Fragment) return mountChildren(vnode.children, parent, anchor)
+
+  if (vnode.type === (ForSymbol as unknown as string)) {
+    const { each, by, children } = vnode.props as unknown as ForProps<unknown>
+    const prevDepth = _elementDepth
+    _elementDepth = 0
+    const cleanup = mountFor(each, by, children, parent, anchor, mountChild)
+    _elementDepth = prevDepth
+    return cleanup
+  }
+
+  if (vnode.type === (PortalSymbol as unknown as string)) {
+    const { target, children } = vnode.props as unknown as PortalProps
+    if (__DEV__ && !target) return noop
+    return mountChild(children, target, null)
+  }
+
+  if (typeof vnode.type === "function") {
+    return mountComponent(vnode as VNode & { type: ComponentFn }, parent, anchor)
+  }
+
+  return mountElement(vnode, parent, anchor)
+}
+
+// ─── Element ─────────────────────────────────────────────────────────────────
+
+function mountElement(vnode: VNode, parent: Node, anchor: Node | null): Cleanup {
+  const el = document.createElement(vnode.type as string)
+
+  // Skip applyProps entirely when props is the shared empty sentinel (identity check — no allocation)
+  const props = vnode.props
+  const propCleanup: Cleanup | null = props !== EMPTY_PROPS ? applyProps(el, props) : null
+
+  // Mount children inside element context — nested elements can skip DOM removal closures
+  _elementDepth++
+  const childCleanup = mountChildren(vnode.children, el, null)
+  _elementDepth--
+
+  parent.insertBefore(el, anchor)
+
+  // Populate ref after the element is in the DOM
+  const ref = props.ref as Ref<Element> | null | undefined
+  if (ref && typeof ref === "object") ref.current = el
+
+  if (!propCleanup && childCleanup === noop && !ref) {
+    if (_elementDepth > 0) return noop
+    return () => {
+      const p = el.parentNode
+      if (p && (p as Element).isConnected !== false) p.removeChild(el)
+    }
+  }
+
+  if (_elementDepth > 0) {
+    if (!ref && !propCleanup) return childCleanup
+    if (!ref && propCleanup)
+      return () => {
+        propCleanup()
+        childCleanup()
+      }
+    const refToClean = ref
+    return () => {
+      if (refToClean && typeof refToClean === "object") refToClean.current = null
+      if (propCleanup) propCleanup()
+      childCleanup()
+    }
+  }
+
+  return () => {
+    if (ref && typeof ref === "object") ref.current = null
+    if (propCleanup) propCleanup()
+    childCleanup()
+    const p = el.parentNode
+    if (p && (p as Element).isConnected !== false) p.removeChild(el)
+  }
+}
+
+// ─── Component ───────────────────────────────────────────────────────────────
+
+function mountComponent(
+  vnode: VNode & { type: ComponentFn },
+  parent: Node,
+  anchor: Node | null,
+): Cleanup {
+  const scope = effectScope()
+  setCurrentScope(scope)
+
+  let hooks: ReturnType<typeof runWithHooks>["hooks"]
+  let output: VNode | null
+
+  const componentName = (vnode.type.name || "Anonymous") as string
+  const compId = `${componentName}-${Math.random().toString(36).slice(2, 9)}`
+  const parentId = _mountingStack[_mountingStack.length - 1] ?? null
+  _mountingStack.push(compId)
+
+  // Merge vnode.children into props.children if not already set
+  const mergedProps =
+    vnode.children.length > 0 && (vnode.props as Record<string, unknown>).children === undefined
+      ? {
+          ...vnode.props,
+          children: vnode.children.length === 1 ? vnode.children[0] : vnode.children,
+        }
+      : vnode.props
+
+  try {
+    const result = runWithHooks(vnode.type, mergedProps)
+    hooks = result.hooks
+    output = result.vnode
+  } catch (err) {
+    _mountingStack.pop()
+    setCurrentScope(null)
+    scope.stop()
+    reportError({
+      component: componentName,
+      phase: "setup",
+      error: err,
+      timestamp: Date.now(),
+      props: vnode.props as Record<string, unknown>,
+    })
+    dispatchToErrorBoundary(err)
+    return noop
+  } finally {
+    setCurrentScope(null)
+  }
+
+  if (__DEV__ && output != null && typeof output === "object" && !("type" in output)) {
+    console.warn(
+      `[Pyreon] Component <${componentName}> returned an invalid value. Components must return a VNode, string, null, or function.`,
+    )
+  }
+
+  for (const fn of hooks.update) {
+    scope.addUpdateHook(fn)
+  }
+
+  let subtreeCleanup: Cleanup = noop
+  try {
+    subtreeCleanup = output != null ? mountChild(output, parent, anchor) : noop
+  } catch (err) {
+    _mountingStack.pop()
+    scope.stop()
+    const handled = propagateError(err, hooks) || dispatchToErrorBoundary(err)
+    if (!handled)
+      reportError({
+        component: componentName,
+        phase: "render",
+        error: err,
+        timestamp: Date.now(),
+        props: vnode.props as Record<string, unknown>,
+      })
+    return noop
+  }
+
+  _mountingStack.pop()
+
+  const firstEl = parent instanceof Element ? parent.firstElementChild : null
+  registerComponent(compId, componentName, firstEl, parentId)
+
+  // Fire onMount hooks inline — effects created inside are tracked by the scope
+  const mountCleanups: Cleanup[] = []
+  for (const fn of hooks.mount) {
+    try {
+      let cleanup: (() => void) | undefined
+      scope.runInScope(() => {
+        cleanup = fn()
+      })
+      if (cleanup) mountCleanups.push(cleanup)
+    } catch (err) {
+      console.error(`[Pyreon] Error in onMount hook of <${componentName}>:`, err)
+      reportError({ component: componentName, phase: "mount", error: err, timestamp: Date.now() })
+    }
+  }
+
+  return () => {
+    unregisterComponent(compId)
+    scope.stop()
+    subtreeCleanup()
+    for (const fn of hooks.unmount) {
+      try {
+        fn()
+      } catch (err) {
+        console.error(`[Pyreon] Error in onUnmount hook of <${componentName}>:`, err)
+        reportError({
+          component: componentName,
+          phase: "unmount",
+          error: err,
+          timestamp: Date.now(),
+        })
+      }
+    }
+    for (const fn of mountCleanups) fn()
+  }
+}
+
+// ─── Children ────────────────────────────────────────────────────────────────
+
+function mountChildren(children: VNodeChild[], parent: Node, anchor: Node | null): Cleanup {
+  if (children.length === 0) return noop
+
+  // 1-child fast path
+  if (children.length === 1) {
+    const c = children[0] as VNodeChild
+    if (c !== undefined) {
+      if (anchor === null && (typeof c === "string" || typeof c === "number")) {
+        ;(parent as HTMLElement).textContent = String(c)
+        return noop
+      }
+      return mountChild(c, parent, anchor)
+    }
+  }
+
+  // 2-child fast path — avoids .map() allocation (covers <tr><td/><td/></tr>)
+  if (children.length === 2) {
+    const c0 = children[0] as VNodeChild
+    const c1 = children[1] as VNodeChild
+    if (c0 !== undefined && c1 !== undefined) {
+      const d0 = mountChild(c0, parent, anchor)
+      const d1 = mountChild(c1, parent, anchor)
+      if (d0 === noop && d1 === noop) return noop
+      if (d0 === noop) return d1
+      if (d1 === noop) return d0
+      return () => {
+        d0()
+        d1()
+      }
+    }
+  }
+
+  const cleanups = children.map((c) => mountChild(c, parent, anchor))
+  return () => {
+    for (const fn of cleanups) fn()
+  }
+}
+
+// ─── Keyed array detection ────────────────────────────────────────────────────
+
+/** Returns true if value is a non-empty array of VNodes that all carry keys. */
+function isKeyedArray(value: unknown): value is VNode[] {
+  if (!Array.isArray(value) || value.length === 0) return false
+  return value.every(
+    (v) =>
+      v !== null &&
+      typeof v === "object" &&
+      !Array.isArray(v) &&
+      (v as VNode).key !== null &&
+      (v as VNode).key !== undefined,
+  )
+}