@pylonsync/functions 0.3.268 → 0.3.270

package/package.json

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

package/src/runtime.ts

@@ -35,6 +35,17 @@ import { validateArgs } from "./validators";
 import { readdirSync } from "fs";
 import { join, basename } from "path";
 
+// Bun runtime globals this process uses. The runtime executes under Bun, but
+// consuming apps type-check this source under node/DOM where the `Bun` global
+// is absent — so declare the surface we touch (mirrors the ambient in
+// ssr-client-bundler.ts). Keeps `tsc` clean in a scaffolded app.
+declare const Bun: {
+  write(destination: unknown, input: string): Promise<number>;
+  stdout: unknown;
+  stderr: unknown;
+  stdin: { stream(): ReadableStream<Uint8Array> };
+};
+
 // ---------------------------------------------------------------------------
 // Protocol types
 // ---------------------------------------------------------------------------

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

@@ -23,6 +23,7 @@ import * as os from "node:os";
 
 import {
   buildClientBundle,
+  nearestBoundaryComponent,
   type PylonBundleManifest,
 } from "./ssr-client-bundler";
 
@@ -234,3 +235,115 @@ describe("ssr-client-bundler (Phase 1.5e)", () => {
     expect(unique.size).toBe(1);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Client error/not-found boundary. Regression coverage for the blank-page bug:
+// a notFound() (or any error) thrown DURING a client render — the normal case
+// when an async lookup 404s after hydration — used to propagate uncaught and
+// blank the whole document because the client runtime wrapped pages in NO
+// error boundary. nearestBoundaryComponent() is the resolution the runtime
+// inlines; the build test guards the boundary wiring + not-found.tsx entry.
+// ---------------------------------------------------------------------------
+
+describe("nearestBoundaryComponent (client boundary resolution)", () => {
+  const routes = new Set([
+    "web/app/not-found",
+    "web/app/dashboard/not-found",
+    "web/app/dashboard/error",
+    "web/app/dashboard/orgs/[slug]/page",
+    "web/app/page",
+  ]);
+
+  test("returns the NEAREST ancestor boundary, not a farther one", () => {
+    // [slug]/page has no own boundary → nearest not-found is dashboard's,
+    // NOT the app-root one.
+    expect(
+      nearestBoundaryComponent(
+        "web/app/dashboard/orgs/[slug]/page",
+        "not-found",
+        routes,
+      ),
+    ).toBe("web/app/dashboard/not-found");
+  });
+
+  test("falls back to a farther ancestor when no nearer one exists", () => {
+    // A page outside /dashboard only has the app-root not-found.
+    expect(
+      nearestBoundaryComponent("web/app/page", "not-found", routes),
+    ).toBe("web/app/not-found");
+    // settings/page is under /dashboard but above no closer boundary → dashboard.
+    expect(
+      nearestBoundaryComponent(
+        "web/app/dashboard/settings/page",
+        "not-found",
+        routes,
+      ),
+    ).toBe("web/app/dashboard/not-found");
+  });
+
+  test("resolves error.tsx independently of not-found.tsx", () => {
+    expect(
+      nearestBoundaryComponent(
+        "web/app/dashboard/orgs/[slug]/page",
+        "error",
+        routes,
+      ),
+    ).toBe("web/app/dashboard/error");
+    // No error.tsx outside /dashboard → null (runtime renders its default).
+    expect(nearestBoundaryComponent("web/app/page", "error", routes)).toBeNull();
+  });
+
+  test("returns null when the app ships no boundary at all", () => {
+    expect(
+      nearestBoundaryComponent("web/app/page", "not-found", new Set(["web/app/page"])),
+    ).toBeNull();
+  });
+
+  test("does not match a boundary in a sibling/unrelated subtree", () => {
+    const r = new Set(["web/app/admin/not-found", "web/app/dashboard/page"]);
+    // dashboard/page must NOT pick up admin's not-found.
+    expect(
+      nearestBoundaryComponent("web/app/dashboard/page", "not-found", r),
+    ).toBeNull();
+  });
+});
+
+const NOT_FOUND_BODY = `
+import React from "react";
+export default function NotFound() {
+  return <div data-boundary="not-found">Not found</div>;
+}
+`;
+
+describe("client boundary is wired into the build", () => {
+  test("not-found.tsx gets its own manifest entry AND the runtime wraps pages in the error boundary", async () => {
+    tempDir = makeFixture(
+      {
+        "page.tsx": PAGE_BODY("Home"),
+        "dashboard/page.tsx": PAGE_BODY("Dash"),
+        "dashboard/not-found.tsx": NOT_FOUND_BODY,
+      },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    originalCwd = process.cwd();
+    process.chdir(tempDir);
+
+    const { manifestPath, outdir } = await buildClientBundle();
+    const manifest = JSON.parse(
+      fs.readFileSync(manifestPath, "utf8"),
+    ) as PylonBundleManifest;
+
+    // The not-found boundary must be a first-class route entry so the client
+    // can resolve + dynamically load it on a client-thrown notFound().
+    expect(manifest.routes["app/dashboard/not-found"]).toBeTruthy();
+
+    // The shared runtime chunk must contain the boundary wiring — without it,
+    // a client-thrown notFound() blanks the page (the bug this fixes).
+    const sharedChunks = fs
+      .readdirSync(path.join(outdir, "chunks"))
+      .map((n) => fs.readFileSync(path.join(outdir, "chunks", n), "utf8"));
+    const allShared = sharedChunks.join("\n");
+    expect(allShared).toContain("PYLON_NOT_FOUND");
+    expect(allShared).toContain("getDerivedStateFromError");
+  });
+});

package/src/ssr-client-bundler.ts

@@ -177,6 +177,39 @@ function discoverRoutes(
   }));
 }
 
