npm - @pyreon/server - Versions diffs - 0.1.0 - Mend

@pyreon/server 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/LICENSE +21 -0
package/README.md +91 -0
package/lib/analysis/index.js.html +5406 -0
package/lib/index.js +294 -0
package/lib/index.js.map +1 -0
package/lib/types/index.d.ts +311 -0
package/lib/types/index.d.ts.map +1 -0
package/lib/types/index2.d.ts +190 -0
package/lib/types/index2.d.ts.map +1 -0
package/package.json +53 -0
package/src/client.ts +239 -0
package/src/handler.ts +187 -0
package/src/html.ts +58 -0
package/src/index.ts +69 -0
package/src/island.ts +137 -0
package/src/middleware.ts +39 -0
package/src/ssg.ts +143 -0
package/src/tests/client.test.ts +577 -0
package/src/tests/server.test.ts +635 -0

package/lib/types/index2.d.ts ADDED Viewed

@@ -0,0 +1,190 @@
+import { ComponentFn, Props } from "@pyreon/core";
+import { RouteRecord } from "@pyreon/router";
+//#region src/middleware.d.ts
+/**
+ * SSR middleware — simple request processing pipeline.
+ *
+ * Middleware runs before rendering. Return a Response to short-circuit
+ * (e.g. for redirects, auth checks, or static file serving).
+ * Return void / undefined to continue to the next middleware or rendering.
+ *
+ * @example
+ * const authMiddleware: Middleware = async (ctx) => {
+ *   const token = ctx.req.headers.get("Authorization")
+ *   if (!token) return new Response("Unauthorized", { status: 401 })
+ *   ctx.locals.user = await verifyToken(token)
+ * }
+ *
+ * const handler = createHandler({
+ *   App,
+ *   routes,
+ *   middleware: [authMiddleware],
+ * })
+ */
+interface MiddlewareContext {
+  /** The incoming request */
+  req: Request;
+  /** Parsed URL */
+  url: URL;
+  /** Pathname + search (passed to router) */
+  path: string;
+  /** Response headers — middleware can set custom headers */
+  headers: Headers;
+  /** Arbitrary per-request data shared between middleware and components */
+  locals: Record<string, unknown>;
+}
+/**
+ * Middleware function. Return a Response to short-circuit, or void to continue.
+ */
+type Middleware = (ctx: MiddlewareContext) => Response | void | Promise<Response | void>;
+//#endregion
+//#region src/handler.d.ts
+interface HandlerOptions {
+  /** Root application component */
+  App: ComponentFn;
+  /** Route definitions */
+  routes: RouteRecord[];
+  /**
+   * HTML template with placeholders:
+   *   <!--pyreon-head-->     — head tags (title, meta, link, etc.)
+   *   <!--pyreon-app-->      — rendered app HTML
+   *   <!--pyreon-scripts-->  — client entry + loader data
+   *
+   * Defaults to a minimal HTML5 template.
+   */
+  template?: string;
+  /** Path to the client entry module (default: "/src/entry-client.ts") */
+  clientEntry?: string;
+  /** Middleware chain — runs before rendering */
+  middleware?: Middleware[];
+  /**
+   * Rendering mode:
+   *   "string" (default) — full renderToString, complete HTML in one response
+   *   "stream" — progressive streaming via renderToStream (Suspense out-of-order)
+   */
+  mode?: "string" | "stream";
+}
+declare function createHandler(options: HandlerOptions): (req: Request) => Promise<Response>;
+//#endregion
+//#region src/html.d.ts
+/**
+ * HTML template processing for SSR/SSG.
+ *
+ * Templates use comment placeholders:
+ *   <!--pyreon-head-->     — replaced with <head> tags (title, meta, link, etc.)
+ *   <!--pyreon-app-->      — replaced with rendered application HTML
+ *   <!--pyreon-scripts-->  — replaced with client entry script + inline loader data
+ */
+declare const DEFAULT_TEMPLATE = "<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"UTF-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  <!--pyreon-head-->\n</head>\n<body>\n  <div id=\"app\"><!--pyreon-app--></div>\n  <!--pyreon-scripts-->\n</body>\n</html>";
+interface TemplateData {
+  head: string;
+  app: string;
+  scripts: string;
+}
+declare function processTemplate(template: string, data: TemplateData): string;
+/**
+ * Build the script tags for client hydration.
+ *
+ * Emits:
+ *   1. Inline script with serialized loader data (if any)
+ *   2. Module script tag pointing to the client entry
+ */
+declare function buildScripts(clientEntry: string, loaderData: Record<string, unknown> | null): string;
+//#endregion
+//#region src/island.d.ts
+type HydrationStrategy = "load" | "idle" | "visible" | "never" | `media(${string})`;
+interface IslandOptions {
+  /** Unique name — must match the key in the client-side hydrateIslands() registry */
+  name: string;
+  /** When to hydrate on the client (default: "load") */
+  hydrate?: HydrationStrategy;
+}
+interface IslandMeta {
+  readonly __island: true;
+  readonly name: string;
+  readonly hydrate: HydrationStrategy;
+}
+/**
+ * Create an island component.
+ *
+ * Returns an async ComponentFn that:
+ *   1. Resolves the dynamic import
+ *   2. Renders the component to VNodes
+ *   3. Wraps the output in `<pyreon-island>` with serialized props + hydration strategy
+ */
+declare function island<P extends Props = Props>(loader: () => Promise<{
+  default: ComponentFn<P>;
+} | ComponentFn<P>>, options: IslandOptions): ComponentFn<P> & IslandMeta;
+//#endregion
+//#region src/ssg.d.ts
+/**
+ * Static Site Generation — pre-render routes to HTML files at build time.
+ *
+ * @example
+ * // ssg.ts (run with: bun run ssg.ts)
+ * import { createHandler } from "@pyreon/server"
+ * import { prerender } from "@pyreon/server"
+ * import { App } from "./src/App"
+ * import { routes } from "./src/routes"
+ *
+ * const handler = createHandler({ App, routes })
+ *
+ * await prerender({
+ *   handler,
+ *   paths: ["/", "/about", "/blog", "/blog/hello-world"],
+ *   outDir: "dist",
+ * })
+ *
+ * @example
+ * // Dynamic paths from a CMS or filesystem
+ * await prerender({
+ *   handler,
+ *   paths: async () => {
+ *     const posts = await fetchAllPosts()
+ *     return ["/", "/about", ...posts.map(p => `/blog/${p.slug}`)]
+ *   },
+ *   outDir: "dist",
+ * })
+ */
+interface PrerenderOptions {
+  /** SSR handler created by createHandler() */
+  handler: (req: Request) => Promise<Response>;
+  /** Routes to pre-render — array of URL paths or async function that returns them */
+  paths: string[] | (() => string[] | Promise<string[]>);
+  /** Output directory for the generated HTML files */
+  outDir: string;
+  /** Origin for constructing full URLs (default: "http://localhost") */
+  origin?: string;
+  /**
+   * Called after each page is rendered — use for logging or progress tracking.
+   * Return false to skip writing this page.
+   */
+  onPage?: (path: string, html: string) => void | boolean | Promise<void | boolean>;
+}
+interface PrerenderResult {
+  /** Number of pages generated */
+  pages: number;
+  /** Paths that failed to render */
+  errors: {
+    path: string;
+    error: unknown;
+  }[];
+  /** Total elapsed time in milliseconds */
+  elapsed: number;
+}
+/**
+ * Pre-render a list of routes to static HTML files.
+ *
+ * For each path:
+ *   1. Constructs a Request for the path
+ *   2. Calls the SSR handler to render to HTML
+ *   3. Writes the HTML to `outDir/<path>/index.html`
+ *
+ * The root path "/" becomes `outDir/index.html`.
+ * Paths like "/about" become `outDir/about/index.html`.
+ */
+declare function prerender(options: PrerenderOptions): Promise<PrerenderResult>;
+//#endregion
+export { DEFAULT_TEMPLATE, type HandlerOptions, type HydrationStrategy, type IslandMeta, type IslandOptions, type Middleware, type MiddlewareContext, type PrerenderOptions, type PrerenderResult, type TemplateData, buildScripts, createHandler, island, prerender, processTemplate };
+//# sourceMappingURL=index2.d.ts.map

