@pylonsync/functions 0.3.311 → 0.3.314

package/dist/server-only.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Marker import that pins a module to the SERVER. Put it at the top of any
+ * module that must never reach the browser — one holding secrets, server
+ * config, or node-only APIs:
+ *
+ *   import "@pylonsync/functions/server-only";
+ *
+ *   export const stripeKey = process.env.STRIPE_SECRET_KEY!;
+ *
+ * Page (`page.tsx`) and layout (`layout.tsx`) modules — and everything they
+ * transitively import — are bundled for client hydration, so a plain literal or
+ * server config in that graph would ship to the browser. If a module marked
+ * with this import is pulled into a client-reachable page, the SSR client
+ * bundler REFUSES to build and names the offending importer (see the
+ * `pylon-server-only` plugin in `ssr-client-bundler.ts`).
+ *
+ * On the server this is an inert no-op. There is nothing to call — importing it
+ * is the whole contract.
+ */
+export {};

package/dist/ssr-client-bundler.d.ts

@@ -14,6 +14,16 @@ interface BundleClientMessage {
      */
     app_dir?: string;
 }
+/**
+ * Fail the CLIENT bundle when a `server-only` module is resolved — meaning it
+ * was pulled into a page/layout's client graph. Page/layout modules (and their
+ * transitive imports) are bundled for hydration, so a literal secret or server
+ * config in that graph would ship to the browser (the `process.env.*` `define`
+ * only neutralizes env reads). Authors mark such modules with
+ * `import "@pylonsync/functions/server-only"`; this turns an accidental client
+ * import into a loud build failure that names the offending importer.
+ */
+export declare function assertNotServerOnly(specifier: string, importer: string): void;
 /**
  * Manifest schema. One entry per route, indexed by the same
  * project-relative component path the SSR side passes through.
@@ -49,6 +59,11 @@ export interface PylonBundleManifest {
      *  independent); rendered into every SSR `<head>` against `public_prefix`.
      *  Absent when the app declares no `font({...})`. */
     fonts?: ManifestFonts;
