@pylonsync/functions 0.3.308 → 0.3.309

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/package.json

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

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-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;
+}