package/lib/types/index2.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"index2.d.ts","names":[],"sources":["../../src/middleware.ts","../../src/handler.ts","../../src/html.ts","../../src/island.ts","../../src/ssg.ts"],"mappings":";;;;;;;;AAqBA;;;;;;;;;;;;;;;;UAAiB,iBAAA;EAUP;EARR,GAAA,EAAK,OAAA;EAQS;EANd,GAAA,EAAK,GAAA;EAae;EAXpB,IAAA;EAW6B;EAT7B,OAAA,EAAS,OAAA;EASoE;EAP7E,MAAA,EAAQ,MAAA;AAAA;;;;KAOE,UAAA,IAAc,GAAA,EAAK,iBAAA,KAAsB,QAAA,UAAkB,OAAA,CAAQ,QAAA;;;UCE9D,cAAA;EDF8D;ECI7E,GAAA,EAAK,WAAA;EDJuE;ECM5E,MAAA,EAAQ,WAAA;EDNqB;;;;;;;;ECe7B,QAAA;;EAEA,WAAA;EAf6B;EAiB7B,UAAA,GAAa,UAAA;EAfR;;;;;EAqBL,IAAA;AAAA;AAAA,iBAGc,aAAA,CAAc,OAAA,EAAS,cAAA,IAAkB,GAAA,EAAK,OAAA,KAAY,OAAA,CAAQ,QAAA;;;;;;;AD7ClF;;;;cEZa,gBAAA;AAAA,UAaI,YAAA;EACf,IAAA;EACA,GAAA;EACA,OAAA;AAAA;AAAA,iBAGc,eAAA,CAAgB,QAAA,UAAkB,IAAA,EAAM,YAAA;;;;;;;;iBAcxC,YAAA,CACd,WAAA,UACA,UAAA,EAAY,MAAA;;;KCeF,iBAAA;AAAA,UAEK,aAAA;EFNf;EEQA,IAAA;EFNa;EEQb,OAAA,GAAU,iBAAA;AAAA;AAAA,UAGK,UAAA;EAAA,SACN,QAAA;EAAA,SACA,IAAA;EAAA,SACA,OAAA,EAAS,iBAAA;AAAA;;;;;;;;;iBAaJ,MAAA,WAAiB,KAAA,GAAQ,KAAA,CAAA,CACvC,MAAA,QAAc,OAAA;EAAU,OAAA,EAAS,WAAA,CAAY,CAAA;AAAA,IAAO,WAAA,CAAY,CAAA,IAChE,OAAA,EAAS,aAAA,GACR,WAAA,CAAY,CAAA,IAAK,UAAA;;;;;;;AHlEpB;;;;;;;;;;;;;;;;;;;;AAiBA;;;;;UILiB,gBAAA;EJKsD;EIHrE,OAAA,GAAU,GAAA,EAAK,OAAA,KAAY,OAAA,CAAQ,QAAA;EJGyC;EID5E,KAAA,+BAAoC,OAAA;EJCZ;EICxB,MAAA;EJDqE;EIGrE,MAAA;EJHqF;;;;EISrF,MAAA,IAAU,IAAA,UAAc,IAAA,8BAAkC,OAAA;AAAA;AAAA,UAG3C,eAAA;;EAEf,KAAA;EHRQ;EGUR,MAAA;IAAU,IAAA;IAAc,KAAA;EAAA;EHZnB;EGcL,OAAA;AAAA;;;;;;;;AHUF;;;;iBGIsB,SAAA,CAAU,OAAA,EAAS,gBAAA,GAAmB,OAAA,CAAQ,eAAA"}