+    /** Set when the Tailwind compile failed for this build: the pages are
+     *  serving WITHOUT styles. Dev surfaces it as an on-page banner (see
+     *  pylonDevHud) — a silent unstyled page reads as a CSS bug, not a
+     *  build failure, and costs real debugging time. */
+    css_error?: string;
 }
 /** Result of an in-process build — same shape the protocol returns. */
 export interface BuildOutput {

package/dist/ssr-runtime.d.ts

@@ -351,6 +351,7 @@ export declare function applyAutoSocialImages(component: string, headers: Record
  */
 export declare function escapeScriptJson(json: string): string;
 export declare function buildDevHudChunk(devInfo: Record<string, unknown>): string;
+export declare function cssHeadTag(css: string, prefix: string, routeOverride?: boolean): Promise<string>;
 /**
  * Build the hydration tail appended after React's stream EOFs: the
  * `__PYLON_DATA__` JSON blob (props + ssrData) + the per-route entry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.311",
+  "version": "0.3.314",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",
@@ -14,6 +14,10 @@
       "types": "./dist/runtime.d.ts",
       "default": "./src/runtime.ts"
     },
+    "./server-only": {
+      "types": "./dist/server-only.d.ts",
+      "default": "./src/server-only.ts"
+    },
     "./client-bundler": {
       "types": "./dist/ssr-client-bundler.d.ts",
       "default": "./src/ssr-client-bundler.ts"

package/src/runtime.ts

@@ -32,6 +32,7 @@ import type {
   AuthInfo,
 } from "./types";
 import { makeRequireMember } from "./member";
+import { isDevMode } from "./ssr-runtime";
 import { validateArgs } from "./validators";
 import { readdirSync } from "fs";
 import { join, basename } from "path";
@@ -989,21 +990,43 @@ async function handleCall(msg: CallMessage): Promise<void> {
     } else {
       // No explicit code — assume it's an unexpected Error/thrown value.
       // Log the real error to stderr (server operator visible) and return
-      // a safe placeholder to the client.
+      // a safe placeholder to the client. In DEV the real message (and
+      // top stack frame) rides along: the developer debugging a 500 IS
+      // the operator, and hiding the reason from the HTTP response just
+      // sends them (or their agent) digging through server logs for
+      // something we already know. Production responses stay masked.
       console.error(
         `[functions] unhandled error in ${msg.fn_name} (${msg.call_id}):`,
         err,
       );
+      const devDetail =
+        isDevMode() && typeof err?.message === "string" && err.message.length > 0
+          ? ` (dev): ${err.message}${firstStackFrame(err)}`
+          : "";
       send({
         type: "error",
         call_id: msg.call_id,
         code: "HANDLER_ERROR",
-        message: "Internal handler error",
+        message: `Internal handler error${devDetail}`,
       });
     }
   }
 }
 
+/**
+ * The first user-code stack frame of an error, for dev-mode error
+ * detail — one frame locates the throw without shipping a whole trace.
+ */
+function firstStackFrame(err: unknown): string {
+  const stack = (err as { stack?: string })?.stack;
+  if (typeof stack !== "string") return "";
+  const frame = stack
+    .split("\n")
+    .map((l) => l.trim())
+    .find((l) => l.startsWith("at "));
+  return frame ? ` [${frame}]` : "";
+}
+
 // ---------------------------------------------------------------------------
 // Startup: scan functions dir, send ready, then start reader loop
 // ---------------------------------------------------------------------------

package/src/server-only.ts

@@ -0,0 +1,20 @@
+/**
+ * Marker import that pins a module to the SERVER. Put it at the top of any
+ * module that must never reach the browser — one holding secrets, server
+ * config, or node-only APIs:
+ *
+ *   import "@pylonsync/functions/server-only";
+ *
+ *   export const stripeKey = process.env.STRIPE_SECRET_KEY!;
+ *
+ * Page (`page.tsx`) and layout (`layout.tsx`) modules — and everything they
+ * transitively import — are bundled for client hydration, so a plain literal or
+ * server config in that graph would ship to the browser. If a module marked
+ * with this import is pulled into a client-reachable page, the SSR client
+ * bundler REFUSES to build and names the offending importer (see the
+ * `pylon-server-only` plugin in `ssr-client-bundler.ts`).
+ *
+ * On the server this is an inert no-op. There is nothing to call — importing it
+ * is the whole contract.
+ */
+export {};

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

@@ -24,6 +24,7 @@ import * as os from "node:os";
 import {
   buildClientBundle,
   buildTailwind,
+  assertNotServerOnly,
   type PylonBundleManifest,
 } from "./ssr-client-bundler";
 import { nearestBoundaryComponent } from "./ssr-client-boundary";
@@ -430,3 +431,60 @@ describe("Tailwind compile is concurrency-safe", () => {
     expect(stranded).toEqual([]);
   }, 20_000);
 });
+
+describe("server-only guard (secrets can't leak into the client bundle)", () => {
+  test("assertNotServerOnly throws for server-only specifiers, passes others", () => {
+    expect(() =>
+      assertNotServerOnly("@pylonsync/functions/server-only", "app/page.tsx"),
+    ).toThrow(/server-only/i);
+    expect(() => assertNotServerOnly("server-only", "app/x/layout.tsx")).toThrow(
+      /server-only/i,
+    );
+    // The importer is named so the author can find the offending module.
+    expect(() => assertNotServerOnly("server-only", "app/secrets.ts")).toThrow(
+      /app\/secrets\.ts/,
+    );
+    // Ordinary imports pass untouched.
+    expect(() => assertNotServerOnly("react", "app/page.tsx")).not.toThrow();
+    expect(() => assertNotServerOnly("@/lib/utils", "app/page.tsx")).not.toThrow();
+  });
+
+  test("a real client build importing a server-only module FAILS via the guard", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pylon-server-only-"));
+    const entry = path.join(dir, "entry.ts");
+    fs.writeFileSync(entry, `import "server-only";\nexport const x = 1;\n`);
+    // Same plugin the bundler installs. `guardFired` proves the guard's
+    // onResolve ran for the marker (Bun runs plugin resolution BEFORE default
+    // resolution) — distinguishing a real guard rejection from an unrelated
+    // "module not found". Bun surfaces the plugin throw as a failed build.
+    let guardFired = false;
+    let failed = false;
+    try {
+      const result = await Bun.build({
+        entrypoints: [entry],
+        outdir: path.join(dir, "out"),
+        target: "browser",
+        plugins: [
+          {
+            name: "pylon-server-only",
+            setup(build: any) {
+              build.onResolve(
+                { filter: /^(@pylonsync\/functions\/server-only|server-only)$/ },
+                (args: any) => {
+                  guardFired = true;
+                  assertNotServerOnly(args.path, args.importer);
+                },
+              );
+            },
+          },
+        ],
+      } as any);
+      failed = !result.success;
+    } catch {
+      failed = true;
+    }
+    expect(guardFired).toBe(true);
+    expect(failed).toBe(true);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+});

package/src/ssr-client-bundler.ts

@@ -101,10 +101,46 @@ declare const Bun: {
         };
     publicPath?: string;
     root?: string;
+    plugins?: Array<{
+      name: string;
+      setup(build: {
+        onResolve(
+          opts: { filter: RegExp; namespace?: string },
+          callback: (args: { path: string; importer: string }) => void,
+        ): void;
+      }): void;
+    }>;
   }): Promise<BunBuildOutput>;
   file(path: string): { exists(): Promise<boolean> };
 };
 
