@pylonsync/functions 0.3.247 → 0.3.249

package/package.json

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

package/src/runtime.ts

@@ -236,6 +236,24 @@ function dispatch(line: string): void {
             String(err),
         });
       });
+  } else if (msg.type === "handle_form") {
+    // route.ts form/method handler (#276) — lazy-imported like SSR so
+    // projects without route handlers pay nothing on startup.
+    import("./ssr-form-runtime")
+      .then((mod) =>
+        mod.handleForm(
+          msg as unknown as Parameters<typeof mod.handleForm>[0],
+          send,
+        ),
+      )
+      .catch((err) => {
+        send({
+          type: "error",
+          call_id: (msg as unknown as { call_id: string }).call_id,
+          code: "SSR_FORM_RUNTIME_CRASH",
+          message: err?.message || String(err),
+        });
+      });
   } else if (msg.type === "bundle_client") {
     // Hydration — build the client-side bundle once and report
     // the path back. Lazy-imported for the same reason as SSR.
@@ -426,7 +444,7 @@ export function buildDbReader(callId: string, unsafeOp = false): DbReader {
   return reader;
 }
 
-function buildDbWriter(callId: string, unsafeOp = false): DbWriter {
+export function buildDbWriter(callId: string, unsafeOp = false): DbWriter {
   // Drop the reader's `unsafe` shortcut before spreading — the
   // writer needs its own (which we attach below). Without this
   // strip, `writer.unsafe` would be a DbReader and the type

package/src/ssr-client-bundler.ts

@@ -130,6 +130,22 @@ function discoverRoutes(
         layouts: nextLayouts,
       });
     }
+    // Boundary modules (not-found.tsx / error.tsx) are hydrated like pages
+    // (#279) so onClick/useState/reset() work — that means each needs its own
+    // client entry + manifest key, keyed by component path exactly like a page.
+    // They wrap in the layouts ABOVE them (nextLayouts), same as a page here.
+    for (const base of ["not-found", "error"]) {
+      const bHere = [`${base}.tsx`, `${base}.ts`, `${base}.jsx`, `${base}.js`]
+        .map((n: string) => path.join(dir, n))
+        .find((p: string) => fs.existsSync(p));
+      if (bHere) {
+        pages.push({
+          segments: [...segments],
+          component: path.relative(cwd, bHere).replace(/\.(tsx?|jsx?)$/, ""),
+          layouts: nextLayouts,
+        });
+      }
+    }
     for (const e of entries) {
       if (!e.isDirectory()) continue;
       if (e.name.startsWith(".") || e.name === "node_modules") continue;
@@ -271,10 +287,18 @@ function makeNoopResponse() {
 
 // Rehydrate the live, server-only props (serverData + response) that were
 // stripped before serialization, so the client tree matches the server's.
+// For a hydrated error boundary (#279), synthesize the reset() the server
+// rendered as a no-op: re-fetch + re-render the current URL (a transient
+// error clears to the page; a deterministic one re-shows the boundary).
 function withClientProps(data) {
   const props = { ...(data.props || {}) };
   props.serverData = makeClientServerData(data.ssrData);
   props.response = makeNoopResponse();
+  if (data.kind === "error") {
+    props.reset = function () {
+      navigate(location.pathname + location.search, { replace: true });
+    };
+  }
   return props;
 }
 
@@ -486,6 +510,52 @@ function installNavHandlers() {
   window.addEventListener("popstate", () => {
     navigate(location.pathname + location.search, { push: false });
   });
+  // Progressive-enhancement form submit (#276): intercept <form data-pylon-form>
+  // so the page doesn't full-reload. fetch the same route.ts endpoint, follow
+  // the handler's redirect, and swap the destination in via navigate(). Without
+  // JS this listener never runs and the browser submits natively (POST →
+  // handler → 303 → GET) — identical result, just a full navigation.
+  document.addEventListener("submit", (e) => {
+    if (e.defaultPrevented) return;
+    const form = e.target;
+    if (!form || form.tagName !== "FORM") return;
+    if (!form.hasAttribute("data-pylon-form")) return;
+    const action = form.getAttribute("action");
+    if (!action) return;
+    // Off-origin actions / new-tab targets → let the browser submit.
+    if (action.startsWith("http://") || action.startsWith("https://") || action.startsWith("//")) return;
+    const tgt = form.getAttribute("target");
+    if (tgt && tgt !== "" && tgt !== "_self") return;
+    const method = (form.getAttribute("method") || "post").toUpperCase();
+    e.preventDefault();
+    // urlencoded body (matches the server's parser; files use the native path).
+    const body = new URLSearchParams();
+    const fd = new FormData(form);
+    fd.forEach((v, k) => {
+      if (typeof v === "string") body.append(k, v);
+    });
+    fetch(action, {
+      method,
+      body,
+      credentials: "same-origin",
+      headers: { Accept: "text/html" },
+    })
+      .then((res) => {
+        // fetch followed the handler's 303 → res.url is the destination page.
+        // Drive a client navigation to it (re-renders without a full reload).
+        const dest = new URL(res.url || action, location.href);
+        if (dest.origin === location.origin) {
+          navigate(dest.pathname + dest.search);
+        } else {
+          window.location.href = dest.href;
+        }
+      })
+      .catch(() => {
+        // Network/abort — fall back to a native submit so the user isn't stuck.
+        form.removeAttribute("data-pylon-form");
+        form.submit();
+      });
+  });
 }
 
 // Expose for <Link> component prefetch.

package/src/ssr-form-runtime.ts

@@ -0,0 +1,188 @@
+// route.ts form/method handler runtime (#276). Invoked by runtime.ts when the
+// host sends a "handle_form" message. Imports the route.ts module, picks the
+// handler by HTTP method, runs it with the parsed form + a read/write `db` +
+// the SsrResponse controller, and replies over the SAME response_start /
+// render_done protocol a render uses. A handler's common job is
+// POST-redirect-GET: write something, then `response.redirect("/x?ok=1")`
+// (303 by default here) so the no-JS browser follows with a GET.
+import {
+  makeResponseController,
+  PylonRouteControl,
+  finalizeHeaders,
+  importModule,
+  type ResponseState,
+} from "./ssr-runtime";
+import { buildDbWriter } from "./runtime";
+
+/** Matches HandleFormMessage in crates/functions/src/protocol.rs. */
+export interface HandleFormMessage {
+  type: "handle_form";
+  call_id: string;
+  component: string;
+  route_path: string;
+  method: string;
+  url: string;
+  params: Record<string, string>;
+  search_params: Record<string, string>;
+  form: Record<string, string | string[]>;
+  headers: Record<string, string>;
+  cookies: Record<string, string>;
+  auth: {
+    user_id: string | null;
+    is_admin: boolean;
+    tenant_id: string | null;
+    roles: string[];
+  };
+}
+
+type Send = (msg: Record<string, unknown>) => void;
+
+/** Parsed form fields. Mirrors URLSearchParams get/getAll/has semantics. */
+export interface FormFields {
+  /** First value for `name`, or null. */
+  get(name: string): string | null;
+  /** All values for `name` (empty array if none). */
+  getAll(name: string): string[];
+  has(name: string): boolean;
+  /** Raw map: name → value | values. */
+  readonly fields: Record<string, string | string[]>;
+}
+
+function makeFormFields(raw: Record<string, string | string[]>): FormFields {
+  return {
+    get(name) {
+      const v = raw[name];
+      if (v == null) return null;
+      return Array.isArray(v) ? (v.length > 0 ? v[0] : null) : v;
+    },
+    getAll(name) {
+      const v = raw[name];
+      if (v == null) return [];
+      return Array.isArray(v) ? v : [v];
+    },
+    has(name) {
+      return Object.prototype.hasOwnProperty.call(raw, name);
+    },
+    fields: raw,
+  };
+}
+
+const HANDLER_METHODS = ["POST", "PUT", "PATCH", "DELETE"] as const;
+const b64 = (s: string) => Buffer.from(s, "utf8").toString("base64");
+const isDev = () =>
+  process.env.PYLON_DEV_MODE === "1" || process.env.PYLON_DEV_MODE === "true";
+
+export async function handleForm(
+  msg: HandleFormMessage,
+  send: Send,
+): Promise<void> {
+  const cwd = process.cwd();
+  // Default 303 See Other — the correct POST-redirect-GET status for a form
+  // (307 would re-issue the POST to the redirect target).
+  const responseState: ResponseState = { status: 303, headers: {}, cookies: [] };
+  const response = makeResponseController(responseState, 303);
+  const req = {
+    form: makeFormFields(msg.form ?? {}),
+    params: msg.params,
+    searchParams: msg.search_params,
+    auth: msg.auth,
+    cookies: msg.cookies,
+    headers: msg.headers,
+    // Read+write DB handle (mutation-shaped; the host answers writes against a
+    // broadcast-capable store). serverData (read-only) isn't given — a handler
+    // writes via `db` and the developer enforces trust with `req.auth`.
+    db: buildDbWriter(msg.call_id),
+    response,
+  };
+
+  let mod: any;
+  try {
+    mod = await importModule(cwd, msg.component);
+  } catch (e: any) {
+    send({
+      type: "error",
+      call_id: msg.call_id,
+      code: "SSR_FORM_IMPORT_FAILED",
+      message: isDev() && e?.stack ? String(e.stack) : e?.message ?? String(e),
+    });
+    return;
+  }
+
+  const method = (msg.method || "POST").toUpperCase();
+  const handler = mod[method];
+  if (typeof handler !== "function") {
+    // 405 — advertise the methods this route.ts actually exports.
+    const allow = HANDLER_METHODS.filter(
+      (m) => typeof mod[m] === "function",
+    ).join(", ");
+    send({
+      type: "response_start",
+      call_id: msg.call_id,
+      status: 405,
+      headers: {
+        "content-type": "text/plain; charset=utf-8",
+        ...(allow ? { allow } : {}),
+      },
+    });
+    send({
+      type: "render_chunk",
+      call_id: msg.call_id,
+      data: b64(`Method ${method} not allowed`),
+    });
+    send({ type: "render_done", call_id: msg.call_id });
+    return;
+  }
+
+  try {
+    await handler(req);
+    // No redirect()/notFound() thrown → commit the handler's response: its
+    // status (default 303) + headers + cookies. A 303 with no explicit
+    // Location redirects back to the route path (POST-redirect-GET).
+    const extra: Record<string, string> = {};
+    if (responseState.status === 303 && !responseState.headers["location"]) {
+      extra["location"] = msg.route_path || "/";
+    }
+    send({
+      type: "response_start",
+      call_id: msg.call_id,
+      status: responseState.status,
+      headers: finalizeHeaders(responseState, extra),
+    });
+    send({ type: "render_done", call_id: msg.call_id });
+  } catch (err: any) {
+    // response.redirect()/notFound() throw PylonRouteControl — turn into a
+    // 3xx + Location / 404, carrying any cookies the handler set first.
+    if (err instanceof PylonRouteControl) {
+      if (err.kind === "redirect") {
+        send({
+          type: "response_start",
+          call_id: msg.call_id,
+          status: err.redirectStatus ?? 303,
+          headers: finalizeHeaders(responseState, { location: err.url ?? "/" }),
+        });
+        send({ type: "render_done", call_id: msg.call_id });
+        return;
+      }
+      send({
+        type: "response_start",
+        call_id: msg.call_id,
+        status: 404,
+        headers: finalizeHeaders(responseState),
+      });
+      send({
+        type: "render_chunk",
+        call_id: msg.call_id,
+        data: b64("Not found"),
+      });
+      send({ type: "render_done", call_id: msg.call_id });
+      return;
+    }
+    send({
+      type: "error",
+      call_id: msg.call_id,
+      code: err?.code ?? "SSR_FORM_FAILED",
+      message:
+        isDev() && err?.stack ? String(err.stack) : err?.message ?? String(err),
+    });
+  }
+}

package/src/ssr-runtime.test.ts

@@ -4,7 +4,22 @@ import { afterEach, describe, expect, test } from "bun:test";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { applyAutoIcons, applyAutoSocialImages, renderMetadata } from "./ssr-runtime";
+import {
+  applyAutoIcons,
+  applyAutoSocialImages,
+  renderMetadata,
+  buildHydrationTail,
+  errorDigest,
+} from "./ssr-runtime";
+
+// Pull the JSON out of the `__PYLON_DATA__` <script> a hydration tail emits.
+function extractPylonData(tail: string): any {
+  const m = tail.match(
+    /<script id="__PYLON_DATA__" type="application\/json">([\s\S]*?)<\/script>/,
+  );
+  if (!m) throw new Error("no __PYLON_DATA__ in tail");
+  return JSON.parse(m[1]); // JSON.parse natively decodes the < escaping
+}
 
 // `react` isn't a dependency of @pylonsync/functions — the SSR runtime
 // imports it dynamically from the host project at render time. For unit
@@ -226,3 +241,107 @@ describe("renderMetadata head-tag marking (client-nav sync)", () => {
     expect(renderMetadata(fakeReact, {})).toBeNull();
   });
 });
+
+describe("buildHydrationTail — boundary hydration (#279) + strip (#270)", () => {
+  const manifestRoute = { file: "app__error-x.js", imports: [], css: [] };
+
+  test("error boundary serializes {message,digest}; raw error/stack/cookies NEVER cross the wire", () => {
+    const tail = buildHydrationTail({
+      component: "app/error",
+      layouts: ["app/layout"],
+      props: {
+        url: "/boom",
+        auth: { user_id: "u1", is_admin: false, tenant_id: null, roles: [] },
+        // live, non-serializable + sensitive handles that MUST be stripped:
+        error: new Error("DB exploded at secretHost:5432"),
+        serverData: { get() {} },
+        response: { setStatus() {} },
+        reset: () => {},
+        headers: { cookie: "pylon_session=SUPERSECRET" },
+        cookies: { pylon_session: "SUPERSECRET" },
+      },
+      ssrData: {},
+      manifestRoute,
+      publicPrefix: "/_pylon/build/",
+      manifestErr: null,
+      kind: "error",
+      errorForClient: { message: "Something went wrong", digest: "deadbeef" },
+    });
+    const data = extractPylonData(tail);
+    expect(data.kind).toBe("error");
+    expect(data.component).toBe("app/error");
+    // The client error.tsx gets ONLY the safe projection.
+    expect(data.props.error).toEqual({
+      message: "Something went wrong",
+      digest: "deadbeef",
+    });
+    // Live handles stripped; headers/cookies emptied (shape preserved).
+    expect(data.props.serverData).toBeUndefined();
+    expect(data.props.response).toBeUndefined();
+    expect(data.props.reset).toBeUndefined();
+    expect(data.props.headers).toEqual({});
+    expect(data.props.cookies).toEqual({});
+    // The session cookie + the raw error message/stack are nowhere in the blob.
+    expect(tail).not.toContain("SUPERSECRET");
+    expect(tail).not.toContain("secretHost");
+    expect(tail).not.toContain("stack");
+    // The per-boundary entry script is appended.
+    expect(tail).toContain('src="/_pylon/build/app__error-x.js"');
+  });
+
+  test("not-found boundary carries kind but no error/reset", () => {
+    const tail = buildHydrationTail({
+      component: "app/not-found",
+      layouts: [],
+      props: { url: "/missing", auth: {}, response: {}, serverData: {} },
+      ssrData: {},
+      manifestRoute,
+      publicPrefix: "/_pylon/build/",
+      manifestErr: null,
+      kind: "not-found",
+    });
+    const data = extractPylonData(tail);
+    expect(data.kind).toBe("not-found");
+    expect(data.props.error).toBeUndefined();
+    expect(data.props.reset).toBeUndefined();
+  });
+
+  test("a page (no kind) hydrates without a kind field", () => {
+    const tail = buildHydrationTail({
+      component: "app/page",
+      layouts: ["app/layout"],
+      props: { url: "/", auth: {}, response: {}, serverData: {} },
+      ssrData: { "list:Note": [] },
+      manifestRoute,
+      publicPrefix: "/_pylon/build/",
+      manifestErr: null,
+    });
+    const data = extractPylonData(tail);
+    expect(data.kind).toBeUndefined();
+    expect(data.ssrData).toEqual({ "list:Note": [] });
+  });
+
+  test("no manifest entry → hydration-disabled warning, not an entry script", () => {
+    const tail = buildHydrationTail({
+      component: "app/page",
+      layouts: [],
+      props: { url: "/" },
+      ssrData: {},
+      manifestRoute: null,
+      publicPrefix: "/_pylon/build/",
+      manifestErr: "manifest crashed",
+    });
+    expect(tail).toContain("hydration disabled");
+    expect(tail).not.toContain('type="module" src=');
+  });
+
+  test("errorDigest is deterministic, stack-free, 8 hex chars", () => {
+    const e = new Error("boom");
+    const d1 = errorDigest(e);
+    const d2 = errorDigest(e);
+    expect(d1).toBe(d2);
+    expect(d1).toMatch(/^[0-9a-f]{8}$/);
+    // A different error yields a different digest.
+    expect(errorDigest(new Error("other"))).not.toBe(d1);
+  });
+});

package/src/ssr-runtime.ts

@@ -75,7 +75,7 @@ type Send = (msg: Record<string, unknown>) => void;
  * it's thrown during the shell render. (Throw it OUTSIDE an error
  * boundary — an enclosing boundary would swallow the signal.)
  */
