@rangojs/router 0.0.0-experimental.150 → 0.0.0-experimental.151

package/src/server/request-context.ts

@@ -108,6 +108,27 @@ export interface RequestContext<
   /** @internal Stub response for collecting headers/cookies. Use ctx.headers or ctx.header() instead. */
   readonly res: Response;
 
+  /**
+   * True for build-time render/capture requests. Live requests use false.
+   * Build-time shell capture sets this while replaying middleware so apps can
+   * skip side-effectful runtime work.
+   */
+  readonly build: boolean;
+
+  /**
+   * Opt this request out of PPR shell serving/capture.
+   * Runtime middleware can call this before the PPR commit point; handlers can
+   * call it on a MISS to prevent the follow-up capture.
+   *
+   * Scope: the PPR SHELL axis only. It does NOT disable prerender B-segment
+   * (Prerender/Static) serving, and it is inert in the prerender-collect /
+   * static-render contexts (no live shell decision to influence there).
+   */
+  dynamic(): void;
+
+  /** @internal Request-local PPR opt-out marker set by ctx.dynamic(). */
+  _dynamic?: boolean;
+
   /** @internal Get a cookie value (effective: request + response mutations). Use cookies().get() instead. */
   cookie(name: string): string | undefined;
   /** @internal Get all cookies (effective merged view). Use cookies().getAll() instead. */
@@ -628,6 +649,7 @@ export type PublicRequestContext<
   | "_variables"
   | "_classifiedRoute"
   | "_cacheSignal"
+  | "_dynamic"
   | "res"
 >;
 
