@pylonsync/functions 0.11.5 → 0.12.0

package/src/ssr-client-bundler.ts

@@ -34,6 +34,14 @@
 //   - CSS chunking. No CSS support in SSR yet.
 
 import { buildFonts, readManifestFonts, type ManifestFonts } from "./ssr-fonts";
+import {
+  applyClientCompat,
+  resolveClientCompat,
+  transformCss,
+  type ClientCompat,
+  type ManifestBuildConfig,
+} from "./build-compat";
+import { serverBundle } from "./server-bundle";
 
 type Send = (msg: Record<string, unknown>) => void;
 
@@ -88,7 +96,7 @@ declare const Bun: {
     target?: "browser" | "bun" | "node";
     format?: "esm" | "iife";
     minify?: boolean;
-    sourcemap?: "none" | "inline" | "external";
+    sourcemap?: "none" | "inline" | "external" | "linked";
     define?: Record<string, string>;
     external?: string[];
     splitting?: boolean;
@@ -141,6 +149,20 @@ export function assertNotServerOnly(specifier: string, importer: string): void {
   }
 }
 
+/**
+ * A module file → its project-relative, extension-less component path
+ * (`<cwd>/app/blog/page.tsx` → `app/blog/page`). Always "/"-separated, on
+ * Windows too: the result is a manifest key, the input to the SSR boundary
+ * walk, and is spliced into generated `import` specifiers, where a backslash
+ * is a string escape (`"../app\page"` resolves `../apppage`).
+ */
+export function componentPathFor(path: any, cwd: string, file: string): string {
+  return path
+    .relative(cwd, file)
+    .replace(/\.(tsx?|jsx?)$/, "")
+    .replace(/\\/g, "/");
+}
+
 /**
  * Synchronously walk the route dir (`<appDirRel>` under cwd, e.g.
  * `app` or `web/app`) and return one entry per discovered page, each
@@ -182,7 +204,7 @@ function discoverRoutes(
       .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, componentPathFor(path, cwd, layoutHere)]
       : layouts;
     const pageHere = ["page.tsx", "page.ts", "page.jsx", "page.js"]
       .map((n: string) => path.join(dir, n))
@@ -190,7 +212,7 @@ function discoverRoutes(
     if (pageHere) {
       pages.push({
         segments: [...segments],
-        component: path.relative(cwd, pageHere).replace(/\.(tsx?|jsx?)$/, ""),
+        component: componentPathFor(path, cwd, pageHere),
         layouts: nextLayouts,
         // e.g. [] → "/", ["p","[slug]"] → "/p/[slug]".
         pattern: "/" + segments.join("/"),
@@ -207,7 +229,7 @@ function discoverRoutes(
       if (bHere) {
         pages.push({
           segments: [...segments],
-          component: path.relative(cwd, bHere).replace(/\.(tsx?|jsx?)$/, ""),
+          component: componentPathFor(path, cwd, bHere),
           layouts: nextLayouts,
         });
       }
@@ -255,9 +277,7 @@ export function discoverLoadingModules(
       .map((n: string) => path.join(dir, n))
       .find((p: string) => fs.existsSync(p));
     if (here) {
-      found.push(
-        path.relative(cwd, here).replace(/\.(tsx?|jsx?)$/, "").replace(/\\/g, "/"),
-      );
+      found.push(componentPathFor(path, cwd, here));
     }
     for (const e of entries) {
       if (!e.isDirectory()) continue;
@@ -1137,8 +1157,12 @@ function slugForComponent(component: string): string {
 export interface PylonBundleManifest {
   /** Build identity — bumps every successful build. */
   build_id: string;
-  /** Output root, relative to cwd (always `.pylon/client-build`). */
+  /** Output root, relative to cwd: `.pylon/client-build`, or `client` in a
+   *  `pylon build` artifact. */
   outdir: string;
+  /** core-js polyfill bundle (relative to outdir), loaded before any route
+   *  entry. Present when `build.polyfill` is set and the targets need one. */
+  polyfills?: string;
   /** Public URL prefix the Rust host serves chunks under. */
   public_prefix: string;
   /** routeComponentPath → file + imports for that route. */
