@pyreon/server 0.15.0 → 0.16.0

package/src/client.ts

@@ -29,7 +29,16 @@ import type { ComponentFn } from '@pyreon/core'
 import { h } from '@pyreon/core'
 import { createRouter, hydrateLoaderData, type RouteRecord, RouterProvider } from '@pyreon/router'
 import { hydrateRoot, mount } from '@pyreon/runtime-dom'
-import type { HydrationStrategy } from './island'
+import type { HydrationStrategy, PrefetchStrategy } from './island'
+
+// Dev-time counter sink — see packages/internals/perf-harness for contract.
+// Same pattern as @pyreon/runtime-dom: bare process.env.NODE_ENV gate (the
+// bundler-agnostic library standard) so counter strings tree-shake out under
+// every modern bundler (Vite, Webpack/Next.js, Rolldown, esbuild, Rollup,
+// Parcel, Bun) when consumers ship a production bundle. The optional-chain
+// short-circuits in dev when no consumer has called perfHarness.install().
+const __DEV__ = process.env.NODE_ENV !== 'production'
+const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }
 
 // ─── Full app hydration ──────────────────────────────────────────────────────
 
@@ -53,6 +62,9 @@ export interface StartClientOptions {
  * Returns a cleanup function that unmounts the app.
  */
 export function startClient(options: StartClientOptions): () => void {
+  // SSR-only guard: hard-fails if startClient is called server-side. Cannot be
+  // exercised under happy-dom (document is always defined in the test env).
+  /* v8 ignore next 3 */
   if (typeof document === 'undefined') {
     throw new Error('[Pyreon] startClient() can only be called in the browser.')
   }
@@ -91,19 +103,24 @@ type IslandLoader = () => Promise<{ default: ComponentFn } | ComponentFn>
  * Hydrate all `<pyreon-island>` elements on the page.
  *
  * Only loads JavaScript for components that are actually present in the HTML.
- * Respects hydration strategies (load, idle, visible, media, never).
+ * Respects hydration strategies (load, idle, visible, media, never). Returns
+ * a cleanup function that disconnects any pending observers/listeners.
+ *
+ * **`hydrate: 'never'` islands do NOT require a registry entry** — the whole
+ * point of the strategy is shipping zero client JS, so importing the loader
+ * (which would pull the component into the client bundle graph) defeats it.
+ * Such islands are silently skipped here without a `data-island-error` flag.
  *
  * @example
  * hydrateIslands({
  *   Counter: () => import("./Counter"),
  *   Search:  () => import("./Search"),
+ *   // No entry for `StaticBadge` even though it appears as a never-island
+ *   // in the HTML — registering one would defeat the strategy.
  * })
  */
-/**
- * Hydrate all `<pyreon-island>` elements on the page.
- * Returns a cleanup function that disconnects any pending observers/listeners.
- */
 export function hydrateIslands(registry: Record<string, IslandLoader>): () => void {
+  /* v8 ignore next */
   if (typeof document === 'undefined') return () => {}
   const islands = document.querySelectorAll('pyreon-island')
   const cleanups: (() => void)[] = []
@@ -112,15 +129,52 @@ export function hydrateIslands(registry: Record<string, IslandLoader>): () => vo
     const componentId = el.getAttribute('data-component')
     if (!componentId) continue
 
+    // Detect nested islands. An island whose ancestor (up the DOM tree) is
+    // also a `<pyreon-island>` would, on hydration, be torn out and replaced
+    // when the outer island hydrates — losing its hydrate strategy entirely.
+    // Mark it as errored, log, and skip rather than silently break.
+    if (el.parentElement?.closest('pyreon-island')) {
+      console.error(
+        `[Pyreon] island "${componentId}" is nested inside another <pyreon-island>. ` +
+          `Nested islands are not supported — the outer island's hydrateRoot replaces ` +
+          `the inner element before its loader runs. Move the inner island out of the ` +
+          `outer island's tree, or fold them into a single component.`,
+      )
+      el.setAttribute('data-island-error', 'nested')
+      if (__DEV__) _countSink.__pyreon_count__?.('island.skipped.nested')
+      continue
+    }
+
+    const strategy = (el.getAttribute('data-hydrate') ?? 'load') as HydrationStrategy
+
+    // `hydrate: 'never'` deliberately ships zero client JS for the island —
+    // no loader is registered because the loader's whole purpose is to be
+    // imported. Skip the missing-loader warning for never-strategy islands;
+    // any other strategy without a loader IS a real misconfiguration.
+    if (strategy === 'never') {
+      if (__DEV__) _countSink.__pyreon_count__?.('island.skipped.never')
+      continue
+    }
+
     const loader = registry[componentId]
     if (!loader) {
       console.warn(`No loader registered for island "${componentId}"`)
+      el.setAttribute('data-island-error', 'no-loader')
+      if (__DEV__) _countSink.__pyreon_count__?.('island.skipped.no-loader')
       continue
     }
 
-    const strategy = (el.getAttribute('data-hydrate') ?? 'load') as HydrationStrategy
     const propsJson = el.getAttribute('data-props') ?? '{}'
 
+    // Prefetch (if requested) primes the module cache before the hydration
+    // trigger fires. Independent of hydration scheduling — the same loader
+    // promise is reused, so a `visible` island with `prefetch: 'idle'` will
+    // hit a warm cache when the IntersectionObserver finally fires.
+    const prefetch = (el.getAttribute('data-prefetch') ?? 'none') as PrefetchStrategy
+    const prefetchCleanup = schedulePrefetch(el as HTMLElement, loader, prefetch)
+    if (prefetchCleanup) cleanups.push(prefetchCleanup)
+
+    if (__DEV__) _countSink.__pyreon_count__?.('island.scheduled')
     const cleanup = scheduleHydration(el as HTMLElement, loader, propsJson, strategy)
     if (cleanup) cleanups.push(cleanup)
   }
@@ -130,16 +184,127 @@ export function hydrateIslands(registry: Record<string, IslandLoader>): () => vo
   }
 }
 
