@pylonsync/functions 0.3.308 → 0.3.310

package/dist/runtime.d.ts

@@ -15,5 +15,5 @@
  *   needs to queue multiple RPCs per call_id.
  */
 import type { DbReader, DbWriter } from "./types";
-export declare function buildDbReader(callId: string): DbReader;
+export declare function buildDbReader(callId: string, ssrRead?: boolean): DbReader;
 export declare function buildDbWriter(callId: string): DbWriter;

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

@@ -40,6 +40,9 @@ export interface PylonBundleManifest {
         imports: string[];
         /** CSS chunks (Phase 1.5f). */
         css: string[];
+        /** URL pattern (e.g. `/p/[slug]`) — page routes only. Lets the client
+         *  matcher resolve an href to this route for optimistic navigation. */
+        path?: string;
     }>;
     /** Self-hosted fonts (next/font parity): structured `@font-face`s + the
      *  `:root` CSS variables + the woff2 files to preload. Global (route-

package/dist/ssr-route-match.d.ts

@@ -0,0 +1,20 @@
+export interface RouteMatch {
+    /** Route component path — the manifest key + __PYLON_DATA__.component value. */
+    component: string;
+    /** Decoded dynamic params captured from the path (e.g. `{ slug: "shoe-x" }`). */
+    params: Record<string, string>;
+}
+/** The slice of the build manifest this matcher needs. */
+export interface MatchableManifest {
+    routes: Record<string, {
+        path?: string;
+    }>;
+}
+/**
+ * Resolve a concrete pathname to the route that would render it, plus its
+ * decoded dynamic params. Returns null when no page route matches (the caller
+ * then falls back to a normal server round-trip). When several patterns match,
+ * the most specific wins: fewer catch-alls first, then fewer dynamic segments —
+ * so `/orders/new` beats `/orders/[id]` beats `/[...all]`.
+ */
+export declare function matchRoute(manifest: MatchableManifest | null | undefined, pathname: string): RouteMatch | null;

package/dist/ssr-runtime.d.ts

@@ -181,7 +181,7 @@ export declare function makeRevocableReadTrackingProxy(obj: Record<string, unkno
     proxy: Record<string, unknown>;
     revoke: () => void;
 };
