@pylonsync/functions 0.3.293 → 0.3.295

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

@@ -58,6 +58,14 @@ export interface BuildOutput {
  * from `getManifest` (in-process SSR path).
  */
 export declare function buildClientBundle(appDirRel?: string): Promise<BuildOutput>;
+/**
+ * Compile `app/globals.css` through Tailwind v4 (`@tailwindcss/cli`)
+ * if both are present. Returns the relative output path (under
+ * outdir) when produced, else null. Skipped silently when the
+ * project hasn't opted in to Tailwind — we don't want every SSR
+ * project to need Tailwind installed.
+ */
+export declare function buildTailwind(fs: any, path: any, cwd: string, outdir: string, appDirRel: string): Promise<string | null>;
 /**
  * Return the bundle manifest. If a fresh manifest exists on disk,
  * use it (caching parse output across requests). Otherwise build

package/package.json

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

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

@@ -23,6 +23,7 @@ import * as os from "node:os";
 
 import {
   buildClientBundle,
+  buildTailwind,
   type PylonBundleManifest,
 } from "./ssr-client-bundler";
 import { nearestBoundaryComponent } from "./ssr-client-boundary";
@@ -160,6 +161,38 @@ describe("ssr-client-bundler (Phase 1.5e)", () => {
     expect(chunkHasReact).toBe(true);
   });
 
+  test("client runtime wires the nav-fallback guard (uncaught render error → full page load)", async () => {
+    // Regression: a page that renders React-19-hoisted <title>/<meta>/<link> in
+    // its own tree (use the `metadata` export instead) makes a client-side nav
+    // re-render throw in React's commit phase — the URL changes but the page
+    // can't swap (white screen). hydrateRoot must carry an onUncaughtError that
+    // falls back to a full page load of the in-flight destination so nav
+    // degrades gracefully. The distinctive console string is preserved through
+    // minification, so we assert the guard actually ships in the bundle.
+    tempDir = makeFixture(
+      { "page.tsx": PAGE_BODY("Home") },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    originalCwd = process.cwd();
+    process.chdir(tempDir);
+
+    const { outdir } = await buildClientBundle();
+    // The runtime (hydrateRoot + guard) lands in the shared chunk with multiple
+    // entries, or inlined in the entry with one — read every emitted .js.
+    const readJsRecursive = (dir: string): string[] =>
+      fs.readdirSync(dir, { withFileTypes: true }).flatMap((d) => {
+        const full = path.join(dir, d.name);
+        if (d.isDirectory()) return readJsRecursive(full);
+        return d.name.endsWith(".js") ? [fs.readFileSync(full, "utf8")] : [];
+      });
+    const bundled = readJsRecursive(outdir).join("\n");
+
+    // onUncaughtError is a React hydrateRoot option (property name preserved).
+    expect(bundled).toMatch(/onUncaughtError/);
+    // The fallback path: a full page load of the pending destination.
+    expect(bundled).toMatch(/falling back to a full page load/);
+  });
+
   test("manifest names every route, each with a non-empty imports list", async () => {
     tempDir = makeFixture(
       {
@@ -347,3 +380,53 @@ describe("client boundary is wired into the build", () => {
     expect(allShared).toContain("getDerivedStateFromError");
   });
 });
+
+describe("Tailwind compile is concurrency-safe", () => {
+  // Regression: `pylon dev` warms the SSR bundle in one runner process while the
+  // first requests drive their own rebuild in another. Both compiled Tailwind to
+  // a SHARED temp file (`.styles.build.css`); whichever renamed it first won, and
+  // the other's `renameSync` ENOENT'd → the compile threw → the route shipped
+  // with no `css` → the page rendered UNSTYLED. Reproduced ~25% of cold boots
+  // under concurrent load. The fix gives each compile a process-unique temp path
+  // and publishes (rename) before pruning others. Drive several compiles at once
+  // against one outdir and prove they all succeed.
+  test("concurrent compiles against one outdir all produce the stylesheet", async () => {
+    const root = makeFixture(
+      { "page.tsx": PAGE_BODY("Home") },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    tempDir = root; // registers it for afterEach cleanup
+    // Opt into Tailwind: a real globals.css the CLI can compile. `@tailwindcss/cli`
+    // + `tailwindcss` resolve through the fixture's node_modules symlink (it points
+    // at examples/ssr-hello/node_modules, which declares both).
+    fs.writeFileSync(
+      path.join(root, "app", "globals.css"),
+      '@import "tailwindcss";\n@source "../app/**/*.{tsx,ts,jsx,js}";\n',
+      "utf8",
+    );
+    originalCwd = process.cwd();
+    process.chdir(root);
+
+    const outdir = path.join(root, ".pylon", "client-build");
+    fs.mkdirSync(outdir, { recursive: true });
+
+    // Old code: at least one of these rejects with the rename ENOENT.
+    const results = await Promise.all(
+      Array.from({ length: 4 }, () =>
+        buildTailwind(fs, path, root, outdir, "app"),
+      ),
+    );
+
+    for (const name of results) {
+      expect(name).toMatch(/^styles-[a-z0-9]+\.css$/);
+      expect(fs.existsSync(path.join(outdir, name as string))).toBe(true);
+    }
+    // Deterministic output → identical hash → one published asset, no leftover
+    // temp files stranded in the outdir.
+    expect(new Set(results).size).toBe(1);
+    const stranded = (fs.readdirSync(outdir) as string[]).filter((f) =>
+      f.startsWith(".styles.build."),
+    );
+    expect(stranded).toEqual([]);
+  }, 20_000);
+});

