npm - @pylonsync/functions - Versions diffs - 0.3.235 → 0.3.237 - Mend

@pylonsync/functions 0.3.235 → 0.3.237

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 (3) hide show

package/package.json CHANGED Viewed

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

package/src/index.ts CHANGED Viewed

@@ -25,7 +25,7 @@ export { slugifyName, availableSlug } from "./slugify";
 // SSR page response controller — pages/layouts receive `response` in
 // props (response.setStatus / redirect / notFound / setHeader / setCookie).
 // Type-only; the runtime instance is injected per-render by the SSR adapter.
-export type { SsrResponse, SsrCookieOptions } from "./ssr-runtime";
+export type { SsrResponse, SsrCookieOptions, SsrMetadata } from "./ssr-runtime";
 export type {
   QueryCtx,
   MutationCtx,

package/src/ssr-runtime.ts CHANGED Viewed

@@ -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;
 }
@@ -240,14 +253,331 @@ function finalizeHeaders(
  * has flushed) are uncatchable here — React's `onError` would have
  * to feed into a separate signal, deferred to Phase 1.5.
  */
+/**
+ * Page SEO metadata. A page exports `export const metadata = {...}`
+ * (static) or `export async function generateMetadata(props)` (dynamic,
+ * e.g. param-derived titles). Kept flat — no deep nesting beyond og/twitter.
+ *
+ * React 19 hoists the resulting <title>/<meta>/<link> into <head>. A page
+ * `title` overrides a layout's static `<title>` (both render; the browser
+ * uses the last, which is the page's). React does NOT dedupe arbitrary
+ * `<meta>`, so set `description`/OG in EITHER the layout OR page metadata,
+ * not both, to avoid duplicate tags.
+ */
+export interface SsrMetadata {
+  title?: string;
+  description?: string;
+  keywords?: string | string[];
+  canonical?: string;
+  robots?: string;
+  openGraph?: {
+    title?: string;
+    description?: string;
+    image?: string;
+    url?: string;
+    type?: string;
+  };
+  twitter?: {
+    card?: string;
+    title?: string;
+    description?: string;
+    image?: string;
+  };
+}
+/**
+ * Build a React fragment of <title>/<meta>/<link> from a page's metadata.
+ * React 19 auto-hoists these into <head> wherever they render, and the
+ * host's </head> splice preserves them. React escapes all text/attrs, so
+ * there's no manual XSS handling. Returns null when there's nothing to emit.
+ */
+function renderMetadata(React: any, m: SsrMetadata | undefined): any {
+  if (!m) return null;
+  const el = React.createElement;
+  const kids: any[] = [];
+  if (m.title != null) kids.push(el("title", { key: "t" }, m.title));
+  if (m.description != null) {
+    kids.push(el("meta", { key: "d", name: "description", content: m.description }));
+  }
+  const kw = Array.isArray(m.keywords) ? m.keywords.join(", ") : m.keywords;
+  if (kw) kids.push(el("meta", { key: "kw", name: "keywords", content: kw }));
+  if (m.robots) kids.push(el("meta", { key: "r", name: "robots", content: m.robots }));
+  if (m.canonical) {
+    kids.push(el("link", { key: "c", rel: "canonical", href: m.canonical }));
+  }
+  const og = m.openGraph;
+  if (og) {
+    if (og.title != null) kids.push(el("meta", { key: "ogt", property: "og:title", content: og.title }));
+    if (og.description != null) kids.push(el("meta", { key: "ogd", property: "og:description", content: og.description }));
+    if (og.image) kids.push(el("meta", { key: "ogi", property: "og:image", content: og.image }));
+    if (og.url) kids.push(el("meta", { key: "ogu", property: "og:url", content: og.url }));
+    if (og.type) kids.push(el("meta", { key: "ogy", property: "og:type", content: og.type }));
+  }
+  const tw = m.twitter;
+  if (tw) {
+    if (tw.card) kids.push(el("meta", { key: "twc", name: "twitter:card", content: tw.card }));
+    if (tw.title != null) kids.push(el("meta", { key: "twt", name: "twitter:title", content: tw.title }));
+    if (tw.description != null) kids.push(el("meta", { key: "twd", name: "twitter:description", content: tw.description }));
+    if (tw.image) kids.push(el("meta", { key: "twi", name: "twitter:image", content: tw.image }));
+  }
+  return kids.length > 0 ? el(React.Fragment, null, ...kids) : null;
+}
+const MODULE_EXTS = [".tsx", ".ts", ".jsx", ".js"];
+/** Import a project-relative module, trying each common extension. */
+async function importModule(cwd: string, relPath: string): Promise<any> {
+  const base = `${cwd}/${relPath}`;
+  let lastErr: unknown = null;
+  for (const ext of MODULE_EXTS) {
+    try {
+      return await import(`${base}${ext}`);
+    } catch (e) {
+      lastErr = e;
+    }
+  }
+  throw lastErr ?? new Error(`could not import module "${relPath}"`);
+}
+/**
+ * Wrap a leaf element in its layout chain (leaf → root). Resolves ALL
+ * layouts first so a missing one fails before any chunk is emitted. Reused
+ * by the page render and by the not-found / error boundary render.
+ */
+async function buildLayoutTree(
+  cwd: string,
+  leaf: any,
+  layouts: string[] | undefined,
+  props: any,
+  React: any,
+): Promise<any> {
+  if (!layouts || layouts.length === 0) return leaf;
+  const layoutComps: any[] = [];
+  for (const layoutPath of layouts) {
+    let lMod: any;
+    try {
+      lMod = await importModule(cwd, layoutPath);
+    } catch {
+      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")`,
+      );
+    }
+    layoutComps.push(LayoutComp);
+  }
+  let tree = leaf;
+  for (let i = layoutComps.length - 1; i >= 0; i--) {
+    tree = React.createElement(layoutComps[i], props, tree);
+  }
+  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;
+  }
+}
 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;
   try {
     // react + react-dom are USER deps. ssr-runtime.ts lives in
     // packages/functions/src/, but the user's react install is under
@@ -255,7 +585,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)
@@ -281,8 +610,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") {
@@ -291,23 +620,14 @@ export async function handleRenderRoute(
       );
     }
