@pyreon/runtime-dom 0.1.0

package/src/devtools.ts

@@ -0,0 +1,304 @@
+/**
+ * Pyreon DevTools — exposes a `__PYREON_DEVTOOLS__` global hook for browser devtools extensions
+ * and in-app debugging utilities.
+ *
+ * Installed automatically on first `mount()` call in the browser.
+ * No-op on the server (typeof window === "undefined").
+ *
+ * Usage:
+ *   window.__PYREON_DEVTOOLS__.getComponentTree()    // root component entries
+ *   window.__PYREON_DEVTOOLS__.getAllComponents()     // flat list of all live components
+ *   window.__PYREON_DEVTOOLS__.highlight("comp-id")  // outline a component's DOM node
+ *   window.__PYREON_DEVTOOLS__.onComponentMount(cb)  // subscribe to mount events
+ *   window.__PYREON_DEVTOOLS__.onComponentUnmount(cb)// subscribe to unmount events
+ *   window.__PYREON_DEVTOOLS__.enableOverlay()       // Ctrl+Shift+P: hover to inspect components
+ */
+
+export interface DevtoolsComponentEntry {
+  id: string
+  name: string
+  /** First DOM element produced by this component, if any */
+  el: Element | null
+  parentId: string | null
+  childIds: string[]
+}
+
+export interface PyreonDevtools {
+  readonly version: string
+  getComponentTree(): DevtoolsComponentEntry[]
+  getAllComponents(): DevtoolsComponentEntry[]
+  highlight(id: string): void
+  onComponentMount(cb: (entry: DevtoolsComponentEntry) => void): () => void
+  onComponentUnmount(cb: (id: string) => void): () => void
+  /** Toggle the component inspector overlay (also: Ctrl+Shift+P) */
+  enableOverlay(): void
+  disableOverlay(): void
+}
+
+// ─── Internal registry ────────────────────────────────────────────────────────
+
+const _components = new Map<string, DevtoolsComponentEntry>()
+const _mountListeners: ((entry: DevtoolsComponentEntry) => void)[] = []
+const _unmountListeners: ((id: string) => void)[] = []
+
+export function registerComponent(
+  id: string,
+  name: string,
+  el: Element | null,
+  parentId: string | null,
+): void {
+  const entry: DevtoolsComponentEntry = { id, name, el, parentId, childIds: [] }
+  _components.set(id, entry)
+  if (parentId) {
+    const parent = _components.get(parentId)
+    if (parent) parent.childIds.push(id)
+  }
+  for (const cb of _mountListeners) cb(entry)
+}
+
+export function unregisterComponent(id: string): void {
+  const entry = _components.get(id)
+  if (!entry) return
+  if (entry.parentId) {
+    const parent = _components.get(entry.parentId)
+    if (parent) parent.childIds = parent.childIds.filter((c) => c !== id)
+  }
+  _components.delete(id)
+  for (const cb of _unmountListeners) cb(id)
+}
+
+// ─── Component Inspector Overlay ─────────────────────────────────────────────
+
+let _overlayActive = false
+let _overlayEl: HTMLDivElement | null = null
+let _tooltipEl: HTMLDivElement | null = null
+let _currentHighlight: Element | null = null
+
+function findComponentForElement(el: Element): DevtoolsComponentEntry | null {
+  // Walk up from the hovered element to find the nearest registered component
+  let node: Element | null = el
+  while (node) {
+    for (const entry of _components.values()) {
+      if (entry.el === node) return entry
+    }
+    node = node.parentElement
+  }
+  return null
+}
+
+function createOverlayElements(): void {
+  if (_overlayEl) return
+
+  _overlayEl = document.createElement("div")
+  _overlayEl.id = "__pyreon-overlay"
+  _overlayEl.style.cssText =
+    "position:fixed;pointer-events:none;border:2px solid #00b4d8;border-radius:3px;z-index:999999;display:none;transition:all 0.08s ease-out;"
+
+  _tooltipEl = document.createElement("div")
+  _tooltipEl.style.cssText =
+    "position:fixed;pointer-events:none;background:#1a1a2e;color:#e0e0e0;font:12px/1.4 ui-monospace,monospace;padding:6px 10px;border-radius:4px;z-index:999999;display:none;box-shadow:0 2px 8px rgba(0,0,0,0.3);max-width:400px;white-space:pre-wrap;"
+
+  document.body.appendChild(_overlayEl)
+  document.body.appendChild(_tooltipEl)
+}
+
+function positionOverlay(rect: DOMRect): void {
+  if (!_overlayEl) return
+  _overlayEl.style.display = "block"
+  _overlayEl.style.top = `${rect.top}px`
+  _overlayEl.style.left = `${rect.left}px`
+  _overlayEl.style.width = `${rect.width}px`
+  _overlayEl.style.height = `${rect.height}px`
+}
+
+function positionTooltip(entry: DevtoolsComponentEntry, rect: DOMRect): void {
+  if (!_tooltipEl) return
+  const childCount = entry.childIds.length
+  let info = `<${entry.name}>`
+  if (childCount > 0) info += `\n  ${childCount} child component${childCount === 1 ? "" : "s"}`
+  _tooltipEl.textContent = info
+  _tooltipEl.style.display = "block"
+  _tooltipEl.style.top = `${rect.top - 30}px`
+  _tooltipEl.style.left = `${rect.left}px`
+  if (rect.top < 35) {
+    _tooltipEl.style.top = `${rect.bottom + 4}px`
+  }
+}
+
+function hideOverlayElements(): void {
+  if (_overlayEl) _overlayEl.style.display = "none"
+  if (_tooltipEl) _tooltipEl.style.display = "none"
+  _currentHighlight = null
+}
+
+/** @internal — exported for testing only */
+export function onOverlayMouseMove(e: MouseEvent): void {
+  const target = document.elementFromPoint(e.clientX, e.clientY)
+  if (!target || target === _overlayEl || target === _tooltipEl) return
+
+  const entry = findComponentForElement(target)
+  if (!entry?.el) {
+    hideOverlayElements()
+    return
+  }
+
+  if (entry.el === _currentHighlight) return
+  _currentHighlight = entry.el
+
+  const rect = entry.el.getBoundingClientRect()
+  positionOverlay(rect)
+  positionTooltip(entry, rect)
+}
+
+/** @internal — exported for testing only */
+export function onOverlayClick(e: MouseEvent): void {
+  e.preventDefault()
+  e.stopPropagation()
+  const target = document.elementFromPoint(e.clientX, e.clientY)
+  if (!target) return
+  const entry = findComponentForElement(target)
+  if (entry) {
+    console.group(`[Pyreon] <${entry.name}>`)
+    console.log("element:", entry.el)
+    console.log("children:", entry.childIds.length)
+    if (entry.parentId) {
+      const parent = _components.get(entry.parentId)
+      if (parent) {
+        console.log("parent:", `<${parent.name}>`)
+      }
+    }
+    console.groupEnd()
+  }
+  disableOverlay()
+}
+
+function onOverlayKeydown(e: KeyboardEvent): void {
+  if (e.key === "Escape") {
+    disableOverlay()
+  }
+}
+
+function enableOverlay(): void {
+  if (_overlayActive) return
+  _overlayActive = true
+  createOverlayElements()
+  document.addEventListener("mousemove", onOverlayMouseMove, true)
+  document.addEventListener("click", onOverlayClick, true)
+  document.addEventListener("keydown", onOverlayKeydown, true)
+  document.body.style.cursor = "crosshair"
+}
+
+function disableOverlay(): void {
+  if (!_overlayActive) return
+  _overlayActive = false
+  document.removeEventListener("mousemove", onOverlayMouseMove, true)
+  document.removeEventListener("click", onOverlayClick, true)
+  document.removeEventListener("keydown", onOverlayKeydown, true)
+  document.body.style.cursor = ""
+  if (_overlayEl) _overlayEl.style.display = "none"
+  if (_tooltipEl) _tooltipEl.style.display = "none"
+  _currentHighlight = null
+}
+
+// ─── Installation ─────────────────────────────────────────────────────────────
+
+let _installed = false
+// Resolved once at module load — avoids per-call typeof branch in coverage
+const _hasWindow = typeof window !== "undefined"
+
+export function installDevTools(): void {
+  if (!_hasWindow || _installed) return
+  _installed = true
+
+  const devtools: PyreonDevtools = {
+    version: "0.1.0",
+
+    getComponentTree() {
+      return Array.from(_components.values()).filter((e) => e.parentId === null)
+    },
+
+    getAllComponents() {
+      return Array.from(_components.values())
+    },
+
+    highlight(id: string) {
+      const entry = _components.get(id)
+      if (!entry?.el) return
+      const el = entry.el as HTMLElement
+      const prev = el.style.outline
+      el.style.outline = "2px solid #00b4d8"
+      setTimeout(() => {
+        el.style.outline = prev
+      }, 1500)
+    },
+
+    onComponentMount(cb: (entry: DevtoolsComponentEntry) => void): () => void {
+      _mountListeners.push(cb)
+      return () => {
+        const i = _mountListeners.indexOf(cb)
+        if (i >= 0) _mountListeners.splice(i, 1)
+      }
+    },
+
+    onComponentUnmount(cb: (id: string) => void): () => void {
+      _unmountListeners.push(cb)
+      return () => {
+        const i = _unmountListeners.indexOf(cb)
+        if (i >= 0) _unmountListeners.splice(i, 1)
+      }
+    },
+
+    enableOverlay,
+    disableOverlay,
+  }
+
+  // Attach to window — compatible with browser devtools extensions
+  ;(window as unknown as Record<string, unknown>).__PYREON_DEVTOOLS__ = devtools
+
+  // Ctrl+Shift+P toggles the component inspector overlay
+  window.addEventListener("keydown", (e) => {
+    if (e.ctrlKey && e.shiftKey && e.key === "P") {
+      e.preventDefault()
+      if (_overlayActive) disableOverlay()
+      else enableOverlay()
+    }
+  })
+
+  // ── $p console helper ────────────────────────────────────────────────────
+  // Type `$p` in the browser console for quick access to Pyreon debug tools.
+  const win = window as unknown as Record<string, unknown>
+  win.$p = {
+    /** List all mounted components */
+    components: () => devtools.getAllComponents(),
+    /** Component tree (roots only) */
+    tree: () => devtools.getComponentTree(),
+    /** Highlight a component by id */
+    highlight: (id: string) => devtools.highlight(id),
+    /** Toggle component inspector overlay */
+    inspect: () => {
+      if (_overlayActive) disableOverlay()
+      else enableOverlay()
+    },
+    /** Print component count */
+    stats: () => {
+      const all = devtools.getAllComponents()
+      const roots = devtools.getComponentTree()
+      console.log(
+        `[Pyreon] ${all.length} component${all.length === 1 ? "" : "s"}, ${roots.length} root${roots.length === 1 ? "" : "s"}`,
+      )
+      return { total: all.length, roots: roots.length }
+    },
+    /** Quick help */
+    help: () => {
+      console.log(
+        "[Pyreon] $p commands:\n" +
+          "  $p.components() — list all mounted components\n" +
+          "  $p.tree()       — component tree (roots only)\n" +
+          "  $p.highlight(id)— outline a component\n" +
+          "  $p.inspect()    — toggle component inspector\n" +
+          "  $p.stats()      — print component count\n" +
+          "  $p.help()       — this message",
+      )
+    },
+  }
+}

