@pylonsync/functions 0.3.312 → 0.3.315

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

@@ -59,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.312",
+  "version": "0.3.315",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.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/ssr-client-bundler.ts

@@ -935,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. */
@@ -1457,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">`.
@@ -1470,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,