+/**
+ * Specifiers marking a module as SERVER-ONLY: `@pylonsync/functions/server-only`
+ * (in-ecosystem) or the bare `server-only` (Next.js compat). A module that
+ * imports one must never reach the browser.
+ */
+const SERVER_ONLY_RE = /^(@pylonsync\/functions\/server-only|server-only)$/;
+
+/**
+ * Fail the CLIENT bundle when a `server-only` module is resolved — meaning it
+ * was pulled into a page/layout's client graph. Page/layout modules (and their
+ * transitive imports) are bundled for hydration, so a literal secret or server
+ * config in that graph would ship to the browser (the `process.env.*` `define`
+ * only neutralizes env reads). Authors mark such modules with
+ * `import "@pylonsync/functions/server-only"`; this turns an accidental client
+ * import into a loud build failure that names the offending importer.
+ */
+export function assertNotServerOnly(specifier: string, importer: string): void {
+  if (SERVER_ONLY_RE.test(specifier)) {
+    throw new Error(
+      `pylon: "${specifier}" is server-only but was imported into the client bundle by ` +
+        `${importer || "a page/layout module"}. Page/layout modules (and everything they import) ship to ` +
+        `the browser — move server-only code (secrets, server config, node-only APIs) into a server function ` +
+        `(functions/) or a route.ts handler and pass only the rendered values as props.`,
+    );
+  }
+}
+
 /**
  * Synchronously walk the route dir (`<appDirRel>` under cwd, e.g.
  * `app` or `web/app`) and return one entry per discovered page, each
@@ -899,6 +935,11 @@ export interface PylonBundleManifest {
    *  independent); rendered into every SSR `<head>` against `public_prefix`.
    *  Absent when the app declares no `font({...})`. */
   fonts?: ManifestFonts;
+  /** Set when the Tailwind compile failed for this build: the pages are
+   *  serving WITHOUT styles. Dev surfaces it as an on-page banner (see
+   *  pylonDevHud) — a silent unstyled page reads as a CSS bug, not a
+   *  build failure, and costs real debugging time. */
+  css_error?: string;
 }
 
 /** Result of an in-process build — same shape the protocol returns. */
@@ -1240,6 +1281,19 @@ async function _doBuildInner(
         chunk: "chunks/[name]-[hash].js",
         asset: "assets/[name]-[hash][ext]",
       },
+      // Refuse to bundle a server-only module into a client-reachable page —
+      // secrets / server config in a page's import graph would otherwise ship
+      // to the browser.
+      plugins: [
+        {
+          name: "pylon-server-only",
+          setup(build) {
+            build.onResolve({ filter: SERVER_ONLY_RE }, (args) => {
+              assertNotServerOnly(args.path, args.importer);
+            });
+          },
+        },
+      ],
     });
 
     if (!result.success) {
@@ -1281,6 +1335,52 @@ async function _doBuildInner(
       }
     }
 
