@rangojs/router 0.17.0 → 0.18.0

package/src/types/handler-context.ts

@@ -342,6 +342,12 @@ export type HandlerContext<
    * Current theme (from cookie or default).
    * Only available when theme is enabled in router config.
    *
+   * The visitor's cookie, so it is guarded like `cookies()`: reading it on a
+   * `ppr` route refuses the shell capture, and inside a `cache()` boundary or
+   * a `"use cache"` function it throws (#971). Read it with `useTheme()` in a
+   * client component, or in a live loader, on those routes. A read-only,
+   * non-enumerable getter: `{ ...ctx }` does not carry it.
+   *
    * @example
    * ```typescript
    * route("settings", (ctx) => {
@@ -350,7 +356,7 @@ export type HandlerContext<
    * });
    * ```
    */
-  theme?: Theme;
+  readonly theme?: Theme;
   /**
    * Set the theme (only available when theme is enabled in router config).
    * Sets a cookie with the new theme value.
@@ -469,6 +475,13 @@ export type InternalHandlerContext<
    * from the page. See setupLoaderAccess.
    */
   _runLoaderIsolated?: (loader: any) => Promise<any>;
+  /**
+   * @internal A loader's cache() binding started with these cache() tags: an
+   * execution of that loader outside the binding (a reader started it first,
+   * or a stale refresh runs it) answers for them too (#964). See
+   * setupLoaderAccess.
+   */
+  _bindLoaderCacheTags?: (loaderId: string, tags: Set<string>) => void;
 };
 
 /**

package/src/urls/pattern-types.ts

@@ -59,30 +59,34 @@ export interface PartialPrerenderProps {
   /**
    * Operational tags attached to the captured shell entry for
    * `updateTag()`/`revalidateTag()`-driven eviction. UNIONED with the tags the
-   * capture render auto-collects (the shell's own non-loader request tags).
+   * capture collects: its doc record's tags (what the handler layer and the
+   * server components it rendered recorded) and its bake-lane loaders'.
    */
   tags?: string[];
   /**
-   * Upper bound (serialized UTF-8 bytes) on the capture data snapshot riding
-   * inside the shell entry. The snapshot duplicates every cache-store value
-   * the capture pinned, so a page over a large cache() segment can push the
-   * entry toward store value limits (Cloudflare KV caps a value at 25 MiB).
-   * Over the cap the snapshot is skipped: the shell is still stored and
-   * served, but pinned reads fall back to the live store, so drifted cached
-   * content can hydration-mismatch and be repaired client-side (the
-   * pre-snapshot behavior). Reported once per key. Defaults to 8 MiB.
+   * Upper bound (serialized UTF-8 bytes) on the loader pins in the capture
+   * data snapshot: the loader records and the cache values loaders read,
+   * duplicated into the shell entry. The doc record (the handler layer every
+   * HIT replays) is exempt. Over the cap the pins are dropped: the shell is
+   * still stored and every HIT still replays the handler layer, but the
+   * pinned loaders read the live store, so drifted cached content can
+   * hydration-mismatch and be repaired client-side. Reported once per key.
+   * Defaults to 8 MiB. The whole entry is bounded separately by the store's
+   * value limit (Cloudflare KV: 25 MiB); an entry over it is refused.
    */
   maxSnapshotBytes?: number;
   /**
-   * Capture settle budget in MILLISECONDS (default 15000). Bounds the whole
-   * background capture: the wait for deferred shell material — top-level
-   * pushed handle promises (`ctx.use(Meta)(promise.then(...))` and friends)
-   * are AWAITED and their settled values baked into the stored shell — AND
-   * the fizz prerender deadline. Declare it to tighten the budget below the
-   * default or when a route's shell material takes longer than 15s to
-   * settle. A budget that expires with pushes still pending REFUSES the
-   * capture (the route stays MISS with the once-per-key warning) — a shell
-   * with missing head material is never stored. Capture is background work
+   * Capture settle budget in MILLISECONDS (default 15000). One deadline for
+   * the whole background capture: the match (the handlers, and the loaders
+   * they await), the wait for handler output (handle pushes and the promises
+   * nested in them, bake-lane loaders, and the doc record's encode, which
+   * awaits handler promises and async server components), AND the fizz
+   * prerender. Everything a handler produces is
+   * awaited and baked into the stored shell. Declare it to tighten the
+   * budget below the default or when a route's shell material takes longer
+   * than 15s to settle. A budget that expires before the doc record is
+   * written REFUSES the capture (the route stays MISS with the once-per-key
+   * warning): a shell with missing handler output is never stored. Capture is background work
    * (waitUntil), so a longer budget costs latency-to-HIT only, never a served
    * response; the platform waitUntil lifetime (workerd: ~30s past response
    * completion) is the physical ceiling — the default's derivation lives in

package/src/vite/discovery/shell-prerender-phase.ts

@@ -64,6 +64,14 @@ export async function runShellPrerenderPhase(
   const startTotal = performance.now();
   console.log(`[rango] Shell-prerendering ${candidates.length} URL(s)...`);
 
+  // Hold the process open for the phase. The capture's waits are unref'd
+  // timers (retry delay, Flight quiesce hops) so a runtime capture never keeps
+  // Node alive; every bundle is already written and the build temp server has
+  // no file watcher (#947). Its only remaining handle is the HMR WebSocket on
+  // 24678, which fails to bind silently when another Vite server holds the
+  // port; `vite build` then exited 0 mid-phase without writing
+  // __shell-manifest.js.
+  const keepAlive = setInterval(() => {}, 60_000);
   let restoreClientRequire: (() => void) | undefined;
   try {
     // Runner access needs the RunnableDevEnvironment surface; the environments
@@ -343,6 +351,7 @@ export async function runShellPrerenderPhase(
     // buildApp post hook's finally on success, buildEnd on an aborted build.
     delete (globalThis as any).__loadPrerenderManifestModule;
     restoreClientRequire?.();
+    clearInterval(keepAlive);
   }
 }
 

package/src/vite/router-discovery.ts

@@ -6,7 +6,7 @@
  * generation, virtual module codegen, and bundle post-processing.
  */
 