-export declare function finalizeHeaders(state: ResponseState, extra?: Record<string, string>, internal?: Record<string, string>): Record<string, string>;
+export declare function finalizeHeaders(state: ResponseState, extra?: Record<string, string>, internal?: Record<string, string>, effectiveStatus?: number): Record<string, string>;
 /**
  * Phase 1 SSR handler. Resolves the component, renders it via
  * react-dom/server.renderToReadableStream, pumps chunks back to the

package/package.json

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

package/src/runtime.ts

@@ -391,11 +391,24 @@ function rpc(callId: string, msg: Record<string, unknown>): Promise<unknown> {
 // `serverData` read handle that reuses this module's `send` + `pendingRpcs`
 // + reader loop. The render call_id ("r_<n>") correlates DB replies back
 // through the shared pendingRpcs map.
-export function buildDbReader(callId: string): DbReader {
-  return { ...buildReaderOps(callId, false), unsafe: buildReaderOps(callId, true) };
+export function buildDbReader(callId: string, ssrRead = false): DbReader {
+  return {
+    ...buildReaderOps(callId, false, ssrRead),
+    unsafe: buildReaderOps(callId, true, ssrRead),
+  };
 }
 
-function buildReaderOps(callId: string, unsafeOp: boolean): Omit<DbReader, "unsafe"> {
+function buildReaderOps(
+  callId: string,
+  unsafeOp: boolean,
+  // `ssrRead`: true when the reader backs SSR `serverData.*` (results are
+  // serialized into the client-visible `__PYLON_DATA__` blob). The Rust side
+  // then applies the same per-row policy filter + `server_only`/`passwordHash`
+  // projection the entity/sync read API does — UNLESS `unsafe_op` is also set
+  // (`serverData.unsafe.*` stays server-trust). Server-function `ctx.db.*`
+  // leaves it false and reads raw.
+  ssrRead = false,
+): Omit<DbReader, "unsafe"> {
   // All DB ops use rpcDb so Promise.all over ctx.db reads can run in
   // parallel without colliding on the outer call_id key.
   //
@@ -412,6 +425,7 @@ function buildReaderOps(callId: string, unsafeOp: boolean): Omit<DbReader, "unsa
         entity,
         id,
         unsafe_op: unsafeOp,
+        ssr_read: ssrRead,
       })) as any;
     },
     async list(entity) {
@@ -420,6 +434,7 @@ function buildReaderOps(callId: string, unsafeOp: boolean): Omit<DbReader, "unsa
         op: "list",
         entity,
         unsafe_op: unsafeOp,
+        ssr_read: ssrRead,
       })) as any;
     },
     async lookup(entity, field, value) {
@@ -430,6 +445,7 @@ function buildReaderOps(callId: string, unsafeOp: boolean): Omit<DbReader, "unsa
         field,
         value,
         unsafe_op: unsafeOp,
+        ssr_read: ssrRead,
       })) as any;
     },
     async query(entity, filter) {
@@ -439,6 +455,7 @@ function buildReaderOps(callId: string, unsafeOp: boolean): Omit<DbReader, "unsa
         entity,
         data: filter,
         unsafe_op: unsafeOp,
+        ssr_read: ssrRead,
       })) as any;
     },
     async queryGraph(query) {
@@ -448,6 +465,7 @@ function buildReaderOps(callId: string, unsafeOp: boolean): Omit<DbReader, "unsa
         entity: "",
         data: query,
         unsafe_op: unsafeOp,
+        ssr_read: ssrRead,
       })) as any;
     },
     async paginate(entity, opts) {
@@ -461,6 +479,7 @@ function buildReaderOps(callId: string, unsafeOp: boolean): Omit<DbReader, "unsa
         after: opts.cursor ?? undefined,
         limit: numItems,
         unsafe_op: unsafeOp,
+        ssr_read: ssrRead,
       })) as any;
     },
     async search(entity, query) {
@@ -470,6 +489,7 @@ function buildReaderOps(callId: string, unsafeOp: boolean): Omit<DbReader, "unsa
         entity,
         data: query,
         unsafe_op: unsafeOp,
+        ssr_read: ssrRead,
       })) as any;
     },
   };
@@ -1057,11 +1077,15 @@ async function main() {
   send({ type: "ready", functions });
 
   // Belt-and-suspenders against orphaning: if the host dies in a way that
-  // somehow leaves our stdin open, we'll have been reparented to init
-  // (ppid === 1). Notice and exit. Unref'd so it never keeps us alive on its
-  // own.
+  // somehow leaves our stdin open, we'll have been REPARENTED — our ppid
+  // changes (to init or the nearest subreaper). Compare against the ppid we
+  // were born with rather than testing `ppid === 1`: in a container the
+  // host pylon usually IS PID 1, so every healthy runner is born with
+  // ppid 1 and the equality check kills the whole pool in a 2s respawn
+  // loop. Unref'd so the watch never keeps us alive on its own.
+  const initialPpid = process.ppid;
   const orphanWatch = setInterval(() => {
-    if (process.ppid === 1) process.exit(0);
+    if (process.ppid !== initialPpid) process.exit(0);
   }, 2000);
   if (typeof orphanWatch.unref === "function") orphanWatch.unref();
 

package/src/ssr-client-bundler.ts

@@ -61,6 +61,12 @@ interface DiscoveredRoute {
   component: string;
   /** Layout chain root → leaf, same format as `component`. */
   layouts: string[];
+  /**
+   * URL pattern this page serves (e.g. `/`, `/p/[slug]`). Set for `page`
+   * routes only — boundary modules (not-found/error) leave it undefined so the
+   * client route matcher (optimistic navigation) never resolves to them.
+   */
+  pattern?: string;
 }
 
 /** Bun.build returns this shape (the subset we depend on). */
@@ -120,7 +126,13 @@ function discoverRoutes(
     return [];
   }
 