+    // loro-crdt's web build locates its WASM sibling at RUNTIME via
+    // `new URL("loro_wasm_bg.wasm", import.meta.url)` — the file never
+    // appears in the static import graph, so Bun doesn't emit it and every
+    // CRDT-using page 404s on /_pylon/build/loro_wasm_bg.wasm during
+    // hydration. When any built output references the wasm by name, copy
+    // 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) => {
+        if (!o.path.endsWith(".js")) return false;
+        try {
+          return fs.readFileSync(o.path, "utf8").includes("loro_wasm_bg.wasm");
+        } catch {
+          return false;
+        }
+      });
+      if (referencesLoroWasm) {
+        const loroPkg = (Bun as any).resolveSync(
+          "loro-crdt/package.json",
+          cwd,
+        ) as string;
+        // The wasm must come from the SAME build variant whose JS glue got
+        // bundled — the wasm-bindgen import namespaces differ between
+        // variants (mixing them fails instantiation with `Import #0 "wbg"`).
+        // `target: "browser"` resolves the package's "browser" condition, so
+        // prefer browser/; web/ is the fallback for older package layouts.
+        const loroDir = path.dirname(loroPkg);
+        const wasmSrc = ["browser", "web"]
+          .map((v) => path.join(loroDir, v, "loro_wasm_bg.wasm"))
+          .find((p) => fs.existsSync(p));
+        if (wasmSrc) {
+          fs.copyFileSync(wasmSrc, path.join(outdir, "loro_wasm_bg.wasm"));
+          const chunksDir = path.join(outdir, "chunks");
+          if (fs.existsSync(chunksDir)) {
+            fs.copyFileSync(
+              wasmSrc,
+              path.join(chunksDir, "loro_wasm_bg.wasm"),
+            );
+          }
+        }
+      }
+    } catch {
+      // Best-effort: failing to copy just reproduces the 404 this guards
+      // against; the build itself is fine.
+    }
+
     // 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
@@ -1362,6 +1462,20 @@ async function _doBuildInner(
       );
     }
 
+    // Manifest-driven features (fonts, route metadata) read
+    // 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"))) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        "[pylon ssr] pylon.manifest.json not found — building the client " +
+          "bundle WITHOUT manifest-derived features (declared fonts will " +
+          "be missing). Run `pylon codegen` first, or deploy through a " +
+          "path that derives the manifest.",
+      );
+    }
+
     // 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">`.
@@ -1375,10 +1489,20 @@ async function _doBuildInner(
         }
       }
     } catch (twErr: any) {
-      // Tailwind failure shouldn't kill the SSR build — log a loud
-      // warning + ship the bundle without styles so devs can iterate.
+      // Tailwind failure shouldn't kill the SSR build — ship the bundle
+      // without styles so devs can iterate. But NOT silently: the error
+      // rides the bundle manifest so dev renders banner it on-page.
+      // (The log line alone proved invisible in practice — an unstyled
+      // page doesn't say "go read the bundler log".)
+      // Tailwind's CLI output arrives ANSI-colored; strip the escapes —
+      // this string renders in a browser banner, not a terminal.
+      const cssMsg = String(twErr?.message ?? twErr).replace(
+        /\u001b\[[0-9;]*m/g,
+        "",
+      );
+      manifest.css_error = cssMsg;
       // eslint-disable-next-line no-console
-      console.warn(`[pylon ssr] tailwind compile failed: ${twErr?.message ?? twErr}`);
+      console.warn(`[pylon ssr] tailwind compile failed: ${cssMsg}`);
     }
 
     // Self-hosted fonts (next/font parity). Reads `fonts` from the app's

package/src/ssr-inline-css.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test, afterEach } from "bun:test";
+import { cssHeadTag } from "./ssr-runtime";
+
+const CSS = "styles-abc123.css";
+
+afterEach(() => {
+  delete process.env.PYLON_SSR_INLINE_CSS;
+  delete process.env.PYLON_SSR_INLINE_CSS_MAX;
+});
+
+describe("cssHeadTag (PYLON_SSR_INLINE_CSS)", () => {
+  test("default off → plain stylesheet link, untouched", async () => {
+    const tag = await cssHeadTag(CSS, "/_pylon/build/");
+    expect(tag).toBe(`<link rel="stylesheet" href="/_pylon/build/${CSS}">`);
+  });
+
+  test("enabled but sheet unreadable → falls back to the link", async () => {
+    process.env.PYLON_SSR_INLINE_CSS = "1";
+    // No client build exists in the test cwd — the helper must degrade
+    // to the link, never throw or emit an empty <style>.
+    const tag = await cssHeadTag("styles-does-not-exist.css", "/_pylon/build/");
+    expect(tag).toBe(
+      '<link rel="stylesheet" href="/_pylon/build/styles-does-not-exist.css">',
+    );
+  });
+
+  test("CDN prefix rides the fallback link unchanged", async () => {
+    process.env.PYLON_SSR_INLINE_CSS = "true";
+    const tag = await cssHeadTag(
+      "styles-missing.css",
+      "https://assets.pyln.dev/o/p/",
+    );
+    expect(tag).toBe(
+      '<link rel="stylesheet" href="https://assets.pyln.dev/o/p/styles-missing.css">',
+    );
+  });
+});
+
+describe("cssHeadTag per-route override", () => {
+  test("route true wins over env off (falls back to link only because no build exists here)", async () => {
+    // Override=true ENABLES the inline path with env unset; with no
+    // client build in the test cwd it degrades to the link — proving
+    // the override reached the enabled gate (default-off would have
+    // returned the link WITHOUT attempting the read; exercised via the
+    // cache: a distinct filename keeps the assertions independent).
+    const tag = await cssHeadTag("styles-override.css", "/_pylon/build/", true);
+    expect(tag).toBe(
+      '<link rel="stylesheet" href="/_pylon/build/styles-override.css">',
+    );
+  });
+
+  test("route false wins over env on", async () => {
+    process.env.PYLON_SSR_INLINE_CSS = "1";
+    const tag = await cssHeadTag("styles-forced-off.css", "/_pylon/build/", false);
+    expect(tag).toBe(
+      '<link rel="stylesheet" href="/_pylon/build/styles-forced-off.css">',
+    );
+  });
+});

