npm - @pylonsync/functions - Versions diffs - 0.3.246 → 0.3.248 - Mend

@pylonsync/functions 0.3.246 → 0.3.248

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/package.json +1 -1
package/src/runtime.ts +7 -1
package/src/ssr-client-bundler.ts +63 -3
package/src/ssr-runtime.test.ts +166 -1
package/src/ssr-runtime.ts +286 -55

package/package.json CHANGED Viewed

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

package/src/runtime.ts CHANGED Viewed

@@ -223,11 +223,17 @@ function dispatch(line: string): void {
         ),
       )
       .catch((err) => {
+        const devMode =
+          process.env.PYLON_DEV_MODE === "1" ||
+          process.env.PYLON_DEV_MODE === "true";
         send({
           type: "error",
           call_id: (msg as unknown as { call_id: string }).call_id,
           code: "SSR_RUNTIME_CRASH",
-          message: err?.message || String(err),
+          // Dev: full stack for the host's error overlay. Prod: message only.
+          message:
+            (devMode && err?.stack ? String(err.stack) : err?.message) ||
+            String(err),
         });
       });
   } else if (msg.type === "bundle_client") {

package/src/ssr-client-bundler.ts CHANGED Viewed

@@ -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;
 }
@@ -382,6 +406,27 @@ export function hydrate(component, Page, Layouts) {
   // only need to populate the cache (already done above).
 }
+// Swap the page's SEO/social <head> tags on a client-side navigation.
+// The SSR runtime marks every page-metadata <meta>/<link> with
+// data-pylon-meta; we drop the current set and import the incoming page's
+// set, so description / canonical / og:* / twitter:* / icons track the new
+// route. The layout's charset/viewport and Pylon's injected stylesheet
+// links carry no marker, so they survive untouched (no FOUC). The page
+// component never renders these tags on the client, so React doesn't own
+// them — this manual swap can't fight hydration.
+function syncHeadMeta(doc) {
+  const head = document.head;
+  if (!head) return;
+  const current = head.querySelectorAll("[data-pylon-meta]");
+  for (let i = 0; i < current.length; i++) current[i].remove();
+  const incoming = doc.head
+    ? doc.head.querySelectorAll("[data-pylon-meta]")
+    : [];
+  for (let i = 0; i < incoming.length; i++) {
+    head.appendChild(document.importNode(incoming[i], true));
+  }
+}
 async function navigate(href, opts) {
   const push = !opts || opts.push !== false;
   const url = new URL(href, location.href);
@@ -426,11 +471,19 @@ async function navigate(href, opts) {
     return;
   }
   document.title = doc.title || document.title;
+  syncHeadMeta(doc);
   const tree = buildTree(route.Page, route.Layouts, withClientProps(data));
   activeRoot.render(tree);
-  if (push) {
-    history.pushState({ component: data.component }, "", url.pathname + url.search);
+  const target = url.pathname + url.search;
+  if (opts && opts.replace) {
+    history.replaceState({ component: data.component }, "", target);
+  } else if (push) {
+    history.pushState({ component: data.component }, "", target);
   }
+  // Notify the router hooks (useSearchParams / usePathname) so deep children
+  // re-read location after a Link click or a router.push(). popstate already
+  // covers back/forward, but pushState/replaceState fire no event.
+  window.dispatchEvent(new Event("pylon:navigation"));
   // After a successful nav, scroll to top (Next.js default).
   window.scrollTo(0, 0);
 }
@@ -635,7 +688,14 @@ async function buildTailwind(
   // 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).
-  const stylesName = `styles-${hash.toString(36)}.css`;
+  //
+  // 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

package/src/ssr-runtime.test.ts CHANGED Viewed

@@ -4,7 +4,36 @@ 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 } 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
+// tests we hand renderMetadata a fake React that records each created
+// element's shape, which is all renderMetadata touches.
+const FAKE_FRAGMENT = Symbol("Fragment");
+const fakeReact = {
+  Fragment: FAKE_FRAGMENT,
+  createElement: (type: any, props: any, ...children: any[]) => ({
+    type,
+    props: props ?? {},
+    children,
+  }),
+};
 // A minimal PNG: 8-byte signature + an IHDR chunk carrying width/height.
 // `readSocialImageMeta` only reads the first 32 bytes, so a full valid
@@ -180,3 +209,139 @@ describe("icon / apple-icon / favicon file convention", () => {
     expect(applyAutoIcons("app/page", input)).toEqual(input);
   });
 });
