@pylonsync/functions 0.3.248 → 0.3.250

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.248",
+  "version": "0.3.250",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",
@@ -21,7 +21,8 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "build": "tsc"
+    "build": "tsc",
+    "test": "bun test"
   },
   "keywords": [
     "pylon",
@@ -31,7 +32,12 @@
   ],
   "license": "MIT OR Apache-2.0",
   "devDependencies": {
-    "typescript": "^5.5"
+    "typescript": "^5.5",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "happy-dom": "^15.0.0"
   },
   "peerDependencies": {
     "bun-types": "*"

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

@@ -510,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-hydration.test.ts

@@ -0,0 +1,166 @@
+/**
+ * #278 Stage 2 — streaming-hydration regression guard (the prod-killer check).
+ *
+ * Proves the load-bearing claim behind multi-boundary streaming: hydrating the
+ * RESOLVED SSR DOM (which is what a streamed page's DOM becomes after React's
+ * $RC reveals run) with a `fulfilledThenable`-backed serverData shim produces
+ * clean output — the inner <Suspense> boundary renders its RESOLVED rows on the
+ * first committed pass, NOT a fallback, and React logs NO hydration mismatch.
+ *
+ * This is why Pylon needs NO inline per-boundary patch scripts: it withholds
+ * the bootstrap from renderToReadableStream and runs hydrateRoot ONCE, after
+ * the full ssrData blob — so `use()` reads a fulfilled value synchronously and
+ * never re-suspends. If a future change made `use()` suspend at hydration (a
+ * broken shim handing back a pending promise), the boundary would mismatch /
+ * lose its content — caught here.
+ *
+ * Isolated in its own file because it registers DOM globals (window/document)
+ * for react-dom/client; they're restored after each test.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import { Window } from "happy-dom";
+import React, { Suspense, use } from "react";
+import { renderToReadableStream } from "react-dom/server.browser";
+
+// Mirrors `fulfilledThenable` in ssr-client-bundler.ts's CLIENT_RUNTIME_SOURCE:
+// a React-recognized fulfilled thenable so use() reads `.value` synchronously
+// (status === "fulfilled") instead of suspending.
+function fulfilledThenable<T>(value: T) {
+  return {
+    status: "fulfilled" as const,
+    value,
+    then(onFulfilled?: (v: T) => any) {
+      return onFulfilled ? onFulfilled(value) : (value as any);
+    },
+  };
+}
+
+function Rows({ p }: { p: PromiseLike<string[]> }) {
+  const rows = use(p as any) as string[];
+  return React.createElement(
+    "ul",
+    { id: "rows" },
+    rows.map((r) => React.createElement("li", { key: r }, r)),
+  );
+}
+function Page({ p }: { p: PromiseLike<string[]> }) {
+  return React.createElement(
+    "div",
+    { id: "app" },
+    React.createElement("h1", { id: "shell" }, "Shell"),
+    React.createElement(
+      Suspense,
+      { fallback: React.createElement("p", { id: "fallback" }, "Loading…") },
+      React.createElement(Rows, { p }),
+    ),
+  );
+}
+
+const dec = new TextDecoder();
+
+// Server-render the page (data pre-resolved) to its final resolved HTML — the
+// same DOM a streamed page settles to once React's reveal scripts have run.
+async function renderResolvedHtml(rows: string[]): Promise<string> {
+  const stream = await renderToReadableStream(
+    React.createElement(Page, { p: Promise.resolve(rows) }),
+  );
+  await (stream as any).allReady;
+  const reader = stream.getReader();
+  let html = "";
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    html += dec.decode(value);
+  }
+  return html;
+}
+
+// Globals react-dom/client touches; saved + restored so this file's DOM
+// registration never bleeds into sibling test files.
+const DOM_GLOBAL_KEYS = [
+  "window",
+  "document",
+  "navigator",
+  "HTMLElement",
+  "Node",
+  "Event",
+  "MutationObserver",
+  "requestAnimationFrame",
+  "cancelAnimationFrame",
+];
+let savedGlobals: Record<string, any> | null = null;
+
+function registerDom(win: any) {
+  const g = globalThis as any;
+  savedGlobals = {};
+  for (const k of DOM_GLOBAL_KEYS) savedGlobals[k] = g[k];
+  g.window = win;
+  g.document = win.document;
+  g.navigator = win.navigator;
+  g.HTMLElement = win.HTMLElement;
+  g.Node = win.Node;
+  g.Event = win.Event;
+  g.MutationObserver = win.MutationObserver;
+  g.requestAnimationFrame = (cb: any) => setTimeout(() => cb(Date.now()), 0);
+  g.cancelAnimationFrame = (id: any) => clearTimeout(id);
+}
+
+afterEach(() => {
+  if (!savedGlobals) return;
+  const g = globalThis as any;
+  for (const k of DOM_GLOBAL_KEYS) {
+    if (savedGlobals[k] === undefined) delete g[k];
+    else g[k] = savedGlobals[k];
+  }
+  savedGlobals = null;
+});
+
+describe("streaming hydration (#278)", () => {
+  test("fulfilledThenable shim → boundary hydrates to RESOLVED rows, no fallback, no mismatch", async () => {
+    const rows = ["alpha", "beta"];
+    const serverHtml = await renderResolvedHtml(rows);
+    // Sanity: the SSR DOM has the resolved rows (not a fallback).
+    expect(serverHtml).toContain("<li>alpha</li>");
+
+    const win = new Window({ url: "http://localhost/" });
+    // Parse the server HTML into a container element via HTML parsing (this
+    // preserves React's <!--$--> boundary comment markers, which hydrateRoot
+    // reads to locate Suspense boundaries). insertAdjacentHTML is the parse
+    // entry point; the input is our own rendered markup, not untrusted data.
+    const root = win.document.createElement("div");
+    root.setAttribute("id", "root");
+    root.insertAdjacentHTML("afterbegin", serverHtml);
+    win.document.body.appendChild(root);
+    registerDom(win);
+
+    const errors: string[] = [];
+    const origErr = console.error;
+    console.error = (...a: any[]) => {
+      errors.push(a.map(String).join(" "));
+    };
+    try {
+      const { hydrateRoot } = await import("react-dom/client");
+      // Client tree: same component, but serverData yields a fulfilled thenable
+      // (the value the server already streamed) — exactly the client shim's job.
+      hydrateRoot(
+        root as any,
+        React.createElement(Page, { p: fulfilledThenable(rows) }),
+      );
+      await new Promise((r) => setTimeout(r, 50));
+      const html = (root as any).innerHTML as string;
+
+      // The boundary committed its RESOLVED content on hydration...
+      expect(html).toContain("alpha");
+      expect(html).toContain("beta");
+      // ...NOT the fallback (no flash / no stuck boundary)...
+      expect(html).not.toContain("Loading…");
+      // ...and React logged NO hydration mismatch.
+      const mismatch = errors.filter((e) =>
+        /hydrat|did not match|mismatch|Text content does not match/i.test(e),
+      );
+      expect(mismatch).toEqual([]);
+    } finally {
+      console.error = origErr;
+    }
+  });
+});

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) {
@@ -1127,6 +1134,78 @@ function makeServerData(reader: any, valueCache: Record<string, any>): any {
   return sd;
 }
 
+/**
+ * #278: does this route STREAM (vs buffer the whole document)? Streaming is
+ * opt-in: a `loading.tsx` (route-level Suspense) or `export const streaming =
+ * true` (inner-boundary). Pure for testing.
+ */
+export function computeWantsStream(hasLoading: boolean, mod: any): boolean {
+  return hasLoading || mod?.streaming === true;
+}
+
+/**
+ * #277: how long an opt-in page stays cacheable, in seconds — or null if it
+ * never opted in. `export const revalidate = N` (N>0) → N; `dynamic:
+ * "force-static"` → a year (only a deploy invalidates); else null. Pure.
+ */
+export function computeRevalidateSecs(mod: any): number | null {
+  if (typeof mod?.revalidate === "number" && mod.revalidate > 0) {
+    return Math.floor(mod.revalidate);
+  }
+  if (mod?.dynamic === "force-static") return 31536000;
+  return null;
+}
+
+/**
+ * #277 cache verdict — the security-critical predicate, extracted pure so the
+ * leak class (a personalized/streaming render marked cacheable) is a TEST, not
+ * a mental walkthrough. INVARIANT: result ⟹ !wantsStream (a streaming render
+ * commits its head before auth/cookies/status are final, so it can never be
+ * cached). Fail-closed: every condition must hold.
+ */
+export function computeCacheVerdict(args: {
+  revalidateSecs: number | null;
+  forceDynamic: boolean;
+  authTouched: boolean;
+  cookieCount: number;
+  strictPolicies: boolean;
+  wantsStream: boolean;
+  status: number;
+}): boolean {
+  return (
+    args.revalidateSecs != null &&
+    !args.forceDynamic &&
+    !args.authTouched &&
+    args.cookieCount === 0 &&
+    !args.strictPolicies &&
+    !args.wantsStream &&
+    args.status === 200
+  );
+}
+
+/**
+ * #278: diff the response head committed at `response_start` against the final
+ * state after EOF, to catch a late response.* mutation from a suspended subtree
+ * that the already-sent head couldn't carry. Returns the dropped pieces, or
+ * null if nothing was lost. Pure.
+ */
+export function diffCommittedResponse(
+  snapshot: { status: number; cookies: string[]; headerKeys: string[] },
+  final: { status: number; cookies: string[]; headers: Record<string, string> },
+): { droppedCookies: string[]; statusChanged: boolean; newHeaderKeys: string[] } | null {
+  const droppedCookies = final.cookies.filter(
+    (c) => !snapshot.cookies.includes(c),
+  );
+  const statusChanged = final.status !== snapshot.status;
+  const newHeaderKeys = Object.keys(final.headers)
+    .sort()
+    .filter((k) => !snapshot.headerKeys.includes(k));
+  if (droppedCookies.length || statusChanged || newHeaderKeys.length) {
+    return { droppedCookies, statusChanged, newHeaderKeys };
+  }
+  return null;
+}
+
 export async function handleRenderRoute(
   msg: RenderRouteMessage,
   send: Send,
@@ -1221,13 +1300,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,
@@ -1285,6 +1379,16 @@ export async function handleRenderRoute(
       );
     }
 
+    // Streaming decision (#278). Computed from STATIC module exports only —
+    // knowable before any await, so the buffer/cache decision never reads
+    // non-final render state. A page STREAMS (shell + each inner <Suspense>
+    // fallback flush immediately, content reveals as data resolves) when it has
+    // a loading.tsx (route-level boundary, #278 Stage 1) OR explicitly opts in
+    // with `export const streaming = true` (inner-boundary streaming, Stage 2).
+    // Every un-annotated page keeps the byte-identical BUFFERED path (allReady)
+    // that 100% of today's prod traffic rides — this is opt-in, never default.
+    const wantsStream = computeWantsStream(!!Loading, mod);
+
     // 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
@@ -1302,9 +1406,26 @@ export async function handleRenderRoute(
       {
         onError(err: unknown) {
           // React captures render errors during the streaming render
-          // and feeds them here. Phase 1 logs to stderr; Phase 1.5
-          // sends a structured signal so the host can truncate the
-          // body + emit a debug overlay.
+          // and feeds them here. We log to stderr; we do NOT truncate or
+          // rewrite the response here — on a streamed render the HTTP head is
+          // already committed, so a mid-stream error just closes the body
+          // (partial HTML); the dev overlay (#275) only covers failures BEFORE
+          // response_start (host-side err channel). Buffered renders surface
+          // their error through the catch/boundary path below.
+          if (err instanceof PylonRouteControl) {
+            // A redirect()/notFound() thrown from BELOW a <Suspense> boundary:
+            // the shell already committed the head, so React swallowed it and
+            // it can't change the response. This is a known limitation on BOTH
+            // the buffered and streamed paths (response.* must fire in the
+            // synchronous shell). Surface it loudly instead of silently losing.
+            // eslint-disable-next-line no-console
+            console.error(
+              `[ssr] response.${err.kind}() called below a <Suspense> boundary was ignored — ` +
+                `the HTTP head was already sent. Call response.redirect()/notFound() in the ` +
+                `synchronous shell render, before any await/<Suspense>.`,
+            );
+            return;
+          }
           // eslint-disable-next-line no-console
           console.error("[ssr] renderToReadableStream onError:", err);
         },
@@ -1321,15 +1442,17 @@ export async function handleRenderRoute(
     // fallback). Pages with no async data have no boundaries, so `allReady`
     // resolves immediately — zero cost for the common case.
     //
-    // 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) {
+    // EXCEPTION (#278): a STREAMING render (loading.tsx route-level boundary,
+    // or `export const streaming = true` for inner boundaries) DELIBERATELY
+    // skips the buffer — the shell + each <Suspense> fallback flush first, then
+    // React reveals each boundary's real content + its reveal script as that
+    // boundary's `use()` resolves. Hydration stays clean for ANY number of
+    // boundaries because Pylon runs hydrateRoot ONCE, post-EOF: the entry
+    // <script> is appended AFTER the full `__PYLON_DATA__` blob (which carries
+    // the fully-resolved `ssrData` map) and after all of React's $RC reveals,
+    // so the client's `use()` reads a fulfilled value and never re-suspends —
+    // there is no progressive hydration racing the stream.
+    if (!wantsStream && (stream as any).allReady) {
       await (stream as any).allReady;
     }
 
@@ -1338,11 +1461,61 @@ 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 = computeRevalidateSecs(mod);
+    const forceDynamic = (mod as any).dynamic === "force-dynamic";
+    const strictPolicies = process.env.PYLON_STRICT_FN_POLICIES === "1";
+    // INVARIANT: cacheable ⟹ !wantsStream. A streaming render commits its head
+    // (response_start) BEFORE suspended subtrees finish, so `authTouched`,
+    // `responseState.cookies`, and `.status` are NOT final here — caching it
+    // could share a personalized/non-final body. So `!wantsStream` (NOT just
+    // `!Loading`) is the gate: a `streaming = true` page has `Loading` null but
+    // `wantsStream` true, and must still be excluded. Fail-closed. (See
+    // computeCacheVerdict — pure + unit-tested for the leak class.)
+    const cacheable = computeCacheVerdict({
+      revalidateSecs,
+      forceDynamic,
+      authTouched,
+      cookieCount: responseState.cookies.length,
+      strictPolicies,
+      wantsStream,
+      status: responseState.status,
+    });
+    // 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;
+    // #278: on a STREAMING render the head commits NOW, before suspended
+    // subtrees run. Snapshot what's committed so we can detect (after EOF) a
+    // late response.setStatus/setCookie/setHeader from a suspended subtree that
+    // got silently dropped — and warn loudly instead of leaving the dev to
+    // debug a missing Set-Cookie. Buffered renders need no snapshot (the whole
+    // render is done before this point, so nothing can change after).
+    const committedSnapshot = wantsStream
+      ? {
+          status: responseState.status,
+          cookies: responseState.cookies.map((c) => String(c)),
+          headerKeys: Object.keys(responseState.headers).sort(),
+        }
+      : null;
     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
@@ -1408,6 +1581,47 @@ export async function handleRenderRoute(
     };
     await streamWithHeadInjection(stream.getReader(), headBlob, sendChunk);
 
+    // #278: detect a late response.* mutation from a suspended subtree that the
+    // already-committed head couldn't carry, and warn loudly (a silently
+    // dropped Set-Cookie reads as "logged out" / missing CSRF in prod). Only
+    // for streamed renders — a buffered render finalized before response_start,
+    // so nothing changes after. The fix for the dev is to move the call into
+    // the synchronous shell (or drop `streaming = true`); we name what was lost.
+    if (committedSnapshot) {
+      // Same diff the unit tests exercise — call the pure helper so the tested
+      // path IS the prod path (no drift).
+      const dropped = diffCommittedResponse(committedSnapshot, {
+        status: responseState.status,
+        cookies: responseState.cookies,
+        headers: responseState.headers,
+      });
+      if (dropped) {
+        const parts: string[] = [];
+        if (dropped.droppedCookies.length)
+          parts.push(
+            `Set-Cookie [${dropped.droppedCookies
+              .map((c) => {
+                const eq = c.indexOf("="); // serialized "name=value; …"
+                return eq >= 0 ? c.slice(0, eq) : c;
+              })
+              .join(", ")}]`,
+          );
+        if (dropped.statusChanged)
+          parts.push(
+            `status ${committedSnapshot.status}→${responseState.status}`,
+          );
+        if (dropped.newHeaderKeys.length)
+          parts.push(`headers [${dropped.newHeaderKeys.join(", ")}]`);
+        // eslint-disable-next-line no-console
+        console.error(
+          `[ssr] response.* called below a <Suspense> boundary on a streaming ` +
+            `route was DROPPED (the HTTP head already shipped): ${parts.join("; ")}. ` +
+            `Set response status/cookies/headers in the synchronous shell render, ` +
+            `before any await/<Suspense> — or remove \`export const streaming = true\`.`,
+        );
+      }
+    }
+
     // Hydration tail. After React's stream EOFs we append the
     // hydration markers so the browser can hydrate:
     //   1. `__PYLON_DATA__` — JSON-typed script with the props the

package/src/ssr-streaming.test.ts

@@ -0,0 +1,264 @@
+/**
+ * #278 Stage 2 — progressive streaming harness.
+ *
+ * Two layers:
+ *  1. PURE verdict logic (computeWantsStream / computeRevalidateSecs /
+ *     computeCacheVerdict / diffCommittedResponse) — the security-critical
+ *     "is this render cacheable / should it stream" gate, tested directly
+ *     including the leak-class invariant `cacheable ⟹ !wantsStream`.
+ *  2. The actual React streaming MECHANISM through react-dom/server.browser —
+ *     proving the buffered (allReady) path emits clean inline HTML, and the
+ *     streamed path flushes the shell + Suspense fallback first then reveals.
+ *
+ * Hydration (the prod-killer "stuck on fallback" check) lives in the sibling
+ * ssr-hydration.test.ts (it mutates DOM globals, so it's isolated).
+ */
+import { describe, expect, test } from "bun:test";
+import React, { Suspense, use } from "react";
+import { renderToReadableStream } from "react-dom/server.browser";
+import {
+  buildHydrationTail,
+  computeCacheVerdict,
+  computeRevalidateSecs,
+  computeWantsStream,
+  diffCommittedResponse,
+} from "./ssr-runtime";
+
+// ---------------------------------------------------------------------------
+// Pure verdict logic
+// ---------------------------------------------------------------------------
+
+describe("computeWantsStream", () => {
+  test("loading.tsx OR streaming=true opts in; nothing else does", () => {
+    expect(computeWantsStream(true, {})).toBe(true); // loading.tsx
+    expect(computeWantsStream(false, { streaming: true })).toBe(true); // opt-in
+    expect(computeWantsStream(true, { streaming: true })).toBe(true);
+    expect(computeWantsStream(false, {})).toBe(false); // default = buffered
+    expect(computeWantsStream(false, { streaming: false })).toBe(false);
+    expect(computeWantsStream(false, { streaming: 1 as any })).toBe(false); // strict ===
+    expect(computeWantsStream(false, null)).toBe(false);
+  });
+});
+
+describe("computeRevalidateSecs", () => {
+  test("revalidate>0 → floor; force-static → a year; else null", () => {
+    expect(computeRevalidateSecs({ revalidate: 60 })).toBe(60);
+    expect(computeRevalidateSecs({ revalidate: 12.9 })).toBe(12);
+    expect(computeRevalidateSecs({ revalidate: 0 })).toBeNull();
+    expect(computeRevalidateSecs({ revalidate: -5 })).toBeNull();
+    expect(computeRevalidateSecs({ dynamic: "force-static" })).toBe(31536000);
+    expect(computeRevalidateSecs({ dynamic: "force-dynamic" })).toBeNull();
+    expect(computeRevalidateSecs({})).toBeNull();
+    expect(computeRevalidateSecs(null)).toBeNull();
+  });
+});
+
+describe("computeCacheVerdict (the #277 leak-class gate)", () => {
+  const base = {
+    revalidateSecs: 60 as number | null,
+    forceDynamic: false,
+    authTouched: false,
+    cookieCount: 0,
+    strictPolicies: false,
+    wantsStream: false,
+    status: 200,
+  };
+
+  test("a clean opted-in buffered 200 is cacheable", () => {
+    expect(computeCacheVerdict(base)).toBe(true);
+  });
+
+  test("every single veto flips it to non-cacheable (fail-closed)", () => {
+    expect(computeCacheVerdict({ ...base, revalidateSecs: null })).toBe(false); // no opt-in
+    expect(computeCacheVerdict({ ...base, forceDynamic: true })).toBe(false);
+    expect(computeCacheVerdict({ ...base, authTouched: true })).toBe(false); // read auth
+    expect(computeCacheVerdict({ ...base, cookieCount: 1 })).toBe(false); // set a cookie
+    expect(computeCacheVerdict({ ...base, strictPolicies: true })).toBe(false);
+    expect(computeCacheVerdict({ ...base, wantsStream: true })).toBe(false); // STREAMING
+    expect(computeCacheVerdict({ ...base, status: 404 })).toBe(false);
+    expect(computeCacheVerdict({ ...base, status: 307 })).toBe(false);
+  });
+
+  test("INVARIANT: cacheable ⟹ !wantsStream over the full cross-product", () => {
+    const bools = [false, true];
+    const statuses = [200, 201, 302, 404, 500];
+    const revs: (number | null)[] = [null, 0 as any, 60, 31536000];
+    let checked = 0;
+    for (const forceDynamic of bools)
+      for (const authTouched of bools)
+        for (const strictPolicies of bools)
+          for (const wantsStream of bools)
+            for (const cookieCount of [0, 1])
+              for (const status of statuses)
+                for (const revalidateSecs of revs) {
+                  const c = computeCacheVerdict({
+                    revalidateSecs,
+                    forceDynamic,
+                    authTouched,
+                    cookieCount,
+                    strictPolicies,
+                    wantsStream,
+                    status,
+                  });
+                  // The load-bearing security invariant: a streaming render is
+                  // NEVER cacheable (its head commits before auth/cookies/status
+                  // are final).
+                  if (c) expect(wantsStream).toBe(false);
+                  checked++;
+                }
+    expect(checked).toBe(640); // 2^4 (bools) × 2 (cookies) × 5 (status) × 4 (revs)
+  });
+});
+
+describe("diffCommittedResponse (#278 late-response.* drop detector)", () => {
+  const snap = (over: any = {}) => ({
+    status: 200,
+    cookies: ["sid=committed"],
+    headerKeys: ["x-base"],
+    ...over,
+  });
+
+  test("no change → null", () => {
+    const r = diffCommittedResponse(snap(), {
+      status: 200,
+      cookies: ["sid=committed"],
+      headers: { "x-base": "1" },
+    });
+    expect(r).toBeNull();
+  });
+
+  test("a late Set-Cookie from a suspended subtree is reported", () => {
+    const r = diffCommittedResponse(snap(), {
+      status: 200,
+      cookies: ["sid=committed", "flash=late"],
+      headers: { "x-base": "1" },
+    });
+    expect(r).not.toBeNull();
+    expect(r!.droppedCookies).toEqual(["flash=late"]);
+  });
+
+  test("a late status change + new header are reported", () => {
+    const r = diffCommittedResponse(snap(), {
+      status: 201,
+      cookies: ["sid=committed"],
+      headers: { "x-base": "1", "x-late": "2" },
+    });
+    expect(r!.statusChanged).toBe(true);
+    expect(r!.newHeaderKeys).toEqual(["x-late"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// React streaming mechanism (real renderToReadableStream)
+// ---------------------------------------------------------------------------
+
+function makeDeferred<T>() {
+  let resolve!: (v: T) => void;
+  const promise = new Promise<T>((r) => (resolve = r));
+  return { promise, resolve };
+}
+
+function Rows({ p }: { p: Promise<string[]> }) {
+  const rows = use(p);
+  return React.createElement(
+    "ul",
+    { id: "rows" },
+    rows.map((r) => React.createElement("li", { key: r }, r)),
+  );
+}
+
+// A page with an inner <Suspense> reading async data — the /notes shape.
+function Page({ p }: { p: Promise<string[]> }) {
+  return React.createElement(
+    "div",
+    { id: "app" },
+    React.createElement("h1", { id: "shell" }, "Shell"),
+    React.createElement(
+      Suspense,
+      { fallback: React.createElement("p", { id: "fallback" }, "Loading…") },
+      React.createElement(Rows, { p }),
+    ),
+  );
+}
+
+const dec = new TextDecoder();
+
+describe("react streaming mechanism", () => {
+  test("BUFFERED (await allReady, then drain) → clean inline, no reveal scripts", async () => {
+    // Mirrors the runtime's `if (!wantsStream) await stream.allReady` path.
+    const d = makeDeferred<string[]>();
+    setTimeout(() => d.resolve(["a", "b"]), 5);
+    const stream = await renderToReadableStream(
+      React.createElement(Page, { p: d.promise }),
+    );
+    await (stream as any).allReady;
+    const reader = stream.getReader();
+    let html = "";
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      html += dec.decode(value);
+    }
+    // Resolved rows inline; NO fallback, NO pending marker, NO $RC reveal /
+    // <template>. This is the byte-identical buffered contract today's prod
+    // traffic rides — the regression lock.
+    expect(html).toContain("<li>a</li>");
+    expect(html).toContain("<li>b</li>");
+    expect(html).not.toContain("Loading…");
+    expect(html).not.toContain("<!--$?-->"); // no PENDING boundary marker
+    expect(html).not.toContain("<template");
+    expect(/\$RC|completeBoundary/.test(html)).toBe(false);
+  });
+
+  test("STREAMING (drain progressively) → shell+fallback first, rows+reveal later", async () => {
+    const d = makeDeferred<string[]>();
+    const stream = await renderToReadableStream(
+      React.createElement(Page, { p: d.promise }),
+    );
+    const reader = stream.getReader();
+    // First flush = the shell with the fallback (data still pending).
+    const first = await reader.read();
+    const firstHtml = dec.decode(first.value);
+    expect(firstHtml).toContain("Shell");
+    expect(firstHtml).toContain("Loading…"); // fallback streamed
+    expect(firstHtml).not.toContain("<li>a</li>"); // rows NOT here yet
+    expect(firstHtml).toContain("<template"); // boundary placeholder
+    // Now the data resolves → React reveals the boundary in a later chunk.
+    d.resolve(["a", "b"]);
+    let rest = "";
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      rest += dec.decode(value);
+    }
+    expect(rest).toContain("<li>a</li>");
+    expect(rest).toContain("<li>b</li>");
+    expect(/\$RC|completeBoundary|<template/.test(rest)).toBe(true); // reveal
+  });
+});
+
+describe("hydration tail ordering (#278: data blob before entry script)", () => {
+  test("__PYLON_DATA__ carries ssrData and the entry <script type=module> is LAST", () => {
+    const ssrData = { 'list:["Note"]': [{ id: "1", body: "hi" }] };
+    const tail = buildHydrationTail({
+      component: "app/notes/page",
+      layouts: [],
+      props: { url: "/notes", params: {}, searchParams: {} },
+      ssrData,
+      manifestRoute: { file: "notes.js", imports: ["chunk.js"], css: [] },
+      publicPrefix: "/_pylon/build/",
+      manifestErr: null,
+    });
+    const dataIdx = tail.indexOf('id="__PYLON_DATA__"');
+    const entryIdx = tail.indexOf("notes.js");
+    expect(dataIdx).toBeGreaterThanOrEqual(0);
+    expect(entryIdx).toBeGreaterThanOrEqual(0);
+    // The entry script MUST come after the data blob so hydrateRoot (which the
+    // entry triggers) sees a fully-seeded ssrData — the whole reason multi-
+    // boundary streaming hydrates cleanly without inline patch scripts.
+    expect(entryIdx).toBeGreaterThan(dataIdx);
+    // ssrData round-trips into the blob.
+    expect(tail).toContain("Note");
+    expect(tail).toContain('"body":"hi"');
+  });
+});