package/package.json ADDED Viewed

@@ -0,0 +1,53 @@
+{
+  "name": "@pyreon/server",
+  "version": "0.1.0",
+  "description": "SSR handler, SSG prerender, and island architecture for Pyreon",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pyreon/pyreon.git",
+    "directory": "packages/server"
+  },
+  "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/server#readme",
+  "bugs": {
+    "url": "https://github.com/pyreon/pyreon/issues"
+  },
+  "files": [
+    "lib",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "main": "./lib/index.js",
+  "module": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./lib/index.js",
+      "types": "./lib/types/index.d.ts"
+    },
+    "./client": {
+      "bun": "./src/client.ts",
+      "import": "./lib/client.js",
+      "types": "./lib/types/client.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "vl_rolldown_build",
+    "dev": "vl_rolldown_build-watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@pyreon/core": "workspace:*",
+    "@pyreon/head": "workspace:*",
+    "@pyreon/reactivity": "workspace:*",
+    "@pyreon/router": "workspace:*",
+    "@pyreon/runtime-dom": "workspace:*",
+    "@pyreon/runtime-server": "workspace:*"
+  }
+}

package/src/client.ts ADDED Viewed

@@ -0,0 +1,239 @@
+/**
+ * Client-side entry helpers for Pyreon SSR/SSG apps.
+ *
+ * ## Full app hydration
+ *
+ * ```ts
+ * // entry-client.ts
+ * import { startClient } from "@pyreon/server/client"
+ * import { App } from "./App"
+ * import { routes } from "./routes"
+ *
+ * startClient({ App, routes })
+ * ```
+ *
+ * ## Island hydration (partial)
+ *
+ * ```ts
+ * // entry-client.ts
+ * import { hydrateIslands } from "@pyreon/server/client"
+ *
+ * hydrateIslands({
+ *   Counter: () => import("./Counter"),
+ *   Search:  () => import("./Search"),
+ * })
+ * ```
+ */
+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"
+// ─── Full app hydration ──────────────────────────────────────────────────────
+export interface StartClientOptions {
+  /** Root application component */
+  App: ComponentFn
+  /** Route definitions (same as server) */
+  routes: RouteRecord[]
+  /** CSS selector or element for the app container (default: "#app") */
+  container?: string | Element
+}
+/**
+ * Hydrate a server-rendered Pyreon app on the client.
+ *
+ * Handles:
+ *   - Router creation (history mode)
+ *   - Loader data hydration from `window.__PYREON_LOADER_DATA__`
+ *   - Hydration if container has SSR content, fresh mount otherwise
+ *
+ * Returns a cleanup function that unmounts the app.
+ */
+export function startClient(options: StartClientOptions): () => void {
+  const { App, routes, container = "#app" } = options
+  const el = typeof container === "string" ? document.querySelector(container) : container
+  if (!el) {
+    throw new Error(`[pyreon/client] Container "${container}" not found`)
+  }
+  // Create client-side router (history mode to match SSR)
+  const router = createRouter({ routes, mode: "history" })
+  // Hydrate loader data from SSR (avoids re-fetching on initial render)
+  const loaderData = (window as unknown as Record<string, unknown>).__PYREON_LOADER_DATA__
+  if (loaderData && typeof loaderData === "object") {
+    hydrateLoaderData(router as never, loaderData as Record<string, unknown>)
+  }
+  // Build app tree
+  const app = h(RouterProvider, { router }, h(App, null))
+  // Hydrate if container has SSR content, mount fresh otherwise
+  if (el.childNodes.length > 0) {
+    return hydrateRoot(el, app)
+  }
+  return mount(app, el as HTMLElement)
+}
+// ─── Island hydration ────────────────────────────────────────────────────────
+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).
+ *
+ * @example
+ * hydrateIslands({
+ *   Counter: () => import("./Counter"),
+ *   Search:  () => import("./Search"),
+ * })
+ */
+/**
+ * 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 {
+  const islands = document.querySelectorAll("pyreon-island")
+  const cleanups: (() => void)[] = []
+  for (const el of islands) {
+    const componentId = el.getAttribute("data-component")
+    if (!componentId) continue
+    const loader = registry[componentId]
+    if (!loader) {
+      console.warn(`No loader registered for island "${componentId}"`)
+      continue
+    }
+    const strategy = (el.getAttribute("data-hydrate") ?? "load") as HydrationStrategy
+    const propsJson = el.getAttribute("data-props") ?? "{}"
+    const cleanup = scheduleHydration(el as HTMLElement, loader, propsJson, strategy)
+    if (cleanup) cleanups.push(cleanup)
+  }
+  return () => {
+    for (const fn of cleanups) fn()
+  }
+}
+function scheduleHydration(
+  el: HTMLElement,
+  loader: IslandLoader,
+  propsJson: string,
+  strategy: HydrationStrategy,
+): (() => void) | null {
+  let cancelled = false
+  const hydrate = () => {
+    if (!cancelled) hydrateIsland(el, loader, propsJson)
+  }
+  switch (strategy) {
+    case "load":
+      hydrate()
+      return null
+    case "idle": {
+      if ("requestIdleCallback" in window) {
+        const id = requestIdleCallback(hydrate)
+        return () => {
+          cancelled = true
+          cancelIdleCallback(id)
+        }
+      }
+      const id = setTimeout(hydrate, 200)
+      return () => {
+        cancelled = true
+        clearTimeout(id)
+      }
+    }
+    case "visible":
+      return observeVisibility(el, hydrate)
+    case "never":
+      return null
+    default:
+      // media(query)
+      if (strategy.startsWith("media(")) {
+        const query = strategy.slice(6, -1)
+        const mql = window.matchMedia(query)
+        if (mql.matches) {
+          hydrate()
+          return null
+        }
+        const onChange = (e: MediaQueryListEvent) => {
+          if (e.matches) {
+            mql.removeEventListener("change", onChange)
+            hydrate()
+          }
+        }
+        mql.addEventListener("change", onChange)
+        return () => {
+          cancelled = true
+          mql.removeEventListener("change", onChange)
+        }
+      }
+      hydrate()
+      return null
+  }
+}
+async function hydrateIsland(
+  el: HTMLElement,
+  loader: IslandLoader,
+  propsJson: string,
+): Promise<void> {
+  const name = el.getAttribute("data-component") ?? "unknown"
+  try {
+    let props: Record<string, unknown>
+    try {
+      props = JSON.parse(propsJson)
+      if (typeof props !== "object" || props === null || Array.isArray(props)) {
+        throw new TypeError("Expected object")
+      }
+    } catch (parseErr) {
+      console.error(`Invalid island props JSON for "${name}"`, parseErr)
+      return
+    }
+    const mod = await loader()
+    const Comp = typeof mod === "function" ? mod : mod.default
+    hydrateRoot(el, h(Comp, props))
+  } catch (err) {
+    console.error(`Failed to hydrate island "${name}"`, err)
+  }
+}
+function observeVisibility(el: HTMLElement, callback: () => void): (() => void) | null {
+  if (!("IntersectionObserver" in window)) {
+    callback()
+    return null
+  }
+  const observer = new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          observer.disconnect()
+          callback()
+          return
+        }
+      }
+    },
+    { rootMargin: "200px" },
+  )
+  observer.observe(el)
+  return () => observer.disconnect()
+}

package/src/handler.ts ADDED Viewed

@@ -0,0 +1,187 @@
+/**
+ * SSR request handler.
+ *
+ * Creates a Web-standard `(Request) => Promise<Response>` handler that:
+ *   1. Runs middleware (auth, redirects, headers, etc.)
+ *   2. Creates a per-request router with the matched URL
+ *   3. Prefetches loader data for matched routes
+ *   4. Renders the app to HTML with head tag collection
+ *   5. Injects everything into an HTML template
+ *   6. Returns a Response
+ *
+ * Compatible with Bun.serve, Deno.serve, Cloudflare Workers,
+ * Express (via adapter), and any Web-standard server.
+ *
+ * @example
+ * import { createHandler } from "@pyreon/server"
+ *
+ * const handler = createHandler({
+ *   App,
+ *   routes,
+ *   template: await Bun.file("index.html").text(),
+ * })
+ *
+ * Bun.serve({ fetch: handler })
+ */
+import type { ComponentFn } from "@pyreon/core"
+import { h } from "@pyreon/core"
+import { renderWithHead } from "@pyreon/head"
+import {
+  createRouter,
+  prefetchLoaderData,
+  type RouteRecord,
+  RouterProvider,
+  serializeLoaderData,
+} from "@pyreon/router"
+import { renderToStream, runWithRequestContext } from "@pyreon/runtime-server"
+import { buildScripts, DEFAULT_TEMPLATE, processTemplate } from "./html"
+import type { Middleware, MiddlewareContext } from "./middleware"
+export interface HandlerOptions {
+  /** Root application component */
+  App: ComponentFn
+  /** Route definitions */
+  routes: RouteRecord[]
+  /**
+   * HTML template with placeholders:
+   *   <!--pyreon-head-->     — head tags (title, meta, link, etc.)
+   *   <!--pyreon-app-->      — rendered app HTML
+   *   <!--pyreon-scripts-->  — client entry + loader data
+   *
+   * Defaults to a minimal HTML5 template.
+   */
+  template?: string
+  /** Path to the client entry module (default: "/src/entry-client.ts") */
+  clientEntry?: string
+  /** Middleware chain — runs before rendering */
+  middleware?: Middleware[]
+  /**
+   * Rendering mode:
+   *   "string" (default) — full renderToString, complete HTML in one response
+   *   "stream" — progressive streaming via renderToStream (Suspense out-of-order)
+   */
+  mode?: "string" | "stream"
+}
+export function createHandler(options: HandlerOptions): (req: Request) => Promise<Response> {
+  const {
+    App,
+    routes,
+    template = DEFAULT_TEMPLATE,
+    clientEntry = "/src/entry-client.ts",
+    middleware = [],
+    mode = "string",
+  } = options
+  return async function handler(req: Request): Promise<Response> {
+    const url = new URL(req.url)
+    const path = url.pathname + url.search
+    // ── Middleware pipeline ────────────────────────────────────────────────────
+    const ctx: MiddlewareContext = {
+      req,
+      url,
+      path,
+      headers: new Headers({ "Content-Type": "text/html; charset=utf-8" }),
+      locals: {},
+    }
+    for (const mw of middleware) {
+      const result = await mw(ctx)
+      if (result instanceof Response) return result
+    }
+    // ── Per-request router ────────────────────────────────────────────────────
+    const router = createRouter({ routes, mode: "history", url: path })
+    return runWithRequestContext(async () => {
+      try {
+        // Pre-run loaders so data is available during render
+        await prefetchLoaderData(router as never, path)
+        // Build the VNode tree
+        const app = h(RouterProvider, { router }, h(App, null))
+        if (mode === "stream") {
+          return renderStreamResponse(app, router, template, clientEntry, ctx.headers)
+        }
+        // ── String mode (default) ─────────────────────────────────────────────
+        const { html: appHtml, head } = await renderWithHead(app)
+        const loaderData = serializeLoaderData(router as never)
+        const scripts = buildScripts(clientEntry, loaderData)
+        const fullHtml = processTemplate(template, { head, app: appHtml, scripts })
+        return new Response(fullHtml, { status: 200, headers: ctx.headers })
+      } catch (_err) {
+        return new Response("Internal Server Error", {
+          status: 500,
+          headers: { "Content-Type": "text/plain" },
+        })
+      }
+    })
+  }
+}
+/**
+ * Streaming mode: shell is emitted immediately, app content streams progressively.
+ *
+ * Head tags from the initial synchronous render are included in the shell.
+ * Suspense boundaries resolve out-of-order via inline <template> + swap scripts.
+ */
+async function renderStreamResponse(
+  app: ReturnType<typeof h>,
+  router: ReturnType<typeof createRouter>,
+  template: string,
+  clientEntry: string,
+  extraHeaders: Headers,
+): Promise<Response> {
+  const loaderData = serializeLoaderData(router as never)
+  const scripts = buildScripts(clientEntry, loaderData)
+  // Split template around <!--pyreon-app-->
+  const [beforeApp, afterApp] = template.split("<!--pyreon-app-->")
+  if (!beforeApp || afterApp === undefined) {
+    throw new Error("[pyreon/server] Template must contain <!--pyreon-app--> placeholder")
+  }
+  // Replace other placeholders in shell parts
+  const shellHead = beforeApp.replace("<!--pyreon-head-->", "")
+  const shellTail = afterApp.replace("<!--pyreon-scripts-->", scripts)
+  const appStream = renderToStream(app)
+  const reader = appStream.getReader()
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const encoder = new TextEncoder()
+      const push = (s: string) => controller.enqueue(encoder.encode(s))
+      try {
+        push(shellHead)
+        // Stream app content
+        let done = false
+        while (!done) {
+          const result = await reader.read()
+          done = result.done
+          if (result.value) push(result.value)
+        }
+        push(shellTail)
+      } catch (_err) {
+        // Emit an inline error indicator — status code is already sent (200)
+        push(`<script>console.error("[pyreon/server] Stream render failed")</script>`)
+        push(shellTail)
+      } finally {
+        controller.close()
+      }
+    },
+  })
+  return new Response(stream, {
+    status: 200,
+    headers: extraHeaders,
+  })
+}