+describe("renderMetadata head-tag marking (client-nav sync)", () => {
+  test("every <meta>/<link> carries data-pylon-meta; <title> does not", () => {
+    const frag = renderMetadata(fakeReact, {
+      title: "Hello",
+      description: "A page",
+      canonical: "https://x.test/p",
+      openGraph: { title: "OG", image: "https://x.test/og.png" },
+      twitter: { card: "summary" },
+      icons: { icon: { url: "/icon.png" } },
+    });
+    expect(frag.type).toBe(FAKE_FRAGMENT);
+    const kids: any[] = frag.children;
+    const metaLink = kids.filter((k) => k.type === "meta" || k.type === "link");
+    const titles = kids.filter((k) => k.type === "title");
+    expect(metaLink.length).toBeGreaterThan(0);
+    // The marker is what the client runtime swaps on navigation — without it,
+    // SEO/social tags go stale on client-side nav. Every meta/link must carry
+    // it; <title> must NOT (the client syncs document.title separately).
+    for (const el of metaLink) {
+      expect(el.props["data-pylon-meta"]).toBe("");
+    }
+    expect(titles.length).toBe(1);
+    expect(titles[0].props["data-pylon-meta"]).toBeUndefined();
+    expect(titles[0].children).toEqual(["Hello"]);
+  });
+  test("returns null when there's nothing to emit", () => {
+    expect(renderMetadata(fakeReact, undefined)).toBeNull();
+    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 CHANGED Viewed

@@ -306,9 +306,19 @@ export interface SsrMetadata {
  * host's </head> splice preserves them. React escapes all text/attrs, so
  * there's no manual XSS handling. Returns null when there's nothing to emit.
  */
-function renderMetadata(React: any, m: SsrMetadata | undefined): any {
+export function renderMetadata(React: any, m: SsrMetadata | undefined): any {
   if (!m) return null;
-  const el = React.createElement;
+  // Mark every emitted <meta>/<link> with `data-pylon-meta` so the client
+  // runtime can swap exactly these tags on a client-side navigation — and
+  // leave the layout's charset/viewport and Pylon's injected stylesheet
+  // links untouched. <title> is excluded (the client syncs document.title
+  // directly). The metadata fragment is server-only (the client renders the
+  // page component alone), so React on the client never owns these nodes;
+  // this manual marking is what makes the nav-time swap safe.
+  const el = (type: any, props: any, ...children: any[]) =>
+    type === "meta" || type === "link"
+      ? React.createElement(type, { "data-pylon-meta": "", ...props }, ...children)
+      : React.createElement(type, props, ...children);
   const kids: any[] = [];
   if (m.title != null) kids.push(el("title", { key: "t" }, m.title));
   if (m.description != null) {
@@ -782,11 +792,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,
@@ -796,6 +911,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) {
@@ -803,7 +926,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 });
@@ -816,6 +967,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 });
 }
@@ -838,7 +1003,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);
@@ -847,9 +1012,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
@@ -1049,6 +1250,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
@@ -1057,13 +1293,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(
@@ -1089,7 +1320,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;
     }
@@ -1186,44 +1426,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`.
-      const { serverData: _sd, response: _resp, ...serializableProps } = props;
-      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,
-      };
-      const json = JSON.stringify(hydrationPayload).replaceAll("<", "\\u003c");
-      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"
+          : undefined,
       });
+      sendChunk(tail);
     }
     send({ type: "render_done", call_id: msg.call_id });
@@ -1299,11 +1524,17 @@ export async function handleRenderRoute(
     ) {
       return;
     }
+    // In dev, send the full stack as the message so the host can paint a
+    // useful error overlay instead of an opaque 500. In prod, send only the
+    // message (the host shows a generic page; the stack stays in logs).
+    const devMode =
+      process.env.PYLON_DEV_MODE === "1" || process.env.PYLON_DEV_MODE === "true";
     send({
       type: "error",
       call_id: msg.call_id,
       code: err?.code ?? "SSR_RENDER_FAILED",
-      message: err?.message ?? String(err),
+      message:
+        devMode && err?.stack ? String(err.stack) : err?.message ?? String(err),
     });
   }
 }