@@ -1196,7 +1220,7 @@ async function _prebuiltBundle(): Promise<BuildOutput | null> {
   const pathMod: any = await import("node:path");
   const fs = fsMod.default ?? fsMod;
   const path = pathMod.default ?? pathMod;
-  const outdir = path.join(process.cwd(), ".pylon", "client-build");
+  const outdir = path.join(process.cwd(), clientBuildDir());
   const manifestPath = path.join(outdir, "manifest.json");
   if (!fs.existsSync(manifestPath)) return null;
 
@@ -1257,6 +1281,48 @@ export async function buildClientBundle(
   return _inflightBuild;
 }
 
+/** Default client bundle directory, relative to the project root. */
+export const CLIENT_BUILD_DIR = ".pylon/client-build";
+
+/** The client bundle directory, relative to cwd. A production server bundle
+ *  names its own; source mode uses `CLIENT_BUILD_DIR`. */
+export function clientBuildDir(): string {
+  return serverBundle()?.clientDir ?? CLIENT_BUILD_DIR;
+}
+
+export interface ClientBuildOptions {
+  /** Absolute output directory. Default: `<cwd>/.pylon/client-build`. */
+  outdir?: string;
+  /** The manifest's `outdir` value. Default: `outdir` relative to cwd. A
+   *  `pylon build` artifact sets `client`, its path at run time. */
+  manifestOutdir?: string;
+  /** The `build` block to apply. Default: read from `pylon.manifest.json`,
+   *  except in dev (`NODE_ENV=development`), which applies none. `null`
+   *  applies none. */
+  buildConfig?: ManifestBuildConfig | null;
+  /** Fail on a CSS or font build error instead of shipping without it. */
+  strict?: boolean;
+  /** The app manifest (fonts, build settings). Default
+   *  `<cwd>/pylon.manifest.json`. */
+  manifestPath?: string;
+}
+
+/** The `build` block of `<cwd>/pylon.manifest.json`, if any. */
+export function readManifestBuildConfig(
+  fs: any,
+  path: any,
+  cwd: string,
+): ManifestBuildConfig | undefined {
+  const manifestPath = path.join(cwd, "pylon.manifest.json");
+  if (!fs.existsSync(manifestPath)) return undefined;
+  try {
+    const m = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    return m && typeof m.build === "object" && m.build !== null ? m.build : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 async function _doBuild(appDirRel: string): Promise<BuildOutput> {
   // node:* are available in Bun, but `globalThis.require` is
   // not defined in ESM. Use dynamic import; Bun fast-paths these.
@@ -1288,6 +1354,7 @@ export async function buildTailwind(
   cwd: string,
   outdir: string,
   appDirRel: string,
+  cssTargets?: string[],
 ): Promise<string | null> {
   const globalsPath = path.join(cwd, appDirRel, "globals.css");
   if (!fs.existsSync(globalsPath)) return null;
@@ -1348,7 +1415,13 @@ export async function buildTailwind(
     throw new Error(`tailwindcss build failed (exit ${exitCode}): ${err}`);
   }
 
-  const out = fs.readFileSync(tmpPath, "utf8");
+  let out = fs.readFileSync(tmpPath, "utf8");
+  if (cssTargets && cssTargets.length > 0) {
+    // Hash the TRANSFORMED output (below), so a CSS target change changes
+    // the file name.
+    out = await transformCss(cwd, out, "globals.css", cssTargets);
+    fs.writeFileSync(tmpPath, out, "utf8");
+  }
   let hash = 0;
   for (let i = 0; i < out.length; i++) {
     hash = (hash * 31 + out.charCodeAt(i)) >>> 0;
@@ -1381,12 +1454,27 @@ export async function buildTailwind(
   return stylesName;
 }
 
-async function _doBuildInner(
+// Exported for the Windows-separator regression test (ssr-client-bundler.test.ts),
+// which injects a `path` whose `relative` returns "\"-separated paths.
+export async function _doBuildInner(
   fs: any,
   path: any,
   cwd: string,
   appDirRel: string,
+  opts: ClientBuildOptions = {},
 ): Promise<BuildOutput> {
+  // Production settings from the manifest's `build` block. Dev builds skip
+  // them: lowering and polyfills cost build time and change nothing a modern
+  // dev browser needs.
+  const buildConfig =
+    opts.buildConfig !== undefined
+      ? opts.buildConfig
+      : process.env.NODE_ENV === "development"
+        ? undefined
+        : readManifestBuildConfig(fs, path, cwd);
+  const compat = resolveClientCompat(buildConfig ?? undefined);
+  const manifestFile = opts.manifestPath ?? path.join(cwd, "pylon.manifest.json");
+  const sourcemap = buildConfig?.sourcemap === true;
   const routes = discoverRoutes(fs, path, cwd, appDirRel);
     if (routes.length === 0) {
       throw new Error(
@@ -1409,7 +1497,7 @@ async function _doBuildInner(
         }
       }
     }
-    const outdir = path.join(stageDir, "client-build");
+    const outdir = opts.outdir ?? path.join(cwd, CLIENT_BUILD_DIR);
     try {
       fs.rmSync(outdir, { recursive: true, force: true });
     } catch {
@@ -1508,7 +1596,7 @@ async function _doBuildInner(
       target: "browser",
       format: "esm",
       minify: true,
-      sourcemap: "none",
+      sourcemap: sourcemap ? "linked" : "none",
       splitting: true,
       // The browser has no `process`. React, next-themes, sonner, and most
       // npm UI deps reference `process.env.NODE_ENV` (and migrated Next code
@@ -1557,7 +1645,38 @@ async function _doBuildInner(
     //   - chunks (kind === "chunk") — looked up by basename when
     //     scanning entry files for static `import "./chunks/..."`
     //     specifiers.
-    const outdirRel = path.relative(cwd, outdir);
+    // Manifest paths are URL paths under `public_prefix` ("/"-separated). The
+    // runtime's /_pylon/build/ handler rejects any request with a backslash.
+    const toUrlPath = (p: string) => p.replace(/\\/g, "/");
+    const outdirRel =
+      opts.manifestOutdir ?? toUrlPath(path.relative(cwd, outdir));
+
+    // Browser compatibility pass (build.target): lowers syntax, collects
+    // polyfills, and renames the .js outputs. Later steps read the renamed
+    // paths.
+    let outputs: Array<{ path: string; kind: string }> = result.outputs.map(
+      (o) => ({ path: o.path, kind: o.kind }),
+    );
+    let polyfills: string | undefined;
+    if (compat && compat.jsTargets.length > 0) {
+      const jsFiles = outputs
+        .filter((o) => o.path.endsWith(".js"))
+        .map((o) => toUrlPath(path.relative(outdir, o.path)));
+      const res = await applyClientCompat({ fs, path, cwd, outdir, jsFiles, compat });
+      if (res.unsupported.length > 0) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[pylon build] build.target includes browsers that cannot run the Pylon client runtime ` +
+            `(it needs ES modules and dynamic import()): ${res.unsupported.join(", ")}`,
+        );
+      }
+      outputs = outputs.map((o) => {
+        const rel = toUrlPath(path.relative(outdir, o.path));
+        const next = res.renamed.get(rel);
+        return next ? { ...o, path: path.join(outdir, next) } : o;
+      });
+      polyfills = res.polyfills;
+    }
     const entriesByStem = new Map<
       string,
       { absPath: string; relPath: string }
@@ -1566,9 +1685,9 @@ async function _doBuildInner(
       string,
       { absPath: string; relPath: string }
     >();
-    for (const o of result.outputs) {
+    for (const o of outputs) {
       const absPath: string = o.path;
-      const relPath = path.relative(outdir, absPath);
+      const relPath = toUrlPath(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
@@ -1591,7 +1710,7 @@ async function _doBuildInner(
     // the binary next to the entries AND into chunks/ so the runtime URL
     // resolves from either an entry or a split chunk.
     try {
-      const referencesLoroWasm = result.outputs.some((o) => {
+      const referencesLoroWasm = outputs.some((o) => {
         if (!o.path.endsWith(".js")) return false;
         try {
           return fs.readFileSync(o.path, "utf8").includes("loro_wasm_bg.wasm");
@@ -1665,6 +1784,7 @@ async function _doBuildInner(
       outdir: outdirRel,
       public_prefix: "/_pylon/build/",
       routes: {},
+      ...(polyfills ? { polyfills } : {}),
     };
     for (const r of routes) {
       const slug = slugForComponent(r.component);
@@ -1718,7 +1838,7 @@ async function _doBuildInner(
     // pylon.manifest.json from cwd. It's generated output — commonly
     // gitignored — so when it's absent the bundle still builds but
     // silently loses those features. Say so, loudly, instead.
-    if (!fs.existsSync(path.join(cwd, "pylon.manifest.json"))) {
+    if (!fs.existsSync(manifestFile)) {
       // eslint-disable-next-line no-console
       console.warn(
         "[pylon ssr] pylon.manifest.json not found — building the client " +
@@ -1733,7 +1853,14 @@ async function _doBuildInner(
     // array so SSR head injection emits `<link rel="stylesheet">`.
     let stylesRel: string | null = null;
     try {
-      const styles = await buildTailwind(fs, path, cwd, outdir, appDirRel);
+      const styles = await buildTailwind(
+        fs,
+        path,
+        cwd,
+        outdir,
+        appDirRel,
+        compat?.cssTargets,
+      );
       if (styles) {
         stylesRel = styles;
         for (const r of Object.values(manifest.routes)) {
@@ -1752,6 +1879,7 @@ async function _doBuildInner(
         /\u001b\[[0-9;]*m/g,
         "",
       );
+      if (opts.strict) throw new Error(`CSS build failed: ${cssMsg}`);
       manifest.css_error = cssMsg;
       // eslint-disable-next-line no-console
       console.warn(`[pylon ssr] tailwind compile failed: ${cssMsg}`);
@@ -1765,12 +1893,13 @@ async function _doBuildInner(
     // the prebuilt artifact. A fetch/parse failure degrades to a variable-only
     // entry — it never kills the build.
     try {
-      const declaredFonts = readManifestFonts(fs, path, cwd);
+      const declaredFonts = readManifestFonts(fs, path, cwd, manifestFile);
       if (declaredFonts.length > 0) {
         const builtFonts = await buildFonts(fs, path, cwd, outdir, declaredFonts);
         if (builtFonts) manifest.fonts = builtFonts;
       }
     } catch (fErr: any) {
+      if (opts.strict) throw new Error(`font build failed: ${fErr?.message ?? fErr}`);
       // eslint-disable-next-line no-console
       console.warn(`[pylon ssr] font build failed: ${fErr?.message ?? fErr}`);
     }
@@ -1846,7 +1975,7 @@ export async function getManifest(): Promise<PylonBundleManifest> {
   const fs = fsMod.default ?? fsMod;
   const path = pathMod.default ?? pathMod;
   const cwd = process.cwd();
-  const manifestPath = path.join(cwd, ".pylon", "client-build", "manifest.json");
+  const manifestPath = path.join(cwd, clientBuildDir(), "manifest.json");
 
   if (fs.existsSync(manifestPath)) {
     const stat = fs.statSync(manifestPath);

package/src/ssr-fonts.ts

@@ -621,8 +621,8 @@ export function readManifestFonts(
   fs: any,
   path: any,
   cwd: string,
+  manifestPath: string = path.join(cwd, "pylon.manifest.json"),
 ): ManifestFontInput[] {
-  const manifestPath = path.join(cwd, "pylon.manifest.json");
   if (!fs.existsSync(manifestPath)) return [];
   try {
     const m = JSON.parse(fs.readFileSync(manifestPath, "utf8"));

package/src/ssr-og-runtime.ts

@@ -25,6 +25,7 @@
 
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { serverBundle } from "./server-bundle";
 
 // Satori's font descriptor.
 export interface OgFont {
@@ -68,9 +69,15 @@ function loadResvg() {
 	if (!resvgReady) {
 		resvgReady = (async () => {
 			const mod = await import("@resvg/resvg-wasm");
-			// Locate the wasm binary next to the package entry and init once.
-			const entry = fileURLToPath(import.meta.resolve("@resvg/resvg-wasm"));
-			const wasmPath = entry.replace(/index\.[^/]+$/, "index_bg.wasm");
+			// Locate the wasm binary next to the package entry (or in the
+			// production server bundle) and init once.
+			const bundled = serverBundle()?.ogAssets.resvgWasm;
+			const wasmPath =
+				bundled ??
+				fileURLToPath(import.meta.resolve("@resvg/resvg-wasm")).replace(
+					/index\.[^/]+$/,
+					"index_bg.wasm",
+				);
 			await mod.initWasm(readFileSync(wasmPath));
 			return mod;
 		})();
@@ -83,18 +90,23 @@ function loadResvg() {
 let defaultFonts: OgFont[] | null = null;
 function loadDefaultFonts(): OgFont[] {
 	if (defaultFonts) return defaultFonts;
+	const bundled = serverBundle()?.ogAssets;
 	const read = (rel: string) =>
 		readFileSync(fileURLToPath(new URL(rel, import.meta.url)));
 	defaultFonts = [
 		{
 			name: "Inter",
-			data: read("../assets/fonts/Inter-Regular.ttf"),
+			data: bundled
+				? readFileSync(bundled.interRegular)
+				: read("../assets/fonts/Inter-Regular.ttf"),
 			weight: 400,
 			style: "normal",
 		},
 		{
 			name: "Inter",
-			data: read("../assets/fonts/Inter-SemiBold.ttf"),
+			data: bundled
+				? readFileSync(bundled.interSemiBold)
+				: read("../assets/fonts/Inter-SemiBold.ttf"),
 			weight: 600,
 			style: "normal",
 		},

package/src/ssr-runtime.ts

@@ -7,6 +7,8 @@
 // the dispatch arm) so projects without SSR routes pay nothing — no
 // react-dom dependency requirement, no startup cost.
 
+import { moduleKey, serverBundle } from "./server-bundle";
+
 // Bun runtime global. This module runs under Bun but is type-checked by
 // consuming apps under node/DOM (no `Bun` global) — declare the surface used.
 declare const Bun: {
@@ -716,8 +718,19 @@ export function renderMetadata(React: any, m: SsrMetadata | undefined): any {
 
 const MODULE_EXTS = [".tsx", ".ts", ".jsx", ".js"];
 
-/** Import a project-relative module, trying each common extension. */
+/**
+ * Import a project-relative module, trying each common extension. A
+ * production server bundle serves it from the bundle's module registry.
+ */
 export async function importModule(cwd: string, relPath: string): Promise<any> {
+  const bundle = serverBundle();
+  if (bundle) {
+    const load = bundle.modules[moduleKey(relPath)];
+    if (load === undefined) {
+      throw new Error(`module "${relPath}" is not in the server bundle`);
+    }
+    return load();
+  }
   const base = `${cwd}/${relPath}`;
   let lastErr: unknown = null;
   for (const ext of MODULE_EXTS) {
@@ -730,6 +743,58 @@ export async function importModule(cwd: string, relPath: string): Promise<any> {
   throw lastErr ?? new Error(`could not import module "${relPath}"`);
 }
 
+/**
+ * True when the project has a module at `<dir>/<name>` with any code
+ * extension. `dir` is project-relative and "/"-separated. A production server
+ * bundle answers from its module registry; source mode checks the disk.
+ */
+export function moduleExistsIn(
+  fs: any,
+  path: any,
+  cwd: string,
+  dir: string,
+  name: string,
+): boolean {
+  const bundle = serverBundle();
+  if (bundle) return moduleKey(`${dir}/${name}`) in bundle.modules;
+  return MODULE_EXTS.some((ext) =>
+    fs.existsSync(path.join(cwd, dir, `${name}${ext}`)),
+  );
+}
+
+/**
+ * The route-group directories (`(name)`) directly under the project-relative
+ * `dir`, sorted by name. A production server bundle derives them from its
+ * module registry keys; source mode reads the directory.
+ */
+function routeGroupDirsIn(fs: any, path: any, cwd: string, dir: string): string[] {
+  const isGroup = (n: string) => n.startsWith("(") && n.endsWith(")");
+  const bundle = serverBundle();
+  if (bundle) {
+    const prefix = `${dir}/`;
+    const found = new Set<string>();
+    for (const key of Object.keys(bundle.modules)) {
+      if (!key.startsWith(prefix)) continue;
+      const child = key.slice(prefix.length).split("/")[0];
+      // A key with no "/" after the prefix is a module file, not a directory.
+      if (key.slice(prefix.length).includes("/") && isGroup(child)) {
+        found.add(child);
+      }
+    }
+    return [...found].sort();
+  }
+  let entries: any[];
+  try {
+    entries = fs.readdirSync(path.join(cwd, dir), { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e: any) => e.isDirectory() && isGroup(e.name))
+    .map((e: any) => e.name as string)
+    .sort();
+}
+
 /**
  * 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
@@ -829,25 +894,10 @@ function boundaryInDirOrGroups(
   dir: string,
   fileName: string,
 ): string | null {
-  for (const ext of MODULE_EXTS) {
-    if (fs.existsSync(path.join(cwd, dir, `${fileName}${ext}`))) {
-      return `${dir}/${fileName}`;
-    }
-  }
-  let entries: any[];
-  try {
-    entries = fs.readdirSync(path.join(cwd, dir), { withFileTypes: true });
-  } catch {
-    return null;
+  if (moduleExistsIn(fs, path, cwd, dir, fileName)) {
+    return `${dir}/${fileName}`;
   }
-  const groups = entries
-    .filter(
-      (e: any) =>
-        e.isDirectory() && e.name.startsWith("(") && e.name.endsWith(")"),
-    )
-    .map((e: any) => e.name as string)
-    .sort();
-  for (const g of groups) {
+  for (const g of routeGroupDirsIn(fs, path, cwd, dir)) {
     const hit = boundaryInDirOrGroups(fs, path, cwd, `${dir}/${g}`, fileName);
     if (hit) return hit;
   }
@@ -892,8 +942,6 @@ function findColocatedImage(
   return null;
 }
 
-const OG_IMAGE_CODE_EXTS = [".tsx", ".ts", ".jsx", ".js"];
-
 /**
  * Walk up from a page's directory to the nearest colocated dynamic OG
  * module (`opengraph-image.{tsx,ts,jsx,js}`) and return the CONCRETE
@@ -938,14 +986,12 @@ function findColocatedOgImageRoute(
     return below.filter((s) => !(s.startsWith("(") && s.endsWith(")"))).length;
   };
   while (dir && dir !== "." && dir !== "/") {
-    for (const ext of OG_IMAGE_CODE_EXTS) {
-      if (fs.existsSync(path.join(cwd, dir, `opengraph-image${ext}`))) {
-        const prefix =
-          dir === pageDir && !isBoundary
-            ? urlSegs
-            : urlSegs.slice(0, nonGroupDepth(dir));
-        return "/" + [...prefix, "opengraph-image"].join("/");
-      }
+    if (moduleExistsIn(fs, path, cwd, dir, "opengraph-image")) {
+      const prefix =
+        dir === pageDir && !isBoundary
+          ? urlSegs
+          : urlSegs.slice(0, nonGroupDepth(dir));
+      return "/" + [...prefix, "opengraph-image"].join("/");
     }
     const slash = dir.lastIndexOf("/");
     dir = slash >= 0 ? dir.slice(0, slash) : "";
@@ -2098,6 +2144,9 @@ export function buildHydrationTail(args: {
   manifestRoute: { file: string; imports: string[]; css: string[] } | null;
   publicPrefix: string;
   manifestErr: string | null;
+  /** core-js polyfill bundle (relative to `publicPrefix`), from the bundle
+   *  manifest. Loaded before the route entry. */
+  polyfills?: string;
   kind?: "error" | "not-found";
   errorForClient?: { message: string; digest?: string };
   // PPR Phase 0 (auth-bucketed caching): when set, this render is being stored
@@ -2181,6 +2230,11 @@ export function buildHydrationTail(args: {
     // reusable (no double fetch) and surfaces load errors. No-op for the
     // same-origin `/_pylon/build/` default.
     const co = /^https?:\/\//i.test(args.publicPrefix) ? " crossorigin" : "";
+    // Module scripts run in document order, so the polyfills are in place
+    // before the entry (and the shared chunk it imports) runs.
+    if (args.polyfills) {
+      tail += `<script type="module"${co} src="${args.publicPrefix}${args.polyfills}"></script>`;
+    }
     tail += `<script type="module"${co} src="${args.publicPrefix}${args.manifestRoute.file}"></script>`;
   } else {
     // Executable script → the serialized message MUST be script-escaped
@@ -2258,11 +2312,8 @@ function resolveLayoutChain(componentRelPath: string, cwd: string): string[] {
   let acc = "";
   for (const part of parts) {
     acc = acc ? `${acc}/${part}` : part;
-    for (const ext of MODULE_EXTS) {
-      if (fs.existsSync(path.join(cwd, acc, `layout${ext}`))) {
-        layouts.push(`${acc}/layout`);
-        break;
-      }
+    if (moduleExistsIn(fs, path, cwd, acc, "layout")) {
+      layouts.push(`${acc}/layout`);
     }
   }
   return layouts;
@@ -2321,6 +2372,7 @@ async function renderBoundaryToClient(
     | { file: string; imports: string[]; css: string[] }
     | null = null;
   let publicPrefix = "/_pylon/build/";
+  let polyfills: string | undefined;
   let headBlob = "";
   if (tail) {
     try {
@@ -2328,6 +2380,7 @@ async function renderBoundaryToClient(
       const manifest = await getManifest();
       publicPrefix = manifest.public_prefix || publicPrefix;
       manifestRoute = manifest.routes[tail.component] ?? null;
+      polyfills = manifest.polyfills;
     } catch {
       manifestRoute = null;
     }
@@ -2374,6 +2427,7 @@ async function renderBoundaryToClient(
       manifestRoute,
       publicPrefix,
       manifestErr: null,
+      polyfills,
       kind: tail.kind,
       errorForClient: tail.errorForClient,
     });
@@ -3201,22 +3255,30 @@ export async function handleRenderRoute(
     // `react-dom/server` (which is Node-stream-style). Try browser
     // first, fall back to the default entry for environments that
     // re-route it (Next runs a custom dist).
+    //
+    // A production server bundle carries the app's React, bundled with the
+    // page modules, so there is nothing to resolve.
+    const bundle = serverBundle();
     let reactDomServerImport: any;
-    try {
-      // @ts-ignore — user-dep, resolved at runtime
-      reactDomServerImport = await import(
-        /* @vite-ignore */ resolveFromUser("react-dom/server.browser")
-      );
-    } catch {
+    let reactImport: any;
+    if (bundle) {
+      reactDomServerImport = bundle.reactDomServer;
+      reactImport = bundle.react;
+    } else {
+      try {
+        // @ts-ignore — user-dep, resolved at runtime
+        reactDomServerImport = await import(
+          /* @vite-ignore */ resolveFromUser("react-dom/server.browser")
+        );
+      } catch {
+        // @ts-ignore — user-dep, resolved at runtime
+        reactDomServerImport = await import(
+          /* @vite-ignore */ resolveFromUser("react-dom/server")
+        );
+      }
       // @ts-ignore — user-dep, resolved at runtime
-      reactDomServerImport = await import(
-        /* @vite-ignore */ resolveFromUser("react-dom/server")
-      );
+      reactImport = await import(/* @vite-ignore */ resolveFromUser("react"));
     }
-    // @ts-ignore — user-dep, resolved at runtime
-    const reactImport = await import(
-      /* @vite-ignore */ resolveFromUser("react")
-    );
     React = reactImport.default ?? reactImport;
     renderToReadableStream =
       reactDomServerImport.renderToReadableStream ??
@@ -3700,11 +3762,13 @@ export async function handleRenderRoute(
       | null = null;
     let preloadManifestErr: string | null = null;
     let preloadPublicPrefix = "/_pylon/build/";
+    let preloadPolyfills: string | undefined;
     try {
       const { getManifest } = await import("./ssr-client-bundler");
       const manifest = await getManifest();
       preloadPublicPrefix = manifest.public_prefix || preloadPublicPrefix;
       preloadManifestRoute = manifest.routes[msg.component] ?? null;
+      preloadPolyfills = manifest.polyfills;
       if (!preloadManifestRoute) {
         preloadManifestErr = `manifest has no entry for "${msg.component}"`;
       }
@@ -3866,6 +3930,7 @@ export async function handleRenderRoute(
         manifestRoute: preloadManifestRoute,
         publicPrefix: preloadPublicPrefix,
         manifestErr: preloadManifestErr,
+        polyfills: preloadPolyfills,
         kind: isBoundaryComponent
           ? /(^|\/)error$/.test(msg.component)
             ? "error"