@@ -775,6 +797,8 @@ export interface CreateRequestContextOptions<TEnv> {
   >;
   /** Optional Cloudflare execution context for waitUntil support */
   executionContext?: ExecutionContext;
+  /** Build-time render/capture request marker. Defaults to false. */
+  build?: boolean;
   /** Optional theme configuration (enables ctx.theme and ctx.setTheme) */
   themeConfig?: ResolvedThemeConfig | null;
   /** Resolved rango state cookie name, for the server seat of invalidateClientCache(). */
@@ -804,6 +828,7 @@ export function createRequestContext<TEnv>(
     explicitTaggedStores,
     cacheProfiles,
     executionContext,
+    build = false,
     themeConfig,
     stateCookieName,
     version: stateVersion,
@@ -951,6 +976,11 @@ export function createRequestContext<TEnv>(
     pathname: url.pathname,
     searchParams: cleanUrl.searchParams,
     _variables: variables,
+    build,
+    dynamic(): void {
+      ctx._dynamic = true;
+    },
+    _dynamic: false,
     get: ((keyOrVar: any) => {
       if (isNonCacheable(variables, keyOrVar) && isInsideCacheScope()) {
         throw new Error(
@@ -1089,6 +1119,7 @@ export function createRequestContext<TEnv>(
     _cacheProfiles: cacheProfiles,
 
     waitUntil(fn: () => Promise<void>): void {
+      if (ctx.build) return;
       // Wrap in Promise.resolve().then(fn) so a SYNCHRONOUS throw in a
       // non-async callback becomes a rejected promise handed to the host's
       // waitUntil (logged as a background failure), instead of escaping into

package/src/testing/internal/context.ts

@@ -55,6 +55,14 @@ export interface CreateTestContextOptions<TEnv> {
   routeMap?: Record<string, string>;
   routeName?: string;
   params?: Record<string, string>;
+  /**
+   * Seed `ctx.build` (default false). Set `true` to unit-test middleware or a
+   * handler that branches on the build-time PPR shell-capture pass — e.g.
+   * `if (ctx.build) ctx.dynamic()`. Mirrors the synthetic build request the
+   * shell-capture producer creates; also makes `ctx.waitUntil()` inert, as at
+   * build time.
+   */
+  build?: boolean;
   /**
    * Router basename for this request (what the RSC handler stores on the
    * context). Drives redirect() prefixing. Normalized exactly like
@@ -150,6 +158,7 @@ export function createTestRequestContext<TEnv>(
     request,
     url,
     variables,
+    build: opts.build,
     themeConfig:
       opts.theme === undefined ? undefined : resolveThemeConfig(opts.theme),
     cacheStore: opts.cacheStore,

package/src/testing/render-handler.ts

@@ -80,6 +80,12 @@ export interface RenderHandlerOptions<TEnv = any> {
   routeName?: string;
   /** Route name -> pattern map enabling `ctx.reverse()`. */
   routeMap?: Record<string, string>;
+  /**
+   * Seed `ctx.build` (default false) so a handler that branches on the
+   * build-time pass — including calling `ctx.dynamic()` on a MISS — is
+   * unit-testable. Assert a `ctx.dynamic()` call via `result.dynamic`.
+   */
+  build?: boolean;
   /**
    * Seed the data `ctx.use(SomeLoader)` returns — NO real loader runs (same model
    * as `runLoader`'s `loaders`). Matched by loader reference, so a real
@@ -163,6 +169,12 @@ export interface RenderHandlerResult {
   locationState: Record<string, unknown>;
   /** What the handler pushed via `ctx.use(Handle)(...)` (e.g. Meta, Breadcrumbs), keyed by handle. */
   handles: Map<Handle<any, any>, unknown[]>;
+  /**
+   * Whether the handler called `ctx.dynamic()` (the PPR shell opt-out). The
+   * public way to assert the opt-out without reading the `@internal`
+   * `ctx._dynamic`.
+   */
+  dynamic: boolean;
 }
 
 /**
@@ -239,6 +251,7 @@ export async function renderHandler<TEnv = any>(
     request,
     url,
     variables: seedVariables({}, opts.vars),
+    build: opts.build,
     stateCookieName,
     version: opts.stateCookie?.version,
     cacheStore: opts.cacheStore,
@@ -353,5 +366,6 @@ export async function renderHandler<TEnv = any>(
     stateCookieName,
     locationState,
     handles: handlePushes,
+    dynamic: (reqCtx as RequestContext<TEnv>)._dynamic === true,
   };
 }

package/src/testing/run-middleware.ts

@@ -49,6 +49,13 @@ export interface RunMiddlewareOptions<TEnv = any> {
   env?: TEnv;
   /** Route params surfaced as `ctx.params`. */
   params?: Record<string, string>;
+  /**
+   * Seed `ctx.build` (default false) so a middleware that branches on the
+   * build-time PPR shell-capture pass (e.g. `if (ctx.build) ctx.dynamic()`) is
+   * unit-testable. With `build: true`, `ctx.waitUntil()` is inert, matching the
+   * build producer. Assert a `ctx.dynamic()` call via `result.dynamic`.
+   */
+  build?: boolean;
   /** Variables a prior middleware would have set (object or [key, value] list). */
   vars?: VarsInit;
   /** Route name -> pattern map enabling `ctx.reverse()`. */
@@ -102,6 +109,11 @@ export interface RunMiddlewareResult<TEnv = any> {
   ctx: RequestContext<TEnv>;
   /** Number of times the terminal handler ran (0 = short-circuited, 1 = passed through). */
   nextCalled: number;
+  /**
+   * Whether the chain called `ctx.dynamic()` (the PPR shell opt-out). The public
+   * way to assert the opt-out without reading the `@internal` `ctx._dynamic`.
+   */
+  dynamic: boolean;
   /**
    * The effective cookie view after the chain ran: request cookies merged with
    * anything the chain set or deleted (last-write-wins), as `{ name: value }`.
@@ -146,6 +158,7 @@ export async function runMiddleware<TEnv = any>(
     routeMap: opts.routeMap,
     routeName: opts.routeName,
     params: opts.params,
+    build: opts.build,
     basename: opts.basename,
     theme: opts.theme,
     cacheStore: opts.cacheStore,
@@ -197,6 +210,7 @@ export async function runMiddleware<TEnv = any>(
     response,
     ctx,
     nextCalled,
+    dynamic: ctx._dynamic === true,
     cookies,
     headers,
     locationState,

package/src/types/handler-context.ts

@@ -202,7 +202,18 @@ export type HandlerContext<
    * Build-time collection and dev on-demand prerender use `true`.
    * Live request rendering, including passthrough fallback, uses `false`.
    */
-  build: boolean;
+  readonly build: boolean;
+  /**
+   * Opt this request out of PPR shell serving/capture.
+   * Middleware can call this before a shell HIT commits. Handlers run after
+   * that commit point, so they only prevent scheduling a new capture on MISS.
+   *
+   * Scope: this gates the PPR SHELL axis only. It does NOT disable prerender
+   * B-segment (Prerender/Static) serving — a Prerender() route's build-baked
+   * segments still replay at runtime — and it is inert in the prerender-collect
+   * and static-render contexts, which have no live shell decision to influence.
+   */
+  dynamic(): void;
   /**
    * True when running in Vite dev mode, false during production build or
    * live request rendering. Use this to branch on runtime mode without

package/src/vite/discovery/discover-routers.ts

@@ -150,7 +150,6 @@ export async function discoverRouters(
   const newPerRouterManifestDataMap = new Map<string, any>();
   const newPerRouterPrecomputedMap = new Map<string, PrecomputedEntry[]>();
   const newPerRouterTrieMap = new Map<string, any>();
-  let mergedRouteAncestry: Record<string, string[]> = {};
   let mergedRouteTrailingSlash: Record<string, string> = {};
 
   let routerMountIndex = 0;
@@ -245,10 +244,6 @@ export async function discoverRouters(
       factoryOnlyPrefixes,
     });
 
-    // Merge ancestry (internal field, used only for trie building)
-    if (manifest._routeAncestry) {
-      Object.assign(mergedRouteAncestry, manifest._routeAncestry);
-    }
     // Merge trailing slash config
     if (manifest.routeTrailingSlash) {
       Object.assign(mergedRouteTrailingSlash, manifest.routeTrailingSlash);
@@ -303,64 +298,61 @@ export async function discoverRouters(
     (performance.now() - manifestGenStart).toFixed(1),
   );
 
-  // Build route trie from merged manifest + ancestry
+  // Build route trie from merged manifest
   let newMergedRouteTrie: any = null;
   const trieStart = debug ? performance.now() : 0;
   if (Object.keys(newMergedRouteManifest).length > 0) {
-    if (mergedRouteAncestry) {
-      // Build routeToStaticPrefix from saved manifests
-      const routeToStaticPrefix: Record<string, string> = {};
-      for (const { manifest } of allManifests) {
-        // Root-level routes have empty static prefix
-        for (const name of Object.keys(manifest.routeManifest)) {
-          if (!(name in routeToStaticPrefix)) {
-            routeToStaticPrefix[name] = "";
-          }
+    // Build routeToStaticPrefix from saved manifests
+    const routeToStaticPrefix: Record<string, string> = {};
+    for (const { manifest } of allManifests) {
+      // Root-level routes have empty static prefix
+      for (const name of Object.keys(manifest.routeManifest)) {
+        if (!(name in routeToStaticPrefix)) {
+          routeToStaticPrefix[name] = "";
         }
-        buildRouteToStaticPrefix(manifest.prefixTree, routeToStaticPrefix);
       }
+      buildRouteToStaticPrefix(manifest.prefixTree, routeToStaticPrefix);
+    }
 
-      // Collect prerender route names and response type routes from all manifests
-      const prerenderRouteNames = new Set<string>();
-      const passthroughRouteNames = new Set<string>();
-      const mergedResponseTypeRoutes: Record<string, string> = {};
-      for (const { manifest } of allManifests) {
-        if (manifest.prerenderRoutes) {
-          for (const name of manifest.prerenderRoutes) {
-            prerenderRouteNames.add(name);
-          }
+    // Collect prerender route names and response type routes from all manifests
+    const prerenderRouteNames = new Set<string>();
+    const passthroughRouteNames = new Set<string>();
+    const mergedResponseTypeRoutes: Record<string, string> = {};
+    for (const { manifest } of allManifests) {
+      if (manifest.prerenderRoutes) {
+        for (const name of manifest.prerenderRoutes) {
+          prerenderRouteNames.add(name);
         }
-        if (manifest.passthroughRoutes) {
-          for (const name of manifest.passthroughRoutes) {
-            passthroughRouteNames.add(name);
-          }
-        }
-        if (manifest.responseTypeRoutes) {
-          Object.assign(mergedResponseTypeRoutes, manifest.responseTypeRoutes);
+      }
+      if (manifest.passthroughRoutes) {
+        for (const name of manifest.passthroughRoutes) {
+          passthroughRouteNames.add(name);
         }
       }
+      if (manifest.responseTypeRoutes) {
+        Object.assign(mergedResponseTypeRoutes, manifest.responseTypeRoutes);
+      }
+    }
 
-      // buildRouteTrie reads these via ?.has / ?.[] — empty is observationally
-      // identical to undefined, so no empty->undefined coercion is needed.
-      newMergedRouteTrie = buildRouteTrie(
-        newMergedRouteManifest,
-        mergedRouteAncestry,
-        routeToStaticPrefix,
-        mergedRouteTrailingSlash,
-        prerenderRouteNames,
-        passthroughRouteNames,
-        mergedResponseTypeRoutes,
-      );
+    // buildRouteTrie reads these via ?.has / ?.[] — empty is observationally
+    // identical to undefined, so no empty->undefined coercion is needed.
+    newMergedRouteTrie = buildRouteTrie(
+      newMergedRouteManifest,
+      routeToStaticPrefix,
+      mergedRouteTrailingSlash,
+      prerenderRouteNames,
+      passthroughRouteNames,
+      mergedResponseTypeRoutes,
+    );
 
-      // Build per-router tries for multi-router isolation. Uses the single
-      // shared buildPerRouterTrie so the production serialized trie is built by
-      // exactly the same code as the dev/HMR runtime rebuild (manifest-init.ts).
-      // Returns null for route-less manifests (route-trie.ts).
-      for (const { id, manifest } of allManifests) {
-        const perRouterTrie = buildPerRouterTrie(manifest);
-        if (perRouterTrie) {
-          newPerRouterTrieMap.set(id, perRouterTrie);
-        }
+    // Build per-router tries for multi-router isolation. Uses the single
+    // shared buildPerRouterTrie so the production serialized trie is built by
+    // exactly the same code as the dev/HMR runtime rebuild (manifest-init.ts).
+    // Returns null for route-less manifests (route-trie.ts).
+    for (const { id, manifest } of allManifests) {
+      const perRouterTrie = buildPerRouterTrie(manifest);
+      if (perRouterTrie) {
+        newPerRouterTrieMap.set(id, perRouterTrie);
       }
     }
   }

package/src/vite/discovery/virtual-module-codegen.ts

@@ -5,11 +5,25 @@
  * per-router virtual modules used by the load() hook.
  */
 
+import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, basename, join } from "node:path";
 import { jsonParseExpression } from "../utils/manifest-utils.js";
 import { VIRTUAL_ROUTES_MANIFEST_ID } from "./state.js";
 import type { DiscoveryState } from "./state.js";
 
+/**
+ * Serialized-payload size (bytes) at or above which the trie/precomputedEntries
+ * are shipped through a runtime channel (Text module / `?raw` import) instead of
+ * an inline `JSON.parse` literal (issue #665). 512KB is ~2500 routes — the
+ * crossover where the channel's benefit (removing the JS compile on cloudflare,
+ * reclaiming ~19% escaping bloat everywhere) clears the cost of an extra
+ * artifact. Below it the inline literal wins (sub-millisecond compile, ~0 gain),
+ * so the whole long tail of normal apps stays byte-identical. The compile/parse
+ * cost tracks bytes, not route count, so this stays a byte threshold.
+ * RANGO_MANIFEST_TEXT=1 bypasses it.
+ */
+const MANIFEST_EXTERNALIZE_THRESHOLD = 512 * 1024;
+
 /**
  * Generate the code for the main virtual:rsc-router/routes-manifest module.
  */
@@ -137,6 +151,22 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
   return `// Route manifest will be populated at runtime`;
 }
 
+/**
+ * Deterministic short hash (FNV-1a, base36) used to disambiguate staged
+ * manifest filenames. The sanitized `safeId` alone collapses distinct router
+ * ids — e.g. "a/b" and "a.b" both sanitize to "a_b" — which in a multi-router
+ * build would overwrite one router's staged manifest with another's. Appending
+ * a hash of the ORIGINAL id keeps them distinct.
+ */
+function shortHash(input: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(36);
+}
+
 /**
  * Generate the code for a per-router virtual module.
  */
@@ -171,13 +201,93 @@ export function generatePerRouterModule(
       lines.push(`export const manifest = ${jsonParseExpression(manifest)};`);
     }
   }
-  if (trie) {
+  const hasTrie = !!trie;
+  const hasEntries = !!entries && entries.length > 0;
+
+  // The trie + precomputedEntries are the largest generated data. Inlined as a
+  // `JSON.parse('<literal>')` in the JS chunk, the isolate/process must LEX and
+  // compile that multi-MB source literal on first request before JSON.parse even
+  // runs — pure overhead, since it is data, not logic (issue #665). It also
+  // ships bloated: the build minifier re-quotes the literal to double quotes,
+  // escaping every JSON `"` as `\"` (measured 5.71MB vs 4.64MB un-escaped at 26k
+  // routes).
+  //
+  // The ONLY way to fix both is to keep the JSON out of JavaScript source — as a
+  // raw asset file that never passes through the JS minifier/compiler. On
+  // cloudflare that is a workerd Text module: import the staged `.txt` and the
+  // isolate gets the raw un-escaped bytes as a string with no compile pass
+  // (measured ~17% / ~88ms cold first-hit on a real edge deploy at 26k, and it
+  // shrinks the worker upload). The CF vite plugin types `.txt` as Text;
+  // wrangler's default rules type **/*.txt as Text for deploy and dev.
+  //
+  // Scoped to cloudflare deliberately. A Text module is the only no-JS byte
+  // channel that needs no filesystem, and cloudflare is where it pays: edge cold
+  // isolates spin up per-request under load and on every deploy, and Workers
+  // have a hard upload-size limit. node/vercel fall through to the inline
+  // literal below — an efficient runtime channel there needs `fs` (a raw asset
+  // read), whose fragility (asset co-location, runtime ENOENT) is not worth a
+  // large-app-only win that Fluid Compute amortizes and that essentially no real
+  // app reaches. `?raw` is NOT an option: in this build it inlines the JSON as a
+  // (double-quoted, compiled) JS string literal — same bloat, same compile as
+  // the inline form, plus a staged file for nothing.
+  //
+  // Build mode only (dev rebuilds the manifest per HMR; parse cost is
+  // irrelevant). Below MANIFEST_EXTERNALIZE_THRESHOLD the inline literal wins.
+  // RANGO_MANIFEST_TEXT overrides: "0" forces inline, "1" forces the Text module
+  // and bypasses the threshold (used by the cloudflare-basic dogfood e2e, whose
+  // real manifest is below the threshold).
+  const preset = state.opts?.preset ?? "node";
+  const override = process.env.RANGO_MANIFEST_TEXT;
+  const payload = manifestPayload(trie, hasTrie, entries, hasEntries);
+  const payloadJson = hasTrie || hasEntries ? JSON.stringify(payload) : "";
+  const useTextModule =
+    state.isBuildMode &&
+    preset === "cloudflare" &&
+    override !== "0" &&
+    (hasTrie || hasEntries) &&
+    (override === "1" || payloadJson.length >= MANIFEST_EXTERNALIZE_THRESHOLD);
+
+  if (useTextModule) {
+    const dir = join(state.projectRoot, "node_modules", ".rango");
+    mkdirSync(dir, { recursive: true });
+    const safeId = `${routerId.replace(/[^a-zA-Z0-9_-]/g, "_")}-${shortHash(routerId)}`;
+    const filePath = join(dir, `manifest-${safeId}.txt`).replaceAll("\\", "/");
+    writeFileSync(filePath, payloadJson);
+    lines.push(`import __manifestJson from ${JSON.stringify(filePath)};`);
+    lines.push(`const __manifestData = JSON.parse(__manifestJson);`);
+    emitManifestExports(lines, hasTrie, hasEntries);
+    return lines.join("\n");
+  }
+
+  if (hasTrie) {
     lines.push(`export const trie = ${jsonParseExpression(trie)};`);
   }
-  if (entries && entries.length > 0) {
+  if (hasEntries) {
     lines.push(
       `export const precomputedEntries = ${jsonParseExpression(entries)};`,
     );
   }
   return lines.join("\n") || "";
 }
+
+function manifestPayload(
+  trie: unknown,
+  hasTrie: boolean,
+  entries: unknown,
+  hasEntries: boolean,
+): Record<string, unknown> {
+  const payload: Record<string, unknown> = {};
+  if (hasTrie) payload.t = trie;
+  if (hasEntries) payload.p = entries;
+  return payload;
+}
+
+function emitManifestExports(
+  lines: string[],
+  hasTrie: boolean,
+  hasEntries: boolean,
+): void {
+  if (hasTrie) lines.push(`export const trie = __manifestData.t;`);
+  if (hasEntries)
+    lines.push(`export const precomputedEntries = __manifestData.p;`);
+}

package/src/vite/rango.ts

@@ -46,6 +46,31 @@ import { createRangoDebugger, NS } from "./debug.js";
 
 const debugConfig = createRangoDebugger(NS.config);
 
+/**
+ * Syntax target for the node/vercel server (`ssr` + `rsc`) build environments.
+ *
+ * Vite 8's build-target default is `baseline-widely-available`, which resolves
+ * to a BROWSER baseline (`chrome111`/`edge111`/…, ≈ES2022) and is applied
+ * per-environment with NO server carve-out: `resolveRolldownOptions` pipes it
+ * straight into rolldown/oxc's `transform.target` for `consumer:"server"` chunks
+ * too. So without an explicit server target our ssr/rsc bundles — which only run
+ * on Node or workerd — get compiled for browsers, needlessly rewriting modern
+ * syntax (e.g. Explicit Resource Management `using`/`await using`) into
+ * `_usingCtx()` runtime helpers. `esnext` emits server code at authored
+ * modernity: no helpers, marginally smaller/faster bundles, semantics that match
+ * reality. The `client` env is intentionally left at the browser baseline.
+ *
+ * The cloudflare preset does NOT use this: `@cloudflare/vite-plugin` hardcodes
+ * `es2024` on its server envs and its `config()` merges after ours, so anything
+ * we set there is a dead no-op (workerd runs es2024 fine).
+ *
+ * Caveat: `esnext` stops downleveling ERM `using`, which parses natively only on
+ * Node 24+ (workerd runs it). Ordinary ≤ES2022 server code still runs across the
+ * whole supported Node range; only an app that authors `using` AND deploys to
+ * Node < 24 would need to downlevel it itself. See issue #729.
+ */
+const SERVER_BUILD_TARGET = "esnext";
+
 // The leading-directive 'use client' sniff is shared with version-plugin's
 // getClientModuleSignature so the two cannot drift. Imported for local use by the
 // HMR transform below and re-exported because the E8 sniff test imports it from
@@ -409,6 +434,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
             },
             ssr: {
               ...(vercelServerEnv ?? {}),
+              build: {
+                target: SERVER_BUILD_TARGET,
+              },
               optimizeDeps: {
                 entries: [VIRTUAL_IDS.ssr],
                 include: [
@@ -428,6 +456,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
             },
             rsc: {
               ...(vercelServerEnv ?? {}),
+              build: {
+                target: SERVER_BUILD_TARGET,
+              },
               optimizeDeps: {
                 entries: [VIRTUAL_IDS.rsc],
                 include: [