@pyreon/runtime-dom 0.24.4 → 0.24.6

package/src/hydrate.ts

@@ -1,450 +0,0 @@
-/**
- * SSR Hydration — "walk-and-claim" strategy.
- *
- * The server renders plain HTML (no special markers needed). On the client,
- * hydrateRoot walks the VNode tree in parallel with the live DOM tree and:
- *
- *  - Static elements   → matched by tag position, props attached (events + reactive effects)
- *  - Static text       → existing text node reused
- *  - Reactive text     → existing text node found, reactive effect attached to .data
- *  - Reactive blocks   → comment marker inserted, mountReactive takes over
- *  - Components        → component fn called, output VNode matched against DOM subtree
- *  - For lists         → full remount (can't map keys to DOM without SSR markers)
- *  - Fragment          → transparent, children matched directly
- *  - Portal            → always remounts into target
- *
- * Falls back to mountChild() whenever DOM structure doesn't match the VNode.
- */
-
-import type { ComponentFn, RefProp, VNode, VNodeChild } from '@pyreon/core'
-import {
-  dispatchToErrorBoundary,
-  ForSymbol,
-  Fragment,
-  makeReactiveProps,
-  PortalSymbol,
-  reportError,
-  runWithHooks,
-} from '@pyreon/core'
-import { effectScope, renderEffect, runUntracked, setCurrentScope } from '@pyreon/reactivity'
-import { setupDelegation } from './delegate'
-import { warnHydrationMismatch } from './hydration-debug'
-import { mountChild } from './mount'
-import { mountReactive } from './nodes'
-import { applyProps } from './props'
-
-type Cleanup = () => void
-const noop: Cleanup = () => {
-  /* noop */
-}
-
-// ─── DOM cursor helpers ───────────────────────────────────────────────────────
-
-/** Skip comment and whitespace-only text nodes, return first "real" node */
-function firstReal(initialNode: ChildNode | null): ChildNode | null {
-  let node = initialNode
-  while (node) {
-    if (node.nodeType === Node.COMMENT_NODE) {
-      node = node.nextSibling
-      continue
-    }
-    if (node.nodeType === Node.TEXT_NODE && isWhitespaceOnly((node as Text).data)) {
-      node = node.nextSibling
-      continue
-    }
-    return node
-  }
-  return null
-}
-
-/** Check if a string is whitespace-only without allocating a trimmed copy. */
-function isWhitespaceOnly(s: string): boolean {
-  for (let i = 0; i < s.length; i++) {
-    const c = s.charCodeAt(i)
-    // space, tab, newline, carriage return, form feed
-    if (c !== 32 && c !== 9 && c !== 10 && c !== 13 && c !== 12) return false
-  }
-  return true
-}
-
-/** Advance past a node, skipping whitespace-only text and comments */
-function nextReal(node: ChildNode): ChildNode | null {
-  return firstReal(node.nextSibling)
-}
-
-// ─── Core recursive walker ────────────────────────────────────────────────────
-
-/**
- * Hydrate a single VNodeChild against the DOM subtree starting at `domNode`.
- * Returns [cleanup, nextDomSibling].
- */
-/** Insert a comment marker before domNode (or append if domNode is null). */
-function insertMarker(parent: Node, domNode: ChildNode | null, text: string): Comment {
-  const marker = document.createComment(text)
-  if (domNode) {
-    parent.insertBefore(marker, domNode)
-  } else {
-    parent.appendChild(marker)
-  }
-  return marker
-}
-
-/** Hydrate a reactive accessor (function child). */
-function hydrateReactiveChild(
-  child: () => VNodeChild,
-  domNode: ChildNode | null,
-  parent: Node,
-  anchor: Node | null,
-  path: string,
-): [Cleanup, ChildNode | null] {
-  const initial = runUntracked(child)
-
-  if (initial == null || initial === false) {
-    const marker = insertMarker(parent, domNode, 'pyreon')
-    const cleanup = mountReactive(child, parent, marker, mountChild)
-    return [cleanup, domNode]
-  }
-
-  if (typeof initial === 'string' || typeof initial === 'number' || typeof initial === 'boolean') {
-    return hydrateReactiveText(
-      child as () => string | number | boolean | null | undefined,
-      domNode,
-      parent,
-      anchor,
-      path,
-    )
-  }
-
-  // Reactive accessor that produces a VNode/NativeItem subtree.
-  const next = domNode ? nextReal(domNode) : null
-  if (domNode && domNode.parentNode) {
-    domNode.parentNode.removeChild(domNode)
-  }
-  const marker = insertMarker(parent, next, 'pyreon')
-  const cleanup = mountReactive(child, parent, marker, mountChild)
-  return [cleanup, next]
-}
-
-/** Hydrate a reactive text binding against an existing text node. */
-function hydrateReactiveText(
-  child: () => string | number | boolean | null | undefined,
-  domNode: ChildNode | null,
-  parent: Node,
-  anchor: Node | null,
-  path: string,
-): [Cleanup, ChildNode | null] {
-  if (domNode?.nodeType === Node.TEXT_NODE) {
-    const textNode = domNode as Text
-    const dispose = renderEffect(() => {
-      const v = child()
-      textNode.data = v == null ? '' : String(v)
-    })
-    return [dispose, nextReal(domNode)]
-  }
-  warnHydrationMismatch('text', 'TextNode', domNode?.nodeType ?? 'null', `${path} > reactive`)
-  const cleanup = mountChild(child, parent, anchor)
-  return [cleanup, domNode]
-}
-
-/** Hydrate a VNode (fragment, For, Portal, component, element). */
-function hydrateVNode(
-  vnode: VNode,
-  domNode: ChildNode | null,
-  parent: Node,
-  anchor: Node | null,
-  path: string,
-): [Cleanup, ChildNode | null] {
-  if (vnode.type === Fragment) {
-    return hydrateChildren(vnode.children ?? [], domNode, parent, anchor, path)
-  }
-
-  if (vnode.type === ForSymbol) {
-    const marker = insertMarker(parent, domNode, 'pyreon-for')
-    const cleanup = mountChild(vnode, parent, marker)
-    return [cleanup, null]
-  }
-
-  if (vnode.type === PortalSymbol) {
-    const cleanup = mountChild(vnode, parent, anchor)
-    return [cleanup, domNode]
-  }
-
-  if (typeof vnode.type === 'function') {
-    return hydrateComponent(vnode, domNode, parent, anchor, path)
-  }
-
-  if (typeof vnode.type === 'string') {
-    return hydrateElement(vnode, domNode, parent, anchor, path)
-  }
-
-  return [noop, domNode]
-}
-
-function hydrateChild(
-  child: VNodeChild | VNodeChild[],
-  domNode: ChildNode | null,
-  parent: Node,
-  anchor: Node | null,
-  path = 'root',
-): [Cleanup, ChildNode | null] {
-  if (Array.isArray(child)) {
-    const cleanups: Cleanup[] = []
-    let cursor = domNode
-    for (const c of child) {
-      const [cleanup, next] = hydrateChild(c, cursor, parent, anchor, path)
-      cleanups.push(cleanup)
-      cursor = next
-    }
-    return [
-      () => {
-        for (const c of cleanups) c()
-      },
-      cursor,
-    ]
-  }
-
-  if (child == null || child === false) return [noop, domNode]
-
-  if (typeof child === 'function') {
-    return hydrateReactiveChild(child as () => VNodeChild, domNode, parent, anchor, path)
-  }
-
-  if (typeof child === 'string' || typeof child === 'number') {
-    if (domNode?.nodeType === Node.TEXT_NODE) {
-      return [() => (domNode as Text).remove(), nextReal(domNode)]
-    }
-    warnHydrationMismatch('text', 'TextNode', domNode?.nodeType ?? 'null', `${path} > text`)
-    const cleanup = mountChild(child, parent, anchor)
-    return [cleanup, domNode]
-  }
-
-  // NativeItem — output of the compiler's `_tpl()` template fast path. The
-  // client builds a fresh DOM subtree in memory (cloned + reactively bound).
-  // We don't yet have a true hydration mode for `_tpl` (which would adopt
-  // existing DOM nodes and rebind without remount). For now, swap the SSR
-  // subtree at this position for the freshly-mounted one — same final DOM,
-  // no duplication, reactivity intact. This is correctness-first; a true
-  // adopting hydration is a separate compiler-side change.
-  if ((child as unknown as { __isNative?: boolean })?.__isNative === true) {
-    const native = child as unknown as { __isNative: true; el: Node; cleanup?: () => void }
-    const next = domNode ? nextReal(domNode) : null
-    if (domNode && domNode.parentNode) {
-      domNode.parentNode.replaceChild(native.el, domNode)
-    } else {
-      parent.insertBefore(native.el, anchor)
-    }
-    const cleanup = () => {
-      native.cleanup?.()
-      const p = native.el.parentNode
-      if (p && (p as Element).isConnected !== false) p.removeChild(native.el)
-    }
-    return [cleanup, next]
-  }
-
-  return hydrateVNode(child as VNode, domNode, parent, anchor, path)
-}
-
-// ─── Element hydration ────────────────────────────────────────────────────────
-
-function hydrateElement(
-  vnode: VNode,
-  domNode: ChildNode | null,
-  parent: Node,
-  anchor: Node | null,
-  path = 'root',
-): [Cleanup, ChildNode | null] {
-  const elPath = `${path} > ${vnode.type as string}`
-
-  // Check if existing DOM node matches
-  if (
-    domNode?.nodeType === Node.ELEMENT_NODE &&
-    (domNode as Element).tagName.toLowerCase() === vnode.type
-  ) {
-    const el = domNode as Element
-    const cleanups: Cleanup[] = []
-
-    // Attach props (events + reactive effects) — don't set static attrs (SSR already did)
-    const propCleanup = applyProps(el, vnode.props)
-    if (propCleanup) cleanups.push(propCleanup)
-
-    // Hydrate children
-    const firstChild = firstReal(el.firstChild as ChildNode | null)
-    const [childCleanup] = hydrateChildren(vnode.children ?? [], firstChild, el, null, elPath)
-    cleanups.push(childCleanup)
-
-    // Set ref
-    const ref = vnode.props.ref as RefProp<Element> | undefined
-    if (ref) {
-      if (typeof ref === 'function') ref(el)
-      else ref.current = el
-    }
-
-    const cleanup = () => {
-      if (ref) {
-        if (typeof ref === 'function') ref(null)
-        else ref.current = null
-      }
-      for (const c of cleanups) c()
-      el.remove()
-    }
-
-    return [cleanup, nextReal(domNode)]
-  }
-
-  // Mismatch — fall back to fresh mount
-  const actual =
-    domNode?.nodeType === Node.ELEMENT_NODE
-      ? (domNode as Element).tagName.toLowerCase()
-      : (domNode?.nodeType ?? 'null')
-  warnHydrationMismatch('tag', vnode.type, actual, elPath)
-  const cleanup = mountChild(vnode, parent, anchor)
-  return [cleanup, domNode]
-}
-
-// ─── Children hydration ───────────────────────────────────────────────────────
-
-function hydrateChildren(
-  children: VNodeChild[],
-  domNode: ChildNode | null,
-  parent: Node,
-  anchor: Node | null,
-  path = 'root',
-): [Cleanup, ChildNode | null] {
-  if (children.length === 0) return [noop, domNode]
-
-  // Single-child fast path — avoids cleanups array allocation
-  if (children.length === 1) {
-    return hydrateChild(children[0] as VNodeChild, domNode, parent, anchor, path)
-  }
-
-  const cleanups: Cleanup[] = []
-  let cursor = domNode
-  for (const child of children) {
-    const [cleanup, next] = hydrateChild(child, cursor, parent, anchor, path)
-    cleanups.push(cleanup)
-    cursor = next
-  }
-  return [
-    () => {
-      for (const c of cleanups) c()
-    },
-    cursor,
-  ]
-}
-
-// ─── Component hydration ──────────────────────────────────────────────────────
-
-function hydrateComponent(
-  vnode: VNode,
-  domNode: ChildNode | null,
-  parent: Node,
-  anchor: Node | null,
-  path = 'root',
-): [Cleanup, ChildNode | null] {
-  const scope = effectScope()
-  setCurrentScope(scope)
-
-  let subtreeCleanup: Cleanup = noop
-  const mountCleanups: Cleanup[] = []
-  let nextDom: ChildNode | null = domNode
-
-  // Function.name is always a string per spec; || handles empty string, avoids uncoverable ?? branch
-  const componentName = ((vnode.type as ComponentFn).name || 'Anonymous') as string
-  const rawProps =
-    (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 as Record<string, unknown>)
-  // Convert compiler-emitted `_rp(() => expr)` wrappers into getter properties —
-  // mirrors mount.ts so component code can read `props.x` and get the resolved
-  // value (not the raw `_rp` function). Without this, hydration set up reactive
-  // bindings against the wrong values and any signal-driven re-render would
-  // diverge from the SSR HTML.
-  const mergedProps = makeReactiveProps(rawProps as Record<string, unknown>)
-
-  let result: ReturnType<typeof runWithHooks>
-  try {
-    result = runWithHooks(vnode.type as ComponentFn, mergedProps)
-  } catch (err) {
-    setCurrentScope(null)
-    scope.stop()
-
-    console.error(`[Pyreon] Error hydrating component <${componentName}>:`, err)
-    reportError({
-      component: componentName,
-      phase: 'setup',
-      error: err,
-      timestamp: Date.now(),
-      props: vnode.props as Record<string, unknown>,
-    })
-    dispatchToErrorBoundary(err)
-    return [noop, domNode]
-  }
-  setCurrentScope(null)
-
-  const { vnode: output, hooks } = result
-
-  // Register onUpdate hooks with the scope
-  if (hooks.update) {
-    for (const fn of hooks.update) scope.addUpdateHook(fn)
-  }
-
-  if (output != null) {
-    const [childCleanup, next] = hydrateChild(output, domNode, parent, anchor, path)
-    subtreeCleanup = childCleanup
-    nextDom = next
-  }
-
-  // Fire onMount hooks; effects created inside are tracked by the scope via runInScope
-  if (hooks.mount) {
-    for (const fn of hooks.mount) {
-      try {
-        let c: (() => void) | undefined
-        scope.runInScope(() => {
-          c = fn() as (() => void) | undefined
-        })
-        if (c) mountCleanups.push(c)
-      } catch (err) {
-        reportError({ component: componentName, phase: 'mount', error: err, timestamp: Date.now() })
-      }
-    }
-  }
-
-  const cleanup: Cleanup = () => {
-    scope.stop()
-    subtreeCleanup()
-    if (hooks.unmount) for (const fn of hooks.unmount) fn()
-    for (const fn of mountCleanups) fn()
-  }
-
-  return [cleanup, nextDom]
-}
-
-// ─── Public API ───────────────────────────────────────────────────────────────
-
-/**
- * Hydrate a server-rendered container with a Pyreon VNode tree.
- *
- * Reuses existing DOM elements for static structure, attaches event listeners
- * and reactive effects without re-rendering. Falls back to fresh mount for
- * dynamic content (reactive conditionals, For lists).
- *
- * @example
- * // Server:
- * const html = await renderToString(h(App, null))
- *
- * // Client:
- * const unmount = hydrateRoot(document.getElementById("app")!, h(App, null))
- */
-export function hydrateRoot(container: Element, vnode: VNodeChild): () => void {
-  setupDelegation(container)
-  const firstChild = firstReal(container.firstChild as ChildNode | null)
-  const [cleanup] = hydrateChild(vnode, firstChild, container, null)
-  return cleanup
-}