-  type PageHit = { segments: string[]; component: string; layouts: string[] };
+  type PageHit = {
+    segments: string[];
+    component: string;
+    layouts: string[];
+    // URL pattern, set for real pages only (boundary modules get none).
+    pattern?: string;
+  };
   const pages: PageHit[] = [];
 
   function walk(dir: string, segments: string[], layouts: string[]): void {
@@ -144,6 +156,8 @@ function discoverRoutes(
         segments: [...segments],
         component: path.relative(cwd, pageHere).replace(/\.(tsx?|jsx?)$/, ""),
         layouts: nextLayouts,
+        // e.g. [] → "/", ["p","[slug]"] → "/p/[slug]".
+        pattern: "/" + segments.join("/"),
       });
     }
     // Boundary modules (not-found.tsx / error.tsx) are hydrated like pages
@@ -176,6 +190,7 @@ function discoverRoutes(
   return pages.map((p) => ({
     component: p.component,
     layouts: p.layouts,
+    pattern: p.pattern,
   }));
 }
 
@@ -209,6 +224,7 @@ const CLIENT_RUNTIME_SOURCE = `// Generated by Pylon SSR (Phase 2 client runtime
 import { createElement } from "react";
 import { hydrateRoot } from "react-dom/client";
 import { createPylonBoundary } from "./client-boundary";
+import { matchRoute } from "./route-match";
 
 const routeCache = Object.create(null);
 let activeRoot = null;
@@ -252,6 +268,13 @@ let navEpoch = 0;
 // (for instance) redirect to /login instead of showing the not-found page.
 let currentPageProps = {};
 
+// Seed data for the in-flight navigation — the object handed to <Link seed>,
+// exposed to the destination page via useRouteSeed() so it can paint its
+// Suspense fallback with real content before the SSR fetch lands. Set at the
+// start of every navigation (to the seed, or null), so useRouteSeed() reads a
+// value that's consistent for the whole nav. Null on hard load / seedless nav.
+let currentSeed = null;
+
 // The not-found / error boundary lives in a real module (./client-boundary,
 // emitted next to this file by the bundler) so its render behavior is
 // unit-testable instead of buried in this string. Wire the runtime's
@@ -329,6 +352,32 @@ function makeClientServerData(ssrData) {
   return sd;
 }
 
+// serverData stand-in used during the OPTIMISTIC first paint of a navigation:
+// every method returns a never-resolving thenable, so a page that use()s it
+// suspends and shows its Suspense fallback (which useRouteSeed() renders from
+// the clicked-link seed). The thenable is cached per key so React never sees an
+// "uncached promise" if it re-renders the optimistic tree. It never resolves on
+// its own — navigate() replaces the whole tree with real, fulfilled serverData
+// the moment the SSR fetch lands, which is what actually swaps fallback→content.
+function makePendingServerData() {
+  const pc = new Map();
+  const pending = () => ({ then() {} });
+  const wrap = (prefix) => {
+    const out = {};
+    for (const m of SERVER_DATA_METHODS) {
+      out[m] = (...args) => {
+        const key = prefix + m + ":" + stableStringify(args);
+        if (!pc.has(key)) pc.set(key, pending());
+        return pc.get(key);
+      };
+    }
+    return out;
+  };
+  const sd = wrap("");
+  sd.unsafe = wrap("u:");
+  return sd;
+}
+
 // Server-only response controller has no meaning on the client (the status/
 // redirect/cookies already shipped). Give pages a no-op so a body that
 // touches props.response during hydration doesn't crash.
@@ -353,8 +402,11 @@ function makeNoopResponse() {
 // in a deep client child has a reactive source. A fresh object per nav → stable
 // reference between navs (useSyncExternalStore needs that).
 let currentParams = {};
+function setNavParamsRaw(params) {
+  currentParams = params || {};
+}
 function setNavParams(data) {
-  currentParams = (data && data.props && data.props.params) || {};
+  setNavParamsRaw(data && data.props && data.props.params);
 }
 
 function withClientProps(data) {
@@ -530,9 +582,63 @@ async function navigate(href, opts) {
     window.location.href = href;
     return;
   }
+  const target = url.pathname + url.search;
+
+  // Claim an epoch for this navigation. A later navigate() bumps navEpoch, so
+  // every await below can bail once it's been superseded by a newer nav —
+  // otherwise a slow fetch could render a stale destination over a newer one.
+  const myEpoch = ++navEpoch;
+  currentSeed = opts && opts.seed != null ? opts.seed : null;
+
+  // ---- Optimistic first paint --------------------------------------------
+  // With a seed AND a client-resolvable route, render the destination NOW —
+  // before the SSR fetch — with a pending serverData, so the page shows its
+  // Suspense fallback painted from the seed (via useRouteSeed). The real render
+  // below swaps in full data in place. Any failure (no route match, chunk load
+  // error) falls through to the normal blocking fetch-then-render path, so a
+  // seed can never break navigation. Requires the page to keep its serverData
+  // reads inside a <Suspense> (the store detail page does) — a bare top-level
+  // use() would suspend the whole page with no seeded fallback to show.
+  let didOptimistic = false;
+  if (currentSeed != null && activeRoot) {
+    try {
+      const manifest = await loadManifest();
+      if (myEpoch !== navEpoch) return;
+      const matched = matchRoute(manifest, url.pathname);
+      if (matched) {
+        const route = await loadRouteEntry(matched.component);
+        if (myEpoch !== navEpoch) return;
+        setNavParamsRaw(matched.params);
+        currentPageProps = {
+          params: matched.params,
+          serverData: makePendingServerData(),
+          response: makeNoopResponse(),
+        };
+        const tree = withBoundary(
+          buildTree(route.Page, route.Layouts, currentPageProps),
+          matched.component,
+          myEpoch,
+        );
+        pendingNav = target;
+        activeRoot.render(tree);
+        if (opts && opts.replace) {
+          history.replaceState({ component: matched.component }, "", target);
+        } else if (push) {
+          history.pushState({ component: matched.component }, "", target);
+        }
+        window.dispatchEvent(new Event("pylon:navigation"));
+        window.scrollTo(0, 0);
+        didOptimistic = true;
+      }
+    } catch (e) {
+      // Fall through to the normal fetch-then-render path below.
+    }
+  }
+
+  // ---- Real fetch + render -----------------------------------------------
   let html;
   try {
-    const res = await fetch(url.pathname + url.search, {
+    const res = await fetch(target, {
       credentials: "same-origin",
       headers: { Accept: "text/html" },
     });
@@ -545,6 +651,7 @@ async function navigate(href, opts) {
     window.location.href = href;
     return;
   }
+  if (myEpoch !== navEpoch) return;
   const doc = new DOMParser().parseFromString(html, "text/html");
   const dataEl = doc.getElementById("__PYLON_DATA__");
   if (!dataEl) {
@@ -566,16 +673,23 @@ async function navigate(href, opts) {
     window.location.href = href;
     return;
   }
+  if (myEpoch !== navEpoch) return;
   document.title = doc.title || document.title;
   syncHeadMeta(doc);
   setNavParams(data);
-  navEpoch++;
+  // Keep currentSeed set for the rest of this nav: useRouteData renders the seed
+  // as CONTENT (not a Suspense fallback) and upgrades it to real data in place,
+  // so the seed must stay readable across the optimistic→real render. It's reset
+  // at the START of the next navigation. (Clearing it here would degrade the
+  // page to its skeleton for a frame during the swap — a visible flash.)
   currentPageProps = withClientProps(data);
-  const target = url.pathname + url.search;
+  // Reuse myEpoch (do NOT bump) so the optimistic tree and the real tree share
+  // a boundary identity: React resolves the Suspense fallback into the real
+  // content in place instead of remounting the whole subtree (no flash).
   const tree = withBoundary(
     buildTree(route.Page, route.Layouts, currentPageProps),
     data.component,
-    navEpoch,
+    myEpoch,
   );
   // Track the in-flight destination so hydrateRoot's onUncaughtError can fall
   // back to a full page load if this re-render throws in React's commit phase
@@ -586,17 +700,23 @@ async function navigate(href, opts) {
   setTimeout(() => {
     if (pendingNav === target) pendingNav = null;
   }, 0);
-  if (opts && opts.replace) {
+  if (didOptimistic) {
+    // URL + scroll already handled during the optimistic paint; only keep the
+    // history entry's component in sync with the authoritative SSR component.
     history.replaceState({ component: data.component }, "", target);
-  } else if (push) {
-    history.pushState({ component: data.component }, "", target);
+  } else {
+    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);
   }
-  // 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);
 }
 
 function installNavHandlers() {
@@ -616,7 +736,12 @@ function installNavHandlers() {
       return;
     }
     e.preventDefault();
-    navigate(href);
+    // A <Link seed> registers its seed in window.__pylonLinkSeeds keyed by the
+    // anchor element; pass it through so navigate() can paint optimistically.
+    const seeds =
+      typeof window !== "undefined" ? window.__pylonLinkSeeds : undefined;
+    const seed = seeds ? seeds.get(link) : undefined;
+    navigate(href, seed != null ? { seed } : undefined);
   });
   window.addEventListener("popstate", () => {
     navigate(location.pathname + location.search, { push: false });
@@ -677,6 +802,11 @@ const pylonGlobal = {
   get params() {
     return currentParams;
   },
+  // Read by useRouteSeed(); the seed the active navigation was started with
+  // (from <Link seed>), or null. A getter so it always reflects the latest nav.
+  get seed() {
+    return currentSeed;
+  },
 };
 if (typeof window !== "undefined") {
   window.__pylon = pylonGlobal;
@@ -759,6 +889,9 @@ export interface PylonBundleManifest {
       imports: string[];
       /** CSS chunks (Phase 1.5f). */
       css: string[];
+      /** URL pattern (e.g. `/p/[slug]`) — page routes only. Lets the client
+       *  matcher resolve an href to this route for optimistic navigation. */
+      path?: string;
     }
   >;
   /** Self-hosted fonts (next/font parity): structured `@font-face`s + the
@@ -1044,6 +1177,15 @@ async function _doBuildInner(
       "utf8",
     );
 
+    // Same pattern for the optimistic-navigation route matcher — the runtime
+    // imports it as `./route-match`; its source of truth is ssr-route-match.ts,
+    // unit-tested directly.
+    fs.writeFileSync(
+      path.join(stageDir, "route-match.ts"),
+      fs.readFileSync(path.join(here, "ssr-route-match.ts"), "utf8"),
+      "utf8",
+    );
+
     const entryPaths: string[] = [];
     // entryPath (absolute) → component path (for manifest lookup).
     const entryToComponent = new Map<string, string>();
@@ -1197,6 +1339,9 @@ async function _doBuildInner(
         file: entry.relPath,
         imports: Array.from(seen),
         css: [],
+        // Page routes carry their URL pattern for the client route matcher;
+        // boundary modules (no pattern) are omitted so they never match.
+        ...(r.pattern ? { path: r.pattern } : {}),
       };
     }
 

package/src/ssr-form-runtime.ts

@@ -172,11 +172,15 @@ export async function handleForm(
       for (const [k, v] of Object.entries(raw.headers ?? {})) {
         extra[k.toLowerCase()] = String(v);
       }
+      const rawStatus = raw.status ?? responseState.status;
       send({
         type: "response_start",
         call_id: msg.call_id,
-        status: raw.status ?? responseState.status,
-        headers: finalizeHeaders(responseState, extra),
+        status: rawStatus,
+        // Pass rawStatus so the open-redirect guard sees the handler's own
+        // status (a raw GET's redirect status lives on `raw.status`, not
+        // `responseState.status`).
+        headers: finalizeHeaders(responseState, extra, undefined, rawStatus),
       });
       if (raw.body != null) {
         const bodyStr =

package/src/ssr-route-match.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "bun:test";
+import { matchRoute, type MatchableManifest } from "./ssr-route-match";
+
+const manifest: MatchableManifest = {
+  routes: {
+    "app/page": { path: "/" },
+    "app/account/page": { path: "/account" },
+    "app/checkout/page": { path: "/checkout" },
+    "app/p/[slug]/page": { path: "/p/[slug]" },
+    "app/orders/[id]/page": { path: "/orders/[id]" },
+    "app/orders/new/page": { path: "/orders/new" },
+    "app/docs/[...rest]/page": { path: "/docs/[...rest]" },
+    // Boundary modules ship without a `path` and must never match.
+    "app/p/[slug]/not-found": {},
+  },
+};
+
+describe("matchRoute", () => {
+  it("matches the index route", () => {
+    expect(matchRoute(manifest, "/")).toEqual({
+      component: "app/page",
+      params: {},
+    });
+  });
+
+  it("matches a static route", () => {
+    expect(matchRoute(manifest, "/account")).toEqual({
+      component: "app/account/page",
+      params: {},
+    });
+  });
+
+  it("captures a dynamic segment and decodes it", () => {
+    expect(matchRoute(manifest, "/p/blue-runner-9f3a2b")).toEqual({
+      component: "app/p/[slug]/page",
+      params: { slug: "blue-runner-9f3a2b" },
+    });
+    expect(matchRoute(manifest, "/p/a%20b")).toEqual({
+      component: "app/p/[slug]/page",
+      params: { slug: "a b" },
+    });
+  });
+
+  it("prefers a static route over a dynamic one at the same depth", () => {
+    expect(matchRoute(manifest, "/orders/new")).toEqual({
+      component: "app/orders/new/page",
+      params: {},
+    });
+    expect(matchRoute(manifest, "/orders/o_123")).toEqual({
+      component: "app/orders/[id]/page",
+      params: { id: "o_123" },
+    });
+  });
+
+  it("matches a catch-all across the remaining segments", () => {
+    expect(matchRoute(manifest, "/docs/guide/getting-started")).toEqual({
+      component: "app/docs/[...rest]/page",
+      params: { rest: "guide/getting-started" },
+    });
+  });
+
+  it("ignores trailing slashes", () => {
+    expect(matchRoute(manifest, "/account/")).toEqual({
+      component: "app/account/page",
+      params: {},
+    });
+  });
+
+  it("returns null when nothing matches", () => {
+    expect(matchRoute(manifest, "/does/not/exist")).toBeNull();
+  });
+
+  it("never matches a boundary module (no path)", () => {
+    // /p/anything resolves to the page, never the not-found boundary.
+    const m = matchRoute(manifest, "/p/anything");
+    expect(m?.component).toBe("app/p/[slug]/page");
+  });
+
+  it("is null-safe on an empty/absent manifest", () => {
+    expect(matchRoute(null, "/")).toBeNull();
+    expect(matchRoute({ routes: {} }, "/")).toBeNull();
+  });
+});

package/src/ssr-route-match.ts

@@ -0,0 +1,104 @@
+// Client-side route matcher for optimistic navigation.
+//
+// The SSR server owns the authoritative path→component mapping, but for
+// optimistic navigation (painting a destination's Suspense fallback with a
+// `<Link seed>` BEFORE the SSR fetch resolves) the client must resolve the
+// destination route from the clicked href on its own. The build manifest ships
+// each page route's `path` pattern (e.g. `/p/[slug]`) for exactly this — this
+// module is the pure matcher over those patterns.
+//
+// Kept in its own module (not inlined in CLIENT_RUNTIME_SOURCE) so it has one
+// source of truth and is unit-tested directly. The client bundler stages a copy
+// next to the generated runtime, which imports it as `./route-match`.
+
+export interface RouteMatch {
+  /** Route component path — the manifest key + __PYLON_DATA__.component value. */
+  component: string;
+  /** Decoded dynamic params captured from the path (e.g. `{ slug: "shoe-x" }`). */
+  params: Record<string, string>;
+}
+
+/** The slice of the build manifest this matcher needs. */
+export interface MatchableManifest {
+  routes: Record<string, { path?: string }>;
+}
+
+function splitPath(p: string): string[] {
+  const trimmed = p.replace(/\/+$/, "");
+  return trimmed === "" ? [] : trimmed.slice(1).split("/");
+}
+
+interface SegMatch {
+  params: Record<string, string>;
+  /** Count of `[param]` segments — lower is more specific. */
+  dynamic: number;
+  /** Count of `[...rest]` catch-alls — dominates specificity. */
+  catchAll: number;
+}
+
+// Match a route pattern's segments against a concrete path's segments. Handles
+// static segments, `[param]` (single segment), and `[...param]` (catch-all,
+// consumes the remainder). Returns null on any mismatch.
+function matchSegments(
+  patSegs: string[],
+  targetSegs: string[],
+): SegMatch | null {
+  const params: Record<string, string> = {};
+  let dynamic = 0;
+  for (let i = 0; i < patSegs.length; i++) {
+    const seg = patSegs[i];
+    if (seg.startsWith("[...") && seg.endsWith("]")) {
+      const name = seg.slice(4, -1);
+      params[name] = targetSegs
+        .slice(i)
+        .map(safeDecode)
+        .join("/");
+      return { params, dynamic, catchAll: 1 };
+    }
+    if (i >= targetSegs.length) return null;
+    if (seg.startsWith("[") && seg.endsWith("]")) {
+      params[seg.slice(1, -1)] = safeDecode(targetSegs[i]);
+      dynamic++;
+    } else if (seg !== targetSegs[i]) {
+      return null;
+    }
+  }
+  // No catch-all consumed the tail, so the lengths must line up exactly.
+  if (targetSegs.length !== patSegs.length) return null;
+  return { params, dynamic, catchAll: 0 };
+}
+
+function safeDecode(s: string): string {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+}
+
+/**
+ * Resolve a concrete pathname to the route that would render it, plus its
+ * decoded dynamic params. Returns null when no page route matches (the caller
+ * then falls back to a normal server round-trip). When several patterns match,
+ * the most specific wins: fewer catch-alls first, then fewer dynamic segments —
+ * so `/orders/new` beats `/orders/[id]` beats `/[...all]`.
+ */
+export function matchRoute(
+  manifest: MatchableManifest | null | undefined,
+  pathname: string,
+): RouteMatch | null {
+  if (!manifest || !manifest.routes) return null;
+  const targetSegs = splitPath(pathname);
+  let best: { match: RouteMatch; score: number } | null = null;
+  for (const component of Object.keys(manifest.routes)) {
+    const route = manifest.routes[component];
+    if (!route || typeof route.path !== "string") continue;
+    const m = matchSegments(splitPath(route.path), targetSegs);
+    if (!m) continue;
+    const score = m.catchAll * 1000 + m.dynamic;
+    if (best === null || score < best.score) {
+      best = { match: { component, params: m.params }, score };
+    }
+  }
+  return best ? best.match : null;
+}

package/src/ssr-runtime.test.ts

@@ -127,6 +127,54 @@ describe("reserved x-pylon-* header namespace (cache-proof forgery fence)", () =
     expect(out2["x-pylon-cacheable"]).toBeUndefined();
   });
 
+  test("finalizeHeaders: 3xx open-redirect guard on setHeader('location') / returned headers", () => {
+    const st = (status: number, location: string) => ({
+      status,
+      headers: { location } as Record<string, string>,
+      cookies: [] as string[],
+    });
+
+    // An off-site absolute Location on a 3xx (set via setHeader or a route
+    // handler's returned headers) is refused — the same rule redirect() applies.
+    expect(() => finalizeHeaders(st(302, "https://evil.example/steal"))).toThrow(
+      /open redirect/i,
+    );
+    // Protocol-relative `//host` is the classic bypass — also refused.
+    expect(() => finalizeHeaders(st(307, "//evil.example"))).toThrow(/open redirect/i);
+    // A backslash variant that browsers normalize cross-origin — refused.
+    expect(() => finalizeHeaders(st(303, "/\\evil.example"))).toThrow(/open redirect/i);
+
+    // A same-site relative path is fine and passes through unchanged.
+    expect(finalizeHeaders(st(302, "/dashboard"))["location"]).toBe("/dashboard");
+
+    // Case-insensitive header name is still caught (host lowercases, but guard
+    // must not depend on that).
+    expect(() =>
+      finalizeHeaders({
+        status: 302,
+        headers: { Location: "https://evil.example" } as Record<string, string>,
+        cookies: [],
+      }),
+    ).toThrow(/open redirect/i);
+
+    // NON-3xx status → `location` is just a header, not a redirect: no guard.
+    expect(
+      finalizeHeaders(st(200, "https://evil.example"))["location"],
+    ).toBe("https://evil.example");
+
+    // A raw `route.ts` GET returns its OWN status via the `effectiveStatus`
+    // arg — an off-site Location there is still refused even though
+    // `state.status` is 200.
+    expect(() =>
+      finalizeHeaders(
+        { status: 200, headers: {}, cookies: [] },
+        { location: "https://evil.example" },
+        undefined,
+        302,
+      ),
+    ).toThrow(/open redirect/i);
+  });
+
   test("makeReadTrackingProxy trips on get / in / Object.keys / descriptor / spread", () => {
     const probes: Array<(o: any) => unknown> = [
       (o) => o.host,

package/src/ssr-runtime.ts

@@ -385,6 +385,10 @@ export function finalizeHeaders(
   // TRUSTED runtime headers (e.g. the #277 `x-pylon-cacheable` proof). The ONLY
   // legitimate source of `x-pylon-*`; merged last and never stripped.
   internal?: Record<string, string>,
+  // The status this header map ships with, when it isn't `state.status` (a raw
+  // `route.ts` GET handler returns its own status). Used for the open-redirect
+  // guard below. Defaults to `state.status`.
+  effectiveStatus?: number,
 ): Record<string, string> {
   // The host TRUSTS `x-pylon-*` headers (cache verdict, etc.). They must come
   // ONLY from `internal` — strip them from BOTH page-set headers AND `extra` so
@@ -402,6 +406,34 @@ export function finalizeHeaders(
   mergeStripped(state.headers);
   mergeStripped(extra);
   if (internal) Object.assign(h, internal); // trusted, never stripped
+  // SECURITY: open-redirect guard. A 3xx response's `Location` must be same-site
+  // or a trusted host — the SAME rule `response.redirect()` enforces — no matter
+  // how it was set: `response.setHeader("location", …)`, a `route.ts` handler's
+  // returned `headers`, or a `location` in `extra`. Those paths skip
+  // `redirect()`'s check, so without this a request-derived value becomes an
+  // off-site redirect. Fail loud (throws → 500/error boundary) rather than
+  // silently emitting the redirect. The `redirect()`/route-control paths pass an
+  // already-validated URL, so re-checking them here is a safe no-op.
+  const status = effectiveStatus ?? state.status;
+  if (status >= 300 && status < 400) {
+    const locKey = Object.keys(h).find((k) => k.toLowerCase() === "location");
+    if (locKey != null) {
+      const env = (globalThis as any).process?.env ?? {};
+      if (
+        !isSafeRedirect(h[locKey], {
+          publicUrl: env.PYLON_PUBLIC_URL,
+          canonicalHost: env.PYLON_CANONICAL_HOST,
+          trustedHostsCsv: env.PYLON_TRUSTED_HOSTS,
+        })
+      ) {
+        throw new Error(
+          `pylon ssr: refused an untrusted redirect target ${JSON.stringify(h[locKey])} ` +
+            `in a ${status} response — use a same-site path (e.g. "/dashboard") or add the ` +
+            `host to PYLON_TRUSTED_HOSTS. (Refusing to emit an open redirect.)`,
+        );
+      }
+    }
+  }
   if (!h["content-type"]) h["content-type"] = "text/html; charset=utf-8";
   if (state.cookies.length > 0) {
     // Preserve a set-cookie value set via setHeader() (rare) and join it
@@ -2397,8 +2429,12 @@ export async function handleRenderRoute(
     // cached so `use()` doesn't re-suspend forever; resolved values land in
     // `ssrValueCache` for hydration replay.
     const { buildDbReader } = await import("./runtime");
+    // `ssrRead: true` — serverData results are serialized into the
+    // client-visible `__PYLON_DATA__` blob, so the host applies the same
+    // per-row policy filter + `server_only`/`passwordHash` projection the
+    // entity/sync read API does. `serverData.unsafe.*` stays server-trust.
     const serverData = makeServerData(
-      buildDbReader(msg.call_id),
+      buildDbReader(msg.call_id, true),
       ssrValueCache,
     );