+/**
+ * Resolve the nearest boundary module (`<dir>/not-found` or `<dir>/error`)
+ * for a route by walking its component path up to the app root, returning the
+ * first manifest route key that exists. Nearest ancestor wins — the same model
+ * the server's `findBoundary` uses, but driven off the client build manifest's
+ * route keys so the client runtime needs no extra server round-trip.
+ *
+ * Exported as the CANONICAL spec for the client error boundary: the runtime in
+ * `CLIENT_RUNTIME_SOURCE` inlines this exact walk (it can't import across the
+ * bundle), and `ssr-client-bundler.test.ts` exercises this function so a
+ * regression in the algorithm is caught here.
+ *
+ * `component` is a cwd-relative path with "/" separators and no extension
+ * (e.g. "web/app/dashboard/orgs/[slug]/page"); `routeKeys` is
+ * `Object.keys(manifest.routes)`.
+ */
+export function nearestBoundaryComponent(
+  component: string,
+  fileName: "not-found" | "error",
+  routeKeys: Iterable<string>,
+): string | null {
+  const keys = routeKeys instanceof Set ? routeKeys : new Set(routeKeys);
+  let dir = String(component);
+  dir = dir.includes("/") ? dir.slice(0, dir.lastIndexOf("/")) : "";
+  while (dir) {
+    const key = `${dir}/${fileName}`;
+    if (keys.has(key)) return key;
+    const slash = dir.lastIndexOf("/");
+    dir = slash >= 0 ? dir.slice(0, slash) : "";
+  }
+  return null;
+}
+
 /**
  * The shared hydration dispatcher + router. ONE module, imported
  * by every per-route entry. Bun's splitter sees N entries reach
@@ -204,7 +237,7 @@ function discoverRoutes(
 const CLIENT_RUNTIME_SOURCE = `// Generated by Pylon SSR (Phase 2 client runtime).
 // DO NOT EDIT — overwritten on every pylon dev / build.
 
-import { createElement } from "react";
+import { Component, createElement, useEffect, useState } from "react";
 import { hydrateRoot } from "react-dom/client";
 
 const routeCache = Object.create(null);
@@ -222,6 +255,185 @@ function buildTree(Page, Layouts, props) {
   return tree;
 }
 
+// ---------------------------------------------------------------------------
+// Client error / not-found boundary. notFound() (from @pylonsync/react) and
+// any other error thrown DURING a client render — the normal case when an
+// async lookup 404s after hydration — would otherwise propagate uncaught and
+// blank the whole document. React error boundaries must be class components;
+// this one catches the throw, resolves the nearest not-found.tsx / error.tsx
+// for the active route from the build manifest (the same nearest-ancestor
+// model the server's findBoundary uses), and renders it in its own layout
+// chain. It sits at the root and is transparent until something throws, so
+// hydration still matches the server HTML exactly. It resets on navigation
+// via a changing navEpoch prop (NOT a key — a key change would remount every
+// layout on each nav and lose their state).
+// ---------------------------------------------------------------------------
+
+let navEpoch = 0;
+
+// Walk up the active route's component path to the nearest boundary module
+// (<dir>/not-found or <dir>/error) present in the manifest. Manifest route
+// keys are cwd-relative component paths with "/" separators (e.g.
+// "web/app/dashboard/not-found"), so no platform normalization is needed.
+// MUST stay in lockstep with the exported nearestBoundaryComponent() — that
+// function is the tested spec for this exact walk.
+async function resolveBoundaryComponent(component, fileName) {
+  const manifest = await loadManifest();
+  if (!manifest || !manifest.routes || !component) return null;
+  let dir = String(component);
+  dir = dir.includes("/") ? dir.slice(0, dir.lastIndexOf("/")) : "";
+  while (dir) {
+    const key = dir + "/" + fileName;
+    if (manifest.routes[key]) return key;
+    const slash = dir.lastIndexOf("/");
+    dir = slash >= 0 ? dir.slice(0, slash) : "";
+  }
+  return null;
+}
+
+// Last-resort body when the app ships no not-found.tsx / error.tsx anywhere.
+// Renders a full <html> document so it can replace the document root cleanly
+// (the normal path renders the app's boundary wrapped in the root layout,
+// which also owns <html>).
+function DefaultBoundary(props) {
+  const isNF = props.kind === "not-found";
+  return createElement(
+    "html",
+    { lang: "en" },
+    createElement(
+      "head",
+      null,
+      createElement("meta", { charSet: "utf-8" }),
+      createElement("title", null, isNF ? "404 — Not found" : "Something went wrong"),
+    ),
+    createElement(
+      "body",
+      {
+        style: {
+          margin: 0,
+          minHeight: "100vh",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          fontFamily: "system-ui, -apple-system, sans-serif",
+        },
+      },
+      createElement(
+        "div",
+        { style: { textAlign: "center", padding: "2rem" } },
+        createElement(
+          "h1",
+          { style: { fontSize: "1.375rem", margin: "0 0 0.5rem" } },
+          isNF ? "404 — Not found" : "Something went wrong",
+        ),
+        createElement(
+          "p",
+          { style: { color: "#666", margin: "0 0 1.25rem" } },
+          isNF
+            ? "This page doesn't exist or was moved."
+            : "An unexpected error occurred.",
+        ),
+        createElement(
+          "a",
+          { href: "/", style: { color: "#0969da", textDecoration: "none" } },
+          "\\u2190 Go home",
+        ),
+      ),
+    ),
+  );
+}
+
+// Lazily resolves + renders the boundary component in its own layout chain.
+// Renders nothing for the brief moment before the (usually already-cached)
+// entry loads, then the styled boundary — far better than a permanent blank.
+function BoundaryView(props) {
+  const { component, kind, error, reset } = props;
+  const [resolved, setResolved] = useState(null);
+  useEffect(() => {
+    let cancelled = false;
+    const fileName = kind === "not-found" ? "not-found" : "error";
+    (async () => {
+      const comp = await resolveBoundaryComponent(component, fileName);
+      if (cancelled) return;
+      if (!comp) {
+        setResolved({ missing: true });
+        return;
+      }
+      try {
+        const entry = await loadRouteEntry(comp);
+        if (!cancelled) setResolved({ entry });
+      } catch {
+        if (!cancelled) setResolved({ missing: true });
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [component, kind]);
+  if (!resolved) return null;
+  if (resolved.missing) return createElement(DefaultBoundary, { kind });
+  const bProps = {
+    params: currentParams,
+    searchParams: Object.fromEntries(new URLSearchParams(location.search)),
+    url: location.pathname + location.search,
+    reset,
+  };
+  // error.tsx receives the SAFE error projection (message + digest) — never a
+  // raw Error/stack, matching the server boundary's #270 posture.
+  if (kind === "error" && error) {
+    bProps.error = {
+      message: String((error && error.message) || error),
+      digest: error && error.digest,
+    };
+  }
+  return buildTree(resolved.entry.Page, resolved.entry.Layouts, bProps);
+}
+
+class PylonBoundary extends Component {
+  constructor(p) {
+    super(p);
+    this.state = { err: null };
+  }
+  static getDerivedStateFromError(err) {
+    return { err };
+  }
+  componentDidUpdate(prev) {
+    // A navigation bumps navEpoch — clear a prior error so the freshly
+    // rendered children (the new page) show instead of the stale boundary.
+    if (prev.navEpoch !== this.props.navEpoch && this.state.err) {
+      this.setState({ err: null });
+    }
+  }
+  componentDidCatch(err) {
+    // notFound() is expected control flow, not a crash — keep it quiet.
+    // Genuine errors stay loud.
+    if (!(err && err.digest === "PYLON_NOT_FOUND")) {
+      console.error("[pylon ssr] render error caught by boundary:", err);
+    }
+  }
+  render() {
+    const err = this.state.err;
+    if (!err) return this.props.children;
+    const kind = err.digest === "PYLON_NOT_FOUND" ? "not-found" : "error";
+    const self = this;
+    return createElement(BoundaryView, {
+      component: this.props.component,
+      kind,
+      error: err,
+      reset() {
+        self.setState({ err: null });
+        navigate(location.pathname + location.search, { replace: true });
+      },
+    });
+  }
+}
+
+// Wrap a page tree in the root boundary. navEpoch (a prop, not a key) lets the
+// boundary clear its error on navigation without remounting the layouts.
+function withBoundary(tree, component) {
+  return createElement(PylonBoundary, { navEpoch, component }, tree);
+}
+
 // Deterministic stringify — MUST match stableStringify in ssr-runtime.ts so
 // a serverData call's cache key is identical on server and client.
 function stableStringify(v) {
@@ -420,7 +632,10 @@ export function hydrate(component, Page, Layouts) {
       return;
     }
     setNavParams(data);
-    const tree = buildTree(Page, Layouts, withClientProps(data));
+    const tree = withBoundary(
+      buildTree(Page, Layouts, withClientProps(data)),
+      data.component,
+    );
     activeRoot = hydrateRoot(document, tree);
     installNavHandlers();
     return;
@@ -497,7 +712,11 @@ async function navigate(href, opts) {
   document.title = doc.title || document.title;
   syncHeadMeta(doc);
   setNavParams(data);
-  const tree = buildTree(route.Page, route.Layouts, withClientProps(data));
+  navEpoch++;
+  const tree = withBoundary(
+    buildTree(route.Page, route.Layouts, withClientProps(data)),
+    data.component,
+  );
   activeRoot.render(tree);
   const target = url.pathname + url.search;
   if (opts && opts.replace) {
@@ -759,30 +978,20 @@ async function buildTailwind(
     );
   }
 
-  // Hash the source content so we can name the output uniquely +
-  // serve it with long-cache immutable headers.
-  const src = fs.readFileSync(globalsPath, "utf8");
-  let hash = 0;
-  for (let i = 0; i < src.length; i++) {
-    hash = (hash * 31 + src.charCodeAt(i)) >>> 0;
-  }
-  // Mix in the discovered routes so adding/removing pages changes
-  // the hash (Tailwind v4 auto-discovers `@source` paths; we still
-  // want the cache to bust on layout changes).
+  // Compile to a temp file first, then name the asset by a hash of the
+  // COMPILED OUTPUT — NOT the source. Hashing `globals.css` was the wrong
+  // input: adding a Tailwind class in any component regenerates the CSS but
+  // leaves globals.css untouched, so the `styles-<hash>.css` filename never
+  // changed and browsers / CDNs kept serving the STALE stylesheet (missing the
+  // new classes — dropdowns rendered unstyled, etc.). The compiled output, by
+  // contrast, changes iff a scanned class changes: its hash busts the cache
+  // exactly when it must, and stays identical (cache stays warm) otherwise.
   //
-  // Pad the base36 hash to 8 chars: the runtime's `is_hashed_name`
-  // (frontend.rs) only sends `Cache-Control: immutable` for hashes ≥8
-  // chars (Bun's JS chunk convention). A 32-bit base36 hash is ≤7 chars,
-  // so WITHOUT the pad the content-hashed CSS was served `no-cache` —
-  // browsers + any CDN refetched it on every page load (defeats the cache
-  // and, behind Cloudflare, needlessly wakes an autostopped origin).
-  const stylesName = `styles-${hash.toString(36).padStart(8, "0")}.css`;
-  const outPath = path.join(outdir, stylesName);
-
-  // Spawn the CLI. Bun is already running; reuse it as the
-  // interpreter so the user doesn't need node on PATH.
+  // 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");
   const proc = (Bun as any).spawn({
-    cmd: [process.execPath, cliPath, "-i", globalsPath, "-o", outPath, "--minify"],
+    cmd: [process.execPath, cliPath, "-i", globalsPath, "-o", tmpPath, "--minify"],
     cwd,
     stdout: "pipe",
     stderr: "pipe",
@@ -792,6 +1001,34 @@ async function buildTailwind(
     const err = await new Response(proc.stderr).text();
     throw new Error(`tailwindcss build failed (exit ${exitCode}): ${err}`);
   }
+
+  const out = fs.readFileSync(tmpPath, "utf8");
+  let hash = 0;
+  for (let i = 0; i < out.length; i++) {
+    hash = (hash * 31 + out.charCodeAt(i)) >>> 0;
+  }
+  // Pad the base36 hash to 8 chars: the runtime's `is_hashed_name`
+  // (frontend.rs) only sends `Cache-Control: immutable` for hashes ≥8 chars
+  // (Bun's JS chunk convention). A 32-bit base36 hash is ≤7 chars, so without
+  // the pad the content-hashed CSS would be served `no-cache` — browsers + any
+  // CDN would refetch it on every page load (and, behind Cloudflare, wake an
+  // autostopped origin).
+  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.
+  try {
+    for (const f of fs.readdirSync(outdir) as string[]) {
+      if (f.startsWith("styles-") && f.endsWith(".css")) {
+        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;
 }
 

package/src/ssr-runtime.ts

@@ -7,6 +7,12 @@
 // the dispatch arm) so projects without SSR routes pay nothing — no
 // react-dom dependency requirement, no startup cost.
 
+// 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: {
+  resolveSync?(specifier: string, from: string): string;
+};
+
 /**
  * Is the runtime in dev mode? MUST match the Rust host's `is_dev_mode()`
  * (crates/runtime/src/frontend.rs): `PYLON_DEV_MODE` is on ONLY for the exact