package/src/ssr-client-bundler.ts

@@ -212,6 +212,10 @@ import { createPylonBoundary } from "./client-boundary";
 
 const routeCache = Object.create(null);
 let activeRoot = null;
+// Destination of an in-flight client navigation. Read by hydrateRoot's
+// onUncaughtError so a re-render that throws mid-nav degrades to a full page
+// load instead of a white screen. Null when no nav is in flight.
+let pendingNav = null;
 let manifestPromise = null;
 const prefetchedChunks = new Set();
 
@@ -466,7 +470,30 @@ export function hydrate(component, Page, Layouts) {
       data.component,
       navEpoch,
     );
-    activeRoot = hydrateRoot(document, tree);
+    activeRoot = hydrateRoot(document, tree, {
+      // Safety net for client navigation. If a nav re-render throws an uncaught
+      // error in React's commit phase, the URL has already changed but the page
+      // can't swap — a white/stale screen. The classic trigger is a page that
+      // renders hoisted <title>/<meta>/<link> in its own tree (use the
+      // \`metadata\` export instead); React 19 owns those head nodes on the client
+      // and reconciling them across routes can throw. Rather than strand the
+      // user, fall back to a full page load of the pending destination, which
+      // re-renders it cleanly from SSR. Non-navigation errors keep React's
+      // default reporting.
+      onUncaughtError(error) {
+        if (pendingNav) {
+          const dest = pendingNav;
+          pendingNav = null;
+          console.error(
+            "[pylon ssr] client navigation failed to render; falling back to a full page load:",
+            error,
+          );
+          window.location.href = dest;
+          return;
+        }
+        console.error(error);
+      },
+    });
     installNavHandlers();
     return;
   }
