@pylonsync/functions 0.4.8 → 0.4.10

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

@@ -1,15 +1,19 @@
+/** A per-directory module resolved by walking up from a route: the two error
+ *  boundaries, plus `loading` (the pending-navigation skeleton). */
+export type BoundaryFile = "not-found" | "error" | "loading";
 /**
- * Resolve the nearest boundary module (`<dir>/not-found` or `<dir>/error`)
- * for a route by walking its component path up to the app root, returning the
- * first manifest route key that exists. Nearest ancestor wins — the same model
- * the server's `findBoundary` uses, but driven off the client build manifest's
- * route keys so the client runtime needs no extra server round-trip.
+ * Resolve the nearest `<dir>/<fileName>` module for a route by walking its
+ * component path up to the app root, returning the first key that exists.
+ * Nearest ancestor wins — the same model the server's `findBoundary` uses, but
+ * driven off client-side keys so the runtime needs no extra server round-trip.
  *
  * `component` is a cwd-relative path with "/" separators and no extension
- * (e.g. "web/app/dashboard/orgs/[slug]/page"); `routeKeys` is
- * `Object.keys(manifest.routes)`.
+ * (e.g. "web/app/dashboard/orgs/[slug]/page"). `keys` is the set to resolve
+ * against: `Object.keys(manifest.routes)` for not-found/error, which ship as
+ * route entries, or the loading registry's keys for `loading`, which ships in
+ * the shared chunk instead.
  */