-    // Resolve the page module. The component string is project-
-    // relative without extension; try .tsx → .ts → .jsx → .js so
-    // any of the common page-file shapes work. cwd was captured
-    // above for the react resolver.
-    const baseName = `${cwd}/${msg.component}`;
-    let mod: any = null;
-    let lastErr: unknown = null;
-    for (const ext of [".tsx", ".ts", ".jsx", ".js"]) {
-      try {
-        mod = await import(`${baseName}${ext}`);
-        break;
-      } catch (e) {
-        lastErr = e;
-      }
-    }
-    if (!mod) {
-      throw lastErr ?? new Error(`could not import component "${msg.component}"`);
+    // Resolve the page module (project-relative, extension-agnostic).
+    let mod: any;
+    try {
+      mod = await importModule(cwd, msg.component);
+    } catch (e) {
+      throw e instanceof Error
+        ? e
+        : new Error(`could not import component "${msg.component}"`);
     }
     const Component = mod.default ?? mod.Page ?? mod.page;
     if (typeof Component !== "function") {
@@ -316,7 +636,7 @@ export async function handleRenderRoute(
       );
     }
-    const props = {
+    props = {
       url: msg.url,
       params: msg.params,
       searchParams: msg.search_params,
@@ -328,50 +648,32 @@ export async function handleRenderRoute(
       response,
     };
+    // SEO metadata: static `export const metadata` or dynamic
+    // `export async function generateMetadata(props)`. Awaited before the
+    // first byte, so keep it to cheap derivations (params → title); heavy
+    // data belongs in the page body behind <Suspense>.
+    let metadata: SsrMetadata | undefined = mod.metadata;
+    if (typeof mod.generateMetadata === "function") {
+      metadata = await mod.generateMetadata(props);
+    }
+    const metaFragment = renderMetadata(React, metadata);
     // 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);
-      }
-    }
+    // the page. The metadata fragment is the FIRST child so React hoists
+    // its <title>/<meta> into the <head> a layout renders.
+    let tree: any = metaFragment
+      ? React.createElement(
+          React.Fragment,
+          null,
+          metaFragment,
+          React.createElement(Component, props),
+        )
+      : React.createElement(Component, props);
+    tree = await buildLayoutTree(cwd, tree, msg.layouts, props, React);
     const element = tree;
     const stream: ReadableStream<Uint8Array> = await renderToReadableStream(
       element,
@@ -433,16 +735,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({
@@ -451,50 +762,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:
@@ -514,28 +782,30 @@ 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) {
+      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>`;
+      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) {
@@ -553,7 +823,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({
@@ -570,7 +859,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,