@pyreon/runtime-server 0.24.5 → 0.24.6

package/src/index.ts

@@ -1,885 +0,0 @@
-/**
- * @pyreon/runtime-server — SSR/SSG renderer for Pyreon.
- *
- * Walks a VNode tree and produces HTML strings.
- * Signal accessors (reactive getters `() => value`) are called synchronously
- * to snapshot their current value — no effects are set up on the server.
- *
- * Async components (`async function Component()`) are fully supported:
- * renderToString will await them before continuing the tree walk.
- *
- * API:
- *   renderToString(vnode)   → Promise<string>
- *   renderToStream(vnode)   → ReadableStream<string>
- */
-
-import { AsyncLocalStorage } from 'node:async_hooks'
-import type { ClassValue, ComponentFn, ForProps, VNode, VNodeChild } from '@pyreon/core'
-import {
-  cx,
-  ForSymbol,
-  Fragment,
-  getContextStackLength,
-  makeReactiveProps,
-  normalizeStyleValue,
-  popContext,
-  runWithHooks,
-  Suspense,
-  setContextStackProvider,
-} from '@pyreon/core'
-
-const __DEV__ = typeof process !== 'undefined' && process.env.NODE_ENV !== 'production'
-
-// Dev-mode perf counter sink. Zero coupling to @pyreon/perf-harness — we just
-// call the global if it's installed. Guarded on __DEV__ so NODE_ENV=production
-// short-circuits at runtime; @pyreon/runtime-server is a server package, so the
-// `typeof process` gate is correct here (not `import.meta.env.DEV`, which is a
-// browser-bundler concern). See .claude/rules/test-environment-parity.md.
-const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }
-
-// ─── Streaming Suspense context ───────────────────────────────────────────────
-// Tracks in-flight async Suspense boundary resolutions within a single stream.
-
-interface StreamCtx {
-  pending: Promise<void>[]
-  nextId: () => number
-  mainEnqueue: (s: string) => void
-  /** Depth counter — non-zero when rendering inside a Suspense child resolution. */
-  suspenseDepth: number
-  /**
-   * Abort signal fired when EITHER the upstream caller's signal aborts
-   * OR the stream consumer (`ReadableStream.cancel()`) closes. Boundary
-   * resolvers check this before enqueuing post-resolve HTML so they
-   * stop streaming once the client has hung up.
-   */
-  signal?: AbortSignal
-  /**
-   * Per-boundary Suspense timeout (ms). When an async Suspense child
-   * doesn't resolve within this window, the fallback stays visible and
-   * the resolved content is dropped. Set to `Infinity` to disable the
-   * timeout entirely (apps that prefer waiting indefinitely over showing
-   * the fallback). Defaults to 30_000 (30s) — matches the pre-config
-   * hard-coded value, so unset is byte-identical to prior behavior.
-   */
-  suspenseTimeoutMs: number
-}
-
-const _streamCtxAls = new AsyncLocalStorage<StreamCtx>()
-
-// ─── Concurrent SSR context isolation ────────────────────────────────────────
-// Each renderToString call runs in its own ALS store (a fresh empty stack[]).
-// Concurrent requests never share context frames.
-
-const _contextAls = new AsyncLocalStorage<Map<symbol, unknown>[]>()
-const _fallbackStack: Map<symbol, unknown>[] = []
-
-setContextStackProvider(() => _contextAls.getStore() ?? _fallbackStack)
-
-// ─── Store isolation (optional) ───────────────────────────────────────────────
-// A second ALS isolates store registries between concurrent requests.
-// Activated only when the user calls configureStoreIsolation().
-
-const _storeAls = new AsyncLocalStorage<Map<string, unknown>>()
-let _storeIsolationActive = false
-
-/**
- * Wire up per-request store isolation.
- * Call once at server startup, passing a `setStoreRegistryProvider` function.
- *
- * @example
- * import { configureStoreIsolation } from "@pyreon/runtime-server"
- * configureStoreIsolation(setStoreRegistryProvider)
- */
-export function configureStoreIsolation(
-  setStoreRegistryProvider: (fn: () => Map<string, unknown>) => void,
-): void {
-  setStoreRegistryProvider(() => _storeAls.getStore() ?? new Map())
-  _storeIsolationActive = true
-}
-
-/** Wrap a function call in a fresh store registry (no-op if isolation not configured). */
-function withStoreContext<T>(fn: () => T): T {
-  if (!_storeIsolationActive) return fn()
-  return _storeAls.run(new Map(), fn)
-}
-
-// ─── Public API ───────────────────────────────────────────────────────────────
-
-/** Render a VNode tree to an HTML string. Supports async component functions. */
-export async function renderToString(root: VNode | null): Promise<string> {
-  if (root === null) return ''
-  if (__DEV__) _countSink.__pyreon_count__?.('runtime-server.render')
-  // Each call gets a fresh isolated context stack and (optionally) store registry
-  return withStoreContext(() => _contextAls.run([], () => renderNode(root)))
-}
-
-/**
- * Run an async function with a fresh, isolated context stack and store registry.
- * Useful when you need to call Pyreon APIs (e.g. useHead, prefetchLoaderData)
- * outside of renderToString but still want per-request isolation.
- */
-export function runWithRequestContext<T>(fn: () => Promise<T>): Promise<T> {
-  return withStoreContext(() => _contextAls.run([], fn))
-}
-
-/**
- * Render a VNode tree to a Web-standard ReadableStream of HTML chunks.
- *
- * True progressive streaming: HTML is flushed to the client as soon as each
- * node is ready. Synchronous subtrees are enqueued immediately; async component
- * boundaries are awaited in-order and their output is enqueued as it resolves.
- *
- * Suspense boundaries are streamed out-of-order: the fallback is emitted
- * immediately, and the resolved children are sent as a `<template>` + inline
- * swap script once ready — without blocking the rest of the page.
- *
- * Each renderToStream call gets its own isolated ALS context stack.
- */
-export interface RenderToStreamOptions {
-  /**
-   * AbortSignal to cancel in-flight Suspense work when the client
-   * disconnects (browser back-button, navigation, fetch reader closes,
-   * etc.). On abort, the stream's `cancel()` fires the signal —
-   * pending Suspense boundaries are abandoned (the fallback HTML they
-   * already wrote stays in the buffer that's now closed) and the
-   * background async work they spawned is no longer awaited. The work
-   * itself isn't forcibly killed (JS has no async cancellation
-   * primitive at the language level), but the framework stops blocking
-   * on it. Pass your own signal from upstream (e.g. a `Request.signal`)
-   * to chain abort propagation.
-   */
-  signal?: AbortSignal
-  /**
-   * Per-boundary Suspense timeout in milliseconds. When an async
-   * Suspense child doesn't resolve within this window, its fallback
-   * stays visible (the resolved content is dropped — no `<template>`
-   * + swap script is emitted) and a dev-mode warning fires. Defaults
-   * to 30_000 (30s); unset behavior is byte-identical to the
-   * pre-config implementation.
-   *
-   * Ops control: tighten this for tight-SLA deploys (5_000–10_000 is
-   * typical for user-facing apps where a fallback is preferable to a
-   * delayed full render). Loosen it (or pass `Infinity` to disable)
-   * for renders that legitimately need long async work — exports,
-   * reports, scheduled jobs, etc.
-   *
-   * Values ≤0 or `NaN` fall back to the default. `Infinity` is honored
-   * verbatim — the timeout race is skipped entirely so a hung boundary
-   * keeps the stream open until the AbortSignal fires or the consumer
-   * cancels.
-   */
-  suspenseTimeoutMs?: number
-}
-
-export function renderToStream(
-  root: VNode | null,
-  options: RenderToStreamOptions = {},
-): ReadableStream<string> {
-  if (__DEV__) _countSink.__pyreon_count__?.('runtime-server.stream')
-  // Internal AbortController — fires when EITHER the caller's signal
-  // aborts (upstream cancellation, e.g. `Request.signal`) OR the consumer
-  // of the stream calls `.cancel()` (client closed the fetch reader).
-  const ac = new AbortController()
-  const signal = ac.signal
-  if (options.signal) {
-    if (options.signal.aborted) ac.abort(options.signal.reason)
-    else options.signal.addEventListener('abort', () => ac.abort(options.signal!.reason), { once: true })
-  }
-  // Resolve the Suspense timeout. Invalid input (≤0, NaN) falls back to
-  // 30_000 — same as pre-config behavior. `Infinity` is preserved so the
-  // boundary code can detect it and skip the race entirely.
-  const userTimeout = options.suspenseTimeoutMs
-  const suspenseTimeoutMs
-    = userTimeout === Infinity
-      ? Infinity
-      : userTimeout !== undefined && Number.isFinite(userTimeout) && userTimeout > 0
-        ? userTimeout
-        : 30_000
-
-  return new ReadableStream<string>({
-    start(controller) {
-      const enqueue = (chunk: string) => {
-        if (signal.aborted) return // stop appending after abort
-        controller.enqueue(chunk)
-      }
-      let bid = 0
-      const ctx: StreamCtx = {
-        pending: [],
-        nextId: () => bid++,
-        mainEnqueue: enqueue,
-        suspenseDepth: 0,
-        signal,
-        suspenseTimeoutMs,
-      }
-      // One shared abort-promise — registered ONCE, resolved on signal
-      // abort. Racing each pending batch against this lets the drain
-      // loop exit promptly when the consumer hangs up, without accruing
-      // one abort listener per loop iteration.
-      const abortPromise: Promise<void> = signal.aborted
-        ? Promise.resolve()
-        : new Promise<void>((resolve) => {
-            signal.addEventListener('abort', () => resolve(), { once: true })
-          })
-
-      return withStoreContext(() =>
-        _contextAls.run([], () =>
-          _streamCtxAls
-            .run(ctx, async () => {
-              await streamNode(root, enqueue)
-              // Drain all pending Suspense resolutions (may spawn nested
-              // ones). Each batch is RACED against the abort signal so a
-              // mid-flight Suspense child doesn't keep us blocked after
-              // the consumer hung up. Per-boundary work also checks
-              // `ctx.signal.aborted` to skip its post-resolve enqueue.
-              while (ctx.pending.length > 0) {
-                if (signal.aborted) break
-                const batch = Promise.all(ctx.pending.splice(0))
-                await Promise.race([batch, abortPromise])
-              }
-              // ALWAYS close — gracefully on natural completion AND on
-              // abort. (Pre-fix: `if (!aborted) close()` left the stream
-              // open forever on cancel, hanging the reader.) Wrap in
-              // try/catch because the stream may have already been
-              // closed by `cancel()` upstream.
-              try {
-                controller.close()
-              } catch {
-                /* already closed (e.g. cancel raced ahead) */
-              }
-            })
-            .catch((err) => {
-              // Aborts are expected, not errors — close silently to mirror
-              // a normal end-of-stream when the consumer hung up.
-              if (signal.aborted) {
-                try {
-                  controller.close()
-                } catch {
-                  /* already closed */
-                }
-                return
-              }
-              controller.error(err)
-            }),
-        ),
-      )
-    },
-    cancel(reason) {
-      // Consumer (browser fetch reader) closed the stream — propagate to
-      // the internal controller so in-flight Suspense work stops being
-      // awaited.
-      ac.abort(reason)
-    },
-  })
-}
-
-// ─── Streaming renderer ───────────────────────────────────────────────────────
-
-async function streamVNode(vnode: VNode, enqueue: (s: string) => void): Promise<void> {
-  if (vnode.type === Fragment) {
-    for (const child of vnode.children) await streamNode(child, enqueue)
-    return
-  }
-
-  if (vnode.type === (ForSymbol as unknown as string)) {
-    const { each, children, by } = vnode.props as unknown as ForProps<unknown>
-    enqueue('<!--pyreon-for-->')
-    // Defensive: `each` is normally `_rp(() => arr)` (a function). PR #410's
-    // `makeReactiveProps` in `mergeChildrenIntoProps` invokes `_rp` getters
-    // when the For COMPONENT runs, which flips `props.each` to the resolved
-    // array on the re-emitted ForSymbol vnode. Accept both forms.
-    const items = typeof each === 'function' ? each() : (each as Iterable<unknown>)
-    for (const item of items) {
-      const key = by(item)
-      if (__DEV__) _countSink.__pyreon_count__?.('runtime-server.for.keyMarker')
-      enqueue(`<!--k:${safeKeyForMarker(key)}-->`)
-      await streamNode(children(item) as VNodeChild, enqueue)
-    }
-    enqueue('<!--/pyreon-for-->')
-    return
-  }
-
-  if (typeof vnode.type === 'function') {
-    await streamComponentNode(vnode, enqueue)
-    return
-  }
-
-  await streamElementNode(vnode, enqueue)
-}
-
-async function streamComponentNode(vnode: VNode, enqueue: (s: string) => void): Promise<void> {
-  if (vnode.type === Suspense) {
-    await streamSuspenseBoundary(vnode, enqueue)
-    return
-  }
-  if (__DEV__) _countSink.__pyreon_count__?.('runtime-server.component')
-  // Snapshot the context stack BEFORE the component renders so we can pop
-  // any frames pushed via `provide()` after children stream. We do NOT run
-  // user-registered unmount hooks during SSR — that would clear state still
-  // needed by post-render extraction (e.g. `useHead` uses `onUnmount` to
-  // remove its registered tags from the head store; running it during SSR
-  // wipes the entries before `renderWithHead` reads them). See `renderComponent`
-  // for the full architectural rationale.
-  const stackLenBefore = getContextStackLength()
-  try {
-    const { vnode: output } = runWithHooks(
-      vnode.type as ComponentFn,
-      mergeChildrenIntoProps(vnode),
-    )
-    const resolved = output instanceof Promise ? await output : output
-    if (resolved !== null) await streamNode(resolved, enqueue)
-  } catch (err) {
-    if (__DEV__) {
-      const name = (vnode.type as ComponentFn).name || 'Anonymous'
-      console.error(`[Pyreon SSR] Error rendering <${name}>:`, err)
-    }
-    // Inside a Suspense child resolution, re-throw so the boundary can catch and
-    // suppress the swap (fallback stays visible). Outside Suspense, swallow the
-    // error and emit a marker so the stream can continue.
-    const ctx = _streamCtxAls.getStore()
-    if (ctx && ctx.suspenseDepth > 0) throw err
-    enqueue('<!--pyreon-error-->')
-  } finally {
-    trimContextStack(stackLenBefore)
-  }
-}
-
-async function streamElementNode(vnode: VNode, enqueue: (s: string) => void): Promise<void> {
-  const tag = vnode.type as string
-  warnIfUnsafeTag(tag)
-  let open = `<${tag}`
-  const props = vnode.props as Record<string, unknown>
-  for (const key in props) {
-    const attr = renderProp(key, props[key])
-    if (attr) open += ` ${attr}`
-  }
-  if (isVoidElement(tag)) {
-    enqueue(`${open} />`)
-    return
-  }
-  enqueue(`${open}>`)
-  // `dangerouslySetInnerHTML` and `innerHTML` both become inner content
-  // of the element (NOT attributes). Skipped in `renderPropSkipped` to
-  // keep them out of the open-tag attribute list. Function values —
-  // emitted by the compiler for signal-derived prop expressions — are
-  // called once at render time (SSR is one-shot; any reactivity happens
-  // post-hydration on the client).
-  const dangerous = props.dangerouslySetInnerHTML as { __html: string } | (() => { __html: string }) | undefined
-  const innerHtml = props.innerHTML as string | (() => string) | undefined
-  const dangerousHtml =
-    typeof dangerous === 'function' ? (dangerous as () => { __html: string })()?.__html : dangerous?.__html
-  const plainInnerHtml =
-    typeof innerHtml === 'function' ? (innerHtml as () => string)() : innerHtml
-  if (dangerousHtml) {
-    enqueue(dangerousHtml)
-  } else if (plainInnerHtml != null && plainInnerHtml !== '') {
-    enqueue(String(plainInnerHtml))
-  } else {
-    for (const child of vnode.children) await streamNode(child, enqueue)
-  }
-  enqueue(`</${tag}>`)
-}
-
-async function streamNode(
-  node: VNodeChild | null | (() => VNodeChild),
-  enqueue: (s: string) => void,
-): Promise<void> {
-  if (typeof node === 'function') {
-    return streamNode((node as () => VNodeChild)(), enqueue)
-  }
-  if (node == null || node === false) return
-  if (typeof node === 'string') {
-    enqueue(escapeHtml(node))
-    return
-  }
-  if (typeof node === 'number' || typeof node === 'boolean') {
-    enqueue(String(node))
-    return
-  }
-  if (Array.isArray(node)) {
-    for (const child of node) await streamNode(child, enqueue)
-    return
-  }
-
-  await streamVNode(node as VNode, enqueue)
-}
-
-// Inline swap helper emitted once per stream, before the first <template>
-const SUSPENSE_SWAP_FN =
-  '<script>function __NS(s,t){var e=document.getElementById(s),l=document.getElementById(t);' +
-  'if(e&&l){e.replaceWith(l.content.cloneNode(!0));l.remove()}}</script>'
-
-/**
- * Stream a Suspense boundary: emit fallback immediately, then resolve children
- * asynchronously and emit them as a `<template>` + client-side swap.
- *
- * The actual children HTML is buffered until fully resolved, then emitted to the
- * main stream enqueue so it always arrives after the fallback placeholder.
- */
-async function streamSuspenseBoundary(vnode: VNode, enqueue: (s: string) => void): Promise<void> {
-  if (__DEV__) _countSink.__pyreon_count__?.('runtime-server.suspense.boundary')
-  const ctx = _streamCtxAls.getStore()
-  const { fallback, children } = vnode.props as { fallback: VNodeChild; children?: VNodeChild }
-
-  // Defensive: the streaming pipeline only enters this function via
-  // `_streamCtxAls.run(ctx, ...)` (set up in `renderToStream`), so `ctx`
-  // is always defined when `streamSuspenseBoundary` runs. Kept as a safety
-  // net in case a future entry point bypasses the streaming context — the
-  // block performs the same context-stack hygiene as `renderComponent` /
-  // `streamComponentNode` so a Suspense `provide()` wouldn't leak into
-  // siblings if it ever fires. Excluded from coverage because no public-API
-  // path reaches it; including a unit test would either require exporting
-  // `streamSuspenseBoundary` (leaks an internal) or stubbing the ALS (false
-  // signal).
-  /* c8 ignore start */
-  if (!ctx) {
-    const stackLenBefore = getContextStackLength()
-    const { vnode: output } = runWithHooks(Suspense as ComponentFn, vnode.props)
-    try {
-      if (output !== null) await streamNode(output, enqueue)
-    } finally {
-      trimContextStack(stackLenBefore)
-    }
-    return
-  }
-  /* c8 ignore stop */
-
-  const id = ctx.nextId()
-  const { mainEnqueue } = ctx
-
-  // Emit the swap helper function once (before first use)
-  if (id === 0) mainEnqueue(SUSPENSE_SWAP_FN)
-
-  // Stream the fallback synchronously (no await on children)
-  mainEnqueue(`<div id="pyreon-s-${id}">`)
-  await streamNode(fallback ?? null, enqueue)
-  mainEnqueue('</div>')
-
-  // Capture the context store for the async resolution so it inherits context
-  const ctxStore = _contextAls.getStore() ?? []
-
-  // Queue async resolution — runs in parallel, emits to main stream when done.
-  // Errors are caught per-boundary so one failing Suspense doesn't abort the stream.
-  // Timeout prevents hung async children from keeping the stream open forever.
-  // Configurable via `RenderToStreamOptions.suspenseTimeoutMs` (default 30_000;
-  // `Infinity` disables the race so a hung boundary waits indefinitely until
-  // the upstream AbortSignal or consumer cancel fires).
-  const suspenseTimeoutMs = ctx.suspenseTimeoutMs
-
-  ctx.pending.push(
-    _contextAls.run(ctxStore, async () => {
-      try {
-        ctx.suspenseDepth++
-        const buf: string[] = []
-
-        // Race the async children against a timeout (skipped when the
-        // user passed `Infinity` to opt out). Class I — capture the
-        // timer id and clear on the success path; without this, every
-        // successful Suspense boundary leaks a pending timer + resolve
-        // callback until it fires. Caught by the `audit-leak-classes`
-        // script's promise-race-no-clear detector.
-        let result: 'resolved' | 'timeout'
-        if (suspenseTimeoutMs === Infinity) {
-          // No-timeout mode: just await children. AbortSignal still
-          // applies via the outer drain-loop race in renderToStream.
-          await streamNode(children ?? null, (s) => buf.push(s))
-          result = 'resolved'
-        } else {
-          let timeoutId: ReturnType<typeof setTimeout> | undefined
-          try {
-            result = await Promise.race([
-              streamNode(children ?? null, (s) => buf.push(s)).then(() => 'resolved' as const),
-              new Promise<'timeout'>((resolve) => {
-                timeoutId = setTimeout(() => resolve('timeout'), suspenseTimeoutMs)
-              }),
-            ])
-          }
-          finally {
-            if (timeoutId !== undefined) clearTimeout(timeoutId)
-          }
-        }
-
-        if (result === 'timeout') {
-          if (__DEV__) {
-            _countSink.__pyreon_count__?.('runtime-server.suspense.fallback')
-            console.warn(
-              `[Pyreon SSR] Suspense boundary timed out after ${suspenseTimeoutMs}ms — fallback will remain.`,
-            )
-          }
-          // Fallback stays visible — no swap
-          return
-        }
-
-        // Client disconnected (or upstream aborted) while we were
-        // resolving — don't bother enqueueing the post-resolve content.
-        // The drain loop also checks `signal.aborted` so the stream
-        // closes promptly without us racing it.
-        if (ctx.signal?.aborted) return
-
-        // Escape </template> in buffered content to prevent early close + XSS
-        const content = buf.join('').replace(/<\/template/gi, '<\\/template')
-        mainEnqueue(`<template id="pyreon-t-${id}">${content}</template>`)
-        mainEnqueue(`<script>__NS("pyreon-s-${id}","pyreon-t-${id}")</script>`)
-      } catch (err) {
-        if (__DEV__) {
-          console.error(
-            `[Pyreon SSR] Suspense boundary caught an error — fallback will remain:`,
-            err,
-          )
-        }
-        // Fallback stays visible — no swap script emitted
-      } finally {
-        ctx.suspenseDepth--
-      }
-    }),
-  )
-}
-
-// ─── Core renderer ───────────────────────────────────────────────────────────
-
-async function renderNode(node: VNodeChild | (() => VNodeChild)): Promise<string> {
-  // Reactive accessor — call it synchronously (snapshot)
-  if (typeof node === 'function') {
-    return renderNode((node as () => VNodeChild)())
-  }
-
-  if (node == null || node === false) return ''
-
-  if (typeof node === 'string') return escapeHtml(node)
-  if (typeof node === 'number' || typeof node === 'boolean') return String(node)
-
-  if (Array.isArray(node)) {
-    let html = ''
-    for (const child of node) html += await renderNode(child)
-    return html
-  }
-
-  const vnode = node as VNode
-
-  if (vnode.type === Fragment) {
-    return renderChildren(vnode.children)
-  }
-
-  if (vnode.type === (ForSymbol as unknown as string)) {
-    const { each, children, by } = vnode.props as unknown as ForProps<unknown>
-    let forHtml = '<!--pyreon-for-->'
-    // Defensive: `each` is normally `_rp(() => arr)` (a function). PR #410's
-    // `makeReactiveProps` in `mergeChildrenIntoProps` invokes `_rp` getters
-    // when the For COMPONENT runs, which flips `props.each` to the resolved
-    // array on the re-emitted ForSymbol vnode. Accept both forms.
-    const items = typeof each === 'function' ? each() : (each as Iterable<unknown>)
-    for (const item of items) {
-      const key = by(item)
-      if (__DEV__) _countSink.__pyreon_count__?.('runtime-server.for.keyMarker')
-      forHtml += `<!--k:${safeKeyForMarker(key)}-->`
-      forHtml += await renderNode(children(item) as VNodeChild)
-    }
-    forHtml += '<!--/pyreon-for-->'
-    return forHtml
-  }
-
-  if (typeof vnode.type === 'function') {
-    return renderComponent(vnode as VNode & { type: ComponentFn })
-  }
-
-  return renderElement(vnode)
-}
-
-async function renderChildren(children: VNodeChild[]): Promise<string> {
-  let html = ''
-  for (const child of children) html += await renderNode(child)
-  return html
-}
-
-async function renderComponent(vnode: VNode & { type: ComponentFn }): Promise<string> {
-  if (__DEV__) _countSink.__pyreon_count__?.('runtime-server.component')
-  // Snapshot the context stack length BEFORE the component renders. After
-  // children render, trim back to this length — that pops every frame the
-  // component pushed via `provide(ctx, value)` (which calls `pushContext` +
-  // registers `onUnmount(popContext)`). Without this, every provider during
-  // SSR leaks its frame onto the global stack and subsequent siblings see
-  // the wrong context value (Bug 4 — bokisch.com `<PyreonUI inversed>`
-  // inside `<Intro>` flipped every later section to dark).
-  //
-  // We trim the stack DIRECTLY instead of running the component's unmount
-  // hooks because users register `onUnmount` for things still load-bearing
-  // at post-render time during SSR — `useHead({ title })` uses `onUnmount`
-  // to remove its head entries, and running it here wipes the head store
-  // before `renderWithHead` extracts it. SSR has no real "unmount" phase
-  // (the response ships, the process moves on); user-registered cleanup
-  // is for the CSR lifecycle. `provide()`'s frame cleanup is the only
-  // SSR-visible side effect and we handle it structurally below.
-  const stackLenBefore = getContextStackLength()
-  const { vnode: output } = runWithHooks(vnode.type, mergeChildrenIntoProps(vnode))
-
-  // Async component function (async function Component()) — await the promise
-  let html: string
-  try {
-    if (output instanceof Promise) {
-      const resolved = await output
-      html = resolved === null ? '' : await renderNode(resolved)
-    } else if (output === null) {
-      html = ''
-    } else {
-      html = await renderNode(output)
-    }
-  } finally {
-    trimContextStack(stackLenBefore)
-  }
-  return html
-}
-
-/**
- * Pop context frames pushed during a component's render. Trims the global
- * context stack back to the snapshot length captured before the component
- * ran. Each iteration calls `popContext` once — symmetric with `provide()`'s
- * `pushContext()` so frames pop in LIFO order even when a single component
- * called `provide()` multiple times.
- *
- * Why not run user unmount hooks here? See `renderComponent` for the full
- * architectural rationale — TL;DR: SSR has no unmount phase, `useHead` uses
- * `onUnmount` to clear head entries that the post-render extraction still
- * needs, etc. The structural fix is to clean up the ONE SSR-visible side
- * effect of `provide()` (its context frame) without firing other hooks.
- */
-function trimContextStack(targetLen: number): void {
-  let current = getContextStackLength()
-  while (current > targetLen) {
-    popContext()
-    current--
-  }
-}
-
-async function renderElement(vnode: VNode): Promise<string> {
-  const tag = vnode.type as string
-  warnIfUnsafeTag(tag)
-  let html = `<${tag}`
-
-  const props = vnode.props as Record<string, unknown>
-  for (const key in props) {
-    const attr = renderProp(key, props[key])
-    if (attr) html += ` ${attr}`
-  }
-
-  if (isVoidElement(tag)) {
-    html += ' />'
-    return html
-  }
-
-  html += '>'
-
-  // `dangerouslySetInnerHTML` and `innerHTML` become inner content of the
-  // element (NOT attributes — skipped in `renderPropSkipped`). Function
-  // values — emitted by the compiler for signal-derived prop expressions —
-  // are called once at render time (SSR is one-shot; reactivity happens
-  // post-hydration on the client). Kept in sync with `streamElementNode`.
-  const dangerous = props.dangerouslySetInnerHTML as
-    | { __html: string }
-    | (() => { __html: string })
-    | undefined
-  const innerHtml = props.innerHTML as string | (() => string) | undefined
-  const dangerousHtml =
-    typeof dangerous === 'function'
-      ? (dangerous as () => { __html: string })()?.__html
-      : dangerous?.__html
-  const plainInnerHtml =
-    typeof innerHtml === 'function' ? (innerHtml as () => string)() : innerHtml
-  if (dangerousHtml) {
-    html += dangerousHtml
-  } else if (plainInnerHtml != null && plainInnerHtml !== '') {
-    html += String(plainInnerHtml)
-  } else {
-    for (const child of vnode.children) {
-      html += await renderNode(child)
-    }
-  }
-
-  html += `</${tag}>`
-  return html
-}
-
-const SSR_URL_ATTRS = new Set(['href', 'src', 'action', 'formaction', 'poster', 'cite', 'data'])
-const SSR_UNSAFE_URL_RE = /^\s*(?:javascript|data):/i
-
-function renderPropSkipped(key: string): boolean {
-  // `innerHTML` and `dangerouslySetInnerHTML` are NOT attributes — they
-  // get written as inner content in `streamElementNode`. Without this
-  // skip, `innerHTML` would be emitted as a literal HTML attribute
-  // (`<span innerHTML="&lt;svg&gt;…">`) and the client hydration would
-  // fix it up — wasted bytes, hydration mismatch, and (with the recent
-  // client-side `innerHTML` bug) literal closure text visible before
-  // hydration completed.
-  if (key === 'key' || key === 'ref') return true
-  if (key === 'innerHTML' || key === 'dangerouslySetInnerHTML') return true
-  if (/^on[A-Z]/.test(key)) return true
-  return false
-}
-
-function renderPropValue(key: string, value: unknown): string | null {
-  if (value === null || value === undefined || value === false) return null
-  if (value === true) return escapeHtml(toAttrName(key))
-
-  if (key === 'class') {
-    const cls = cx(value as ClassValue)
-    return cls ? `class="${escapeHtml(cls)}"` : null
-  }
-
-  if (key === 'style') {
-    const style = normalizeStyle(value)
-    return style ? `style="${escapeHtml(style)}"` : null
-  }
-
-  return `${escapeHtml(toAttrName(key))}="${escapeHtml(String(value))}"`
-}
-
-function renderProp(key: string, value: unknown): string | null {
-  if (renderPropSkipped(key)) return null
-
-  if (typeof value === 'function') {
-    return renderProp(key, (value as () => unknown)())
-  }
-
-  if (SSR_URL_ATTRS.has(key) && typeof value === 'string' && SSR_UNSAFE_URL_RE.test(value)) {
-    return null
-  }
-
-  return renderPropValue(key, value)
-}
-
-// ─── Helpers ─────────────────────────────────────────────────────────────────
-
-const VOID_ELEMENTS = new Set([
-  'area',
-  'base',
-  'br',
-  'col',
-  'embed',
-  'hr',
-  'img',
-  'input',
-  'link',
-  'meta',
-  'param',
-  'source',
-  'track',
-  'wbr',
-])
-
-function isVoidElement(tag: string): boolean {
-  return VOID_ELEMENTS.has(tag.toLowerCase())
-}
-
-/** camelCase prop → kebab-case HTML attribute (e.g. className → class, htmlFor → for) */
-function toAttrName(key: string): string {
-  if (key === 'className') return 'class'
-  if (key === 'htmlFor') return 'for'
-  return key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)
-}
-
-function isStyleObject(value: unknown): value is Record<string, unknown> {
-  if (!value) return false
-  return typeof value === 'object'
-}
-
-function normalizeStyle(value: unknown): string {
-  if (typeof value === 'string') return value
-  if (isStyleObject(value)) {
-    const proto = Object.getPrototypeOf(value)
-    if (proto === Object.prototype || proto === null) {
-      return Object.entries(value)
-        .map(([k, v]) => `${toKebab(k)}: ${normalizeStyleValue(k, v)}`)
-        .join('; ')
-    }
-  }
-  return ''
-}
-
-function toKebab(str: string): string {
-  return str.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)
-}
-
-const ESCAPE_MAP: Record<string, string> = {
-  '&': '&amp;',
-  '<': '&lt;',
-  '>': '&gt;',
-  '"': '&quot;',
-  "'": '&#39;',
-}
-
-/**
- * Encode a For-list key so it's safe to inline inside an HTML comment
- * marker `<!--k:KEY-->`. If a user-supplied key contains `-->` the naive
- * form breaks out of the comment and may inject markup. Per-byte URL
- * encoding with an extra `-` substitution makes `-->` impossible in the
- * output: `%2D%2D>` no longer terminates the comment. Client-side
- * hydration does not read the marker body today, so any reversible-or-
- * irreversible encoding works; this one is predictable enough for a
- * future consumer to decode if needed.
- */
-function safeKeyForMarker(key: unknown): string {
-  return encodeURIComponent(String(key)).replace(/-/g, '%2D')
-}
-
-/**
- * Inverse of `safeKeyForMarker` — decode a marker-safe key back to the
- * original string. Not used by runtime today (hydration does not read
- * per-item `<!--k:KEY-->` markers) but shipped alongside the encoder so
- * future hydration or devtools consumers decode symmetrically without
- * having to re-derive the encoding from source.
- */
-export function decodeKeyFromMarker(encoded: string): string {
-  return decodeURIComponent(encoded.replace(/%2D/gi, '-'))
-}
-
-// Detect tag names that would break out of the `<TAG>` or `</TAG>` form
-// and inject HTML. If user data ever feeds `h(userTag, ...)` the attack
-// `userTag = 'div><script>alert(1)</script><div'` yields executable
-// markup. Framework doesn't HTML-escape tag names (React/Vue/Solid
-// match) — responsibility is on the caller — but a dev-mode warning
-// catches the mistake before it reaches prod. Safe tag pattern covers
-// HTML element names and custom elements (letter start, then
-// alphanumerics + hyphens).
-const SAFE_TAG_RE = /^[a-zA-Z][a-zA-Z0-9-]*$/
-function warnIfUnsafeTag(tag: string): void {
-  if (!__DEV__) return
-  if (SAFE_TAG_RE.test(tag)) return
-  // oxlint-disable-next-line no-console
-  console.warn(
-    `[Pyreon SSR] Tag name "${tag}" contains characters that could break HTML structure. ` +
-      `Tag names must match /^[a-zA-Z][a-zA-Z0-9-]*$/. ` +
-      `If user-supplied data drives a tag name, validate it against an allowlist before passing to h().`,
-  )
-}
-
-// Fast test — most strings in SSR have no special chars (tag names, class names, etc.)
-const NEEDS_ESCAPE_RE = /[&<>"']/
-
-function escapeHtml(str: string): string {
-  if (!NEEDS_ESCAPE_RE.test(str)) return str
-  if (__DEV__) _countSink.__pyreon_count__?.('runtime-server.escape')
-  return str.replace(/[&<>"']/g, (c) => ESCAPE_MAP[c] ?? c)
-}
-
-/**
- * Merge vnode.children into props.children for component rendering, AND
- * convert compiler-emitted `_rp(() => expr)` reactive-prop wrappers into
- * getter properties via `makeReactiveProps`.
- *
- * mount.ts (CSR) does the same dance — without it, components reading
- * `props.x` get the raw `_rp` function instead of the resolved value.
- * Pre-fix, SSR (and hydrate.ts — same bug, fixed alongside) skipped the
- * `makeReactiveProps` step, so any `<Comp prop={signal()}>` shape rendered
- * the function source as the attribute value (e.g. `<a href="() => …">`).
- * Visible end-to-end through the fundamentals NavItem layout — see
- * `e2e/fundamentals/playground.spec.ts`.
- */
-function mergeChildrenIntoProps(vnode: VNode): Record<string, unknown> {
-  const raw =
-    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>)
-  return makeReactiveProps(raw)
-}