@pylonsync/functions 0.3.223 → 0.3.225

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.223",
+  "version": "0.3.225",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/runtime.ts

@@ -230,6 +230,24 @@ function dispatch(line: string): void {
           message: err?.message || String(err),
         });
       });
+  } else if (msg.type === "bundle_client") {
+    // Hydration — build the client-side bundle once and report
+    // the path back. Lazy-imported for the same reason as SSR.
+    import("./ssr-client-bundler")
+      .then((mod) =>
+        mod.handleBundleClient(
+          msg as unknown as Parameters<typeof mod.handleBundleClient>[0],
+          send,
+        ),
+      )
+      .catch((err) => {
+        send({
+          type: "bundle_client_result",
+          call_id: (msg as unknown as { call_id: string }).call_id,
+          path: "",
+          error: err?.message || String(err),
+        });
+      });
   } else if (msg.type === "result") {
     const res = msg as unknown as ResultMessage & { op_id?: string };
     // Prefer op_id when the host sent it. Fall back to call_id for replies

package/src/ssr-client-bundler.test.ts

@@ -0,0 +1,236 @@
+// Regression tests for the Phase 1.5e SSR client bundler.
+//
+// These guard the shape we DEPEND on for shared chunks to actually
+// save bytes:
+//   1. multi-entry build with `splitting: true` produces a
+//      `chunks/` subdirectory.
+//   2. React lands in the shared chunk, NOT in any per-route entry
+//      (otherwise we'd duplicate ~120KB per page).
+//   3. the manifest names every discovered route, each pointing at
+//      exactly one entry file with its preload-list of chunks.
+//   4. adding a third page expands the manifest by one entry, and
+//      the new entry stays small (proves splitting is doing work,
+//      not just renaming the monolith).
+//
+// We exercise the bundler against a fixture app directory created
+// fresh per test. This keeps the test self-contained and lets us
+// verify behavior on real Bun.build outputs — no mocking.
+
+import { afterEach, describe, expect, test } from "bun:test";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+import {
+  buildClientBundle,
+  type PylonBundleManifest,
+} from "./ssr-client-bundler";
+
+// State that needs cleanup between tests.
+let originalCwd: string | null = null;
+let tempDir: string | null = null;
+
+function makeFixture(pages: Record<string, string>, layouts: Record<string, string>): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pylon-ssr-bundler-test-"));
+  fs.mkdirSync(path.join(dir, "app"), { recursive: true });
+  for (const [relPath, source] of Object.entries(pages)) {
+    const full = path.join(dir, "app", relPath);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, source, "utf8");
+  }
+  for (const [relPath, source] of Object.entries(layouts)) {
+    const full = path.join(dir, "app", relPath);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, source, "utf8");
+  }
+  // The bundler resolves `react` and `react-dom/client` relative
+  // to CWD. Point at `examples/ssr-hello/node_modules` — that
+  // fixture installs them already and we don't want to maintain a
+  // second copy.
+  const wsRoot = path.resolve(import.meta.dir, "..", "..", "..");
+  const reactSource = path.join(
+    wsRoot,
+    "examples",
+    "ssr-hello",
+    "node_modules",
+  );
+  if (!fs.existsSync(reactSource)) {
+    throw new Error(
+      `react fixture not present at ${reactSource}; run \`bun install\` inside examples/ssr-hello`,
+    );
+  }
+  fs.symlinkSync(reactSource, path.join(dir, "node_modules"));
+  return dir;
+}
+
+afterEach(() => {
+  if (originalCwd) {
+    process.chdir(originalCwd);
+    originalCwd = null;
+  }
+  if (tempDir) {
+    try {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      /* best-effort */
+    }
+    tempDir = null;
+  }
+});
+
+const PAGE_BODY = (name: string) => `
+import React, { useState } from "react";
+export default function ${name}() {
+  const [n] = useState(0);
+  return <div data-page="${name.toLowerCase()}">Hello {n}</div>;
+}
+`;
+
+const LAYOUT_BODY = `
+import React from "react";
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return <html><body>{children}</body></html>;
+}
+`;
+
+describe("ssr-client-bundler (Phase 1.5e)", () => {
+  test("multi-entry build emits per-route entries + shared chunks dir", async () => {
+    tempDir = makeFixture(
+      {
+        "page.tsx": PAGE_BODY("Home"),
+        "hello/page.tsx": PAGE_BODY("Hello"),
+      },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    originalCwd = process.cwd();
+    process.chdir(tempDir);
+
+    const { manifestPath, outdir } = await buildClientBundle();
+
+    expect(fs.existsSync(manifestPath)).toBe(true);
+    expect(fs.existsSync(outdir)).toBe(true);
+    expect(fs.existsSync(path.join(outdir, "chunks"))).toBe(true);
+
+    const entries = fs
+      .readdirSync(outdir)
+      .filter((n) => n.startsWith("client-entry-") && n.endsWith(".js"));
+    expect(entries.length).toBe(2);
+
+    const chunks = fs.readdirSync(path.join(outdir, "chunks"));
+    expect(chunks.length).toBeGreaterThan(0);
+  });
+
+  test("react-dom appears in the shared chunk, not in any per-route entry", async () => {
+    tempDir = makeFixture(
+      {
+        "page.tsx": PAGE_BODY("Home"),
+        "hello/page.tsx": PAGE_BODY("Hello"),
+      },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    originalCwd = process.cwd();
+    process.chdir(tempDir);
+
+    const { outdir } = await buildClientBundle();
+
+    const entryFiles = fs
+      .readdirSync(outdir)
+      .filter((n) => n.startsWith("client-entry-") && n.endsWith(".js"))
+      .map((n) => path.join(outdir, n));
+    const chunkFiles = fs
+      .readdirSync(path.join(outdir, "chunks"))
+      .map((n) => path.join(outdir, "chunks", n));
+
+    // The entry files should be TINY — just an import + hydrate
+    // call. Anything > a few KB means react was inlined.
+    for (const ef of entryFiles) {
+      const src = fs.readFileSync(ef, "utf8");
+      // No copy of react's reconciler ("Fiber") symbols should be
+      // in the entry file.
+      expect(src.length).toBeLessThan(5_000);
+      expect(src).not.toMatch(/Fiber/);
+    }
+
+    // At least one chunk should contain the react-dom internals.
+    const chunkHasReact = chunkFiles.some((cf) => {
+      const src = fs.readFileSync(cf, "utf8");
+      return /hydrateRoot|reactDom|react-dom/i.test(src);
+    });
+    expect(chunkHasReact).toBe(true);
+  });
+
+  test("manifest names every route, each with a non-empty imports list", async () => {
+    tempDir = makeFixture(
+      {
+        "page.tsx": PAGE_BODY("Home"),
+        "hello/page.tsx": PAGE_BODY("Hello"),
+        "about/page.tsx": PAGE_BODY("About"),
+      },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    originalCwd = process.cwd();
+    process.chdir(tempDir);
+
+    const { manifestPath } = await buildClientBundle();
+    const manifest = JSON.parse(
+      fs.readFileSync(manifestPath, "utf8"),
+    ) as PylonBundleManifest;
+
+    expect(manifest.public_prefix).toBe("/_pylon/build/");
+    expect(Object.keys(manifest.routes).sort()).toEqual([
+      "app/about/page",
+      "app/hello/page",
+      "app/page",
+    ]);
+
+    for (const [component, route] of Object.entries(manifest.routes)) {
+      expect(route.file).toMatch(/^client-entry-.+\.js$/);
+      expect(route.imports.length).toBeGreaterThan(0);
+      for (const imp of route.imports) {
+        // Should be outdir-relative.
+        expect(imp).not.toMatch(/^\//);
+        expect(imp).not.toMatch(/^\.\.\//);
+      }
+    }
+  });
+
+  test("adding a route grows the manifest by one and stays small per-entry", async () => {
+    tempDir = makeFixture(
+      {
+        "page.tsx": PAGE_BODY("Home"),
+        "hello/page.tsx": PAGE_BODY("Hello"),
+        "about/page.tsx": PAGE_BODY("About"),
+        "settings/page.tsx": PAGE_BODY("Settings"),
+      },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    originalCwd = process.cwd();
+    process.chdir(tempDir);
+
+    const { outdir, manifestPath } = await buildClientBundle();
+    const manifest = JSON.parse(
+      fs.readFileSync(manifestPath, "utf8"),
+    ) as PylonBundleManifest;
+
+    expect(Object.keys(manifest.routes).length).toBe(4);
+
+    // Per-entry file size cap. Each entry is just an import +
+    // hydrate boilerplate; the dominant cost (React) is shared.
+    // We allow generous slack for minifier variance but stay
+    // well below the "would have been a monolith" baseline of
+    // ~320KB.
+    for (const route of Object.values(manifest.routes)) {
+      const full = path.join(outdir, route.file);
+      const size = fs.statSync(full).size;
+      expect(size).toBeLessThan(5_000);
+    }
+
+    // All routes should reference the SAME shared chunk so the
+    // browser caches it once and reuses across navigations.
+    const sharedImports = Object.values(manifest.routes).map(
+      (r) => r.imports.join("|"),
+    );
+    const unique = new Set(sharedImports);
+    expect(unique.size).toBe(1);
+  });
+});

package/src/ssr-client-bundler.ts

@@ -0,0 +1,866 @@
+// Build the client-side hydration bundle for a Pylon SSR project.
+//
+// Phase 1.5e: code splitting with shared chunks. The bundler:
+//
+//   1. Discovers `app/**/page.tsx` + `app/**/layout.tsx` under cwd.
+//   2. Generates one tiny `client-runtime.ts` module containing the
+//      hydration dispatcher + React imports (the *only* place that
+//      pulls in react-dom/client).
+//   3. Generates one per-route entry — `client-entry-<slug>.tsx` —
+//      that statically imports its page + its layout chain, then
+//      calls into the runtime.
+//   4. Hands every per-route entry to `Bun.build` with
+//      `splitting: true` + `metafile: true`. Bun's splitter sees
+//      `client-runtime` (and thus React) imported by every entry
+//      and extracts it into a shared chunk under `chunks/`.
+//   5. Walks `metafile.outputs` to emit a `manifest.json` keyed on
+//      the project-relative component path the SSR side already
+//      uses. The manifest lists the route's entry file + every
+//      transitive `import` chunk so the SSR HTML head can emit the
+//      right `<script type=module>` + `<link rel=modulepreload>`
+//      pair.
+//
+// Result for `examples/ssr-hello` (2 routes, 1 layout): one shared
+// `chunks/chunk-*.js` carrying React (~120KB gz), plus two tiny
+// per-route entries (~1-2KB each). A visit to /hello loads the
+// shared chunk + the /hello entry; a subsequent click to / hits the
+// cache for the shared chunk and only pulls the / entry.
+//
+// What it doesn't do (Phase 1.5f+):
+//   - File-watcher invalidation. Rebuild requires pylon dev restart.
+//   - Source maps. Will enable in dev once the basics are solid.
+//   - Link prefetching. <PylonLink> with IntersectionObserver
+//     prefetch is a follow-up — splitting is the precondition.
+//   - CSS chunking. No CSS support in SSR yet.
+
+type Send = (msg: Record<string, unknown>) => void;
+
+interface BundleClientMessage {
+  type: "bundle_client";
+  call_id: string;
+}
+
+interface DiscoveredRoute {
+  /**
+   * Project-relative module path without extension. This is the
+   * key the SSR side passes in __PYLON_DATA__.component and the key
+   * the manifest is indexed by.
+   */
+  component: string;
+  /** Layout chain root → leaf, same format as `component`. */
+  layouts: string[];
+}
+
+/** Bun.build returns this shape (the subset we depend on). */
+type BunBuildOutput = {
+  success: boolean;
+  outputs: Array<{
+    path: string;
+    kind: string;
+    hash?: string;
+    text?(): Promise<string>;
+  }>;
+  logs?: Array<{ level: string; message: string }>;
+};
+
+declare const Bun: {
+  build(opts: {
+    entrypoints: string[];
+    outdir?: string;
+    target?: "browser" | "bun" | "node";
+    format?: "esm" | "iife";
+    minify?: boolean;
+    sourcemap?: "none" | "inline" | "external";
+    external?: string[];
+    splitting?: boolean;
+    naming?:
+      | string
+      | {
+          entry?: string;
+          chunk?: string;
+          asset?: string;
+        };
+    publicPath?: string;
+    root?: string;
+  }): Promise<BunBuildOutput>;
+  file(path: string): { exists(): Promise<boolean> };
+};
+
+/**
+ * Synchronously walk `app/` under cwd. Returns one entry per
+ * discovered page, each carrying its layout chain (root → leaf).
+ * Mirrors the discovery logic in @pylonsync/sdk's
+ * `discoverAppRoutes` exactly — same sort order, same group-strip,
+ * so the in-browser map keys line up with the manifest's component
+ * field.
+ */
+function discoverRoutes(
+  fs: any,
+  path: any,
+  cwd: string,
+): DiscoveredRoute[] {
+  const appDir = path.join(cwd, "app");
+  if (!fs.existsSync(appDir) || !fs.statSync(appDir).isDirectory()) {
+    return [];
+  }
+
+  type PageHit = { segments: string[]; component: string; layouts: string[] };
+  const pages: PageHit[] = [];
+
+  function walk(dir: string, segments: string[], layouts: string[]): void {
+    let entries: Array<{ name: string; isDirectory(): boolean }>;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    const layoutHere = ["layout.tsx", "layout.ts", "layout.jsx", "layout.js"]
+      .map((n: string) => path.join(dir, n))
+      .find((p: string) => fs.existsSync(p));
+    const nextLayouts = layoutHere
+      ? [...layouts, path.relative(cwd, layoutHere).replace(/\.(tsx?|jsx?)$/, "")]
+      : layouts;
+    const pageHere = ["page.tsx", "page.ts", "page.jsx", "page.js"]
+      .map((n: string) => path.join(dir, n))
+      .find((p: string) => fs.existsSync(p));
+    if (pageHere) {
+      pages.push({
+        segments: [...segments],
+        component: path.relative(cwd, pageHere).replace(/\.(tsx?|jsx?)$/, ""),
+        layouts: nextLayouts,
+      });
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (e.name.startsWith(".") || e.name === "node_modules") continue;
+      const sub = path.join(dir, e.name);
+      const isGroup = e.name.startsWith("(") && e.name.endsWith(")");
+      const newSegments = isGroup ? segments : [...segments, e.name];
+      walk(sub, newSegments, nextLayouts);
+    }
+  }
+  walk(appDir, [], []);
+
+  return pages.map((p) => ({
+    component: p.component,
+    layouts: p.layouts,
+  }));
+}
+
+/**
+ * The shared hydration dispatcher + router. ONE module, imported
+ * by every per-route entry. Bun's splitter sees N entries reach
+ * for it and pulls it (and React via the transitive imports) into
+ * a shared chunk.
+ *
+ * Two responsibilities:
+ *   1. `hydrate(component, Page, Layouts)` — called by each route
+ *      entry. The first call (matching the SSR'd component) calls
+ *      hydrateRoot; subsequent calls (after a client-side
+ *      navigation) re-render the cached root with the new tree.
+ *      Either way, the entry also registers itself in the route
+ *      cache so future navigations don't need to refetch the chunk.
+ *   2. `navigate(href)` — fetches the new SSR HTML, parses out the
+ *      `__PYLON_DATA__` payload, dynamically loads the new route's
+ *      entry from the manifest, and re-renders into the existing
+ *      React root. Layouts that match the previous render survive
+ *      reconciliation (React keeps their state).
+ *
+ * Global click handler intercepts `a[data-pylon-link]` clicks for
+ * client-side nav. popstate handles back/forward. The runtime
+ * exposes `window.__pylon` for the `<Link>` component to call
+ * directly (prefetch, navigate).
+ */
+const CLIENT_RUNTIME_SOURCE = `// Generated by Pylon SSR (Phase 2 client runtime).
+// DO NOT EDIT — overwritten on every pylon dev / build.
+
+import { createElement } from "react";
+import { hydrateRoot } from "react-dom/client";
+
+const routeCache = Object.create(null);
+let activeRoot = null;
+let manifestPromise = null;
+const prefetchedChunks = new Set();
+
+function buildTree(Page, Layouts, props) {
+  let tree = createElement(Page, props);
+  for (let i = Layouts.length - 1; i >= 0; i--) {
+    const Layout = Layouts[i];
+    if (!Layout) continue;
+    tree = createElement(Layout, props, tree);
+  }
+  return tree;
+}
+
+function readPylonData() {
+  const dataEl = document.getElementById("__PYLON_DATA__");
+  if (!dataEl) return null;
+  try {
+    return JSON.parse(dataEl.textContent || "{}");
+  } catch {
+    return null;
+  }
+}
+
+async function loadManifest() {
+  if (!manifestPromise) {
+    manifestPromise = fetch("/_pylon/build/manifest.json", {
+      credentials: "same-origin",
+    })
+      .then((r) => (r.ok ? r.json() : null))
+      .catch(() => null);
+  }
+  return manifestPromise;
+}
+
+function preloadChunks(routeInfo) {
+  if (!routeInfo) return;
+  const prefix = routeInfo.public_prefix || "/_pylon/build/";
+  const all = [routeInfo.file, ...(routeInfo.imports || [])];
+  for (const c of all) {
+    if (prefetchedChunks.has(c)) continue;
+    prefetchedChunks.add(c);
+    const link = document.createElement("link");
+    link.rel = "modulepreload";
+    link.href = prefix + c;
+    document.head.appendChild(link);
+  }
+}
+
+async function prefetch(href) {
+  // HTML prefetch — primes the SSR response cache.
+  const url = new URL(href, location.href);
+  if (url.origin !== location.origin) return;
+  if (!document.querySelector('link[rel="prefetch"][href="' + url.pathname + '"]')) {
+    const html = document.createElement("link");
+    html.rel = "prefetch";
+    html.as = "document";
+    html.href = url.pathname + url.search;
+    document.head.appendChild(html);
+  }
+  // Chunk prefetch — peek at the manifest, but we don't know the
+  // component path from the href without server help. v1: rely on
+  // the shared chunk already being cached + the SSR head emitting
+  // the right preload tags after the user lands. So all prefetch
+  // does today is HTML — chunk dedup happens via the manifest.
+  const manifest = await loadManifest();
+  if (manifest) {
+    // Pre-warm all routes' shared chunks (one chunk in practice).
+    const shared = new Set();
+    for (const r of Object.values(manifest.routes || {})) {
+      for (const i of r.imports || []) shared.add(i);
+    }
+    const info = { public_prefix: manifest.public_prefix, file: "", imports: Array.from(shared) };
+    preloadChunks(info);
+  }
+}
+
+async function loadRouteEntry(component) {
+  if (routeCache[component]) return routeCache[component];
+  const manifest = await loadManifest();
+  if (!manifest) throw new Error("manifest unavailable");
+  const routeInfo = manifest.routes[component];
+  if (!routeInfo) throw new Error("unknown component " + component);
+  const prefix = manifest.public_prefix || "/_pylon/build/";
+  preloadChunks({ ...routeInfo, public_prefix: prefix });
+  // Dynamic import the entry. It will call hydrate(...) which
+  // populates routeCache[component], then this returns.
+  await import(/* @vite-ignore */ prefix + routeInfo.file);
+  if (!routeCache[component]) {
+    throw new Error("route entry did not register: " + component);
+  }
+  return routeCache[component];
+}
+
+export function hydrate(component, Page, Layouts) {
+  // Always cache the route for nav.
+  routeCache[component] = { Page, Layouts };
+  const data = readPylonData();
+  // First hydrate: the entry's component MATCHES the SSR'd page.
+  // Establish the root + install the click + popstate handlers
+  // exactly once.
+  if (!activeRoot) {
+    if (!data || data.component !== component) {
+      console.warn(
+        "[pylon ssr] entry/__PYLON_DATA__ mismatch — initial hydration skipped",
+      );
+      return;
+    }
+    const tree = buildTree(Page, Layouts, data.props);
+    activeRoot = hydrateRoot(document, tree);
+    installNavHandlers();
+    return;
+  }
+  // Subsequent hydrate calls fire from dynamic-loaded entries
+  // during navigation. The render is driven by navigate(), so we
+  // only need to populate the cache (already done above).
+}
+
+async function navigate(href, opts) {
+  const push = !opts || opts.push !== false;
+  const url = new URL(href, location.href);
+  if (url.origin !== location.origin) {
+    window.location.href = href;
+    return;
+  }
+  let html;
+  try {
+    const res = await fetch(url.pathname + url.search, {
+      credentials: "same-origin",
+      headers: { Accept: "text/html" },
+    });
+    if (!res.ok) {
+      window.location.href = href;
+      return;
+    }
+    html = await res.text();
+  } catch {
+    window.location.href = href;
+    return;
+  }
+  const doc = new DOMParser().parseFromString(html, "text/html");
+  const dataEl = doc.getElementById("__PYLON_DATA__");
+  if (!dataEl) {
+    window.location.href = href;
+    return;
+  }
+  let data;
+  try {
+    data = JSON.parse(dataEl.textContent || "{}");
+  } catch {
+    window.location.href = href;
+    return;
+  }
+  let route;
+  try {
+    route = await loadRouteEntry(data.component);
+  } catch (e) {
+    console.warn("[pylon ssr] nav fallback (entry load failed):", e);
+    window.location.href = href;
+    return;
+  }
+  document.title = doc.title || document.title;
+  const tree = buildTree(route.Page, route.Layouts, data.props);
+  activeRoot.render(tree);
+  if (push) {
+    history.pushState({ component: data.component }, "", url.pathname + url.search);
+  }
+  // After a successful nav, scroll to top (Next.js default).
+  window.scrollTo(0, 0);
+}
+
+function installNavHandlers() {
+  document.addEventListener("click", (e) => {
+    if (e.defaultPrevented) return;
+    if (e.button !== 0) return;
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+    const target = e.target;
+    if (!target || !target.closest) return;
+    const link = target.closest("a[data-pylon-link]");
+    if (!link) return;
+    const href = link.getAttribute("href");
+    if (!href) return;
+    if (link.target && link.target !== "" && link.target !== "_self") return;
+    if (href.startsWith("http://") || href.startsWith("https://") || href.startsWith("//")) {
+      // External — let the browser handle.
+      return;
+    }
+    e.preventDefault();
+    navigate(href);
+  });
+  window.addEventListener("popstate", () => {
+    navigate(location.pathname + location.search, { push: false });
+  });
+}
+
+// Expose for <Link> component prefetch.
+const pylonGlobal = { prefetch, navigate };
+if (typeof window !== "undefined") {
+  window.__pylon = pylonGlobal;
+}
+`;
+
+/**
+ * Per-route entry source. Stays tiny on purpose — react /
+ * react-dom / client-runtime get hoisted into the shared chunk
+ * by the splitter, so this body ends up as roughly "load the
+ * shared chunk, then call hydrate(Page, [L0, L1, ...])".
+ *
+ * Each route gets its own entry file under `.pylon/`. The entry
+ * path for component `app/hello/page` is
+ * `.pylon/client-entry-app__hello__page.tsx` — flat namespace
+ * keyed on the slug we'd already need anyway for the manifest.
+ */
+function generateRouteEntry(route: DiscoveredRoute): string {
+  const layoutImports = route.layouts
+    .map((l, i) => `import L${i} from "${cwd_to_import(l)}";`)
+    .join("\n");
+  const layoutArray = route.layouts.map((_, i) => `L${i}`).join(", ");
+  return `// Generated by Pylon SSR (Phase 2 per-route entry).
+// DO NOT EDIT — overwritten on every pylon dev / build.
+
+import { hydrate } from "./client-runtime";
+import Page from "${cwd_to_import(route.component)}";
+${layoutImports}
+
+hydrate(${JSON.stringify(route.component)}, Page, [${layoutArray}]);
+`;
+}
+
+/**
+ * Bun's static import-path resolution runs against the source
+ * file's directory. Per-route entries live at
+ * `<cwd>/.pylon/client-entry-<slug>.tsx`, so reaching
+ * `<cwd>/app/page.tsx` is `../app/page`. The shared runtime stays
+ * at `./client-runtime` since it sits next to the entries.
+ */
+function cwd_to_import(modulePath: string): string {
+  return `../${modulePath}`;
+}
+
+/**
+ * Project-relative component path → filename-safe slug.
+ * `app/hello/page` → `app__hello__page`. Used for the entry
+ * filename and (after Bun appends the hash) for the manifest key
+ * mapping back to the component path.
+ */
+function slugForComponent(component: string): string {
+  return component.replace(/[^A-Za-z0-9_]/g, "__");
+}
+
+/**
+ * Manifest schema. One entry per route, indexed by the same
+ * project-relative component path the SSR side passes through.
+ * `file` is the entry chunk, `imports` is the transitive set of
+ * shared chunks the browser needs to load BEFORE the entry runs
+ * — that's the modulepreload list.
+ *
+ * Paths in the manifest are relative to `.pylon/client-build/` so
+ * the Rust host can serve them under `/_pylon/build/<path>` with
+ * no rewriting.
+ */
+export interface PylonBundleManifest {
+  /** Build identity — bumps every successful build. */
+  build_id: string;
+  /** Output root, relative to cwd (always `.pylon/client-build`). */
+  outdir: string;
+  /** Public URL prefix the Rust host serves chunks under. */
+  public_prefix: string;
+  /** routeComponentPath → file + imports for that route. */
+  routes: Record<
+    string,
+    {
+      /** Per-route entry file, relative to outdir. */
+      file: string;
+      /** Transitive shared chunks to modulepreload, relative to outdir. */
+      imports: string[];
+      /** CSS chunks (Phase 1.5f). */
+      css: string[];
+    }
+  >;
+}
+
+/** Result of an in-process build — same shape the protocol returns. */
+export interface BuildOutput {
+  manifestPath: string;
+  outdir: string;
+}
+
+/**
+ * Single-flight in-process build promise. SSR + asset-route handlers
+ * both reach for `buildClientBundle()` lazily, so without dedup we
+ * could fire two concurrent Bun.build calls under load and trample
+ * each other's outputs (especially the `rm -rf outdir` step). The
+ * Promise is kept as long as a build is in flight, then cleared so
+ * the next invalidation re-builds.
+ */
+let _inflightBuild: Promise<BuildOutput> | null = null;
+
+/**
+ * Run the bundler in-process and return the manifest path + outdir.
+ * Used from `handleBundleClient` (protocol RPC path from Rust) AND
+ * from `getManifest` (in-process SSR path).
+ */
+export async function buildClientBundle(): Promise<BuildOutput> {
+  if (_inflightBuild) return _inflightBuild;
+  _inflightBuild = (async () => {
+    try {
+      return await _doBuild();
+    } finally {
+      _inflightBuild = null;
+    }
+  })();
+  return _inflightBuild;
+}
+
+async function _doBuild(): Promise<BuildOutput> {
+  // node:* are available in Bun, but `globalThis.require` is
+  // not defined in ESM. Use dynamic import; Bun fast-paths these.
+  const fsMod: any = await import("node:fs");
+  const pathMod: any = await import("node:path");
+  const fs = fsMod.default ?? fsMod;
+  const path = pathMod.default ?? pathMod;
+  const cwd = process.cwd();
+  return _doBuildInner(fs, path, cwd);
+}
+
+/**
+ * Compile `app/globals.css` through Tailwind v4 (`@tailwindcss/cli`)
+ * if both are present. Returns the relative output path (under
+ * outdir) when produced, else null. Skipped silently when the
+ * project hasn't opted in to Tailwind — we don't want every SSR
+ * project to need Tailwind installed.
+ */
+async function buildTailwind(
+  fs: any,
+  path: any,
+  cwd: string,
+  outdir: string,
+): Promise<string | null> {
+  const globalsPath = path.join(cwd, "app", "globals.css");
+  if (!fs.existsSync(globalsPath)) return null;
+  // Resolve @tailwindcss/cli. The package only exports
+  // `./package.json` in its `exports` map (it's a binary, not a
+  // library), so we resolve THAT and reach for `dist/index.mjs`
+  // next to it. If the dep isn't installed, surface a clear hint.
+  let cliPath: string;
+  try {
+    const pkgPath = (Bun as any).resolveSync(
+      "@tailwindcss/cli/package.json",
+      cwd,
+    );
+    cliPath = path.join(path.dirname(pkgPath), "dist", "index.mjs");
+    if (!fs.existsSync(cliPath)) {
+      throw new Error(`tailwindcss CLI entry not found at ${cliPath}`);
+    }
+  } catch (err: any) {
+    throw new Error(
+      `app/globals.css exists but @tailwindcss/cli is not installed — run \`bun add @tailwindcss/cli tailwindcss\` (resolver said: ${err?.message ?? err})`,
+    );
+  }
+
+  // Hash the source content so we can name the output uniquely +
+  // serve it with long-cache immutable headers.
+  const src = fs.readFileSync(globalsPath, "utf8");
+  let hash = 0;
+  for (let i = 0; i < src.length; i++) {
+    hash = (hash * 31 + src.charCodeAt(i)) >>> 0;
+  }
+  // Mix in the discovered routes so adding/removing pages changes
+  // the hash (Tailwind v4 auto-discovers `@source` paths; we still
+  // want the cache to bust on layout changes).
+  const stylesName = `styles-${hash.toString(36)}.css`;
+  const outPath = path.join(outdir, stylesName);
+
+  // Spawn the CLI. Bun is already running; reuse it as the
+  // interpreter so the user doesn't need node on PATH.
+  const proc = (Bun as any).spawn({
+    cmd: [process.execPath, cliPath, "-i", globalsPath, "-o", outPath, "--minify"],
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    const err = await new Response(proc.stderr).text();
+    throw new Error(`tailwindcss build failed (exit ${exitCode}): ${err}`);
+  }
+  return stylesName;
+}
+
+async function _doBuildInner(fs: any, path: any, cwd: string): Promise<BuildOutput> {
+  const routes = discoverRoutes(fs, path, cwd);
+    if (routes.length === 0) {
+      throw new Error("no SSR routes discovered under app/ — nothing to bundle");
+    }
+
+    const stageDir = path.join(cwd, ".pylon");
+    fs.mkdirSync(stageDir, { recursive: true });
+
+    // Wipe stale per-route entries so deletions are picked up.
+    // Hashed chunk outputs live under client-build/ and are wiped
+    // by the same `rm -rf` so renamed routes don't leave orphans.
+    for (const name of fs.readdirSync(stageDir)) {
+      if (name.startsWith("client-entry-")) {
+        try {
+          fs.unlinkSync(path.join(stageDir, name));
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+    const outdir = path.join(stageDir, "client-build");
+    try {
+      fs.rmSync(outdir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+    fs.mkdirSync(outdir, { recursive: true });
+
+    // The shared runtime + per-route entries. We track which file
+    // each entry corresponds to so we can match metafile.outputs
+    // back to the original route afterwards.
+    const runtimePath = path.join(stageDir, "client-runtime.ts");
+    fs.writeFileSync(runtimePath, CLIENT_RUNTIME_SOURCE, "utf8");
+
+    const entryPaths: string[] = [];
+    // entryPath (absolute) → component path (for manifest lookup).
+    const entryToComponent = new Map<string, string>();
+    for (const r of routes) {
+      const slug = slugForComponent(r.component);
+      const entryPath = path.join(stageDir, `client-entry-${slug}.tsx`);
+      fs.writeFileSync(entryPath, generateRouteEntry(r), "utf8");
+      entryPaths.push(entryPath);
+      entryToComponent.set(entryPath, r.component);
+    }
+
+    // splitting: true gates code-splitting. Bun 1.3.14 does NOT
+    // expose a `metafile` flag — its build result lists per-output
+    // `path` + `kind` (`entry-point` vs `chunk`) but no import
+    // graph. We recover the per-entry preload set by parsing the
+    // entry files' literal `import "./chunks/<name>.js"`
+    // statements after the build.
+    const result = await Bun.build({
+      entrypoints: entryPaths,
+      outdir,
+      target: "browser",
+      format: "esm",
+      minify: true,
+      sourcemap: "none",
+      splitting: true,
+      naming: {
+        entry: "[name]-[hash].js",
+        chunk: "chunks/[name]-[hash].js",
+        asset: "assets/[name]-[hash][ext]",
+      },
+    });
+
+    if (!result.success) {
+      const msgs = (result.logs ?? [])
+        .map((l) => `${l.level}: ${l.message}`)
+        .join("\n");
+      throw new Error(`Bun.build failed:\n${msgs || "(no log messages)"}`);
+    }
+
+    // Index outputs:
+    //   - entries (kind === "entry-point") — matched to components
+    //     by filename stem (`client-entry-<slug>`).
+    //   - chunks (kind === "chunk") — looked up by basename when
+    //     scanning entry files for static `import "./chunks/..."`
+    //     specifiers.
+    const outdirRel = path.relative(cwd, outdir);
+    const entriesByStem = new Map<
+      string,
+      { absPath: string; relPath: string }
+    >();
+    const chunksByBasename = new Map<
+      string,
+      { absPath: string; relPath: string }
+    >();
+    for (const o of result.outputs) {
+      const absPath: string = o.path;
+      const relPath = path.relative(outdir, absPath);
+      const base = path.basename(absPath);
+      // Strip `-<hash>.js` to recover the entry source's stem
+      // (e.g. `client-entry-app__hello__page`). The hash is
+      // alphanumeric (Bun uses base36-ish), the slug we wrote is
+      // `[A-Za-z0-9_]+`, so splitting on the LAST `-<hash>.js` is
+      // unambiguous.
+      const stem = base.replace(/-[A-Za-z0-9]+\.(?:m?js)$/, "");
+      if (o.kind === "entry-point") {
+        entriesByStem.set(stem, { absPath, relPath });
+      } else if (o.kind === "chunk") {
+        chunksByBasename.set(base, { absPath, relPath });
+      }
+    }
+
+    // Scan a built JS file for static `import` literals pointing
+    // at `./chunks/<file>.js` and return them resolved to outdir-
+    // relative paths. Bun's minified output uses simple double
+    // quotes for module specifiers, so a `matchAll` covers both
+    // `import X from "Y"` and bare `import "Y"`.
+    function scanChunkImports(jsAbsPath: string): string[] {
+      let src: string;
+      try {
+        src = fs.readFileSync(jsAbsPath, "utf8");
+      } catch {
+        return [];
+      }
+      const found = new Set<string>();
+      const matches = src.matchAll(
+        /(?:from\s*|import\s*\(?\s*)["']([^"']+)["']/g,
+      );
+      for (const m of matches) {
+        const spec = m[1];
+        if (spec.startsWith("./chunks/") || spec.startsWith("chunks/")) {
+          const base = path.basename(spec);
+          const hit = chunksByBasename.get(base);
+          if (hit) found.add(hit.relPath);
+        }
+      }
+      return Array.from(found);
+    }
+
+    const manifest: PylonBundleManifest = {
+      build_id: makeBuildId(),
+      outdir: outdirRel,
+      public_prefix: "/_pylon/build/",
+      routes: {},
+    };
+    for (const r of routes) {
+      const slug = slugForComponent(r.component);
+      const stem = `client-entry-${slug}`;
+      const entry = entriesByStem.get(stem);
+      if (!entry) continue;
+      // Walk transitively in case Bun emits chunks that reference
+      // other chunks (rare in the single-level splitting we use,
+      // but free to compute).
+      const seen = new Set<string>();
+      const queue: string[] = scanChunkImports(entry.absPath);
+      for (const q of queue) seen.add(q);
+      while (queue.length > 0) {
+        const relChunk = queue.shift()!;
+        const absChunk = path.join(outdir, relChunk);
+        for (const nested of scanChunkImports(absChunk)) {
+          if (!seen.has(nested)) {
+            seen.add(nested);
+            queue.push(nested);
+          }
+        }
+      }
+      manifest.routes[r.component] = {
+        file: entry.relPath,
+        imports: Array.from(seen),
+        css: [],
+      };
+    }
+
+    // Bail loudly if discovery succeeded but the manifest came
+    // out empty — means our entryPoint → component matching broke
+    // and SSR will silently hydration-skip.
+    if (Object.keys(manifest.routes).length === 0) {
+      throw new Error(
+        "manifest is empty after build — entryPoint matching against metafile failed",
+      );
+    }
+    if (Object.keys(manifest.routes).length !== routes.length) {
+      const missing = routes
+        .filter((r) => !(r.component in manifest.routes))
+        .map((r) => r.component);
+      throw new Error(
+        `manifest missing entries for routes: ${missing.join(", ")}`,
+      );
+    }
+
+    // Tailwind v4 compile. Optional — only fires if the project has
+    // `app/globals.css`. Adds the stylesheet to every route's css
+    // array so SSR head injection emits `<link rel="stylesheet">`.
+    try {
+      const styles = await buildTailwind(fs, path, cwd, outdir);
+      if (styles) {
+        for (const r of Object.values(manifest.routes)) {
+          r.css = [styles];
+        }
+      }
+    } catch (twErr: any) {
+      // Tailwind failure shouldn't kill the SSR build — log a loud
+      // warning + ship the bundle without styles so devs can iterate.
+      // eslint-disable-next-line no-console
+      console.warn(`[pylon ssr] tailwind compile failed: ${twErr?.message ?? twErr}`);
+    }
+
+  const manifestPath = path.join(outdir, "manifest.json");
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf8");
+
+  // Bump our in-process manifest cache so SSR re-reads on next request.
+  _manifestCache = null;
+
+  return { manifestPath, outdir };
+}
+
+/**
+ * Cached parsed manifest for the SSR head-injection path. Keyed on
+ * mtime so an external `pylon build` that overwrites manifest.json
+ * gets picked up by the next SSR request without a process restart.
+ */
+let _manifestCache: { mtimeMs: number; data: PylonBundleManifest } | null = null;
+
+/**
+ * Return the bundle manifest. If a fresh manifest exists on disk,
+ * use it (caching parse output across requests). Otherwise build
+ * the bundle in-process (deduped by `buildClientBundle`) and read.
+ *
+ * Called from `ssr-runtime.ts` per-request, so the disk-stat fast
+ * path matters. Bun's `fs.statSync` is a ~5µs syscall; cheap enough
+ * that we don't gate it on a flag.
+ */
+export async function getManifest(): Promise<PylonBundleManifest> {
+  const fsMod: any = await import("node:fs");
+  const pathMod: any = await import("node:path");
+  const fs = fsMod.default ?? fsMod;
+  const path = pathMod.default ?? pathMod;
+  const cwd = process.cwd();
+  const manifestPath = path.join(cwd, ".pylon", "client-build", "manifest.json");
+
+  if (fs.existsSync(manifestPath)) {
+    const stat = fs.statSync(manifestPath);
+    if (_manifestCache && _manifestCache.mtimeMs === stat.mtimeMs) {
+      return _manifestCache.data;
+    }
+    const raw = fs.readFileSync(manifestPath, "utf8");
+    const data = JSON.parse(raw) as PylonBundleManifest;
+    _manifestCache = { mtimeMs: stat.mtimeMs, data };
+    return data;
+  }
+
+  // Manifest missing → build in-process, then read.
+  const { manifestPath: built } = await buildClientBundle();
+  const raw = fs.readFileSync(built, "utf8");
+  const data = JSON.parse(raw) as PylonBundleManifest;
+  const stat = fs.statSync(built);
+  _manifestCache = { mtimeMs: stat.mtimeMs, data };
+  return data;
+}
+
+/**
+ * Protocol entry. Builds + responds. Rust calls this via the
+ * `bundle_client` RPC; on success the response carries both
+ * the manifest path (so Rust can load it if it wants, today it
+ * doesn't) and the outdir (so `/_pylon/build/<rel>` serves the
+ * right tree).
+ */
+export async function handleBundleClient(
+  msg: BundleClientMessage,
+  send: Send,
+): Promise<void> {
+  try {
+    const { manifestPath, outdir } = await buildClientBundle();
+    send({
+      type: "bundle_client_result",
+      call_id: msg.call_id,
+      path: manifestPath,
+      outdir,
+    });
+  } catch (err: any) {
+    send({
+      type: "bundle_client_result",
+      call_id: msg.call_id,
+      path: "",
+      outdir: "",
+      error: err?.message || String(err),
+    });
+  }
+}
+
+/**
+ * Stable-ish build id. We don't have Date.now() in workflow scripts
+ * but Bun's runtime is fine — performance.now() + a counter would
+ * also do. Falling back to a randomish hex string keyed on the
+ * process pid + a monotonic counter is good enough for telling
+ * "did the bundle change" without claiming to be cryptographic.
+ */
+let _buildCounter = 0;
+function makeBuildId(): string {
+  _buildCounter += 1;
+  return `${process.pid.toString(36)}-${Date.now().toString(36)}-${_buildCounter}`;
+}

package/src/ssr-runtime.ts

@@ -19,6 +19,23 @@ export interface RenderRouteMessage {
    * adapter joins cwd + this + the right extension (.tsx → .ts).
    */
   component: string;
+  /**
+   * Project-relative module paths for the layout chain, walked
+   * root → leaf. Each layout's default export wraps the next as
+   * `children`. Absent / empty when no layouts apply.
+   *
+   * Example:
+   *   layouts: ["app/layout", "app/blog/layout"]
+   *   component: "app/blog/[slug]/page"
+   *
+   * Resolves to:
+   *   <RootLayout>
+   *     <BlogLayout>
+   *       <Page {...props} />
+   *     </BlogLayout>
+   *   </RootLayout>
+   */
+  layouts?: string[];
   /** The matched route pattern (e.g. `/blog/:slug`). */
   route_path: string;
   /** The incoming URL path (e.g. `/blog/hello-world`). */
@@ -133,7 +150,51 @@ export async function handleRenderRoute(
       auth: msg.auth,
     };
 
-    const element = React.createElement(Component, props);
+    // Resolve the layout chain. Each layout module exports a default
+    // function that accepts the same props + `children`. Walk leaf →
+    // root: start with the page component as `tree`, then for each
+    // layout (innermost first) wrap it as the new tree. Result is
+    // the outermost layout containing all nested layouts down to
+    // the page.
+    let tree: any = React.createElement(Component, props);
+    const layouts = msg.layouts ?? [];
+    if (layouts.length > 0) {
+      // Resolve all layouts first so we fail fast on a missing one
+      // BEFORE we start emitting headers / chunks.
+      const layoutMods: any[] = [];
+      for (const layoutPath of layouts) {
+        const lBase = `${cwd}/${layoutPath}`;
+        let lMod: any = null;
+        for (const ext of [".tsx", ".ts", ".jsx", ".js"]) {
+          try {
+            lMod = await import(`${lBase}${ext}`);
+            break;
+          } catch {
+            // try next extension
+          }
+        }
+        if (!lMod) {
+          throw new Error(
+            `could not import layout "${layoutPath}" — checked .tsx / .ts / .jsx / .js`,
+          );
+        }
+        const LayoutComp =
+          lMod.default ?? lMod.Layout ?? lMod.layout;
+        if (typeof LayoutComp !== "function") {
+          throw new Error(
+            `layout "${layoutPath}" has no default export (or named export "Layout")`,
+          );
+        }
+        layoutMods.push(LayoutComp);
+      }
+      // Walk LEAF → ROOT (reverse iteration on the layouts array).
+      // The innermost layout wraps the page first; each outer layout
+      // wraps the result.
+      for (let i = layoutMods.length - 1; i >= 0; i--) {
+        tree = React.createElement(layoutMods[i], props, tree);
+      }
+    }
+    const element = tree;
     const stream: ReadableStream<Uint8Array> = await renderToReadableStream(
       element,
       {
@@ -157,20 +218,144 @@ export async function handleRenderRoute(
       headers: { "content-type": "text/html; charset=utf-8" },
     });
 
+    // Pre-load the manifest BEFORE the React stream starts emitting
+    // so we know which `<link rel="stylesheet">` and
+    // `<link rel="modulepreload">` tags to inject into the HEAD.
+    // We splice them in before `</head>` so the browser starts
+    // fetching CSS + chunks concurrently with parsing the body —
+    // no FOUC, no waterfall.
+    let preloadManifestRoute:
+      | { file: string; imports: string[]; css: string[] }
+      | null = null;
+    let preloadManifestErr: string | null = null;
+    let preloadPublicPrefix = "/_pylon/build/";
+    try {
+      const { getManifest } = await import("./ssr-client-bundler");
+      const manifest = await getManifest();
+      preloadPublicPrefix = manifest.public_prefix || preloadPublicPrefix;
+      preloadManifestRoute = manifest.routes[msg.component] ?? null;
+      if (!preloadManifestRoute) {
+        preloadManifestErr = `manifest has no entry for "${msg.component}"`;
+      }
+    } catch (e: any) {
+      preloadManifestErr = e?.message || String(e);
+    }
+
+    // Build the head-injection blob — stylesheet first, then
+    // modulepreloads. The entry script tag stays in the body-tail
+    // (it needs the inline __PYLON_DATA__ to have been parsed first).
+    let headBlob = "";
+    if (preloadManifestRoute) {
+      for (const css of preloadManifestRoute.css) {
+        headBlob += `<link rel="stylesheet" href="${preloadPublicPrefix}${css}">`;
+      }
+      for (const chunk of preloadManifestRoute.imports) {
+        headBlob += `<link rel="modulepreload" href="${preloadPublicPrefix}${chunk}">`;
+      }
+    }
+
+    // Stream-rewrite: watch for `</head>` and inject `headBlob`
+    // before it. `</head>` may straddle chunk boundaries so we
+    // keep a small carry buffer (7 bytes — len("</head>")) at the
+    // tail of each chunk.
     const reader = stream.getReader();
-    while (true) {
-      const { value, done } = await reader.read();
-      if (done) break;
-      if (!value || value.byteLength === 0) continue;
-      // base64 in pure JS via Buffer (Bun ships it). For large
-      // pages this is O(n) per chunk; fine for Phase 1.
-      const b64 = Buffer.from(value).toString("base64");
+    let headInjected = headBlob.length === 0;
+    let carry = ""; // utf8 tail from previous chunk for boundary detection
+    const HEAD_CLOSE = "</head>";
+    const sendChunk = (text: string) => {
+      if (!text) return;
       send({
         type: "render_chunk",
         call_id: msg.call_id,
-        data: b64,
+        data: Buffer.from(text, "utf8").toString("base64"),
       });
+    };
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      if (!value || value.byteLength === 0) continue;
+      let text = Buffer.from(value).toString("utf8");
+      if (!headInjected) {
+        const combined = carry + text;
+        const idx = combined.indexOf(HEAD_CLOSE);
+        if (idx >= 0) {
+          // Send everything up to the </head> position, then the
+          // headBlob, then </head>, then the remainder.
+          const before = combined.slice(0, idx);
+          const after = combined.slice(idx + HEAD_CLOSE.length);
+          // Drop the carry portion from `before` that we already
+          // emitted as part of the previous chunk's send. But since
+          // we DIDN'T emit `carry` previously (it was withheld), we
+          // can send the full `before` here.
+          sendChunk(before);
+          sendChunk(headBlob);
+          sendChunk(HEAD_CLOSE);
+          if (after) sendChunk(after);
+          headInjected = true;
+          carry = "";
+        } else {
+          // No </head> yet — emit everything except the last
+          // (HEAD_CLOSE.length - 1) bytes so a tag split across
+          // chunk boundaries still gets caught next pass.
+          const keep = HEAD_CLOSE.length - 1;
+          if (combined.length > keep) {
+            sendChunk(combined.slice(0, combined.length - keep));
+            carry = combined.slice(combined.length - keep);
+          } else {
+            carry = combined;
+          }
+        }
+      } else {
+        // base64 in pure JS via Buffer (Bun ships it). For large
+        // pages this is O(n) per chunk; fine for Phase 1.
+        sendChunk(text);
+      }
     }
+    // Flush any residual carry (head close never seen — page
+    // didn't have a </head>, which is fine for fragment renders).
+    if (carry) sendChunk(carry);
+
+    // Hydration tail. After React's stream EOFs we append the
+    // hydration markers so the browser can hydrate:
+    //   1. `__PYLON_DATA__` — JSON-typed script with the props the
+    //      page was rendered with. The per-route bundle reads this
+    //      to seed hydrateRoot.
+    //   2. `<link rel="modulepreload">` for every transitive shared
+    //      chunk (react, react-dom, client-runtime). These preload
+    //      tags fire as soon as the parser sees them; the browser
+    //      can start fetching while it's still parsing the body.
+    //   3. `<script type="module" src="<route-entry>.js">` — the
+    //      per-route entry. It imports the shared chunks, which
+    //      were already in the cache from step 2.
+    //
+    // Per-route entry + chunk paths come from
+    // `.pylon/client-build/manifest.json`, which the bundler writes
+    // and `getManifest` parses with mtime-keyed caching. Falls back
+    // to a no-hydration warning if the manifest can't be loaded
+    // (rare — usually means the bundler crashed).
+    const hydrationPayload = {
+      component: msg.component,
+      layouts: msg.layouts ?? [],
+      props,
+    };
+    const json = JSON.stringify(hydrationPayload).replaceAll("<", "\\u003c");
+
+    let tail = `<script id="__PYLON_DATA__" type="application/json">${json}</script>`;
+    if (preloadManifestRoute) {
+      // Per-route entry script comes last — it needs the inline
+      // `__PYLON_DATA__` above to have been parsed before it runs.
+      // CSS + modulepreload links were already injected into `<head>`
+      // above so they could start fetching as early as possible.
+      tail += `<script type="module" src="${preloadPublicPrefix}${preloadManifestRoute.file}"></script>`;
+    } else {
+      tail += `<script>console.warn(${JSON.stringify(`[pylon ssr] hydration disabled: ${preloadManifestErr}`)})</script>`;
+    }
+    send({
+      type: "render_chunk",
+      call_id: msg.call_id,
+      data: Buffer.from(tail, "utf8").toString("base64"),
+    });
+
     send({ type: "render_done", call_id: msg.call_id });
   } catch (err: any) {
     // Pre-first-chunk error → host returns 500.