@rangojs/router 0.26.6 → 0.28.0

package/src/testing/e2e/page-helpers.ts

@@ -4,6 +4,7 @@
 
 import type { ConsoleMessage, Expect, Locator, Page } from "@playwright/test";
 import { PREFETCH_HEADER } from "../../prefetch-markers.js";
+import { WIRE } from "../../wire-params.js";
 
 // ============================================================================
 //  Standalone helpers (need only a page/locator)
@@ -177,8 +178,7 @@ export function isPrefetchRequest(req: {
 
 // Module-level matcher + handler so blockPrefetch/unblockPrefetch share
 // stable references — Playwright's unroute matches by identity.
-const rscPartialUrl = (url: URL): boolean =>
-  url.searchParams.has("_rsc_partial");
+const rscPartialUrl = (url: URL): boolean => url.searchParams.has(WIRE.partial);
 async function abortPrefetchRoute(
   route: import("@playwright/test").Route,
 ): Promise<void> {

package/src/testing/serve-shell-request.ts

@@ -53,12 +53,16 @@ import type { ExecutionContext } from "../types/request-scope.js";
 import type { HandlerCacheConfig, SSRModule } from "../rsc/types.js";
 import type { createRSCHandler } from "../rsc/handler.js";
 import { setDefaultSSRModuleLoaderForTests } from "../rsc/ssr-module-loader.js";
+import {
+  createPrerenderStore,
+  prerenderManifestEntries,
+} from "../prerender/store.js";
 import {
   POST_QUIESCE_TASK_HOPS,
   SHELL_CAPTURE_MAX_WAIT_MS,
 } from "../rsc/shell-capture-constants.js";
 import { SEGMENT_FRAGMENT_CAPABILITY_HEADER } from "../segment-fragments.js";
-import { FILL_PARAM, PREFETCH_HEADER } from "../prefetch-markers.js";
+import { PREFETCH_HEADER } from "../prefetch-markers.js";
 import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
 import { withoutPushedBy } from "../handles/pushed-by.js";
 import type { HandleData } from "../server/handle-store.js";
@@ -72,6 +76,8 @@ import {
   type PprReplayStatus,
   type ShellStatus,
 } from "./shell-status.js";
+import { WIRE } from "../wire-params.js";
+import { writePartialParams } from "../browser/wire-protocol.js";
 
 /** Options for {@link serveShellRequest}. */
 export interface ServeShellRequestOptions<TEnv = any> {
@@ -105,6 +111,12 @@ export interface ServeShellRequestOptions<TEnv = any> {
    * that source. `rewriteTarget` sends the `metadata.rewriteTarget` the page at
    * `from` carried when middleware rewrote it (`_rsc_rt`), as the browser
    * does: the server then diffs against the route that rendered that page.
+   * `stale: true` sends a stale request (`_rsc_stale`), as the browser sends
+   * it: every `revalidate()` sees `stale: true` (see `revalidate()`'s `stale`)
+   * and segments take an action's revalidation defaults; it renders live, as
+   * an action does, so neither the route cache nor the document cache answers
+   * or stores it, and a `ppr` route's `replayStatus` is
+   * `{ outcome: "BYPASS", reason: "stale" }`.
    */
   partial?:
     | true
@@ -115,6 +127,7 @@ export interface ServeShellRequestOptions<TEnv = any> {
         prefetch?: boolean;
         fill?: boolean;
         interceptSource?: string;
+        stale?: boolean;
       };
   /**
    * POST this form as a submit before hydration: the no-JS request the
@@ -474,29 +487,14 @@ async function servePrerenderArtifacts(
     const { hashParams } = await import("../prerender/param-hash.js");
     baked.add(pathname);
     if (result && !result.passthrough) {
-      const key = `${result.routeName}/${hashParams(result.params)}`;
-      payloads.set(
-        key,
-        JSON.stringify({ segments: result.segments, handles: result.handles }),
-      );
-      // The intercept variant, keyed and shaped as the build writes it
-      // (vite/discovery/prerender-collection.ts).
-      if (result.interceptSegments?.length) {
-        payloads.set(
-          `${key}/i`,
-          JSON.stringify({
-            segments: [...result.segments, ...result.interceptSegments],
-            handles: result.interceptHandles ?? "",
-          }),
-        );
+      const paramHash = hashParams(result.params);
+      for (const [key, value] of prerenderManifestEntries(result, paramHash)) {
+        payloads.set(key, value);
       }
     }
   }
-  const [{ createPrerenderStore }, { setPrerenderStoreForTests }] =
-    await Promise.all([
-      import("../prerender/store.js"),
-      import("../router/match-middleware/cache-lookup.js"),
-    ]);
+  const { setPrerenderStoreForTests } =
+    await import("../router/match-middleware/cache-lookup.js");
   const previousLoader = globalThis.__loadPrerenderManifestModule;
   globalThis.__loadPrerenderManifestModule = async () => ({
     default: Object.fromEntries([...payloads.keys()].map((key) => [key, key])),
@@ -574,12 +572,12 @@ async function buildActionRequest(
   const { encodeReply } =
     await import("@vitejs/plugin-rsc/vendor/react-server-dom/client.edge");
   registerTestAction(action.ref, action.id, "serveShellRequest");
-  const target = new URL(url);
-  target.searchParams.set("_rsc_action", action.id);
-  target.searchParams.set("_rsc_segments", (action.segments ?? []).join(","));
-  if (action.rewriteTarget) {
-    target.searchParams.set("_rsc_rt", action.rewriteTarget);
-  }
+  const target = writePartialParams(new URL(url), {
+    action: action.id,
+    segmentIds: action.segments ?? [],
+    emptySegments: "send",
+    rewriteTarget: action.rewriteTarget,
+  });
   headers.set("rsc-action", action.id);
   if (!headers.has("X-RSC-Router-Client-Path")) {
     headers.set("X-RSC-Router-Client-Path", url.href);
@@ -628,14 +626,21 @@ async function buildRequest(
     prefetch = false,
     fill = false,
     interceptSource,
+    stale = false,
   } = partial === true ? {} : partial;
+  if (stale && prefetch) {
+    throw new Error(
+      "serveShellRequest: partial.stale cannot be combined with partial.prefetch",
+    );
+  }
   const target = new URL(url);
-  target.searchParams.set("_rsc_partial", "true");
-  target.searchParams.set("_rsc_segments", segments.join(","));
-  if (rewriteTarget) target.searchParams.set("_rsc_rt", rewriteTarget);
-  // As the browser sends them: browser/navigation-client.ts (fill) and
+  target.searchParams.set(WIRE.partial, "true");
+  target.searchParams.set(WIRE.segments, segments.join(","));
+  if (rewriteTarget) target.searchParams.set(WIRE.rewriteTarget, rewriteTarget);
+  // As the browser sends them: browser/navigation-client.ts (fill, stale) and
   // browser/prefetch/fetch.ts (prefetch).
-  if (fill) target.searchParams.set(FILL_PARAM, "1");
+  if (fill) target.searchParams.set(WIRE.fill, "1");
+  if (stale) target.searchParams.set(WIRE.stale, "true");
   if (prefetch && !headers.has(PREFETCH_HEADER)) {
     headers.set(PREFETCH_HEADER, "1");
   }

package/src/types/cache-types.ts

@@ -137,9 +137,12 @@ export interface CacheOptions<TEnv = unknown> {
   ) => boolean;
 
   /**
-   * Custom cache key function - FULL OVERRIDE.
-   * Bypasses default key generation AND store's keyGenerator. The result is
-   * stored namespaced (`key:` plus its URI encoding), so no value it returns
+   * Custom cache key function. Replaces the URL part of the default key
+   * (host, path, params, search) AND bypasses the store's keyGenerator. The
+   * request kind stays: a document request, a navigation and each intercept
+   * navigation keep their own record under one result, so the result decides
+   * which requests of one kind share a record. It is stored namespaced
+   * (`key:` plus its URI encoding, then the kind), so no value it returns
    * names another route's record; a nested cache() keys its records within
    * this partition.
    *

package/src/types/error-types.ts

@@ -83,7 +83,15 @@ export interface OnErrorContext<TEnv = any> {
   env?: TEnv;
   /** Duration from request start to error (milliseconds) */
   duration?: number;
-  /** Whether this is a partial/navigation request */
+  /**
+   * Whether this is a partial/navigation request, on an error the segment
+   * walk catches (a handler that throws, a DSL loader that rejects): `true`
+   * for a navigation, unset for a document. An error in the background
+   * re-render of a `cache()` record (a stale HIT's refresh, the write of a
+   * navigation that kept a layout mounted) reports the request that started
+   * it. A streamed (`loading()`) handler's rejection does not carry it, in
+   * either render; the `routing` phase reports `false`.
+   */
   isPartial?: boolean;
   /** Whether an error boundary caught the error */
   handledByBoundary?: boolean;

package/src/types/handler-context.ts

@@ -462,7 +462,7 @@ export type InternalHandlerContext<
   _reverseScope?: import("../server/context.js").ReverseScope;
   /**
    * @internal The on-demand overlay holds a "removed" marker for this request
-   * (tryPrerenderLookup, cache-lookup.ts); gateOnDemandProducer reads it. On
+   * (readPrerenderSource, cache-lookup.ts); gateOnDemandProducer reads it. On
    * this context, not the request's: withCacheLookup documents that the
    * request ALS can be lost mid-pipeline on workerd.
    */
@@ -510,6 +510,17 @@ export type InternalHandlerContext<
    * request is a fill. See router/segment-resolution/prefetch-deferral.ts.
    */
   _prefetchDeferral?: import("../router/segment-resolution/prefetch-deferral.js").PrefetchDeferral;
+  /**
+   * @internal DSL loaders registered and not started, by `$$id`: a prefetch
+   * deferred them, or a pass that skips loaders (`skipLoaders`) did not run
+   * them. A reader's ctx.use() starts one through its registration
+   * (registerDeferredLoader, startDeferredLoader in
+   * router/segment-resolution/prefetch-deferral.ts).
+   */
+  _deferredLoaders?: Map<
+    string,
+    import("../router/segment-resolution/prefetch-deferral.js").DeferredLoader
+  >;
   /**
    * @internal Whether a loader was started in this request: a run of it (a
    * handler's or another loader's ctx.use()) or its cache() binding. A
@@ -637,10 +648,10 @@ export type IsActionFn = (...actions: ActionRef[]) => boolean;
  * ```ts
  * import * as CartActions from "./actions/cart";
  *
- * // Idiom A — "mine, else defer": re-render on my actions, otherwise return
- * // undefined so the segment's default decision still applies (and downstream
- * // revalidators get a say).
- * revalidate((ctx) => ctx.isAction(CartActions) || undefined)
+ * // Idiom A — "mine, else defer": re-render on my actions and on Back after
+ * // an action, otherwise return undefined so the segment's default decision
+ * // still applies (and downstream revalidators get a say).
+ * revalidate((ctx) => ctx.isAction(CartActions) || ctx.stale || undefined)
  *
  * // Idiom B — "mine only": re-render on my actions and suppress everything
  * // else (isAction returns a raw boolean, so an unrelated action yields false).
@@ -768,8 +779,11 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
   // ── Staleness signal ─────────────────────────────────────────────────
 
   /**
-   * `true` when the browser signals that data may be stale — typically because
-   * a server action was executed in this or another tab (`_rsc_stale` header).
+   * `true` on a revalidation of a page the browser marked stale (the
+   * `_rsc_stale` query param): Back/Forward onto a history entry after a
+   * server action in this or another tab, or while one is in flight. A request
+   * that holds no segments (the follow-up after an action, `refresh()`) is
+   * marked stale too, but there every segment renders and no predicate runs.
    *
    * This is NOT segment cache staleness (loaders are never segment-cached).
    * Use this to decide whether loader data should be re-fetched after an

package/src/types/segments.ts

@@ -165,7 +165,7 @@ export interface ResolvedSegment {
   loaderData?: any; // For loaders: the resolved data from loader execution
   /**
    * True when this loader was awaited before first flush
-   * (loader(Def, { ssr: false })). Stamped by resolveLoaders (fresh.ts) on
+   * (loader(Def, { ssr: false })). Stamped by resolveOwnerLoaders on
    * document AND shell-capture renders — capture bakes flagged loaders and
    * awaits the same lane. Feeds segment-system's settled-value delivery and
    * the dev SSR suspension warning (ssr-suspension-warning.ts).

package/src/vite/discovery/build-discovery-phase.ts

@@ -0,0 +1,204 @@
+/**
+ * Build discovery phase: the discovery plugin's buildStart, buildApp (post)
+ * and buildEnd hooks.
+ *
+ * buildStart discovers routers through a temp RSC server and writes the
+ * generated route types. When PPR shell candidates exist, it defers closing
+ * that server, and releasing the buildEnv, as a PAIR: the buildApp post hook
+ * releases them after the shell capture (success), buildEnd after an
+ * environment build failure (abort).
+ */
+
+import type { Rolldown, ViteBuilder } from "vite";
+import type { DiscoveryState } from "./state.js";
+import { createTempRscServer } from "../temp-rsc-server.js";
+import { acquireBuildEnv, releaseBuildEnv } from "./build-env.js";
+import { discoverRouters } from "./discover-routers.js";
+import { writeRouteTypesFiles } from "./route-types-writer.js";
+import { runShellPrerenderPhase } from "./shell-prerender-phase.js";
+import { runRouterVersionsPhase } from "./router-versions-phase.js";
+import { resetStagedBuildAssets } from "../utils/prerender-utils.js";
+import { createRangoDebugger, timed, timedSync, NS } from "../debug.js";
+
+const debugDiscovery = createRangoDebugger(NS.discovery);
+
+/**
+ * Reset the per-build prerender collection state. A helper (not inline
+ * assignments in buildStart) so TS's property narrowing does not pin
+ * `s.shellCandidates` to `null` across the discovery call that repopulates
+ * it — the finally block re-reads it to decide the temp-server keep-alive.
+ */
+function resetPrerenderCollection(s: DiscoveryState): void {
+  s.prerenderManifestEntries = null;
+  s.staticManifestEntries = null;
+  s.shellCandidates = null;
+  s.prerenderPayloadValues = null;
+  s.buildData = [];
+}
+
+/**
+ * buildStart. Build mode: create a temporary Vite dev server to access the
+ * RSC environment's module runner, then discover routers and generate
+ * manifests. The manifest data is stored for the virtual module's load hook.
+ */
+export async function buildDiscoveryPhase(
+  s: DiscoveryState,
+  context: Rolldown.PluginContext,
+): Promise<void> {
+  if (!s.isBuildMode) return;
+  // Only run once across environment builds
+  if (s.mergedRouteManifest !== null) {
+    debugDiscovery?.(
+      "build: skip (already discovered, env=%s)",
+      context.environment?.name ?? "?",
+    );
+    return;
+  }
+  const buildStartTime = performance.now();
+  debugDiscovery?.("build: start (env=%s)", context.environment?.name ?? "?");
+  resetStagedBuildAssets(s.projectRoot);
+  resetPrerenderCollection(s);
+
+  // Acquire build-time env bindings if configured
+  await timed(debugDiscovery, "build acquireBuildEnv", () =>
+    acquireBuildEnv(s, s.viteCommand, s.viteMode),
+  );
+
+  let tempServer: any = null;
+  // Signal to user-space code (e.g. reverse.ts) that build-time discovery
+  // is active. Uses globalThis because the temp server's module runner
+  // creates a separate module context — there is no shared import path
+  // between the vite plugin and user code loaded via runner.import().
+  (globalThis as any).__rscRouterDiscoveryActive = true;
+  try {
+    tempServer = await timed(debugDiscovery, "build createTempRscServer", () =>
+      createTempRscServer(s, { forceBuild: true }),
+    );
+
+    const rscEnv = (tempServer.environments as any)?.rsc;
+    if (!rscEnv?.runner) {
+      console.warn(
+        "[rango] RSC environment runner not available during build, skipping manifest generation",
+      );
+      return;
+    }
+
+    // Point resolvedStaticModules at the temp server's expose-internal-ids
+    // plugin so that discoverRouters() can access the static handler module
+    // map after the temp server's transforms populate it.
+    const tempIdsPlugin = (tempServer as any).config?.plugins?.find(
+      (p: any) => p.name === "@rangojs/router:expose-internal-ids",
+    );
+    if (tempIdsPlugin?.api?.staticHandlerModules) {
+      s.resolvedStaticModules = tempIdsPlugin.api.staticHandlerModules;
+    }
+
+    await timed(debugDiscovery, "build discoverRouters", () =>
+      discoverRouters(s, rscEnv, (tempServer.environments as any)?.ssr),
+    );
+    // Update named-routes.gen.ts from runtime discovery.
+    // The runtime manifest includes dynamically generated routes
+    // that the static parser cannot extract from source code.
+    timedSync(debugDiscovery, "build writeRouteTypesFiles", () =>
+      writeRouteTypesFiles(s),
+    );
+  } catch (err: any) {
+    // Extract the user source file from the stack trace (skip internal frames)
+    const sourceFile = err.stack
+      ?.split("\n")
+      .find(
+        (line: string) =>
+          line.includes(s.projectRoot) && !line.includes("node_modules"),
+      )
+      ?.match(/\(([^)]+)\)/)?.[1];
+    // Extract the route name from "Unknown route: <name>" errors
+    const routeName = err.message?.match(/Unknown route: (.+)/)?.[1];
+    const details = [
+      routeName ? `  Route name: ${routeName}` : null,
+      sourceFile ? `  File: ${sourceFile}` : null,
+      err.stack ? `  Stack:\n${err.stack}` : null,
+    ]
+      .filter(Boolean)
+      .join("\n");
+    throw new Error(`[rango] Build-time router discovery failed:\n${details}`, {
+      cause: err,
+    });
+  } finally {
+    delete (globalThis as any).__rscRouterDiscoveryActive;
+    if (tempServer && s.shellCandidates?.length) {
+      // Prerender+ppr candidates exist: keep the temp server (and its
+      // realm — tries installed, registry populated) alive for the
+      // post-build shell capture phase (buildApp post, producer B #699).
+      // The prelude embeds built client asset URLs, so the capture can
+      // only run after the client build; that phase closes the server.
+      // buildEnv release is deferred with it — a bake-lane loader
+      // executing during the capture may read ctx.env.
+      s.shellPhaseTempServer = tempServer;
+    } else {
+      if (tempServer) {
+        await timed(debugDiscovery, "build tempServer.close", () =>
+          tempServer.close(),
+        );
+      }
+      await releaseBuildEnv(s);
+    }
+    debugDiscovery?.(
+      "build discovery done (%sms)",
+      (performance.now() - buildStartTime).toFixed(1),
+    );
+  }
+}
+
+/**
+ * buildApp (post). Post-build phases, after EVERY environment bundle is
+ * written.
+ *
+ * 1. Cache versions (router-versions-phase.ts): hashes the server output as
+ *    postprocessBundle left it and writes the per-router table into the
+ *    built version module. First, because phase 2 stamps its entries with
+ *    these versions and reads the same RSC out dir.
+ * 2. PPR shell capture (producer B, #699): the shell prelude embeds built
+ *    client asset URLs (bootstrap entry), which do not exist at buildStart.
+ *    The kept temp server and the buildEnv were deferred AS A PAIR in
+ *    buildStart's finally; this finally is the pair's success-path owner
+ *    (buildEndPhase owns the aborted-build path) — the phase itself is a pure
+ *    producer and tears down only the globals it installs.
+ */
+export async function postBuildPhase(
+  s: DiscoveryState,
+  builder: ViteBuilder,
+): Promise<void> {
+  try {
+    await runShellPrerenderPhase(
+      s,
+      builder as any,
+      runRouterVersionsPhase(s, builder as any),
+    );
+  } finally {
+    if (s.isBuildMode) {
+      const tempServer = s.shellPhaseTempServer;
+      s.shellPhaseTempServer = null;
+      if (tempServer) await tempServer.close();
+      await releaseBuildEnv(s);
+    }
+  }
+}
+
+/**
+ * buildEnd. An environment build failure aborts the builder before the
+ * buildApp post hook — never leak the kept temp server (open handles hang
+ * the CLI) or the deferred buildEnv (a live miniflare proxy).
+ */
+export async function buildEndPhase(
+  s: DiscoveryState,
+  error: Error | undefined,
+): Promise<void> {
+  if (!error || !s.shellPhaseTempServer) return;
+  const tempServer = s.shellPhaseTempServer;
+  s.shellPhaseTempServer = null;
+  try {
+    await tempServer.close();
+  } finally {
+    await releaseBuildEnv(s);
+  }
+}

package/src/vite/discovery/build-env.ts

@@ -0,0 +1,148 @@
+/**
+ * Build-time env (rango({ buildEnv })): resolution of the option and the
+ * lifetime of the resolved bindings on DiscoveryState. Acquired by dev
+ * discovery (dev-server-phase.ts) and build discovery
+ * (build-discovery-phase.ts).
+ */
+
+import { dirname, join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { BUILD_ENV_GLOBAL_KEY } from "../plugins/cloudflare-protocol-stub.js";
+import type {
+  BuildEnvOption,
+  BuildEnvFactoryContext,
+  BuildEnvResult,
+} from "../plugin-types.js";
+import type { DiscoveryState } from "./state.js";
+
+const WRANGLER_CONFIG_NAMES: readonly string[] = [
+  "wrangler.json",
+  "wrangler.jsonc",
+  "wrangler.toml",
+];
+
+/**
+ * getPlatformProxy() looks for the wrangler config from process.cwd() and
+ * resolves its default persist path against cwd, so building from another
+ * directory dropped the app's bindings (#1037). Search upward from the Vite
+ * root with wrangler's own file names and order. Persisted state goes under
+ * the Vite root, where @cloudflare/vite-plugin reads it in dev and preview
+ * (its getPersistenceRoot), also when the config sits above the root. No
+ * config found: no options, wrangler's own lookup.
+ */
+function wranglerProxyOptions(
+  root: string,
+): Record<string, unknown> | undefined {
+  const viteRoot = resolve(root);
+  for (let dir = viteRoot; ; dir = dirname(dir)) {
+    for (const name of WRANGLER_CONFIG_NAMES) {
+      const configPath = join(dir, name);
+      if (existsSync(configPath)) {
+        return {
+          configPath,
+          persist: { path: join(viteRoot, ".wrangler", "state", "v3") },
+        };
+      }
+    }
+    if (dirname(dir) === dir) return undefined;
+  }
+}
+
+/**
+ * Resolve the buildEnv option into a concrete { env, dispose? } result.
+ * Handles all four input shapes: false, "auto", factory, plain object.
+ */
+export async function resolveBuildEnv(
+  option: BuildEnvOption | undefined,
+  factoryCtx: BuildEnvFactoryContext,
+): Promise<BuildEnvResult | null> {
+  if (!option) return null;
+
+  if (option === "auto") {
+    if (factoryCtx.preset !== "cloudflare") {
+      throw new Error(
+        '[rango] buildEnv: "auto" is only supported with preset: "cloudflare". ' +
+          "Use a factory function or plain object for other presets.",
+      );
+    }
+    try {
+      // Resolve wrangler from the user's project root (not the router package)
+      const userRequire = createRequire(
+        resolve(factoryCtx.root, "package.json"),
+      );
+      const wranglerPath = userRequire.resolve("wrangler");
+      const { getPlatformProxy } = (await import(
+        pathToFileURL(wranglerPath).href
+      )) as {
+        getPlatformProxy: (opts?: any) => Promise<any>;
+      };
+      const proxy = await getPlatformProxy(
+        wranglerProxyOptions(factoryCtx.root),
+      );
+      return {
+        env: proxy.env as Record<string, unknown>,
+        dispose: proxy.dispose,
+      };
+    } catch (err: any) {
+      throw new Error(
+        '[rango] buildEnv: "auto" requires wrangler to be installed.\n' +
+          `Install it with: pnpm add -D wrangler\n${err.message}`,
+      );
+    }
+  }
+
+  if (typeof option === "function") {
+    return await option(factoryCtx);
+  }
+
+  // Plain object
+  return { env: option };
+}
+
+/**
+ * Acquire build-time env bindings and store on discovery state.
+ * Returns true if env was acquired, false if buildEnv is disabled.
+ */
+export async function acquireBuildEnv(
+  s: DiscoveryState,
+  command: "serve" | "build",
+  mode: string,
+): Promise<boolean> {
+  const option = s.opts?.buildEnv;
+  if (!option) return false;
+
+  const result = await resolveBuildEnv(option, {
+    root: s.projectRoot,
+    mode,
+    command,
+    preset: s.opts?.preset ?? "node",
+  });
+  if (!result) return false;
+
+  s.resolvedBuildEnv = result.env;
+  s.buildEnvDispose = result.dispose ?? null;
+  // Bridge the resolved env into `cloudflare:workers`'s stubbed `env`
+  // export so user code that does `import { env } from "cloudflare:workers"`
+  // sees the real bindings proxy during discovery + prerender instead of
+  // an empty object. The stub reads this global at module-evaluation time.
+  (globalThis as Record<string, unknown>)[BUILD_ENV_GLOBAL_KEY] = result.env;
+  return true;
+}
+
+/**
+ * Release build-time env resources and clear state.
+ */
+export async function releaseBuildEnv(s: DiscoveryState): Promise<void> {
+  if (s.buildEnvDispose) {
+    try {
+      await s.buildEnvDispose();
+    } catch (err: any) {
+      console.warn(`[rango] buildEnv dispose failed: ${err.message}`);
+    }
+    s.buildEnvDispose = null;
+  }
+  s.resolvedBuildEnv = undefined;
+  delete (globalThis as Record<string, unknown>)[BUILD_ENV_GLOBAL_KEY];
+}