-export declare function nearestBoundaryComponent(component: string, fileName: "not-found" | "error", routeKeys: Iterable<string>): string | null;
+export declare function nearestBoundaryComponent(component: string, fileName: BoundaryFile, routeKeys: Iterable<string>): string | null;
 /** Runtime internals the boundary needs, injected so the module stays
  *  browser-safe AND unit-testable. */
 export interface BoundaryDeps {

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

@@ -24,6 +24,30 @@ interface BundleClientMessage {
  * import into a loud build failure that names the offending importer.
  */
 export declare function assertNotServerOnly(specifier: string, importer: string): void;
+/**
+ * Every route-level `loading` module under the app dir, as project-relative
+ * component paths (`app/dashboard/loading`), sorted for a stable build.
+ *
+ * Unlike not-found / error, these get NO client entry of their own — see
+ * `generateLoadingRegistry` for why.
+ */
+export declare function discoverLoadingModules(fs: any, path: any, cwd: string, appDirRel: string): string[];
+/**
+ * The module the client runtime imports as `./loading-registry`: every
+ * loading.tsx in the app, keyed by component path so the runtime can walk up
+ * from a destination route to its nearest one — the same nearest-ancestor rule
+ * the server's findBoundary applies.
+ *
+ * Statically imported, so these land in the SHARED chunk rather than shipping
+ * as route entries the way not-found / error do. A loading state exists to
+ * acknowledge a click that is already waiting on the network; fetching a chunk
+ * to render it would put it behind the very delay it covers.
+ *
+ * Route groups need no special handling: a page under `app/(dash)/settings`
+ * resolves against `app/(dash)/loading` by path, exactly as it does on the
+ * server.
+ */
+export declare function generateLoadingRegistry(components: string[]): string;
 /**
  * Manifest schema. One entry per route, indexed by the same
  * project-relative component path the SSR side passes through.

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

@@ -4,10 +4,14 @@ export interface RouteMatch {
     /** 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. */
+/** The slice of the build manifest this module needs. */
 export interface MatchableManifest {
     routes: Record<string, {
         path?: string;
+        /** The route's own entry chunk (outdir-relative). */
+        file?: string;
+        /** Shared chunks the browser needs before that entry runs. */
+        imports?: string[];
     }>;
 }
 /**
@@ -18,3 +22,22 @@ export interface MatchableManifest {
  * so `/orders/new` beats `/orders/[id]` beats `/[...all]`.
  */
 export declare function matchRoute(manifest: MatchableManifest | null | undefined, pathname: string): RouteMatch | null;
+/** What `<Link prefetch>` should warm for a destination href. */
+export interface PrefetchTargets {
+    /** The destination route's own entry chunk, or "" when no page route matches. */
+    file: string;
+    /** Shared chunks to warm alongside it. */
+    imports: string[];
+}
+/**
+ * The chunks a click on `pathname` will need before anything can render: the
+ * destination route's entry, plus the shared chunks (React, the client
+ * runtime, common layouts) that every route pulls in.
+ *
+ * Warming the page payload alone leaves the entry chunk to be fetched after
+ * the click, and the route cannot render until it lands — so the prefetch
+ * covers only the half that was already fast. An href matching no page route
+ * (an API path, a route this build doesn't serve) still yields the shared set;
+ * `file` is "" and the caller skips it.
+ */
+export declare function prefetchTargets(manifest: MatchableManifest | null | undefined, pathname: string): PrefetchTargets;

package/dist/ssr-runtime.d.ts

@@ -339,6 +339,28 @@ export declare function isSafeRedirect(url: string, opts: {
  *  into a page's metadata. Explicit `metadata.icons.*` wins. */
 export declare function applyAutoIcons(component: string, metadata: SsrMetadata | undefined): SsrMetadata | undefined;
 export declare function applyAutoSocialImages(component: string, headers: Record<string, string> | undefined, metadata: SsrMetadata | undefined, requestUrl?: string): SsrMetadata | undefined;
+/**
+ * Drain a `renderToReadableStream` reader, injecting `headBlob` immediately
+ * before the first `</head>` (or, if the document has none, the blob is
+ * never emitted — fragment renders have no head). `</head>` can straddle a
+ * chunk boundary, so a small carry buffer (len("</head>") − 1 bytes) is
+ * withheld at each chunk's tail until the next read confirms the match.
+ * Each emitted slice is handed to `sendChunk` as utf-8 text.
+ *
+ * Shared by the page render and the boundary render so head injection has
+ * exactly one implementation.
+ *
+ * Decoding uses ONE `TextDecoder` with `{stream: true}` for the whole
+ * reader, never a per-chunk decode. React splits the byte stream at
+ * arbitrary offsets, so a multi-byte character can land across two chunks;
+ * decoding each chunk independently turns the orphaned bytes into one
+ * U+FFFD apiece — `…` (e2 80 a6) arrives as three replacement characters.
+ * The failure is silent and position-dependent: markup added anywhere
+ * earlier shifts the boundary, so a page can render correctly for months
+ * and corrupt on an unrelated CSS change. A streaming decoder holds the
+ * partial sequence back until the bytes that complete it arrive.
+ */
+export declare function streamWithHeadInjection(reader: ReadableStreamDefaultReader<Uint8Array>, headBlob: string, sendChunk: (text: string) => void): Promise<void>;
 /**
  * Dev-only tail chunk: the `__PYLON_DEV__` info blob (cache verdict, render
  * mode/timing, route) + the HUD bootstrap. Embedded after the page tail so the

package/package.json

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

package/src/ssr-client-boundary.ts

@@ -21,20 +21,25 @@
 
 import { Component, createElement, useEffect, useState } from "react";
 
+/** A per-directory module resolved by walking up from a route: the two error
+ *  boundaries, plus `loading` (the pending-navigation skeleton). */
+export type BoundaryFile = "not-found" | "error" | "loading";
+
 /**
- * Resolve the nearest boundary module (`<dir>/not-found` or `<dir>/error`)
- * for a route by walking its component path up to the app root, returning the
- * first manifest route key that exists. Nearest ancestor wins — the same model
- * the server's `findBoundary` uses, but driven off the client build manifest's
- * route keys so the client runtime needs no extra server round-trip.
+ * Resolve the nearest `<dir>/<fileName>` module for a route by walking its
+ * component path up to the app root, returning the first key that exists.
+ * Nearest ancestor wins — the same model the server's `findBoundary` uses, but
+ * driven off client-side keys so the runtime needs no extra server round-trip.
  *
  * `component` is a cwd-relative path with "/" separators and no extension
- * (e.g. "web/app/dashboard/orgs/[slug]/page"); `routeKeys` is
- * `Object.keys(manifest.routes)`.
+ * (e.g. "web/app/dashboard/orgs/[slug]/page"). `keys` is the set to resolve
+ * against: `Object.keys(manifest.routes)` for not-found/error, which ship as
+ * route entries, or the loading registry's keys for `loading`, which ships in
+ * the shared chunk instead.
  */
 export function nearestBoundaryComponent(
   component: string,
-  fileName: "not-found" | "error",
+  fileName: BoundaryFile,
   routeKeys: Iterable<string>,
 ): string | null {
   const keys = routeKeys instanceof Set ? routeKeys : new Set(routeKeys);

package/src/ssr-client-bundler.test.ts

@@ -25,6 +25,8 @@ import {
   buildClientBundle,
   buildTailwind,
   assertNotServerOnly,
+  discoverLoadingModules,
+  generateLoadingRegistry,
   type PylonBundleManifest,
 } from "./ssr-client-bundler";
 import { nearestBoundaryComponent } from "./ssr-client-boundary";
@@ -488,3 +490,163 @@ describe("server-only guard (secrets can't leak into the client bundle)", () =>
     fs.rmSync(dir, { recursive: true, force: true });
   });
 });
+
+// ---------------------------------------------------------------------------
+// loading.tsx during client-side navigation.
+//
+// Regression: a route-level loading.tsx was honored ONLY by the server's
+// streaming render. The client bundler emitted entries for not-found and error
+// but not loading, so no loading module existed on the client at all and a
+// pending navigation left the previous page fully painted until the
+// destination was ready. Polling the DOM every 15ms across a sidebar click
+// never saw the skeleton; the same route hard-loaded streamed it fine.
+// ---------------------------------------------------------------------------
+
+const LOADING_BODY = `
+import React from "react";
+export default function Loading() {
+  return <div aria-busy="true" data-skeleton="pylon-pending">Loading…</div>;
+}
+`;
+
+describe("discoverLoadingModules", () => {
+  test("finds loading modules at every depth, sorted", () => {
+    tempDir = makeFixture(
+      {
+        "page.tsx": PAGE_BODY("Home"),
+        "loading.tsx": LOADING_BODY,
+        "dashboard/page.tsx": PAGE_BODY("Dash"),
+        "dashboard/events/[id]/page.tsx": PAGE_BODY("Event"),
+        "dashboard/events/[id]/loading.tsx": LOADING_BODY,
+      },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    expect(discoverLoadingModules(fs, path, tempDir, "app")).toEqual([
+      "app/dashboard/events/[id]/loading",
+      "app/loading",
+    ]);
+  });
+
+  test("finds one inside a route group", () => {
+    // Chrome commonly lives in a (group) layout; its loading sibling has to be
+    // discoverable by the same path walk the server uses.
+    tempDir = makeFixture(
+      {
+        "(dash)/settings/page.tsx": PAGE_BODY("Settings"),
+        "(dash)/loading.tsx": LOADING_BODY,
+      },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    expect(discoverLoadingModules(fs, path, tempDir, "app")).toEqual([
+      "app/(dash)/loading",
+    ]);
+  });
+
+  test("an app with no loading.tsx yields an empty list, not an error", () => {
+    tempDir = makeFixture(
+      { "page.tsx": PAGE_BODY("Home") },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    expect(discoverLoadingModules(fs, path, tempDir, "app")).toEqual([]);
+  });
+});
+
+describe("generateLoadingRegistry", () => {
+  test("keys each module by component path so the nearest-ancestor walk works", () => {
+    const src = generateLoadingRegistry([
+      "app/loading",
+      "app/dashboard/loading",
+    ]);
+    expect(src).toContain(`import M0 from "../app/loading";`);
+    expect(src).toContain(`import M1 from "../app/dashboard/loading";`);
+    expect(src).toContain(`"app/loading": M0,`);
+    expect(src).toContain(`"app/dashboard/loading": M1,`);
+  });
+
+  test("emits a valid empty registry when the app has none", () => {
+    // The runtime imports LOADING_MODULES unconditionally — an app without a
+    // loading.tsx must still produce a module that parses and exports it.
+    const src = generateLoadingRegistry([]);
+    expect(src).toContain("export const LOADING_MODULES = {");
+    expect(src).not.toContain("import M0");
+  });
+});
+
+describe("nearestBoundaryComponent resolves loading.tsx", () => {
+  const loadingKeys = new Set([
+    "web/app/loading",
+    "web/app/dashboard/events/[id]/loading",
+  ]);
+
+  test("a sibling route picks up the nearest ancestor's skeleton", () => {
+    // Every tab under events/[id] shares that one loading.tsx.
+    expect(
+      nearestBoundaryComponent(
+        "web/app/dashboard/events/[id]/speakers/page",
+        "loading",
+        loadingKeys,
+      ),
+    ).toBe("web/app/dashboard/events/[id]/loading");
+  });
+
+  test("falls back to the root skeleton outside that subtree", () => {
+    expect(
+      nearestBoundaryComponent("web/app/settings/page", "loading", loadingKeys),
+    ).toBe("web/app/loading");
+  });
+
+  test("returns null when the app ships none", () => {
+    expect(
+      nearestBoundaryComponent("web/app/page", "loading", new Set()),
+    ).toBeNull();
+  });
+});
+
+describe("loading.tsx is wired into the client build", () => {
+  test("ships in the SHARED chunk — a skeleton can't wait on its own fetch", async () => {
+    tempDir = makeFixture(
+      {
+        "page.tsx": PAGE_BODY("Home"),
+        "dashboard/page.tsx": PAGE_BODY("Dash"),
+        "dashboard/loading.tsx": LOADING_BODY,
+      },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    originalCwd = process.cwd();
+    process.chdir(tempDir);
+
+    const { manifestPath, outdir } = await buildClientBundle();
+    const manifest = JSON.parse(
+      fs.readFileSync(manifestPath, "utf8"),
+    ) as PylonBundleManifest;
+
+    // Not a route entry: it has no URL of its own, and a loading state that
+    // costs a chunk fetch sits behind the very delay it exists to cover.
+    expect(manifest.routes["app/dashboard/loading"]).toBeUndefined();
+
+    const sharedChunks = fs
+      .readdirSync(path.join(outdir, "chunks"))
+      .map((n) => fs.readFileSync(path.join(outdir, "chunks", n), "utf8"))
+      .join("\n");
+    // The skeleton's own markup, and the registry key the runtime walks to.
+    expect(sharedChunks).toContain("pylon-pending");
+    expect(sharedChunks).toContain("app/dashboard/loading");
+  });
+
+  test("an app with no loading.tsx still builds and navigates", async () => {
+    // The runtime's import of ./loading-registry is unconditional, so the
+    // staged module must exist even with nothing to put in it.
+    tempDir = makeFixture(
+      { "page.tsx": PAGE_BODY("Home"), "about/page.tsx": PAGE_BODY("About") },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    originalCwd = process.cwd();
+    process.chdir(tempDir);
+
+    const { manifestPath } = await buildClientBundle();
+    expect(fs.existsSync(manifestPath)).toBe(true);
+    expect(
+      fs.existsSync(path.join(tempDir, ".pylon", "loading-registry.ts")),
+    ).toBe(true);
+  });
+});

package/src/ssr-client-bundler.ts

@@ -230,6 +230,77 @@ function discoverRoutes(
   }));
 }
 
+/**
+ * Every route-level `loading` module under the app dir, as project-relative
+ * component paths (`app/dashboard/loading`), sorted for a stable build.
+ *
+ * Unlike not-found / error, these get NO client entry of their own — see
+ * `generateLoadingRegistry` for why.
+ */
+export function discoverLoadingModules(
+  fs: any,
+  path: any,
+  cwd: string,
+  appDirRel: string,
+): string[] {
+  const found: string[] = [];
+  function walk(dir: string) {
+    let entries: any[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    const here = ["loading.tsx", "loading.ts", "loading.jsx", "loading.js"]
+      .map((n: string) => path.join(dir, n))
+      .find((p: string) => fs.existsSync(p));
+    if (here) {
+      found.push(
+        path.relative(cwd, here).replace(/\.(tsx?|jsx?)$/, "").replace(/\\/g, "/"),
+      );
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (e.name.startsWith(".") || e.name === "node_modules") continue;
+      walk(path.join(dir, e.name));
+    }
+  }
+  walk(path.join(cwd, appDirRel));
+  found.sort();
+  return found;
+}
+
+/**
+ * The module the client runtime imports as `./loading-registry`: every
+ * loading.tsx in the app, keyed by component path so the runtime can walk up
+ * from a destination route to its nearest one — the same nearest-ancestor rule
+ * the server's findBoundary applies.
+ *
+ * Statically imported, so these land in the SHARED chunk rather than shipping
+ * as route entries the way not-found / error do. A loading state exists to
+ * acknowledge a click that is already waiting on the network; fetching a chunk
+ * to render it would put it behind the very delay it covers.
+ *
+ * Route groups need no special handling: a page under `app/(dash)/settings`
+ * resolves against `app/(dash)/loading` by path, exactly as it does on the
+ * server.
+ */
+export function generateLoadingRegistry(components: string[]): string {
+  const imports = components
+    .map((c, i) => `import M${i} from "${cwd_to_import(c)}";`)
+    .join("\n");
+  const entries = components
+    .map((c, i) => `  ${JSON.stringify(c)}: M${i},`)
+    .join("\n");
+  return `// Generated by Pylon SSR (route-level loading.tsx registry).
+// DO NOT EDIT — overwritten on every pylon dev / build.
+${imports ? "\n" + imports + "\n" : ""}
+export const LOADING_MODULES = {
+${entries}
+};
+`;
+}
+
 /**
  * The shared hydration dispatcher + router. ONE module, imported
  * by every per-route entry. Bun's splitter sees N entries reach
@@ -259,11 +330,15 @@ 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";
+import { createPylonBoundary, nearestBoundaryComponent } from "./client-boundary";
+import { LOADING_MODULES } from "./loading-registry";
+import { matchRoute, prefetchTargets } from "./route-match";
 
 const routeCache = Object.create(null);
 let activeRoot = null;
+// Component path of the route currently mounted (the manifest key). Its cached
+// layout chain is what a pending-navigation skeleton renders inside.
+let currentComponent = null;
 // Destination of an in-flight client navigation. Read by hydrateRoot's
 // onUncaughtError so a re-render that throws mid-nav degrades to a full page
 // load instead of a white screen. Null when no nav is in flight.
@@ -509,6 +584,19 @@ function preloadChunks(routeInfo) {
   }
 }
 
+// Run fn once the page itself has finished loading. modulepreload fetches at
+// high priority, and a sidebar of links warms on first paint (Link's
+// IntersectionObserver), so warming a dozen route chunks inline would compete
+// with the current page's own scripts and data — buying a faster second
+// navigation with a slower first render.
+function whenLoaded(fn) {
+  if (document.readyState === "complete") {
+    fn();
+    return;
+  }
+  window.addEventListener("load", fn, { once: true });
+}
+
 async function prefetch(href) {
   // HTML prefetch — primes the SSR response cache.
   const url = new URL(href, location.href);
@@ -520,21 +608,19 @@ async function prefetch(href) {
     html.href = url.pathname + url.search;
     document.head.appendChild(html);
   }
-  // Chunk prefetch — peek at the manifest, but we don't know the
-  // component path from the href without server help. v1: rely on
-  // the shared chunk already being cached + the SSR head emitting
-  // the right preload tags after the user lands. So all prefetch
-  // does today is HTML — chunk dedup happens via the manifest.
   const manifest = await loadManifest();
-  if (manifest) {
-    // Pre-warm all routes' shared chunks (one chunk in practice).
-    const shared = new Set();
-    for (const r of Object.values(manifest.routes || {})) {
-      for (const i of r.imports || []) shared.add(i);
-    }
-    const info = { public_prefix: manifest.public_prefix, file: "", imports: Array.from(shared) };
-    preloadChunks(info);
-  }
+  if (!manifest) return;
+  // Chunk prefetch. The page payload above is the half that was already
+  // cheap: nothing can render until the destination's own entry chunk lands,
+  // so warming only the HTML leaves a full round-trip on the click.
+  const targets = prefetchTargets(manifest, url.pathname);
+  whenLoaded(() =>
+    preloadChunks({
+      public_prefix: manifest.public_prefix,
+      file: targets.file,
+      imports: targets.imports,
+    }),
+  );
 }
 
 async function loadRouteEntry(component) {
@@ -570,6 +656,7 @@ export function hydrate(component, Page, Layouts) {
     }
     setNavParams(data);
     currentPageProps = withClientProps(data);
+    currentComponent = data.component;
     const tree = withBoundary(
       buildTree(Page, Layouts, currentPageProps),
       data.component,
@@ -628,6 +715,48 @@ function syncHeadMeta(doc) {
   }
 }
 
+// How long a navigation may run before the destination's loading.tsx takes
+// over the page area. Below this, the transition finishes on its own and
+// swapping to a skeleton would read as a flicker rather than as feedback.
+const PENDING_PLACEHOLDER_MS = 100;
+
+// Paint the destination's nearest loading.tsx in place of the current page,
+// so a click that can't complete immediately is still acknowledged. Returns
+// whether anything was rendered — apps without a loading.tsx keep the old
+// behavior (previous page stays put until the new one is ready).
+//
+// Rendered inside the CURRENTLY MOUNTED layout chain, not the destination's:
+// the destination's layouts live in the chunk this skeleton exists to cover,
+// so waiting for them would defeat the point. Sibling routes (the common case
+// for a nav that's slow enough to reach here) share that chain anyway, and
+// React keeps those layouts mounted across the swap — only the page area
+// changes.
+//
+// Props are the current page's, verbatim. Layouts re-render with the data they
+// already had, so one that read serverData or params can't suspend on a
+// never-resolving handle or crash on a cache miss halfway through a
+// transition. A skeleton has no data of its own to show.
+function renderPendingPlaceholder(pathname, manifest, myEpoch) {
+  if (!activeRoot || !currentComponent) return false;
+  const matched = matchRoute(manifest, pathname);
+  if (!matched) return false;
+  const key = nearestBoundaryComponent(
+    matched.component,
+    "loading",
+    Object.keys(LOADING_MODULES),
+  );
+  const Loading = key ? LOADING_MODULES[key] : null;
+  if (!Loading) return false;
+  const current = routeCache[currentComponent];
+  const tree = withBoundary(
+    buildTree(Loading, (current && current.Layouts) || [], currentPageProps),
+    currentComponent,
+    myEpoch,
+  );
+  activeRoot.render(tree);
+  return true;
+}
+
 async function navigate(href, opts) {
   const push = !opts || opts.push !== false;
   const url = new URL(href, location.href);
@@ -643,6 +772,14 @@ async function navigate(href, opts) {
   const myEpoch = ++navEpoch;
   currentSeed = opts && opts.seed != null ? opts.seed : null;
 
+  // Flipped the moment this nav commits or gives up, so a pending-placeholder
+  // timer that fires late can never paint a skeleton over real content.
+  const navState = { settled: false };
+  const fullLoad = () => {
+    navState.settled = true;
+    window.location.href = href;
+  };
+
   // ---- 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
@@ -673,6 +810,7 @@ async function navigate(href, opts) {
           myEpoch,
         );
         pendingNav = target;
+        currentComponent = matched.component;
         activeRoot.render(tree);
         if (opts && opts.replace) {
           history.replaceState({ component: matched.component }, "", target);
@@ -688,6 +826,28 @@ async function navigate(href, opts) {
     }
   }
 
+  // ---- Pending-state placeholder -----------------------------------------
+  // Nothing below paints until the SSR payload AND the destination's chunk are
+  // both in hand, which on a cold route is long enough for the click to look
+  // ignored. Hand the page area to the destination's loading.tsx once the nav
+  // outlives the flicker threshold. Skipped when a seed already painted the
+  // real destination — that's strictly better than a skeleton.
+  let placeholderTimer = null;
+  if (!didOptimistic && activeRoot) {
+    placeholderTimer = setTimeout(() => {
+      placeholderTimer = null;
+      // loadManifest resolves instantly once warm (Link prefetch primes it on
+      // first paint); the settled check covers the cold first navigation,
+      // where the fetch can win the race with it.
+      loadManifest().then((manifest) => {
+        if (navState.settled || myEpoch !== navEpoch) return;
+        if (renderPendingPlaceholder(url.pathname, manifest, myEpoch)) {
+          window.scrollTo(0, 0);
+        }
+      });
+    }, PENDING_PLACEHOLDER_MS);
+  }
+
   // ---- Real fetch + render -----------------------------------------------
   let html;
   try {
@@ -696,26 +856,26 @@ async function navigate(href, opts) {
       headers: { Accept: "text/html" },
     });
     if (!res.ok) {
-      window.location.href = href;
+      fullLoad();
       return;
     }
     html = await res.text();
   } catch {
-    window.location.href = href;
+    fullLoad();
     return;
   }
   if (myEpoch !== navEpoch) return;
   const doc = new DOMParser().parseFromString(html, "text/html");
   const dataEl = doc.getElementById("__PYLON_DATA__");
   if (!dataEl) {
-    window.location.href = href;
+    fullLoad();
     return;
   }
   let data;
   try {
     data = JSON.parse(dataEl.textContent || "{}");
   } catch {
-    window.location.href = href;
+    fullLoad();
     return;
   }
   let route;
@@ -723,10 +883,12 @@ async function navigate(href, opts) {
     route = await loadRouteEntry(data.component);
   } catch (e) {
     console.warn("[pylon ssr] nav fallback (entry load failed):", e);
-    window.location.href = href;
+    fullLoad();
     return;
   }
   if (myEpoch !== navEpoch) return;
+  navState.settled = true;
+  if (placeholderTimer) clearTimeout(placeholderTimer);
   document.title = doc.title || document.title;
   syncHeadMeta(doc);
   setNavParams(data);
@@ -749,6 +911,7 @@ async function navigate(href, opts) {
   // (instead of leaving the URL changed but the page unswapped). Cleared on the
   // next macrotask once the commit has settled with no error.
   pendingNav = target;
+  currentComponent = data.component;
   activeRoot.render(tree);
   setTimeout(() => {
     if (pendingNav === target) pendingNav = null;
@@ -1244,6 +1407,19 @@ async function _doBuildInner(
       "utf8",
     );
 
+    // The app's loading.tsx modules, gathered into one module the runtime
+    // imports statically (`./loading-registry`) so a pending navigation can
+    // paint a skeleton without fetching anything. Always written — an app with
+    // no loading.tsx gets an empty registry, since the runtime's import of it
+    // is unconditional.
+    fs.writeFileSync(
+      path.join(stageDir, "loading-registry.ts"),
+      generateLoadingRegistry(
+        discoverLoadingModules(fs, path, cwd, appDirRel),
+      ),
+      "utf8",
+    );
+
     const entryPaths: string[] = [];
     // entryPath (absolute) → component path (for manifest lookup).
     const entryToComponent = new Map<string, string>();

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

@@ -1,5 +1,9 @@
 import { describe, expect, it } from "bun:test";
-import { matchRoute, type MatchableManifest } from "./ssr-route-match";
+import {
+  matchRoute,
+  prefetchTargets,
+  type MatchableManifest,
+} from "./ssr-route-match";
 
 const manifest: MatchableManifest = {
   routes: {
@@ -81,3 +85,94 @@ describe("matchRoute", () => {
     expect(matchRoute({ routes: {} }, "/")).toBeNull();
   });
 });
+
+// ---------------------------------------------------------------------------
+// prefetchTargets — what <Link prefetch> warms.
+//
+// Regression: prefetch emitted the page payload and the shared chunks but
+// never the destination's OWN entry chunk, so every click paid a full
+// round-trip (126-281ms measured across a 12-link sidebar) before the route
+// could render. The payload it did prefetch was the half that was already fast.
+// ---------------------------------------------------------------------------
+
+const chunked: MatchableManifest = {
+  routes: {
+    "app/page": {
+      path: "/",
+      file: "client-entry-app__page-a1.js",
+      imports: ["chunks/shared-1.js"],
+    },
+    "app/speakers/page": {
+      path: "/speakers",
+      file: "client-entry-app__speakers__page-b2.js",
+      imports: ["chunks/shared-1.js", "chunks/editor-2.js"],
+    },
+    "app/events/[id]/page": {
+      path: "/events/[id]",
+      file: "client-entry-app__events____id____page-c3.js",
+      imports: ["chunks/shared-1.js"],
+    },
+    // A boundary module: no path, so it never matches a href.
+    "app/not-found": { file: "client-entry-app__not_found-d4.js", imports: [] },
+  },
+};
+
+describe("prefetchTargets", () => {
+  it("names the destination's OWN entry chunk", () => {
+    // The whole point: without `file`, the click still blocks on this fetch.
+    expect(prefetchTargets(chunked, "/speakers").file).toBe(
+      "client-entry-app__speakers__page-b2.js",
+    );
+  });
+
+  it("includes chunks belonging to the destination alone", () => {
+    // editor-2 is imported only by /speakers. It has to be in the warm set
+    // whether it's reached as the destination's own import or via the
+    // all-routes union.
+    expect(prefetchTargets(chunked, "/speakers").imports).toContain(
+      "chunks/editor-2.js",
+    );
+  });
+
+  it("warms the shared chunks every route needs", () => {
+    expect(prefetchTargets(chunked, "/").imports).toContain("chunks/shared-1.js");
+  });
+
+  it("resolves a dynamic route to its entry", () => {
+    expect(prefetchTargets(chunked, "/events/42").file).toBe(
+      "client-entry-app__events____id____page-c3.js",
+    );
+  });
+
+  it("yields no entry for an href that matches no page route", () => {
+    // e.g. an API path or a route this build doesn't serve. Shared chunks are
+    // still worth warming; the caller skips an empty `file`.
+    const t = prefetchTargets(chunked, "/api/webhooks/stripe");
+    expect(t.file).toBe("");
+    expect(t.imports).toContain("chunks/shared-1.js");
+  });
+
+  it("never resolves to a boundary module's entry", () => {
+    expect(prefetchTargets(chunked, "/not-found").file).toBe("");
+  });
+
+  it("deduplicates chunks shared across routes", () => {
+    const imports = prefetchTargets(chunked, "/speakers").imports;
+    expect(imports.filter((i) => i === "chunks/shared-1.js")).toHaveLength(1);
+  });
+
+  it("is null-safe on an absent or empty manifest", () => {
+    expect(prefetchTargets(null, "/")).toEqual({ file: "", imports: [] });
+    expect(prefetchTargets({ routes: {} }, "/")).toEqual({
+      file: "",
+      imports: [],
+    });
+  });
+
+  it("tolerates a manifest whose routes carry no chunk fields", () => {
+    // Older build output — must degrade, not throw.
+    expect(prefetchTargets({ routes: { "app/page": { path: "/" } } }, "/")).toEqual(
+      { file: "", imports: [] },
+    );
+  });
+});

package/src/ssr-route-match.ts

@@ -18,9 +18,18 @@ export interface RouteMatch {
   params: Record<string, string>;
 }
 
-/** The slice of the build manifest this matcher needs. */
+/** The slice of the build manifest this module needs. */
 export interface MatchableManifest {
-  routes: Record<string, { path?: string }>;
+  routes: Record<
+    string,
+    {
+      path?: string;
+      /** The route's own entry chunk (outdir-relative). */
+      file?: string;
+      /** Shared chunks the browser needs before that entry runs. */
+      imports?: string[];
+    }
+  >;
 }
 
 function splitPath(p: string): string[] {
@@ -102,3 +111,39 @@ export function matchRoute(
   }
   return best ? best.match : null;
 }
+
+/** What `<Link prefetch>` should warm for a destination href. */
+export interface PrefetchTargets {
+  /** The destination route's own entry chunk, or "" when no page route matches. */
+  file: string;
+  /** Shared chunks to warm alongside it. */
+  imports: string[];
+}
+
+/**
+ * The chunks a click on `pathname` will need before anything can render: the
+ * destination route's entry, plus the shared chunks (React, the client
+ * runtime, common layouts) that every route pulls in.
+ *
+ * Warming the page payload alone leaves the entry chunk to be fetched after
+ * the click, and the route cannot render until it lands — so the prefetch
+ * covers only the half that was already fast. An href matching no page route
+ * (an API path, a route this build doesn't serve) still yields the shared set;
+ * `file` is "" and the caller skips it.
+ */
+export function prefetchTargets(
+  manifest: MatchableManifest | null | undefined,
+  pathname: string,
+): PrefetchTargets {
+  const imports = new Set<string>();
+  if (!manifest || !manifest.routes) return { file: "", imports: [] };
+  for (const r of Object.values(manifest.routes)) {
+    for (const i of r?.imports || []) imports.add(i);
+  }
+  const matched = matchRoute(manifest, pathname);
+  const route = matched ? manifest.routes[matched.component] : null;
+  if (route) {
+    for (const i of route.imports || []) imports.add(i);
+  }
+  return { file: route?.file || "", imports: Array.from(imports) };
+}

package/src/ssr-runtime.ts

@@ -1310,8 +1310,18 @@ export function applyAutoSocialImages(
  *
  * Shared by the page render and the boundary render so head injection has
  * exactly one implementation.
+ *
+ * Decoding uses ONE `TextDecoder` with `{stream: true}` for the whole
+ * reader, never a per-chunk decode. React splits the byte stream at
+ * arbitrary offsets, so a multi-byte character can land across two chunks;
+ * decoding each chunk independently turns the orphaned bytes into one
+ * U+FFFD apiece — `…` (e2 80 a6) arrives as three replacement characters.
+ * The failure is silent and position-dependent: markup added anywhere
+ * earlier shifts the boundary, so a page can render correctly for months
+ * and corrupt on an unrelated CSS change. A streaming decoder holds the
+ * partial sequence back until the bytes that complete it arrive.
  */
-async function streamWithHeadInjection(
+export async function streamWithHeadInjection(
   reader: ReadableStreamDefaultReader<Uint8Array>,
   headBlob: string,
   sendChunk: (text: string) => void,
@@ -1319,11 +1329,15 @@ async function streamWithHeadInjection(
   let headInjected = headBlob.length === 0;
   let carry = "";
   const HEAD_CLOSE = "</head>";
+  const decoder = new TextDecoder("utf-8");
   for (;;) {
     const { value, done } = await reader.read();
     if (done) break;
     if (!value || value.byteLength === 0) continue;
-    const text = Buffer.from(value).toString("utf8");
+    const text = decoder.decode(value, { stream: true });
+    // A chunk that ended mid-character decodes to "" — the bytes are held
+    // in the decoder until the rest arrives. Nothing to emit yet.
+    if (!text) continue;
     if (!headInjected) {
       const combined = carry + text;
       const idx = combined.indexOf(HEAD_CLOSE);
@@ -1348,6 +1362,17 @@ async function streamWithHeadInjection(
       sendChunk(text);
     }
   }
+  // Flush the decoder. A stream that ends mid-character is genuinely
+  // truncated input, and this is where it becomes a replacement character
+  // rather than silently vanishing.
+  const tail = decoder.decode();
+  if (tail) {
+    if (!headInjected) {
+      carry += tail;
+    } else {
+      sendChunk(tail);
+    }
+  }
   if (carry) sendChunk(carry);
 }
 

package/src/ssr-utf8.test.ts

@@ -0,0 +1,110 @@
+/**
+ * SSR stream decoding — multi-byte UTF-8 across chunk boundaries.
+ *
+ * React's `renderToReadableStream` splits the byte stream at arbitrary
+ * offsets, so any non-ASCII character can land with its bytes divided
+ * between two chunks. Decoding each chunk independently turns the orphaned
+ * bytes into one U+FFFD apiece: `…` (e2 80 a6) arrives as three replacement
+ * characters.
+ *
+ * The failure is silent and position-dependent — markup added anywhere
+ * earlier in the document shifts the boundary — so a page renders correctly
+ * for months and corrupts on an unrelated CSS change. React only catches it
+ * when the string is hydrated and compared against the client render;
+ * server-only text corrupts with no warning at all.
+ */
+import { describe, expect, test } from "bun:test";
+import { streamWithHeadInjection } from "./ssr-runtime";
+
+/** A reader over pre-split byte chunks — the shape React hands us. */
+function readerOf(chunks: Uint8Array[]): ReadableStreamDefaultReader<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      for (const c of chunks) controller.enqueue(c);
+      controller.close();
+    },
+  }).getReader();
+}
+
+/** Split `text`'s utf-8 bytes at `at`, mid-character on purpose. */
+function splitAt(text: string, at: number): Uint8Array[] {
+  const bytes = new TextEncoder().encode(text);
+  return [bytes.slice(0, at), bytes.slice(at)];
+}
+
+async function collect(chunks: Uint8Array[], headBlob = ""): Promise<string> {
+  const out: string[] = [];
+  await streamWithHeadInjection(readerOf(chunks), headBlob, (t) => out.push(t));
+  return out.join("");
+}
+
+describe("streamWithHeadInjection — UTF-8 across chunk boundaries", () => {
+  test("an ellipsis split across chunks survives", async () => {
+    const html = "<p>Search speakers by name…</p>";
+    const bytes = new TextEncoder().encode(html);
+    // "…" is e2 80 a6; cut between its first and second byte.
+    const cut = bytes.indexOf(0xe2) + 1;
+    expect(await collect(splitAt(html, cut))).toBe(html);
+  });
+
+  test("every split point of a 3-byte character round-trips", async () => {
+    const html = "<p>a…b</p>";
+    const bytes = new TextEncoder().encode(html);
+    for (let at = 1; at < bytes.length; at++) {
+      expect(await collect(splitAt(html, at))).toBe(html);
+    }
+  });
+
+  test("4-byte characters (emoji) survive every split", async () => {
+    const html = "<p>ship it 🚀 now</p>";
+    const bytes = new TextEncoder().encode(html);
+    for (let at = 1; at < bytes.length; at++) {
+      expect(await collect(splitAt(html, at))).toBe(html);
+    }
+  });
+
+  test("accented names and CJK survive every split", async () => {
+    // Ordinary content, not edge cases: a speaker called José, a Japanese
+    // session title, a middot in a byline.
+    const html = "<p>José · 日本語のセッション</p>";
+    const bytes = new TextEncoder().encode(html);
+    for (let at = 1; at < bytes.length; at++) {
+      expect(await collect(splitAt(html, at))).toBe(html);
+    }
+  });
+
+  test("a character split across THREE chunks survives", async () => {
+    // One byte per chunk — the decoder must hold state across two reads
+    // that each produce nothing.
+    const enc = new TextEncoder().encode("…");
+    const chunks = [enc.slice(0, 1), enc.slice(1, 2), enc.slice(2, 3)];
+    expect(await collect(chunks)).toBe("…");
+  });
+
+  test("head injection still lands, with a split character before it", async () => {
+    const html = "<html><head><title>é…</title></head><body>x</body></html>";
+    const bytes = new TextEncoder().encode(html);
+    const cut = bytes.indexOf(0xe2) + 1; // mid-ellipsis, before </head>
+    const out = await collect(splitAt(html, cut), "<meta name=x>");
+    expect(out).toBe(
+      "<html><head><title>é…</title><meta name=x></head><body>x</body></html>",
+    );
+  });
+
+  test("a stream truncated mid-character does not lose the tail silently", async () => {
+    // Genuinely broken input. One replacement character is the honest
+    // answer; dropping the bytes without a trace is not.
+    const enc = new TextEncoder().encode("ok…");
+    const out = await collect([enc.slice(0, enc.length - 1)]);
+    expect(out.startsWith("ok")).toBe(true);
+    expect(out).toContain("�");
+  });
+
+  test("pure ASCII is unaffected", async () => {
+    const html = "<p>plain ascii only</p>";
+    const bytes = new TextEncoder().encode(html);
+    for (let at = 1; at < bytes.length; at++) {
+      expect(await collect(splitAt(html, at))).toBe(html);
+    }
+  });
+});