-import type { Plugin } from "vite";
+import type { Plugin, ViteDevServer } from "vite";
 import { createServer as createViteServer } from "vite";
 import { resolve } from "node:path";
 import { readFileSync } from "node:fs";
@@ -177,8 +177,9 @@ const injectedShellNotReadyPaths = new Set<string>();
  * - Build: hashed IDs (forceBuild), hashClientRefs for production bundles
  *
  * Returns the ViteDevServer instance. Callers access .environments.rsc as needed.
+ * @internal Exported for tests.
  */
-async function createTempRscServer(
+export async function createTempRscServer(
   state: DiscoveryState,
   options: {
     forceBuild?: boolean;
@@ -195,7 +196,7 @@ async function createTempRscServer(
      */
     realSsrEntry?: boolean;
   } = {},
-) {
+): Promise<ViteDevServer> {
   // Install the Node ESM loader hook before any module evaluation so
   // `cloudflare:*` specifiers in externalized/loader-delegated modules
   // (e.g. packages plugin-rsc marks as external) resolve to stubs
@@ -216,7 +217,16 @@ async function createTempRscServer(
   return createViteServer({
     root: state.projectRoot,
     configFile: false,
-    server: { middlewareMode: true },
+    server: {
+      middlewareMode: true,
+      // Build mode: no file watching. buildStart installs the per-router tries
+      // into this realm and runShellPrerenderPhase reuses it after the bundles
+      // are written. A watched write in between (writeRouteTypesFiles' own
+      // <router>.named-routes.gen.ts, which every router file imports) can
+      // make Vite full-reload the RSC runner; the shell phase then matches in
+      // a fresh realm with no tries and a root path("/*") wins (#947).
+      ...(options.forceBuild ? { watch: null } : {}),
+    },
     appType: "custom",
     logLevel: "silent",
     resolve: resolveConfig,