package/src/hydrate.ts

@@ -0,0 +1,385 @@
+/**
+ * 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, Ref, VNode, VNodeChild } from "@pyreon/core"
+import {
+  dispatchToErrorBoundary,
+  ForSymbol,
+  Fragment,
+  PortalSymbol,
+  reportError,
+  runWithHooks,
+} from "@pyreon/core"
+import { effect, effectScope, runUntracked, setCurrentScope } from "@pyreon/reactivity"
+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 && (node as Text).data.trim() === "") {
+      node = node.nextSibling
+      continue
+    }
+    return node
+  }
+  return null
+}
+
+/** 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,
+    )
+  }
+
+  const marker = insertMarker(parent, domNode, "pyreon")
+  const cleanup = mountReactive(child, parent, marker, mountChild)
+  const next = domNode ? nextReal(domNode) : null
+  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 e = effect(() => {
+      const v = child()
+      textNode.data = v == null ? "" : String(v)
+    })
+    return [() => e.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]
+  }
+
+  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 Ref<Element> | undefined
+    if (ref && typeof ref === "object") ref.current = el
+
+    const cleanup = () => {
+      if (ref && typeof ref === "object") 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] {
+  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 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
+
+  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
+  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
+  for (const fn of hooks.mount) {
+    try {
+      let c: (() => void) | undefined
+      scope.runInScope(() => {
+        c = fn()
+      })
+      if (c) mountCleanups.push(c)
+    } catch (err) {
+      reportError({ component: componentName, phase: "mount", error: err, timestamp: Date.now() })
+    }
+  }
+
+  const cleanup: Cleanup = () => {
+    scope.stop()
+    subtreeCleanup()
+    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 {
+  const firstChild = firstReal(container.firstChild as ChildNode | null)
+  const [cleanup] = hydrateChild(vnode, firstChild, container, null)
+  return cleanup
+}