package/src/hydration-debug.ts

@@ -1,129 +0,0 @@
-/**
- * Hydration mismatch warnings + telemetry hook.
- *
- * Two complementary surfaces:
- *
- * 1. **Dev-mode console.warn** — enabled automatically when
- *    `NODE_ENV !== "production"` (and silent otherwise, matching React /
- *    Vue / Solid). Toggle manually with `enableHydrationWarnings()` /
- *    `disableHydrationWarnings()` if you need verbose production debugging.
- *
- * 2. **Telemetry callback** — register a handler with
- *    `onHydrationMismatch(handler)` to forward every mismatch into your
- *    error-tracking pipeline (Sentry, Datadog, etc.). Fires on EVERY
- *    mismatch, in development AND production, regardless of the warn
- *    toggle. Returns an unregister function.
- *
- * The dev warn and the telemetry callback are independent: a production
- * deployment can install Sentry forwarding via `onHydrationMismatch`
- * WITHOUT enabling the noisy console output.
- *
- * @example — dev console
- * import { enableHydrationWarnings } from "@pyreon/runtime-dom"
- * enableHydrationWarnings()
- *
- * @example — production telemetry
- * import { onHydrationMismatch } from "@pyreon/runtime-dom"
- * import * as Sentry from "@sentry/browser"
- *
- * onHydrationMismatch(ctx => {
- *   Sentry.captureMessage(`Hydration mismatch (${ctx.type})`, {
- *     extra: { expected: ctx.expected, actual: ctx.actual, path: ctx.path },
- *     level: 'warning',
- *   })
- * })
- */
-
-// Dev-mode gate: see `pyreon/no-process-dev-gate` lint rule for why this
-// uses `import.meta.env.DEV` instead of `typeof process !== 'undefined'`.
-const __DEV__ = process.env.NODE_ENV !== 'production'
-
-let _enabled = __DEV__
-
-export function enableHydrationWarnings(): void {
-  _enabled = true
-}
-
-export function disableHydrationWarnings(): void {
-  _enabled = false
-}
-
-// ─── Telemetry callback ─────────────────────────────────────────────────────
-
-export type HydrationMismatchType = 'tag' | 'text' | 'missing'
-
-export interface HydrationMismatchContext {
-  /** Kind of mismatch */
-  type: HydrationMismatchType
-  /** What the VNode expected */
-  expected: unknown
-  /** What the DOM had */
-  actual: unknown
-  /** Human-readable path in the tree, e.g. "root > div > span" */
-  path: string
-  /** Unix timestamp (ms) */
-  timestamp: number
-}
-
-export type HydrationMismatchHandler = (ctx: HydrationMismatchContext) => void
-
-let _handlers: HydrationMismatchHandler[] = []
-
-/**
- * Register a hydration mismatch handler. Called on every mismatch in BOTH
- * development and production, independent of the dev-mode warn toggle.
- *
- * Mirrors `@pyreon/core`'s `registerErrorHandler` pattern — multiple
- * handlers can be registered; each is called in registration order;
- * handler errors are swallowed so they don't propagate into the
- * framework. Returns an unregister function.
- */
-export function onHydrationMismatch(handler: HydrationMismatchHandler): () => void {
-  _handlers.push(handler)
-  return () => {
-    _handlers = _handlers.filter((h) => h !== handler)
-  }
-}
-
-/**
- * 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: HydrationMismatchType,
-  expected: unknown,
-  actual: unknown,
-  path: string,
-): void {
-  // Dev-mode console.warn — gated on _enabled (default __DEV__).
-  if (_enabled) {
-    // oxlint-disable-next-line no-console
-    console.warn(
-      `[Pyreon] Hydration mismatch (${type}): expected ${String(expected)}, got ${String(actual)} at ${path}`,
-    )
-  }
-
-  // Telemetry callbacks — fire in BOTH dev and prod, independent of the
-  // warn toggle. This is the production observability hook (Sentry,
-  // Datadog, etc.) that pre-fix was missing entirely.
-  if (_handlers.length > 0) {
-    const ctx: HydrationMismatchContext = {
-      type,
-      expected,
-      actual,
-      path,
-      timestamp: Date.now(),
-    }
-    for (const h of _handlers) {
-      try {
-        h(ctx)
-      } catch {
-        // handler errors must never propagate back into the hydration
-        // pipeline — a broken Sentry SDK shouldn't crash the app.
-      }
-    }
-  }
-}

package/src/index.ts

@@ -1,83 +0,0 @@
-// @pyreon/runtime-dom — surgical signal-to-DOM renderer (no virtual DOM)
-
-export { DELEGATED_EVENTS, delegatedPropName, setupDelegation } from './delegate'
-export type { DevtoolsComponentEntry, PyreonDevtools } from './devtools'
-export { hydrateRoot } from './hydrate'
-export type {
-  HydrationMismatchContext,
-  HydrationMismatchHandler,
-  HydrationMismatchType,
-} from './hydration-debug'
-export {
-  disableHydrationWarnings,
-  enableHydrationWarnings,
-  onHydrationMismatch,
-} from './hydration-debug'
-export type { KeepAliveProps } from './keep-alive'
-export { KeepAlive } from './keep-alive'
-export { mountChild } from './mount'
-export type { SanitizeFn } from './props'
-export {
-  applyProp,
-  applyProps,
-  applyProps as _applyProps,
-  sanitizeHtml,
-  setSanitizer,
-} from './props'
-export {
-  _bindDirect,
-  _bindText,
-  _mountSlot,
-  _rsCollapse,
-  _rsCollapseDyn,
-  _rsCollapseDynH,
-  _rsCollapseH,
-  _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 { setupDelegation } from './delegate'
-import { installDevTools } from './devtools'
-import { mountChild } from './mount'
-
-// Dev-mode gate: see `pyreon/no-process-dev-gate` lint rule for why this
-// uses `import.meta.env.DEV` instead of `typeof process !== 'undefined'`.
-const __DEV__ = process.env.NODE_ENV !== 'production'
-
-// Dev-time counter sink — see packages/internals/perf-harness for contract.
-const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }
-
-/**
- * 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")',
-    )
-  }
-  if (__DEV__) {
-    _countSink.__pyreon_count__?.('runtime.mount')
-    installDevTools()
-  }
-  setupDelegation(container)
-  container.innerHTML = ''
-  const unmount = mountChild(root, container, null)
-  return () => {
-    if (__DEV__) _countSink.__pyreon_count__?.('runtime.unmount')
-    unmount()
-  }
-}
-
-/** Alias for `mount` */
-export const render = mount

package/src/keep-alive-entry.ts

@@ -1,3 +0,0 @@
-// Subpath entry for @pyreon/runtime-dom/keep-alive
-export type { KeepAliveProps } from './keep-alive'
-export { KeepAlive } from './keep-alive'