package/src/ssr-runtime.ts

@@ -1220,6 +1220,20 @@ function pylonDevHud() {
   // Marker the sync engine checks before publishing its dev status probe.
   g.__PYLON_DEV__ = info;
 
+  // Build failure banner: when the build degraded the page (e.g. the
+  // Tailwind compile failed and the page is serving unstyled), paint an
+  // unmissable fixed banner. This is the loud path for failures that
+  // would otherwise masquerade as app bugs.
+  if (info.buildWarning) {
+    const b = d.createElement("div");
+    b.textContent = "⚠ " + String(info.buildWarning);
+    b.style.cssText =
+      "position:fixed;top:0;left:0;right:0;z-index:2147483647;" +
+      "background:#dc2626;color:#fff;padding:8px 14px;" +
+      "font:13px/1.4 ui-monospace,monospace;white-space:pre-wrap;";
+    d.body.appendChild(b);
+  }
+
   // Client errors.
   const errs: string[] = [];
   const onErr = (m: any) => {
@@ -1553,6 +1567,66 @@ export function buildDevHudChunk(devInfo: Record<string, unknown>): string {
  * would look broken. Returns "" if the manifest can't be loaded — the
  * boundary still renders (unstyled); CSS must never block the error path.
  */
+/**
+ * One `<head>` tag per route stylesheet: a `<link rel="stylesheet">` by
+ * default, or the file's contents inlined in a `<style>` when inlining
+ * is enabled — per route via `export const inlineCss = true|false`
+ * (wins), else globally via PYLON_SSR_INLINE_CSS — and the compiled
+ * sheet is small enough (PYLON_SSR_INLINE_CSS_MAX bytes, default
+ * 32768). Inlining
+ * removes the render-blocking stylesheet round trip on cold
+ * connections — at 14KB of compiled Tailwind that's the whole sheet.
+ *
+ * Read from the local client-build outdir (present even in CDN mode —
+ * the CDN prefix changes where BROWSERS fetch, not where the build
+ * lives). Contents are cached per content-hashed filename. Falls back
+ * to the link on any miss: unreadable file, over threshold, or a
+ * sheet containing "</style" (would break out of the tag).
+ */
+const inlineCssCache = new Map<string, string | null>();
+export async function cssHeadTag(
+  css: string,
+  prefix: string,
+  routeOverride?: boolean,
+): Promise<string> {
+  const link = `<link rel="stylesheet" href="${prefix}${css}">`;
+  // Per-route `export const inlineCss = true|false` beats the env
+  // default — the tradeoff is inherently per-route (cold landing pages
+  // win from inlining; cached logged-in pages win from the link).
+  const enabled =
+    routeOverride ??
+    /^(1|true)$/i.test(process.env.PYLON_SSR_INLINE_CSS ?? "");
+  if (!enabled) return link;
+  let cached = inlineCssCache.get(css);
+  if (cached === undefined) {
+    cached = null;
+    try {
+      const { getManifest } = await import("./ssr-client-bundler");
+      const manifest: any = await getManifest();
+      const fs = await import("fs");
+      const path = await import("path");
+      const max = Number(process.env.PYLON_SSR_INLINE_CSS_MAX ?? "") || 32768;
+      const file = path.join(
+        process.cwd(),
+        manifest.outdir || ".pylon/client-build",
+        css,
+      );
+      const stat = fs.statSync(file);
+      if (stat.size <= max) {
+        const text = fs.readFileSync(file, "utf8");
+        if (!/<\/style/i.test(text)) cached = text;
+      }
+    } catch {
+      cached = null;
+    }
+    if (inlineCssCache.size > 64) inlineCssCache.clear();
+    inlineCssCache.set(css, cached);
+  }
+  return cached === null
+    ? link
+    : `<style data-pylon-css="${css}">${cached}</style>`;
+}
+
 async function collectBoundaryHeadBlob(): Promise<string> {
   try {
     const { getManifest } = await import("./ssr-client-bundler");
@@ -1566,7 +1640,7 @@ async function collectBoundaryHeadBlob(): Promise<string> {
       for (const css of (route.css || []) as string[]) {
         if (seen.has(css)) continue;
         seen.add(css);
-        blob += `<link rel="stylesheet" href="${prefix}${css}">`;
+        blob += await cssHeadTag(css, prefix);
       }
     }
     return blob;
@@ -1791,7 +1865,7 @@ async function renderBoundaryToClient(
     headBlob += await buildFontHeadBlob();
     const co = /^https?:\/\//i.test(publicPrefix) ? " crossorigin" : "";
     for (const css of manifestRoute.css) {
-      headBlob += `<link rel="stylesheet" href="${publicPrefix}${css}">`;
+      headBlob += await cssHeadTag(css, publicPrefix);
     }
     for (const chunk of manifestRoute.imports) {
       headBlob += `<link rel="modulepreload"${co} href="${publicPrefix}${chunk}">`;
@@ -2840,8 +2914,10 @@ export async function handleRenderRoute(
     if (preloadManifestRoute) {
       headBlob += await buildFontHeadBlob();
       const co = /^https?:\/\//i.test(preloadPublicPrefix) ? " crossorigin" : "";
+      const inlineOverride =
+        typeof mod?.inlineCss === "boolean" ? mod.inlineCss : undefined;
       for (const css of preloadManifestRoute.css) {
-        headBlob += `<link rel="stylesheet" href="${preloadPublicPrefix}${css}">`;
+        headBlob += await cssHeadTag(css, preloadPublicPrefix, inlineOverride);
       }
       for (const chunk of preloadManifestRoute.imports) {
         headBlob += `<link rel="modulepreload"${co} href="${preloadPublicPrefix}${chunk}">`;
@@ -2972,8 +3048,18 @@ export async function handleRenderRoute(
     // agent running `pylon dev` sees the verdict without any extra call.
     if (devVerdict) {
       const renderMs = Math.round((performance.now() - renderStart) * 10) / 10;
+      // Build-level failures that degraded this page (currently: the
+      // Tailwind compile). Dev-only and unmissable — the HUD paints a
+      // banner, because an unstyled page never says "go read the log".
+      let buildWarning: string | undefined;
+      try {
+        const { getManifest } = await import("./ssr-client-bundler");
+        const m: any = await getManifest();
+        if (m?.css_error) buildWarning = `Tailwind compile failed — serving without styles: ${m.css_error}`;
+      } catch {}
       sendChunk(
         buildDevHudChunk({
+          buildWarning,
           route: msg.url,
           component: msg.component,
           renderMode,