+function schedulePrefetch(
+  el: HTMLElement,
+  loader: IslandLoader,
+  prefetch: PrefetchStrategy,
+): (() => void) | null {
+  if (prefetch === 'none') return null
+  /* v8 ignore next */
+  if (typeof window === 'undefined') return null
+  let cancelled = false
+  // Fire and forget — we don't await; the dynamic import warms the module
+  // cache and the hydration path will await its OWN loader() call (which
+  // resolves to the same module via JS's import-promise dedup).
+  const prime = () => {
+    if (cancelled) return
+    if (__DEV__) _countSink.__pyreon_count__?.('island.prefetch')
+    loader().catch(() => {
+      // Silent — hydration will surface the failure with its own error path.
+      // Prefetch is a hint, not a contract.
+    })
+  }
+
+  if (prefetch === 'idle') {
+    if ('requestIdleCallback' in window) {
+      const id = requestIdleCallback(prime)
+      return () => {
+        cancelled = true
+        cancelIdleCallback(id)
+      }
+    }
+    const id = setTimeout(prime, 200)
+    return () => {
+      cancelled = true
+      clearTimeout(id)
+    }
+  }
+
+  // 'visible' — fetch ~200px before the island enters the viewport
+  if (!('IntersectionObserver' in window)) {
+    prime()
+    return null
+  }
+  const observer = new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          observer.disconnect()
+          prime()
+          return
+        }
+      }
+    },
+    { rootMargin: '200px' },
+  )
+  observer.observe(el)
+  return () => {
+    cancelled = true
+    observer.disconnect()
+  }
+}
+
+/**
+ * Auto-discovered island registry shape — emitted by `@pyreon/vite-plugin`
+ * as `virtual:pyreon/islands-registry`. The user passes the imported module
+ * to `hydrateIslandsAuto()`.
+ */
+export interface AutoIslandRegistry {
+  readonly __pyreonIslandRegistry: Record<string, IslandLoader>
+  readonly __pyreonIslandsEnabled: boolean
+}
+
+/**
+ * Hydrate all `<pyreon-island>` elements using a registry auto-generated by
+ * `@pyreon/vite-plugin` (`pyreon({ islands: true })` is the default).
+ *
+ * Eliminates the manual sync between `island()` declarations in source and
+ * the client-side `hydrateIslands({ ... })` call — typo / forgotten entry /
+ * registry drift is the #1 author foot-gun for islands.
+ *
+ * The auto-registry omits `hydrate: 'never'` islands by design; their
+ * components stay out of the client bundle entirely. Other strategies
+ * resolve via the same dynamic-import paths their `island()` declaration
+ * specified.
+ *
+ * The user passes the virtual-module result. We don't import it inside
+ * `@pyreon/server/client` because Rolldown's static-import analysis runs
+ * before plugin resolveId hooks for workspace sources, and would fail to
+ * resolve the virtual specifier. Importing in the user's entry-client (where
+ * the plugin's resolveId fires natively) is the clean shape.
+ *
+ * @example
+ * // src/entry-client.ts
+ * import { hydrateIslandsAuto } from '@pyreon/server/client'
+ * import * as registry from 'virtual:pyreon/islands-registry'
+ * hydrateIslandsAuto(registry)
+ */
+export function hydrateIslandsAuto(registry: AutoIslandRegistry): () => void {
+  /* v8 ignore next */
+  if (typeof document === 'undefined') return () => {}
+  if (!registry.__pyreonIslandsEnabled) {
+    throw new Error(
+      `[Pyreon] hydrateIslandsAuto() requires \`pyreon({ islands: true })\` ` +
+        `in vite.config.ts (the default). The plugin emitted a stub registry ` +
+        `because islands support was explicitly disabled. Either re-enable ` +
+        `islands in the plugin, or use the manual hydrateIslands({ ... }) form.`,
+    )
+  }
+  return hydrateIslands(registry.__pyreonIslandRegistry)
+}
+
 function scheduleHydration(
   el: HTMLElement,
   loader: IslandLoader,
   propsJson: string,
   strategy: HydrationStrategy,
 ): (() => void) | null {
+  /* v8 ignore next */
   if (typeof window === 'undefined') return null
   let cancelled = false
-  const hydrate = () => {
-    if (!cancelled) hydrateIsland(el, loader, propsJson)
+  const hydrate = (): Promise<void> => {
+    if (cancelled) return Promise.resolve()
+    return hydrateIsland(el, loader, propsJson)
   }
 
   switch (strategy) {
@@ -165,8 +330,15 @@ function scheduleHydration(
     case 'visible':
       return observeVisibility(el, hydrate)
 
-    case 'never':
-      return null
+    // `case 'never'` is dead here — `hydrateIslands` short-circuits before
+    // calling `scheduleHydration` when strategy === 'never' (the whole point
+    // of the strategy is shipping zero client JS). Removing the case keeps
+    // the branch surface tight; if a future caller invokes scheduleHydration
+    // directly with 'never', the default fallback (immediate hydrate) is the
+    // wrong shape — gate it at the call site, not here.
+
+    case 'interaction':
+      return scheduleInteractionHydration(el, hydrate, DEFAULT_INTERACTION_EVENTS)
 
     default:
       // media(query)
@@ -189,11 +361,162 @@ function scheduleHydration(
           mql.removeEventListener('change', onChange)
         }
       }
+      // interaction(<events>) — comma-separated event names
+      if (strategy.startsWith('interaction(')) {
+        const eventsStr = strategy.slice(12, -1).trim()
+        const events = eventsStr
+          ? eventsStr.split(',').map((s) => s.trim()).filter(Boolean)
+          : DEFAULT_INTERACTION_EVENTS
+        return scheduleInteractionHydration(el, hydrate, events)
+      }
       hydrate()
       return null
   }
 }
 
+/**
+ * Default events for the `interaction` strategy. Picked to cover the common
+ * "user reaches for it" surface: keyboard (`focus`), mouse (`pointerenter`,
+ * `click`), and touch (`touchstart`). First matching event triggers hydrate
+ * + removes ALL listeners (one-shot).
+ */
+const DEFAULT_INTERACTION_EVENTS: readonly string[] = [
+  'focus',
+  'click',
+  'pointerenter',
+  'touchstart',
+]
+
+function scheduleInteractionHydration(
+  el: HTMLElement,
+  hydrate: () => Promise<void>,
+  events: readonly string[],
+): () => void {
+  let hydrationStarted = false
+  let hydrated = false
+  // Holds replay info if a click came in during in-flight hydration —
+  // we replay the click on the equivalent post-hydration element so the
+  // user's first click both wakes the island AND fires the live handler.
+  //
+  // Hydration may REPLACE DOM nodes (mismatch fallback, or even successful
+  // hydrate-as-mount on some shapes). The original `event.target` reference
+  // can therefore be detached after hydration completes. To survive this,
+  // we capture an identifying "replay path" — preferring `data-testid` (a
+  // stable, semantic identifier) and falling back to a tag-based child
+  // index walk relative to `el`. After hydration we re-query the live tree.
+  let replayPath: ReplayPath | null = null
+  // Stamp a "scheduled" marker for tests / devtools introspection.
+  el.setAttribute('data-island-state', 'awaiting-interaction')
+
+  const startHydration = () => {
+    if (hydrationStarted) return
+    hydrationStarted = true
+    el.setAttribute('data-island-state', 'hydrating')
+    void hydrate().then(() => {
+      hydrated = true
+      el.removeAttribute('data-island-state')
+      for (const ev of events) {
+        el.removeEventListener(ev, dispatch, INTERACTION_LISTENER_OPTS)
+      }
+      if (!replayPath) return
+      const liveTarget = resolveReplayPath(el, replayPath)
+      if (liveTarget && liveTarget.isConnected) {
+        liveTarget.dispatchEvent(
+          new MouseEvent('click', { bubbles: true, cancelable: true }),
+        )
+      }
+    })
+  }
+
+  const dispatch = (event: Event) => {
+    // After hydration, listeners are removed in the `then` above —
+    // this branch is defensive only.
+    if (hydrated) return
+
+    if (event.type === 'click') {
+      // Stop the click — the SSR DOM has no live click handler bound yet,
+      // so propagating it does nothing useful. Capture the click target
+      // for replay after hydration. Works whether or not hydration was
+      // already started by a previous non-click event — the click always
+      // replays as the user-intended action.
+      event.stopImmediatePropagation()
+      event.preventDefault()
+      const target = event.target as HTMLElement | null
+      if (target) replayPath = captureReplayPath(el, target)
+    }
+    startHydration()
+  }
+
+  // `passive: false` because the click handler may need preventDefault on
+  // the original event in the replay path. `capture: true` so we run
+  // BEFORE the live event-delegation handler that hydrateRoot installs
+  // on the container (otherwise the click would already have propagated
+  // past us by the time we react to non-click events firing first).
+  for (const ev of events) {
+    el.addEventListener(ev, dispatch, INTERACTION_LISTENER_OPTS)
+  }
+  return () => {
+    if (hydrated) return
+    el.removeAttribute('data-island-state')
+    for (const ev of events) {
+      el.removeEventListener(ev, dispatch, INTERACTION_LISTENER_OPTS)
+    }
+  }
+}
+
+const INTERACTION_LISTENER_OPTS: AddEventListenerOptions = {
+  passive: false,
+  capture: true,
+}
+
+/**
+ * A locator path for replaying a click after hydration MAY have replaced the
+ * original DOM node. Two strategies:
+ *   - `testid`: re-query the live tree by `[data-testid="..."]`. Stable,
+ *     semantic, survives DOM swap.
+ *   - `path`: a tag-name + child-index walk from the island root. Fallback
+ *     for elements without a test id. Less stable (assumes the live tree
+ *     mirrors the SSR tree's shape) but covers the no-testid case.
+ */
+type ReplayPath =
+  | { kind: 'testid'; value: string }
+  | { kind: 'path'; steps: { tag: string; index: number }[] }
+
+function captureReplayPath(el: Element, target: Element): ReplayPath | null {
+  const testid = target.getAttribute?.('data-testid')
+  if (testid) return { kind: 'testid', value: testid }
+  // Walk up from target to el, collecting (tag, child-index) at each step.
+  // `node` is non-null on every iteration because we early-return when
+  // `parent` is null (the only path that could leave node nullable). The
+  // `Element | null` type is preserved for the post-loop `node === el` check
+  // so the path-not-found case still returns null cleanly.
+  const steps: { tag: string; index: number }[] = []
+  let node: Element | null = target
+  while (node !== el) {
+    const parent: Element | null = node.parentElement
+    if (!parent) return null
+    const siblings = Array.from(parent.children)
+    const index = siblings.indexOf(node)
+    if (index < 0) return null
+    steps.unshift({ tag: node.tagName, index })
+    node = parent
+  }
+  return { kind: 'path', steps }
+}
+
+function resolveReplayPath(el: Element, path: ReplayPath): HTMLElement | null {
+  if (path.kind === 'testid') {
+    return el.querySelector<HTMLElement>(`[data-testid="${path.value}"]`)
+  }
+  let node: Element | null = el
+  for (const { tag, index } of path.steps) {
+    const child: Element | undefined = node?.children[index]
+    if (!child || child.tagName !== tag) return null
+    node = child
+  }
+  return node as HTMLElement | null
+}
+
 async function hydrateIsland(
   el: HTMLElement,
   loader: IslandLoader,
@@ -209,18 +532,24 @@ async function hydrateIsland(
       }
     } catch (parseErr) {
       console.error(`Invalid island props JSON for "${name}"`, parseErr)
+      el.setAttribute('data-island-error', 'invalid-props')
+      if (__DEV__) _countSink.__pyreon_count__?.('island.error')
       return
     }
 
     const mod = await loader()
     const Comp = typeof mod === 'function' ? mod : mod.default
     hydrateRoot(el, h(Comp, props))
+    if (__DEV__) _countSink.__pyreon_count__?.('island.hydrated')
   } catch (err) {
     console.error(`Failed to hydrate island "${name}"`, err)
+    el.setAttribute('data-island-error', 'hydration-failed')
+    if (__DEV__) _countSink.__pyreon_count__?.('island.error')
   }
 }
 
 function observeVisibility(el: HTMLElement, callback: () => void): (() => void) | null {
+  /* v8 ignore next */
   if (typeof window === 'undefined') return null
   if (!('IntersectionObserver' in window)) {
     callback()

package/src/handler.ts

@@ -160,7 +160,16 @@ export function createHandler(options: HandlerOptions): (req: Request) => Promis
         const headWithStyles = styleTag ? `${styleTag}\n${head}` : head
         const fullHtml = processCompiledTemplate(compiled, { head: headWithStyles, app: appHtml, scripts })
 
-        return new Response(fullHtml, { status: 200, headers: ctx.headers })
+        // M1.2 — Status 404 when the matched chain resolved via the
+        // `notFoundComponent` fallback (PR L5). The router's
+        // `resolveRoute` sets `isNotFound: true` when no leaf matched
+        // and a parent layout's `notFoundComponent` was used as a
+        // synthetic leaf. Reading the flag after render lets the
+        // handler emit a real HTTP 404 while still serving the
+        // chrome-wrapped 404 HTML.
+        const resolved = router.currentRoute() as { isNotFound?: boolean }
+        const status = resolved?.isNotFound === true ? 404 : 200
+        return new Response(fullHtml, { status, headers: ctx.headers })
       } catch (err) {
         // `redirect()` thrown from a loader — convert to a real HTTP redirect
         // before the SSR error path runs. Done inside the runWithRequestContext
@@ -226,12 +235,18 @@ async function renderStreamResponse(
 
         push(shellTail)
       } catch (err) {
+        // Defensive: catastrophic stream-level failure (rare; the SSR pipeline
+        // emits its own error markup for component-level errors). Status code
+        // is already 200 by the time we get here so we can only emit an
+        // inline error script and close the body. Branch is intentionally
+        // hard to exercise from tests without mocking `reader.read()`.
+        /* v8 ignore start */
         if (__DEV__) {
           console.error('[Pyreon Server] Stream render failed:', err)
         }
-        // Emit an inline error indicator — status code is already sent (200)
         push(`<script>console.error("[pyreon/server] Stream render failed")</script>`)
         push(shellTail)
+        /* v8 ignore stop */
       } finally {
         controller.close()
       }

package/src/html.ts

@@ -6,6 +6,7 @@
  *   <!--pyreon-app-->      — replaced with rendered application HTML
  *   <!--pyreon-scripts-->  — replaced with client entry script + inline loader data
  */
+import { stringifyLoaderData } from '@pyreon/router'
 
 export const DEFAULT_TEMPLATE = `<!DOCTYPE html>
 <html lang="en">
@@ -78,8 +79,10 @@ export function buildScripts(
   const parts: string[] = []
 
   if (loaderData && Object.keys(loaderData).length > 0) {
-    // Escape </script> inside JSON to prevent premature tag close
-    const json = JSON.stringify(loaderData).replace(/<\//g, '<\\/')
+    // M2.2 — safe serializer: strips function/symbol values silently,
+    // throws a Pyreon-prefixed error on circular refs naming the offending
+    // key, and escapes </script> for safe inline embedding.
+    const json = stringifyLoaderData(loaderData)
     parts.push(`<script>window.__PYREON_LOADER_DATA__=${json}</script>`)
   }
 
@@ -99,7 +102,8 @@ export function buildScriptsFast(
   loaderData: Record<string, unknown> | null,
 ): string {
   if (loaderData && Object.keys(loaderData).length > 0) {
-    const json = JSON.stringify(loaderData).replace(/<\//g, '<\\/')
+    // M2.2 — safe serializer (same contract as `buildScripts`).
+    const json = stringifyLoaderData(loaderData)
     return `<script>window.__PYREON_LOADER_DATA__=${json}</script>\n  ${clientEntryTag}`
   }
   return clientEntryTag