@pylonsync/functions 0.3.236 → 0.3.238

package/package.json

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

package/src/runtime.ts

@@ -329,7 +329,11 @@ function rpc(callId: string, msg: Record<string, unknown>): Promise<unknown> {
 // Context builders
 // ---------------------------------------------------------------------------
 
-function buildDbReader(callId: string, unsafeOp = false): DbReader {
+// Exported so the SSR runtime (ssr-runtime.ts) can build a page-facing
+// `serverData` read handle that reuses this module's `send` + `pendingRpcs`
+// + reader loop. The render call_id ("r_<n>") correlates DB replies back
+// through the shared pendingRpcs map.
+export function buildDbReader(callId: string, unsafeOp = false): DbReader {
   // All DB ops use rpcDb so Promise.all over ctx.db reads can run in
   // parallel without colliding on the outer call_id key.
   //

package/src/ssr-client-bundler.ts

@@ -192,6 +192,92 @@ function buildTree(Page, Layouts, props) {
   return tree;
 }
 
+// Deterministic stringify — MUST match stableStringify in ssr-runtime.ts so
+// a serverData call's cache key is identical on server and client.
+function stableStringify(v) {
+  if (v === null || v === undefined || typeof v !== "object") {
+    return JSON.stringify(v === undefined ? null : v);
+  }
+  if (Array.isArray(v)) return "[" + v.map(stableStringify).join(",") + "]";
+  const keys = Object.keys(v).sort();
+  return (
+    "{" +
+    keys.map((k) => JSON.stringify(k) + ":" + stableStringify(v[k])).join(",") +
+    "}"
+  );
+}
+
+const SERVER_DATA_METHODS = [
+  "get",
+  "list",
+  "lookup",
+  "query",
+  "queryGraph",
+  "paginate",
+  "search",
+];
+
+// A React-recognized fulfilled thenable: use() reads .value synchronously
+// (status === "fulfilled") instead of suspending. Critical for hydration —
+// the server streamed the post-Suspense content, so the client must render
+// that content on the FIRST pass without re-suspending (no fallback flash,
+// no mismatch).
+function fulfilledThenable(value) {
+  return {
+    status: "fulfilled",
+    value,
+    then(onFulfilled) {
+      return onFulfilled ? onFulfilled(value) : value;
+    },
+  };
+}
+
+// Client stand-in for the server's serverData handle. Each method returns a
+// pre-fulfilled thenable (cached per key) sourced from the SSR'd ssrData map,
+// keyed identically to the server. Misses yield undefined — the page
+// rendered with whatever the server fetched, so a hit is expected.
+function makeClientServerData(ssrData) {
+  const cache = ssrData || {};
+  const pc = new Map();
+  const wrap = (prefix) => {
+    const out = {};
+    for (const m of SERVER_DATA_METHODS) {
+      out[m] = (...args) => {
+        const key = prefix + m + ":" + stableStringify(args);
+        if (!pc.has(key)) pc.set(key, fulfilledThenable(cache[key]));
+        return pc.get(key);
+      };
+    }
+    return out;
+  };
+  const sd = wrap("");
+  sd.unsafe = wrap("u:");
+  return sd;
+}
+
+// Server-only response controller has no meaning on the client (the status/
+// redirect/cookies already shipped). Give pages a no-op so a body that
+// touches props.response during hydration doesn't crash.
+function makeNoopResponse() {
+  const noop = () => {};
+  return {
+    setStatus: noop,
+    setHeader: noop,
+    setCookie: noop,
+    redirect: noop,
+    notFound: noop,
+  };
+}
+
+// Rehydrate the live, server-only props (serverData + response) that were
+// stripped before serialization, so the client tree matches the server's.
+function withClientProps(data) {
+  const props = { ...(data.props || {}) };
+  props.serverData = makeClientServerData(data.ssrData);
+  props.response = makeNoopResponse();
+  return props;
+}
+
 function readPylonData() {
   const dataEl = document.getElementById("__PYLON_DATA__");
   if (!dataEl) return null;
@@ -286,7 +372,7 @@ export function hydrate(component, Page, Layouts) {
       );
       return;
     }
-    const tree = buildTree(Page, Layouts, data.props);
+    const tree = buildTree(Page, Layouts, withClientProps(data));
     activeRoot = hydrateRoot(document, tree);
     installNavHandlers();
     return;
@@ -340,7 +426,7 @@ async function navigate(href, opts) {
     return;
   }
   document.title = doc.title || document.title;
-  const tree = buildTree(route.Page, route.Layouts, data.props);
+  const tree = buildTree(route.Page, route.Layouts, withClientProps(data));
   activeRoot.render(tree);
   if (push) {
     history.pushState({ component: data.component }, "", url.pathname + url.search);

package/src/ssr-runtime.ts

@@ -55,6 +55,14 @@ export interface RenderRouteMessage {
     tenant_id: string | null;
     roles: string[];
   };
+  /**
+   * Initial HTTP status the response controller starts at (default 200).
+   * The host sets this to 404 when dispatching a `not-found.tsx` render
+   * for an unmatched URL, so the boundary streams at 404 without the
+   * component having to call `response.setStatus`. A page can still
+   * override it via `response.setStatus`.
+   */
+  initial_status?: number;
 }
 
 type Send = (msg: Record<string, unknown>) => void;
@@ -167,7 +175,12 @@ export interface SsrResponse {
   setCookie(name: string, value: string, opts?: SsrCookieOptions): void;
   /** Throw to send a 3xx (default 307) + Location, no body. Shell-render only. */
   redirect(url: string, status?: number): never;
-  /** Throw to send a 404. Currently a fixed framework body (not-found.tsx not yet honored). Shell-render only. */
+  /**
+   * Throw to send a 404. Renders the nearest `not-found.tsx` (walking up
+   * from the page's directory, wrapped in the route's layout chain), or a
+   * minimal framework body if none is defined. Shell-render only — a throw
+   * below a Suspense boundary is swallowed by React.
+   */
   notFound(): never;
 }
 
@@ -364,14 +377,278 @@ async function buildLayoutTree(
   return tree;
 }
 
+/**
+ * Walk up from a page's directory to the nearest boundary file
+ * (not-found / error) — the same render-time, filesystem-resolved model
+ * the page + layouts already use, so no build-time manifest threading.
+ * Returns the project-relative path (no extension) or null.
+ */
+function findBoundary(componentPath: string, fileName: string): string | null {
+  const fs = require("node:fs");
+  const path = require("node:path");
+  const cwd = process.cwd();
+  // Component paths use "/" — walk up directory by directory.
+  let dir = componentPath.replace(/\\/g, "/");
+  dir = dir.includes("/") ? dir.slice(0, dir.lastIndexOf("/")) : "";
+  while (dir && dir !== "." && dir !== "/") {
+    for (const ext of MODULE_EXTS) {
+      if (fs.existsSync(path.join(cwd, dir, `${fileName}${ext}`))) {
+        return `${dir}/${fileName}`;
+      }
+    }
+    const slash = dir.lastIndexOf("/");
+    dir = slash >= 0 ? dir.slice(0, slash) : "";
+  }
+  return null;
+}
+
+/**
+ * Drain a `renderToReadableStream` reader, injecting `headBlob` immediately
+ * before the first `</head>` (or, if the document has none, the blob is
+ * never emitted — fragment renders have no head). `</head>` can straddle a
+ * chunk boundary, so a small carry buffer (len("</head>") − 1 bytes) is
+ * withheld at each chunk's tail until the next read confirms the match.
+ * Each emitted slice is handed to `sendChunk` as utf-8 text.
+ *
+ * Shared by the page render and the boundary render so head injection has
+ * exactly one implementation.
+ */
+async function streamWithHeadInjection(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  headBlob: string,
+  sendChunk: (text: string) => void,
+): Promise<void> {
+  let headInjected = headBlob.length === 0;
+  let carry = "";
+  const HEAD_CLOSE = "</head>";
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    if (!value || value.byteLength === 0) continue;
+    const text = Buffer.from(value).toString("utf8");
+    if (!headInjected) {
+      const combined = carry + text;
+      const idx = combined.indexOf(HEAD_CLOSE);
+      if (idx >= 0) {
+        sendChunk(combined.slice(0, idx));
+        sendChunk(headBlob);
+        sendChunk(HEAD_CLOSE);
+        const after = combined.slice(idx + HEAD_CLOSE.length);
+        if (after) sendChunk(after);
+        headInjected = true;
+        carry = "";
+      } else {
+        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 {
+      sendChunk(text);
+    }
+  }
+  if (carry) sendChunk(carry);
+}
+
+/**
+ * Build the <head> blob for a boundary render: the union of every route's
+ * stylesheet links from the client build manifest. Boundary modules aren't
+ * bundled as their own client entry, but they render inside the same
+ * layout/shell as pages, so without the app's global CSS a 404/500 page
+ * would look broken. Returns "" if the manifest can't be loaded — the
+ * boundary still renders (unstyled); CSS must never block the error path.
+ */
+async function collectBoundaryHeadBlob(): Promise<string> {
+  try {
+    const { getManifest } = await import("./ssr-client-bundler");
+    const manifest = await getManifest();
+    const prefix = manifest.public_prefix || "/_pylon/build/";
+    const seen = new Set<string>();
+    let blob = "";
+    for (const route of Object.values(manifest.routes || {}) as any[]) {
+      for (const css of (route.css || []) as string[]) {
+        if (seen.has(css)) continue;
+        seen.add(css);
+        blob += `<link rel="stylesheet" href="${prefix}${css}">`;
+      }
+    }
+    return blob;
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Render a boundary (not-found/error) tree and stream it as the response
+ * body at `status`. Boundaries render server-side only (no hydration
+ * payload) — they're informational pages, consistent with the keystone's
+ * fixed 404 body that this replaces — but they DO get the app's global
+ * stylesheet injected so they match the rest of the site.
+ */
+async function renderBoundaryToClient(
+  React: any,
+  renderToReadableStream: any,
+  tree: any,
+  send: Send,
+  callId: string,
+  status: number,
+  headers: Record<string, string>,
+): Promise<void> {
+  const stream: ReadableStream<Uint8Array> = await renderToReadableStream(tree, {
+    onError(e: unknown) {
+      // eslint-disable-next-line no-console
+      console.error("[ssr] boundary render error:", e);
+    },
+  });
+  const headBlob = await collectBoundaryHeadBlob();
+  // renderToReadableStream resolved without throwing → safe to commit the
+  // head now, then drain the (already-rendered) shell, injecting CSS.
+  send({ type: "response_start", call_id: callId, status, headers });
+  const sendChunk = (text: string) => {
+    if (!text) return;
+    send({
+      type: "render_chunk",
+      call_id: callId,
+      data: Buffer.from(text, "utf8").toString("base64"),
+    });
+  };
+  await streamWithHeadInjection(stream.getReader(), headBlob, sendChunk);
+  send({ type: "render_done", call_id: callId });
+}
+
+/**
+ * Resolve + render a boundary component wrapped in the route's layout
+ * chain. Returns true if it rendered (caller returns), false to fall back.
+ */
+async function tryRenderBoundary(
+  opts: {
+    React: any;
+    renderToReadableStream: any;
+    cwd: string;
+    componentPath: string;
+    fileName: "not-found" | "error";
+    layouts: string[] | undefined;
+    props: any;
+    send: Send;
+    callId: string;
+    status: number;
+    headers: Record<string, string>;
+  },
+): Promise<boolean> {
+  const { React, renderToReadableStream, cwd, componentPath, fileName, layouts, props, send, callId, status, headers } =
+    opts;
+  if (!React || !renderToReadableStream || !props) return false;
+  const rel = findBoundary(componentPath, fileName);
+  if (!rel) return false;
+  try {
+    const mod = await importModule(cwd, rel);
+    const Comp = mod.default ?? mod.Component ?? mod.NotFound ?? mod.Error;
+    if (typeof Comp !== "function") return false;
+    let tree = React.createElement(Comp, props);
+    tree = await buildLayoutTree(cwd, tree, layouts, props, React);
+    await renderBoundaryToClient(React, renderToReadableStream, tree, send, callId, status, headers);
+    return true;
+  } catch (e) {
+    // Boundary render itself failed — no tertiary fallback; let the caller
+    // emit its default (fixed 404 body / type:"error" → 500).
+    // eslint-disable-next-line no-console
+    console.error(`[ssr] ${fileName}.tsx boundary failed to render:`, e);
+    return false;
+  }
+}
+
+/**
+ * Deterministic stringify (keys sorted recursively) so a `serverData` call's
+ * cache key is identical on the server (here) and on the client (the
+ * hydration shim in ssr-client-bundler's client-runtime). MUST stay in sync
+ * with `stableStringify` in that template.
+ */
+function stableStringify(v: any): string {
+  if (v === null || v === undefined || typeof v !== "object") {
+    return JSON.stringify(v ?? null);
+  }
+  if (Array.isArray(v)) return "[" + v.map(stableStringify).join(",") + "]";
+  const keys = Object.keys(v).sort();
+  return (
+    "{" +
+    keys.map((k) => JSON.stringify(k) + ":" + stableStringify(v[k])).join(",") +
+    "}"
+  );
+}
+
+// The read methods a page reaches through `serverData`. Mirrors the
+// DbReader read surface (writes are blocked server-side). Kept in sync with
+// the client-runtime shim's method list.
+const SERVER_DATA_METHODS = [
+  "get",
+  "list",
+  "lookup",
+  "query",
+  "queryGraph",
+  "paginate",
+  "search",
+] as const;
+
+/**
+ * Wrap a DbReader so each `serverData.x(...)` call returns a PROMISE CACHED
+ * by (method, args) — required for React 19 `use()`, which re-invokes the
+ * call on the post-suspense re-render and must get the same (now-resolved)
+ * promise instead of a fresh pending one (else it suspends forever). Each
+ * resolved value is also recorded into `valueCache` keyed identically, so it
+ * can be serialized into `__PYLON_DATA__.ssrData` and replayed on the client
+ * — keeping hydration free of mismatches.
+ */
+function makeServerData(reader: any, valueCache: Record<string, any>): any {
+  const promiseCache = new Map<string, Promise<any>>();
+  const wrap = (r: any, prefix: string): any => {
+    const out: any = {};
+    for (const m of SERVER_DATA_METHODS) {
+      out[m] = (...args: any[]) => {
+        const key = prefix + m + ":" + stableStringify(args);
+        let p = promiseCache.get(key);
+        if (!p) {
+          p = Promise.resolve(r[m](...args)).then((value: any) => {
+            valueCache[key] = value;
+            return value;
+          });
+          promiseCache.set(key, p);
+        }
+        return p;
+      };
+    }
+    return out;
+  };
+  const sd = wrap(reader, "");
+  if (reader.unsafe) sd.unsafe = wrap(reader.unsafe, "u:");
+  return sd;
+}
+
 export async function handleRenderRoute(
   msg: RenderRouteMessage,
   send: Send,
 ): Promise<void> {
   // Declared OUTSIDE the try so the catch can read page-set status/
   // cookies when turning a redirect()/notFound() throw into a response.
-  const responseState: ResponseState = { status: 200, headers: {}, cookies: [] };
+  const responseState: ResponseState = {
+    status: msg.initial_status ?? 200,
+    headers: {},
+    cookies: [],
+  };
   const response = makeResponseController(responseState);
+  // Hoisted out of the try so the catch can render not-found.tsx /
+  // error.tsx boundaries (which need React + the renderer + cwd + props).
+  const cwd = process.cwd();
+  let React: any = null;
+  let renderToReadableStream: any = null;
+  let props: any = null;
+  // Accumulates the resolved results of every `serverData.*` read the page
+  // made during render, keyed identically to the client shim. Serialized
+  // into `__PYLON_DATA__.ssrData` so hydration replays the same values
+  // without a second round trip — and without a server/client mismatch.
+  const ssrValueCache: Record<string, any> = {};
   try {
     // react + react-dom are USER deps. ssr-runtime.ts lives in
     // packages/functions/src/, but the user's react install is under
@@ -379,7 +656,6 @@ export async function handleRenderRoute(
     // would resolve against pylon's own node_modules (which doesn't
     // declare react), so we route through a Bun-resolveSync against
     // the user's cwd.
-    const cwd = process.cwd();
     const resolveFromUser = (spec: string): string =>
       (Bun as any).resolveSync
         ? (Bun as any).resolveSync(spec, cwd)
@@ -405,8 +681,8 @@ export async function handleRenderRoute(
     const reactImport = await import(
       /* @vite-ignore */ resolveFromUser("react")
     );
-    const React = reactImport.default ?? reactImport;
-    const renderToReadableStream =
+    React = reactImport.default ?? reactImport;
+    renderToReadableStream =
       reactDomServerImport.renderToReadableStream ??
       reactDomServerImport.default?.renderToReadableStream;
     if (typeof renderToReadableStream !== "function") {
@@ -431,7 +707,20 @@ export async function handleRenderRoute(
       );
     }
 
-    const props = {
+    // `serverData` — a read-only DB handle the page reaches during render
+    // via React 19 `use()` + <Suspense>. Reuses runtime.ts's RPC pipe
+    // (shared `send` + pendingRpcs) keyed by this render's call_id; the
+    // Rust render loop answers the frames against the same store + policy
+    // gate as a query function's ctx.db, and rejects any write. Promise-
+    // cached so `use()` doesn't re-suspend forever; resolved values land in
+    // `ssrValueCache` for hydration replay.
+    const { buildDbReader } = await import("./runtime");
+    const serverData = makeServerData(
+      buildDbReader(msg.call_id),
+      ssrValueCache,
+    );
+
+    props = {
       url: msg.url,
       params: msg.params,
       searchParams: msg.search_params,
@@ -441,6 +730,8 @@ export async function handleRenderRoute(
       // Response controller — a page/layout calls response.setStatus /
       // setHeader / setCookie / redirect / notFound to shape the reply.
       response,
+      // Read-only server data handle (see above).
+      serverData,
     };
 
     // SEO metadata: static `export const metadata` or dynamic
@@ -484,6 +775,19 @@ export async function handleRenderRoute(
       },
     );
 
+    // Wait for ALL Suspense boundaries to resolve before emitting the body,
+    // so the HTML is fully formed — no `<!--$?-->` pending markers, no
+    // hidden fallback segments, no `$RC` reveal scripts. This is what makes
+    // `serverData` + `use()` + <Suspense> hydrate cleanly: the client
+    // hydrates a RESOLVED boundary against the SSR'd content (resolved from
+    // `ssrData`), instead of fighting React's streaming-reveal scripts +
+    // whole-document hydration (which leaves the boundary stuck on its
+    // fallback). Pages with no async data have no boundaries, so `allReady`
+    // resolves immediately — zero cost for the common case.
+    if ((stream as any).allReady) {
+      await (stream as any).allReady;
+    }
+
     // Headers go out before the first chunk so the host can write the
     // response head.
     // The shell rendered without a redirect()/notFound() throw, so the
@@ -530,16 +834,25 @@ export async function handleRenderRoute(
       for (const chunk of preloadManifestRoute.imports) {
         headBlob += `<link rel="modulepreload" href="${preloadPublicPrefix}${chunk}">`;
       }
+    } else {
+      // No per-route client entry. This is the unmatched-URL not-found
+      // dispatch (the host renders `app/not-found` by name at 404) or any
+      // other component without a hydration bundle. It still renders inside
+      // the app shell, so inject the global stylesheet(s) — otherwise the
+      // 404 page is unstyled. Hydration stays disabled (handled below).
+      headBlob += await collectBoundaryHeadBlob();
     }
 
-    // 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();
-    let headInjected = headBlob.length === 0;
-    let carry = ""; // utf8 tail from previous chunk for boundary detection
-    const HEAD_CLOSE = "</head>";
+    // The host can dispatch a boundary module (`app/not-found` / `app/error`)
+    // by name for an unmatched-URL 404. Boundaries render server-only — no
+    // hydration payload, and no "hydration disabled" warning (that warning is
+    // for a real page whose client bundle is missing).
+    const isBoundaryComponent = /(^|\/)(not-found|error)$/.test(msg.component);
+
+    // Stream-rewrite: watch for `</head>` and inject `headBlob` before it.
+    // `</head>` may straddle chunk boundaries; the shared helper keeps a
+    // small carry buffer to catch a split tag. base64 of each utf-8 slice
+    // happens in `sendChunk` (Buffer ships with Bun).
     const sendChunk = (text: string) => {
       if (!text) return;
       send({
@@ -548,50 +861,7 @@ export async function handleRenderRoute(
         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);
+    await streamWithHeadInjection(stream.getReader(), headBlob, sendChunk);
 
     // Hydration tail. After React's stream EOFs we append the
     // hydration markers so the browser can hydrate:
@@ -611,28 +881,36 @@ export async function handleRenderRoute(
     // 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");
+    if (!isBoundaryComponent) {
+      // Strip live, non-serializable handles from the props that seed
+      // hydration: `serverData` (an RPC handle — the client rebuilds its
+      // own from `ssrData`) and `response` (a server-only controller — the
+      // client gets a no-op). Their resolved data rides along in `ssrData`.
+      const { serverData: _sd, response: _resp, ...serializableProps } = props;
+      const hydrationPayload = {
+        component: msg.component,
+        layouts: msg.layouts ?? [],
+        props: serializableProps,
+        ssrData: ssrValueCache,
+      };
+      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>`;
+      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_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) {
@@ -650,7 +928,26 @@ export async function handleRenderRoute(
         send({ type: "render_done", call_id: msg.call_id });
         return;
       }
-      // notFound() → 404 with a minimal body (until not-found.tsx wiring).
+      // notFound() → look for the nearest not-found.tsx walking up from the
+      // page's directory; render it (wrapped in the route's layouts) at 404.
+      // Falls back to a minimal framework body if none is defined.
+      if (
+        await tryRenderBoundary({
+          React,
+          renderToReadableStream,
+          cwd,
+          componentPath: msg.component,
+          fileName: "not-found",
+          layouts: msg.layouts,
+          props,
+          send,
+          callId: msg.call_id,
+          status: 404,
+          headers: finalizeHeaders(responseState),
+        })
+      ) {
+        return;
+      }
       const body404 =
         '<!DOCTYPE html><html><head><meta charset="utf-8"><title>404 — Not Found</title></head><body><h1>404</h1><p>This page could not be found.</p></body></html>';
       send({
@@ -667,7 +964,27 @@ export async function handleRenderRoute(
       send({ type: "render_done", call_id: msg.call_id });
       return;
     }
-    // Real pre-first-chunk error → host returns 500.
+    // Real pre-first-chunk error → look for the nearest error.tsx walking up
+    // from the page's directory; render it (wrapped in the route's layouts)
+    // at 500 with the thrown error passed in props. Falls back to a host-level
+    // 500 (type:"error") if none is defined or the boundary itself throws.
+    if (
+      await tryRenderBoundary({
+        React,
+        renderToReadableStream,
+        cwd,
+        componentPath: msg.component,
+        fileName: "error",
+        layouts: msg.layouts,
+        props: props ? { ...props, error: err } : null,
+        send,
+        callId: msg.call_id,
+        status: 500,
+        headers: finalizeHeaders(responseState),
+      })
+    ) {
+      return;
+    }
     send({
       type: "error",
       call_id: msg.call_id,