-class PylonRouteControl extends Error {
+export class PylonRouteControl extends Error {
   kind: "redirect" | "notFound";
   url?: string;
   redirectStatus?: number;
@@ -146,7 +146,7 @@ function serializeCookie(
   return c;
 }
 
-interface ResponseState {
+export interface ResponseState {
   status: number;
   headers: Record<string, string>;
   cookies: string[];
@@ -184,7 +184,14 @@ export interface SsrResponse {
   notFound(): never;
 }
 
-function makeResponseController(state: ResponseState): SsrResponse {
+// `defaultRedirectStatus` is the status `response.redirect(url)` uses when the
+// caller doesn't pass one: 307 for a page render (preserve the method on the
+// rare redirecting GET), 303 for a route.ts form handler (POST-redirect-GET —
+// the browser must follow with a GET, not re-POST).
+export function makeResponseController(
+  state: ResponseState,
+  defaultRedirectStatus = 307,
+): SsrResponse {
   return {
     setStatus(code) {
       if (!Number.isInteger(code) || code < 100 || code > 599) {
@@ -204,7 +211,7 @@ function makeResponseController(state: ResponseState): SsrResponse {
     setCookie(name, value, opts) {
       state.cookies.push(serializeCookie(name, value, opts));
     },
-    redirect(url, status = 307): never {
+    redirect(url, status = defaultRedirectStatus): never {
       assertNoControlChars(url, "redirect url");
       if (!Number.isInteger(status) || status < 300 || status > 399) {
         throw new Error(`pylon ssr: redirect() status must be 3xx, got ${status}`);
@@ -226,7 +233,7 @@ function makeResponseController(state: ResponseState): SsrResponse {
  * into one `Set-Cookie` header each (newline is forbidden inside a
  * cookie, so it can't be turned into header injection).
  */
-function finalizeHeaders(
+export function finalizeHeaders(
   state: ResponseState,
   extra?: Record<string, string>,
 ): Record<string, string> {
@@ -373,7 +380,7 @@ 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. */
-async function importModule(cwd: string, relPath: string): Promise<any> {
+export async function importModule(cwd: string, relPath: string): Promise<any> {
   const base = `${cwd}/${relPath}`;
   let lastErr: unknown = null;
   for (const ext of MODULE_EXTS) {
@@ -792,11 +799,116 @@ async function collectBoundaryHeadBlob(): Promise<string> {
 }
 
 /**
- * Render a boundary (not-found/error) tree and stream it as the response
- * body at `status`. Boundaries render server-side only (no hydration
- * payload) — they're informational pages, consistent with the keystone's
- * fixed 404 body that this replaces — but they DO get the app's global
- * stylesheet injected so they match the rest of the site.
+ * Build the hydration tail appended after React's stream EOFs: the
+ * `__PYLON_DATA__` JSON blob (props + ssrData) + the per-route entry
+ * `<script>` that hydrates it, + (dev) the live-reload snippet. Shared by the
+ * page render AND the now-hydrated boundary render (#279) so a boundary
+ * hydrates through the EXACT same path as a page.
+ *
+ * `kind` marks an error/not-found boundary so the client knows whether to
+ * synthesize a `reset()`. For an error boundary, `errorForClient` is the SAFE
+ * projection ({message, digest}) — the raw `Error` (and its stack) is NEVER
+ * serialized (the dev overlay owns dev stacks; preserves the #270 posture).
+ */
+export function buildHydrationTail(args: {
+  component: string;
+  layouts: string[];
+  props: any;
+  ssrData: Record<string, any>;
+  manifestRoute: { file: string; imports: string[]; css: string[] } | null;
+  publicPrefix: string;
+  manifestErr: string | null;
+  kind?: "error" | "not-found";
+  errorForClient?: { message: string; digest?: string };
+}): string {
+  // Strip live, non-serializable handles (serverData / response / reset) + the
+  // request headers/cookies (SECURITY: never expose the session cookie to
+  // client JS — see #270). The raw `error` Error is dropped too; an error
+  // boundary's client-visible error rides in `errorForClient` instead.
+  const {
+    serverData: _sd,
+    response: _resp,
+    reset: _reset,
+    headers: _h,
+    cookies: _c,
+    error: _err,
+    ...restProps
+  } = args.props ?? {};
+  const serializableProps: any = { ...restProps, headers: {}, cookies: {} };
+  if (args.errorForClient) serializableProps.error = args.errorForClient;
+  const hydrationPayload: any = {
+    component: args.component,
+    layouts: args.layouts ?? [],
+    props: serializableProps,
+    ssrData: args.ssrData,
+  };
+  if (args.kind) hydrationPayload.kind = args.kind;
+  // Escape `<` (closes a </script> breakout) + U+2028/U+2029 (JSON-valid but
+  // JS statement terminators). Regex form keeps the separators visible in
+  // source rather than as invisible literals.
+  const json = JSON.stringify(hydrationPayload)
+    .replace(/</g, "\\u003c")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+  let tail = `<script id="__PYLON_DATA__" type="application/json">${json}</script>`;
+  if (args.manifestRoute) {
+    tail += `<script type="module" src="${args.publicPrefix}${args.manifestRoute.file}"></script>`;
+  } else {
+    tail += `<script>console.warn(${JSON.stringify(`[pylon ssr] hydration disabled: ${args.manifestErr}`)})</script>`;
+  }
+  if (process.env.PYLON_DEV_MODE) tail += DEV_LIVE_RELOAD_SNIPPET;
+  return tail;
+}
+
+/**
+ * The layout chain for a component, walked top-down from `app/` to the
+ * component's own directory — IDENTICAL to the bundler's `discoverRoutes`
+ * accumulation (and the SDK's `discoverAppRoutes`). A boundary's hydration
+ * needs the SERVER tree wrapped in the SAME layouts the bundler baked into
+ * its client entry; the catch path otherwise has only the failing PAGE's
+ * layouts, which would mismatch a root boundary covering a nested page.
+ */
+function resolveLayoutChain(componentRelPath: string, cwd: string): string[] {
+  const fs = require("node:fs");
+  const path = require("node:path");
+  const rel = componentRelPath.replace(/\\/g, "/");
+  const dir = rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "";
+  const parts = dir.split("/").filter(Boolean);
+  const layouts: 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;
+      }
+    }
+  }
+  return layouts;
+}
+
+/**
+ * A short, non-reversible correlation id for an error — surfaced to the
+ * client error boundary as `error.digest` (matching server logs) WITHOUT
+ * carrying any stack content. FNV-1a over message+stack, 8 hex chars.
+ */
+export function errorDigest(err: any): string {
+  const s = `${err?.message ?? ""}\n${err?.stack ?? ""}`;
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+
+/**
+ * Render a boundary (not-found/error) tree, stream it at `status`, and —
+ * when the boundary has a client bundle entry (#279) — append the hydration
+ * tail so onClick/useState/`reset()` work. With no manifest entry the
+ * boundary still renders (server-only, styled) — CSS/hydration must never
+ * block the error path.
  */
 async function renderBoundaryToClient(
   React: any,
@@ -806,6 +918,14 @@ async function renderBoundaryToClient(
   callId: string,
   status: number,
   headers: Record<string, string>,
+  tail?: {
+    component: string;
+    layouts: string[];
+    props: any;
+    ssrData: Record<string, any>;
+    kind: "error" | "not-found";
+    errorForClient?: { message: string; digest?: string };
+  },
 ): Promise<void> {
   const stream: ReadableStream<Uint8Array> = await renderToReadableStream(tree, {
     onError(e: unknown) {
@@ -813,7 +933,35 @@ async function renderBoundaryToClient(
       console.error("[ssr] boundary render error:", e);
     },
   });
-  const headBlob = await collectBoundaryHeadBlob();
+  // Resolve the boundary's own client entry (keyed by its component path) so
+  // the head gets ITS css/modulepreloads and the body-tail loads ITS script.
+  let manifestRoute:
+    | { file: string; imports: string[]; css: string[] }
+    | null = null;
+  let publicPrefix = "/_pylon/build/";
+  let headBlob = "";
+  if (tail) {
+    try {
+      const { getManifest } = await import("./ssr-client-bundler");
+      const manifest = await getManifest();
+      publicPrefix = manifest.public_prefix || publicPrefix;
+      manifestRoute = manifest.routes[tail.component] ?? null;
+    } catch {
+      manifestRoute = null;
+    }
+  }
+  if (manifestRoute) {
+    for (const css of manifestRoute.css) {
+      headBlob += `<link rel="stylesheet" href="${publicPrefix}${css}">`;
+    }
+    for (const chunk of manifestRoute.imports) {
+      headBlob += `<link rel="modulepreload" href="${publicPrefix}${chunk}">`;
+    }
+  } else {
+    // No per-boundary entry → fall back to the global stylesheet union so the
+    // page is at least styled (static).
+    headBlob = await collectBoundaryHeadBlob();
+  }
   // renderToReadableStream resolved without throwing → safe to commit the
   // head now, then drain the (already-rendered) shell, injecting CSS.
   send({ type: "response_start", call_id: callId, status, headers });
@@ -826,6 +974,20 @@ async function renderBoundaryToClient(
     });
   };
   await streamWithHeadInjection(stream.getReader(), headBlob, sendChunk);
+  if (tail && manifestRoute) {
+    const tailHtml = buildHydrationTail({
+      component: tail.component,
+      layouts: tail.layouts,
+      props: tail.props,
+      ssrData: tail.ssrData,
+      manifestRoute,
+      publicPrefix,
+      manifestErr: null,
+      kind: tail.kind,
+      errorForClient: tail.errorForClient,
+    });
+    sendChunk(tailHtml);
+  }
   send({ type: "render_done", call_id: callId });
 }
 
@@ -848,7 +1010,7 @@ async function tryRenderBoundary(
     headers: Record<string, string>;
   },
 ): Promise<boolean> {
-  const { React, renderToReadableStream, cwd, componentPath, fileName, layouts, props, send, callId, status, headers } =
+  const { React, renderToReadableStream, cwd, componentPath, fileName, props, send, callId, status, headers } =
     opts;
   if (!React || !renderToReadableStream || !props) return false;
   const rel = findBoundary(componentPath, fileName);
@@ -857,9 +1019,45 @@ async function tryRenderBoundary(
     const mod = await importModule(cwd, rel);
     const Comp = mod.default ?? mod.Component ?? mod.NotFound ?? mod.Error;
     if (typeof Comp !== "function") return false;
-    let tree = React.createElement(Comp, props);
-    tree = await buildLayoutTree(cwd, tree, layouts, props, React);
-    await renderBoundaryToClient(React, renderToReadableStream, tree, send, callId, status, headers);
+    // The boundary hydrates through its OWN layout chain (walked from app/ to
+    // the boundary's dir) — NOT the failing page's chain — so the server tree
+    // matches the client entry the bundler baked for this boundary (#279).
+    const boundaryLayouts = resolveLayoutChain(rel, cwd);
+    // For an error boundary, project the thrown Error to the SAFE client shape
+    // ({message, digest}) and give BOTH server + client the SAME value (zero
+    // hydration mismatch) + a no-op reset() server-side. The raw Error/stack
+    // never reaches the client (the dev overlay owns dev stacks; #270).
+    let errorForClient: { message: string; digest?: string } | undefined;
+    let compProps = props;
+    if (fileName === "error") {
+      const rawErr = props.error;
+      errorForClient = {
+        message: rawErr?.message ?? String(rawErr ?? "Error"),
+        digest: errorDigest(rawErr),
+      };
+      compProps = { ...props, error: errorForClient, reset: () => {} };
+    }
+    let tree = React.createElement(Comp, compProps);
+    tree = await buildLayoutTree(cwd, tree, boundaryLayouts, compProps, React);
+    await renderBoundaryToClient(
+      React,
+      renderToReadableStream,
+      tree,
+      send,
+      callId,
+      status,
+      headers,
+      {
+        component: rel,
+        layouts: boundaryLayouts,
+        props: compProps,
+        // Catch-path boundaries don't set up serverData/use() (the by-name
+        // not-found dispatch through handleRenderRoute does); empty ssrData.
+        ssrData: {},
+        kind: fileName === "error" ? "error" : "not-found",
+        errorForClient,
+      },
+    );
     return true;
   } catch (e) {
     // Boundary render itself failed — no tertiary fallback; let the caller
@@ -1030,13 +1228,28 @@ export async function handleRenderRoute(
       ssrValueCache,
     );
 
+    // #277 cache-safety proof. A render is shareable (CDN/disk cacheable) ONLY
+    // if its output is auth-INDEPENDENT — so wrap props.auth in a Proxy that
+    // flips `authTouched` the moment a page/layout reads it. Reading auth at
+    // all (even for an anonymous request) opts the render OUT of caching,
+    // because the output could differ by identity. The raw auth is restored
+    // before serialization (so the hydration blob carries real values, and so
+    // JSON.stringify doesn't trip the Proxy itself).
+    let authTouched = false;
+    const authProxy = new Proxy(msg.auth as Record<string, unknown>, {
+      get(target, prop, receiver) {
+        authTouched = true;
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+
     props = {
       url: msg.url,
       params: msg.params,
       searchParams: msg.search_params,
       headers: msg.headers,
       cookies: msg.cookies,
-      auth: msg.auth,
+      auth: authProxy,
       // Response controller — a page/layout calls response.setStatus /
       // setHeader / setCookie / redirect / notFound to shape the reply.
       response,
@@ -1059,6 +1272,41 @@ export async function handleRenderRoute(
     metadata = applyAutoIcons(msg.component, metadata);
     const metaFragment = renderMetadata(React, metadata);
 
+    // loading.tsx (#278): the nearest `loading` module — walked up from the
+    // page dir, like not-found/error — becomes ONE route-level Suspense
+    // fallback wrapping the page. When present, the shell (layouts) + this
+    // skeleton flush immediately and React reveals the real page content when
+    // the page's top-level `use()` resolves, instead of buffering the whole
+    // document (see the `allReady` gate below). A page with no loading.tsx
+    // keeps the byte-identical buffered single-flush path.
+    //
+    // The skeleton is SERVER-ONLY and must not read `serverData` (a read would
+    // suspend the FALLBACK itself, delaying the shell). It gets the page props
+    // for url/params/searchParams/auth.
+    const loadingRel = findBoundary(msg.component, "loading");
+    let Loading: any = null;
+    if (loadingRel) {
+      try {
+        const lMod = await importModule(cwd, loadingRel);
+        const L = lMod.default ?? lMod.Loading ?? lMod.loading;
+        if (typeof L === "function") Loading = L;
+      } catch {
+        // A broken loading.tsx must never block the page — fall back to the
+        // buffered path.
+        Loading = null;
+      }
+    }
+
+    // The page leaf, optionally wrapped in the single Suspense boundary.
+    let pageLeaf: any = React.createElement(Component, props);
+    if (Loading) {
+      pageLeaf = React.createElement(
+        React.Suspense,
+        { fallback: React.createElement(Loading, props) },
+        pageLeaf,
+      );
+    }
+
     // Resolve the layout chain. Each layout module exports a default
     // function that accepts the same props + `children`. Walk leaf →
     // root: start with the page component as `tree`, then for each
@@ -1067,13 +1315,8 @@ export async function handleRenderRoute(
     // the page. The metadata fragment is the FIRST child so React hoists
     // its <title>/<meta> into the <head> a layout renders.
     let tree: any = metaFragment
-      ? React.createElement(
-          React.Fragment,
-          null,
-          metaFragment,
-          React.createElement(Component, props),
-        )
-      : React.createElement(Component, props);
+      ? React.createElement(React.Fragment, null, metaFragment, pageLeaf)
+      : pageLeaf;
     tree = await buildLayoutTree(cwd, tree, msg.layouts, props, React);
     const element = tree;
     const stream: ReadableStream<Uint8Array> = await renderToReadableStream(
@@ -1099,7 +1342,16 @@ export async function handleRenderRoute(
     // whole-document hydration (which leaves the boundary stuck on its
     // fallback). Pages with no async data have no boundaries, so `allReady`
     // resolves immediately — zero cost for the common case.
-    if ((stream as any).allReady) {
+    //
+    // EXCEPTION (#278): when a loading.tsx wraps the page in a Suspense
+    // boundary, we DELIBERATELY skip the buffer and stream — the shell +
+    // skeleton flush first, then React reveals the real content + its reveal
+    // script as the page's `use()` resolves. Hydration stays clean because
+    // there's exactly ONE route-level boundary and the tail `__PYLON_DATA__`
+    // (emitted below, after the stream drains to EOF) still carries a fully
+    // resolved `ssrData` map — so the client's `use()` reads a fulfilled
+    // value and never re-suspends.
+    if (!Loading && (stream as any).allReady) {
       await (stream as any).allReady;
     }
 
@@ -1108,11 +1360,45 @@ export async function handleRenderRoute(
     // The shell rendered without a redirect()/notFound() throw, so the
     // page's chosen status (default 200) + headers + cookies go out now,
     // before the first body byte.
+    //
+    // #277 cache verdict (Stage 1, buffered path only — a streaming render
+    // commits its head before the body resolves, so `authTouched` isn't final
+    // yet). A render is shareable (CDN-cacheable via `public, s-maxage`) ONLY
+    // when ALL hold: it opted in (`export const revalidate` / `dynamic:
+    // "force-static"`), never read props.auth (authTouched), set no cookie,
+    // isn't `force-dynamic`, and per-caller strict policies are OFF — in strict
+    // mode serverData reads are auth-filtered, so the output isn't shareable.
+    // We emit an INTERNAL `x-pylon-cacheable` header the host turns into a
+    // public Cache-Control and STRIPS; its ABSENCE is the fail-closed default
+    // (the host keeps no-cache / no-store). The 200-only guard avoids caching
+    // an error/redirect.
+    const revalidateSecs =
+      typeof (mod as any).revalidate === "number" && (mod as any).revalidate > 0
+        ? Math.floor((mod as any).revalidate)
+        : (mod as any).dynamic === "force-static"
+          ? 31536000 // a year — only a deploy invalidates a force-static page
+          : null;
+    const forceDynamic = (mod as any).dynamic === "force-dynamic";
+    const strictPolicies = process.env.PYLON_STRICT_FN_POLICIES === "1";
+    const cacheable =
+      revalidateSecs != null &&
+      !forceDynamic &&
+      !authTouched &&
+      responseState.cookies.length === 0 &&
+      !strictPolicies &&
+      !Loading &&
+      responseState.status === 200;
+    // Restore the raw auth before any serialization below (the Proxy was only
+    // for the render-time auth-touch probe).
+    if (props) props.auth = msg.auth;
     send({
       type: "response_start",
       call_id: msg.call_id,
       status: responseState.status,
-      headers: finalizeHeaders(responseState),
+      headers: finalizeHeaders(
+        responseState,
+        cacheable ? { "x-pylon-cacheable": String(revalidateSecs) } : {},
+      ),
     });
 
     // Pre-load the manifest BEFORE the React stream starts emitting
@@ -1196,67 +1482,29 @@ export async function handleRenderRoute(
     // and `getManifest` parses with mtime-keyed caching. Falls back
     // to a no-hydration warning if the manifest can't be loaded
     // (rare — usually means the bundler crashed).
-    if (!isBoundaryComponent) {
-      // Strip live, non-serializable handles from the props that seed
-      // hydration: `serverData` (an RPC handle — the client rebuilds its
-      // own from `ssrData`) and `response` (a server-only controller — the
-      // client gets a no-op). Their resolved data rides along in `ssrData`.
-      //
-      // SECURITY: also strip the request `headers` + `cookies`. They were
-      // passed to the page for SERVER-side reads, but serializing them into
-      // the page HTML exposes the request's `Cookie` (the HttpOnly session
-      // token), `Authorization`, and client IP to any client-side JS —
-      // defeating HttpOnly and handing a same-page XSS an exfil target. The
-      // client gets empty maps (shape preserved so `props.headers`/`.cookies`
-      // aren't `undefined`); a page that must surface a request value to the
-      // browser should pass it explicitly via a prop or `serverData`.
-      const {
-        serverData: _sd,
-        response: _resp,
-        headers: _h,
-        cookies: _c,
-        ...restProps
-      } = props;
-      const serializableProps = { ...restProps, headers: {}, cookies: {} };
-      const hydrationPayload = {
+    // Pages always hydrate. A boundary dispatched BY NAME here (the host
+    // rendering `app/not-found` at 404) now hydrates too (#279) when it has a
+    // client entry - only stay server-only (no tail) when there's no entry to
+    // load. `buildHydrationTail` does the props strip (serverData/response +
+    // the security headers/cookies strip) + the </script> + U+2028/2029
+    // escaping. The CSS/modulepreload links were already injected into <head>.
+    const wantsHydration = !isBoundaryComponent || !!preloadManifestRoute;
+    if (wantsHydration) {
+      const tail = buildHydrationTail({
         component: msg.component,
         layouts: msg.layouts ?? [],
-        props: serializableProps,
+        props,
         ssrData: ssrValueCache,
-      };
-      // Escape `<` (closes the </script> breakout) AND the U+2028/U+2029 line
-      // separators — valid in JSON but statement terminators in JS, so they'd
-      // break the page if the blob were ever read as executable JS rather than
-      // application/json. Defense-in-depth.
-      const json = JSON.stringify(hydrationPayload)
-        .replaceAll("<", "\\u003c")
-        .replaceAll("
", "\\u2028")
-        .replaceAll("
", "\\u2029");
-
-      let tail = `<script id="__PYLON_DATA__" type="application/json">${json}</script>`;
-      if (preloadManifestRoute) {
-        // Per-route entry script comes last — it needs the inline
-        // `__PYLON_DATA__` above to have been parsed before it runs.
-        // CSS + modulepreload links were already injected into `<head>`
-        // above so they could start fetching as early as possible.
-        tail += `<script type="module" src="${preloadPublicPrefix}${preloadManifestRoute.file}"></script>`;
-      } else {
-        tail += `<script>console.warn(${JSON.stringify(`[pylon ssr] hydration disabled: ${preloadManifestErr}`)})</script>`;
-      }
-      // Dev-only browser live-reload. `pylon dev` (PYLON_DEV_MODE=1) re-execs
-      // the whole process on every file edit; each process serves a fresh
-      // boot id from /_pylon/dev/live. This client subscribes via
-      // EventSource and reloads the tab when the boot id changes — so saving
-      // a page, a component, or app/globals.css refreshes the browser with
-      // no manual F5. Stripped entirely in production builds.
-      if (process.env.PYLON_DEV_MODE) {
-        tail += DEV_LIVE_RELOAD_SNIPPET;
-      }
-      send({
-        type: "render_chunk",
-        call_id: msg.call_id,
-        data: Buffer.from(tail, "utf8").toString("base64"),
+        manifestRoute: preloadManifestRoute,
+        publicPrefix: preloadPublicPrefix,
+        manifestErr: preloadManifestErr,
+        kind: isBoundaryComponent
+          ? /(^|\/)error$/.test(msg.component)
+            ? "error"
+            : "not-found"
+        .replaceAll("
"          : undefined,
       });
+      sendChunk(tail);
     }
 
     send({ type: "render_done", call_id: msg.call_id });