@@ -544,13 +571,21 @@ async function navigate(href, opts) {
   setNavParams(data);
   navEpoch++;
   currentPageProps = withClientProps(data);
+  const target = url.pathname + url.search;
   const tree = withBoundary(
     buildTree(route.Page, route.Layouts, currentPageProps),
     data.component,
     navEpoch,
   );
+  // Track the in-flight destination so hydrateRoot's onUncaughtError can fall
+  // back to a full page load if this re-render throws in React's commit phase
+  // (instead of leaving the URL changed but the page unswapped). Cleared on the
+  // next macrotask once the commit has settled with no error.
+  pendingNav = target;
   activeRoot.render(tree);
-  const target = url.pathname + url.search;
+  setTimeout(() => {
+    if (pendingNav === target) pendingNav = null;
+  }, 0);
   if (opts && opts.replace) {
     history.replaceState({ component: data.component }, "", target);
   } else if (push) {
@@ -833,6 +868,13 @@ async function _doBuild(appDirRel: string): Promise<BuildOutput> {
   return _doBuildInner(fs, path, cwd, appDirRel);
 }
 
+// Monotonic per-process counter for the Tailwind temp filename. `pylon dev`
+// warms the SSR bundle in one runner process while incoming requests can drive
+// their own rebuild in another, so two `buildTailwind` calls may run against the
+// same outdir at once. Combined with the pid it gives every compile a unique
+// temp path, so concurrent builds never rename each other's file away.
+let _styleBuildSeq = 0;
+
 /**
  * Compile `app/globals.css` through Tailwind v4 (`@tailwindcss/cli`)
  * if both are present. Returns the relative output path (under
@@ -840,7 +882,10 @@ async function _doBuild(appDirRel: string): Promise<BuildOutput> {
  * project hasn't opted in to Tailwind — we don't want every SSR
  * project to need Tailwind installed.
  */
-async function buildTailwind(
+// Exported for the concurrency regression test (ssr-client-bundler.test.ts):
+// it drives several compiles at once against one outdir to prove they no longer
+// race on a shared temp file.
+export async function buildTailwind(
   fs: any,
   path: any,
   cwd: string,
@@ -880,7 +925,15 @@ async function buildTailwind(
   //
   // Spawn the CLI. Bun is already running; reuse it as the interpreter so the
   // user doesn't need node on PATH.
-  const tmpPath = path.join(outdir, ".styles.build.css");
+  // PROCESS-UNIQUE temp file. A shared name (`.styles.build.css`) let a
+  // concurrent build rename the file out from under this one — its `renameSync`
+  // then ENOENT'd, the compile threw, the route shipped with no `css`, and the
+  // page rendered UNSTYLED. Worst under cold-boot traffic (a warm build racing
+  // the first requests), which is exactly when it must not happen.
+  const tmpPath = path.join(
+    outdir,
+    `.styles.build.${process.pid}.${_styleBuildSeq++}.css`,
+  );
   const proc = (Bun as any).spawn({
     cmd: [process.execPath, cliPath, "-i", globalsPath, "-o", tmpPath, "--minify"],
     cwd,
@@ -890,6 +943,11 @@ async function buildTailwind(
   const exitCode = await proc.exited;
   if (exitCode !== 0) {
     const err = await new Response(proc.stderr).text();
+    try {
+      fs.rmSync(tmpPath, { force: true });
+    } catch {
+      /* nothing to clean up */
+    }
     throw new Error(`tailwindcss build failed (exit ${exitCode}): ${err}`);
   }
 
@@ -907,19 +965,22 @@ async function buildTailwind(
   const stylesName = `styles-${hash.toString(36).padStart(8, "0")}.css`;
   const outPath = path.join(outdir, stylesName);
 
-  // Drop previous styles-*.css so the outdir doesn't accumulate stale builds
-  // (the filename now changes on every class change), then move the freshly
-  // compiled file into place.
+  // Publish our freshly-compiled CSS FIRST (rename replaces atomically on
+  // POSIX, so the asset is never momentarily absent), THEN prune OTHER stale
+  // styles-*.css. The old order pruned before renaming, so a concurrent build
+  // could delete the file we were about to publish; pruning our own name could
+  // delete a concurrent winner's identical output. Excluding `stylesName` keeps
+  // both safe while still clearing builds from earlier class changes.
+  fs.renameSync(tmpPath, outPath);
   try {
     for (const f of fs.readdirSync(outdir) as string[]) {
-      if (f.startsWith("styles-") && f.endsWith(".css")) {
+      if (f.startsWith("styles-") && f.endsWith(".css") && f !== stylesName) {
         fs.rmSync(path.join(outdir, f), { force: true });
       }
     }
   } catch {
     /* outdir may not be listable on the first build — ignore */
   }
-  fs.renameSync(tmpPath, outPath);
   return stylesName;
 }