@rangojs/router 0.1.0 → 0.1.1

package/src/cache/vercel/vercel-cache-store.ts

@@ -134,9 +134,9 @@ type CacheFamily = "s" | "i" | "r" | "h" | "tm";
  * invalidateTags for the build-shell read-through's isTagsInvalidatedSince
  * gate. The platform's expireTag() DELETES tagged entries (no queryable
  * history), so the markers are rango's own record of "tag X was invalidated
- * at T". One year: markers must outlive any build's shell entries (which the
- * buildVersion gate retires on the next deploy anyway); an expired marker
- * would silently resurrect an updateTag()-evicted build shell.
+ * at T". One year: runtime tagged-shell retention is capped to this lifetime,
+ * while buildVersion retires build shells on the next deploy. An expired marker
+ * therefore cannot resurrect a runtime shell that outlived its invalidation.
  */
 const TAG_MARKER_TTL_SECONDS = 365 * 24 * 60 * 60;
 
@@ -190,7 +190,7 @@ interface VercelShellEnvelope {
   rv: string;
   /** Build version at capture (ShellCacheEntry.buildVersion). */
   bv?: string;
-  /** createdAt (ms since epoch). */
+  /** Capture-generation start time, used by tag marker checks. */
   c: number;
   /** staleAt (ms since epoch). */
   s: number;
@@ -209,6 +209,8 @@ interface VercelShellEnvelope {
    * their holes only a handler re-run can fill.
    */
   lh?: boolean;
+  /** ShellCacheEntry.transitionWhen; conditional transitions must re-run. */
+  tw?: true;
 }
 
 /** Read-path outcome for the debug sink. */
@@ -355,6 +357,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 export class VercelCacheStore<
   TEnv = unknown,
 > implements SegmentCacheStore<TEnv> {
+  readonly supportsPassiveShellReads: true = true;
   readonly defaults?: CacheDefaults;
   readonly keyGenerator?: (
     ctx: RequestContext<TEnv>,
@@ -731,6 +734,7 @@ export class VercelCacheStore<
 
   async getShell(
     key: string,
+    options?: { claimRevalidation?: boolean },
   ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null> {
     const storeKey = this.toStoreKey(key, "h");
     const started = Date.now();
@@ -774,14 +778,25 @@ export class VercelCacheStore<
       return null;
     }
 
+    if (
+      env.t &&
+      env.t.length > 0 &&
+      (await this.isTagsInvalidatedSince(env.t, env.c))
+    ) {
+      void this.safeDelete(storeKey);
+      this.emitDebug({ op: "getShell", key, outcome: "miss", readMs });
+      return null;
+    }
+
     const isStale = env.s > 0 && now > env.s;
-    const shouldRevalidate = isStale
-      ? await this.claimRevalidation(
-          storeKey,
-          env.e,
-          "[VercelCacheStore] getShell",
-        )
-      : false;
+    let shouldRevalidate = isStale;
+    if (isStale && options?.claimRevalidation !== false) {
+      shouldRevalidate = await this.claimRevalidation(
+        storeKey,
+        env.e,
+        "[VercelCacheStore] getShell",
+      );
+    }
     this.emitDebug({
       op: "getShell",
       key,
@@ -800,6 +815,7 @@ export class VercelCacheStore<
         initialTheme: env.i,
         snapshot: env.sn,
         handlerLiveHoles: env.lh,
+        transitionWhen: env.tw,
         createdAt: env.c,
       },
       shouldRevalidate,
@@ -812,10 +828,12 @@ export class VercelCacheStore<
     ttlSeconds?: number,
     swrSeconds?: number,
     tags?: string[],
-  ): Promise<void> {
+  ): Promise<"stored" | "invalidated" | void> {
     try {
       const ttl = resolveTtl(ttlSeconds, this.defaults, DEFAULT_FUNCTION_TTL);
       const swrWindow = resolveSwrWindow(swrSeconds, this.defaults);
+      const totalTtl = ttl + swrWindow;
+      const now = Date.now();
       const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
       // Store the CLAMPED tags (see putResponse/setItem) so dropped tags don't
       // resurface on a hit; write() re-clamps idempotently.
@@ -823,6 +841,17 @@ export class VercelCacheStore<
         tags,
         "[VercelCacheStore] putShell",
       );
+      const storeKey = this.toStoreKey(key, "h");
+      if (
+        safeTags.length > 0 &&
+        (await this.isTagsInvalidatedSince(safeTags, entry.createdAt))
+      ) {
+        return "invalidated";
+      }
+      const retentionTtl =
+        safeTags.length > 0
+          ? Math.min(totalTtl, TAG_MARKER_TTL_SECONDS)
+          : totalTtl;
       const env: VercelShellEnvelope = {
         p: entry.prelude,
         po: entry.postponed,
@@ -830,22 +859,24 @@ export class VercelCacheStore<
         bv: entry.buildVersion,
         c: entry.createdAt,
         s: staleAt,
-        e: expiresAt,
+        e: Math.min(expiresAt, now + retentionTtl * 1000),
         t: safeTags.length > 0 ? safeTags : undefined,
         i: entry.initialTheme,
         sn: entry.snapshot,
         lh: entry.handlerLiveHoles,
+        tw: entry.transitionWhen,
       };
       // write() enforces the 2 MB per-item ceiling (withinSizeLimit): an
       // oversized shell prelude is reported and skipped (fail-open to a full
       // render), never silently no-op'd on the platform.
       await this.write(
-        this.toStoreKey(key, "h"),
+        storeKey,
         env,
-        ttl + swrWindow,
+        retentionTtl,
         safeTags,
         "[VercelCacheStore] putShell",
       );
+      return "stored";
     } catch (error) {
       reportCacheError(error, "cache-write", "[VercelCacheStore] putShell");
     }
@@ -854,12 +885,10 @@ export class VercelCacheStore<
   // --- Tags ---
 
   /**
-   * Build-shell read-through gate (SegmentCacheStore.isTagsInvalidatedSince).
-   * The platform's expireTag() DELETES tagged entries and keeps no queryable
-   * history, so invalidateTags() below writes its own "tm" marker entries and
-   * this compares them against the baked entry's build-time createdAt
-   * (>= so a same-millisecond invalidation wins). Fails open to `false` on
-   * read errors — the same posture as the CF marker check.
+   * Shell tag-generation gate (SegmentCacheStore.isTagsInvalidatedSince).
+   * expireTag() keeps no queryable history, so invalidateTags() writes "tm"
+   * markers for runtime capture races and immutable build shells. Marker >=
+   * generation start wins; read errors fail open like the CF marker check.
    */
   async isTagsInvalidatedSince(
     tags: string[],
@@ -1163,7 +1192,7 @@ export class VercelCacheStore<
 
   private asShellEnvelope(raw: unknown): VercelShellEnvelope | null {
     if (!isRecord(raw)) return null;
-    const { p, po, rv, bv, c, s, e, t, i, sn, lh } = raw;
+    const { p, po, rv, bv, c, s, e, t, i, sn, lh, tw } = raw;
     if (typeof p !== "string" || typeof rv !== "string") return null;
     if (po !== null && typeof po !== "string") return null;
     if (typeof c !== "number") return null;
@@ -1180,6 +1209,7 @@ export class VercelCacheStore<
       i: typeof i === "string" ? i : undefined,
       sn: Array.isArray(sn) ? (sn as ShellSnapshotRecord[]) : undefined,
       lh: lh === true ? true : undefined,
+      tw: tw === true ? true : undefined,
     };
   }
 

package/src/dev-discovery-protocol.ts

@@ -0,0 +1,11 @@
+export const DEV_DISCOVERY_READY_EVENT = "rango:dev-discovery-ready";
+
+export const DEV_DISCOVERY_QUERY_EVENT = "rango:dev-discovery-query";
+
+export const DEV_DISCOVERY_PROBE_HEADER = "x-rango-dev-discovery-probe";
+
+export const DEV_DISCOVERY_EPOCH_HEADER = "x-rango-dev-discovery-epoch";
+
+export function isValidDevDiscoveryEpoch(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}

package/src/prerender/build-shell-capture.ts

@@ -44,7 +44,7 @@ import { isRouteNotFoundError } from "../errors.js";
 import { createReverseFunction } from "../router/handler-context.js";
 import { executeMiddleware, matchMiddleware } from "../router/middleware.js";
 import type { MiddlewareEntry } from "../router/middleware.js";
-import { getGlobalRouteMap } from "../route-map-builder.js";
+import { getGlobalRouteMap, isRouteRootScoped } from "../route-map-builder.js";
 import {
   resolvePprConfig,
   type ResolvedPprConfig,
@@ -183,6 +183,9 @@ async function attemptBuildCapture(
     stateCookieName: router.resolvedStateCookieName,
     version: opts.buildVersion,
   });
+  // Scope registry lookups (root-scope/search-schema) per router during the
+  // bake, mirroring rsc/handler.ts on the request path (#762).
+  baseCtx._routerId = router.id;
 
   // Entry collector: captureAndStoreShell's sink. putShell never fails here,
   // so a "stored" outcome always carries the entry.
@@ -235,6 +238,9 @@ async function attemptBuildCapture(
       getGlobalRouteMap(),
       preview?.routeKey,
       preview?.params ?? {},
+      preview?.routeKey
+        ? isRouteRootScoped(preview.routeKey, router.id)
+        : undefined,
     );
 
     const runCapture = () =>

package/src/prerender/store.ts

@@ -54,6 +54,11 @@ declare global {
   var __STATIC_MANIFEST:
     | Record<string, () => Promise<{ default: string | StaticEntry }>>
     | undefined;
+  // Injected by closeBundle post-processing: lazy loader for the static
+  // manifest module (which assigns __STATIC_MANIFEST on evaluation). Resolved
+  // by static-store.ts on the first Static() lookup — issue #760.
+  // eslint-disable-next-line no-var
+  var __loadStaticManifestModule: (() => Promise<unknown>) | undefined;
   // Injected by virtual module in dev mode for on-demand prerender
   // eslint-disable-next-line no-var
   var __PRERENDER_DEV_URL: string | undefined;

package/src/route-definition/dsl-helpers.ts

@@ -12,6 +12,7 @@ import {
   getNamePrefix,
   getUrlPrefix,
   requireDslContext,
+  stampStaticDefScope,
   type EntryData,
   type EntryPropDatas,
   type EntryPropSegments,
@@ -560,6 +561,7 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
         if (ctx.namePrefix) {
           (slotHandler as any).$$routePrefix = ctx.namePrefix;
         }
+        stampStaticDefScope(slotHandler);
       }
     } else {
       unwrappedSlots[slotName] = slotHandler;
@@ -1016,8 +1018,11 @@ const layout: RouteHelpers<any, any>["layout"] = (handler, use) => {
   } satisfies EntryData;
 
   // Capture namespace prefix on static handler for build-time reverse() resolution
-  if (isStatic && handler.$$id && ctx.namePrefix) {
-    (handler as any).$$routePrefix = ctx.namePrefix;
+  if (isStatic && handler.$$id) {
+    if (ctx.namePrefix) {
+      (handler as any).$$routePrefix = ctx.namePrefix;
+    }
+    stampStaticDefScope(handler);
   }
 
   // Merge handler.use defaults with explicit use

package/src/route-map-builder.ts

@@ -12,11 +12,6 @@ let globalRouteMap: Record<string, string> = {};
 
 let cachedManifest: Record<string, string> | null = null;
 
-let cachedPrecomputedEntries: Array<{
-  staticPrefix: string;
-  routes: Record<string, string>;
-}> | null = null;
-
 /**
  * Register routes into the global route map.
  * Routes are merged with any existing registered routes.
@@ -87,43 +82,6 @@ export function clearCachedManifest(): void {
   cachedManifest = null;
 }
 
-/**
- * Set pre-computed route entries from build-time data.
- *
- * Each entry corresponds to a leaf node in the prefix tree (no nested includes).
- * evaluateLazyEntry() checks these before running the handler, avoiding the
- * 5-50ms cost of handler evaluation for route matching on the first request.
- *
- * @param entries - Array of { staticPrefix, routes } from build-time prefix tree leaves
- */
-export function setPrecomputedEntries(
-  entries: Array<{
-    staticPrefix: string;
-    routes: Record<string, string>;
-  }> | null,
-): void {
-  cachedPrecomputedEntries = entries;
-}
-
-/**
- * Get pre-computed route entries (if available)
- */
-export function getPrecomputedEntries(): typeof cachedPrecomputedEntries {
-  return cachedPrecomputedEntries;
-}
-
-// Route trie for O(path_length) matching at runtime.
-// Built at build time from the route manifest and serialized into the virtual module.
-let cachedRouteTrie: import("./build/route-trie.js").TrieNode | null = null;
-
-export function setRouteTrie(trie: typeof cachedRouteTrie): void {
-  cachedRouteTrie = trie;
-}
-
-export function getRouteTrie(): typeof cachedRouteTrie {
-  return cachedRouteTrie;
-}
-
 // Per-router isolated data: each router gets its own manifest, trie, and
 // precomputed entries so multi-router setups (e.g. site + admin via
 // createHostRouter()) don't see each other's routes.
@@ -146,14 +104,18 @@ const perRouterPrecomputedEntriesMap: Map<
 export function clearAllRouterData(): void {
   globalRouteMap = {};
   cachedManifest = null;
-  cachedPrecomputedEntries = null;
-  cachedRouteTrie = null;
   rootScopeRoutes.clear();
+  perRouterRootScopeRoutes.clear();
   globalSearchSchemas.clear();
+  perRouterSearchSchemas.clear();
   perRouterManifestMap.clear();
   perRouterTrieMap.clear();
   perRouterPrecomputedEntriesMap.clear();
   authoritativeTrieRouters.clear();
+  // Clear the loader registry too: a loader that survives a clear closes over
+  // a module import whose data predates the clear, and re-running it would
+  // re-install that stale trie as authoritative.
+  routerManifestLoaders.clear();
 }
 
 export function setRouterManifest(
@@ -229,9 +191,9 @@ export async function ensureRouterManifest(routerId: string): Promise<void> {
   // name->path map is pre-set by the eager virtual module's
   // setRouterManifest() and never comes from the loader). Gating on the
   // manifest instead would let the loader be skipped while the per-router
-  // trie is missing, and findMatch would fall back to the global merged
-  // trie — which contains routes from ALL routers and breaks multi-router
-  // setups.
+  // trie is missing, and findMatch would fall back to insertion-order regex
+  // matching — which mishandles wildcard priority (catch-alls match before
+  // specific routes).
   if (perRouterTrieMap.has(routerId)) return;
   const loader = routerManifestLoaders.get(routerId);
   if (loader) {
@@ -265,7 +227,16 @@ export function waitForManifestReady(): Promise<void> | null {
 // Tracks whether each route is at root scope (no named include boundary above).
 // Used by dot-local reverse resolution to decide whether bare-name fallback
 // is allowed after scoped lookups are exhausted.
+//
+// Both this and the search-schema registry below are keyed by route NAME and
+// registered by path() at evaluation time. Two routers can legally declare the
+// same route name (per-router manifests keep them apart), so each registry has
+// a per-router tier consulted first; the global tier is the fallback for
+// contexts with no router identity (single-router apps, unit tests, evaluation
+// outside generateManifestFull). Without the per-router tier, the
+// last-evaluated router silently won for BOTH routers.
 const rootScopeRoutes: Map<string, boolean> = new Map();
+const perRouterRootScopeRoutes: Map<string, Map<string, boolean>> = new Map();
 
 /**
  * Register whether a route is at root scope.
@@ -274,29 +245,65 @@ const rootScopeRoutes: Map<string, boolean> = new Map();
 export function registerRouteRootScope(
   routeName: string,
   rootScoped: boolean,
+  routerId?: string,
 ): void {
   rootScopeRoutes.set(routeName, rootScoped);
+  if (routerId) {
+    let perRouter = perRouterRootScopeRoutes.get(routerId);
+    if (!perRouter) {
+      perRouter = new Map();
+      perRouterRootScopeRoutes.set(routerId, perRouter);
+    }
+    perRouter.set(routeName, rootScoped);
+  }
 }
 
 /**
  * Check if a route is at root scope.
  * Returns undefined if the route has not been registered (e.g. in unit tests).
  */
-export function isRouteRootScoped(routeName: string): boolean | undefined {
+export function isRouteRootScoped(
+  routeName: string,
+  routerId?: string,
+): boolean | undefined {
+  if (routerId) {
+    const scoped = perRouterRootScopeRoutes.get(routerId)?.get(routeName);
+    if (scoped !== undefined) return scoped;
+  }
   return rootScopeRoutes.get(routeName);
 }
 
 import type { SearchSchema } from "./search-params.js";
 
 const globalSearchSchemas: Map<string, SearchSchema> = new Map();
+const perRouterSearchSchemas: Map<
+  string,
+  Map<string, SearchSchema>
+> = new Map();
 
 export function registerSearchSchema(
   routeName: string,
   schema: SearchSchema,
+  routerId?: string,
 ): void {
   globalSearchSchemas.set(routeName, schema);
+  if (routerId) {
+    let perRouter = perRouterSearchSchemas.get(routerId);
+    if (!perRouter) {
+      perRouter = new Map();
+      perRouterSearchSchemas.set(routerId, perRouter);
+    }
+    perRouter.set(routeName, schema);
+  }
 }
 
-export function getSearchSchema(routeName: string): SearchSchema | undefined {
+export function getSearchSchema(
+  routeName: string,
+  routerId?: string,
+): SearchSchema | undefined {
+  if (routerId) {
+    const schema = perRouterSearchSchemas.get(routerId)?.get(routeName);
+    if (schema !== undefined) return schema;
+  }
   return globalSearchSchemas.get(routeName);
 }

package/src/router/handler-context.ts

@@ -96,7 +96,7 @@ function resolveRouteName(
     // Resolution order: explicit param > scope registry > heuristic.
     const isRootScoped =
       rootScoped ??
-      isRouteRootScoped(currentRoutePrefix) ??
+      isRouteRootScoped(currentRoutePrefix, _getRequestContext()?._routerId) ??
       !currentRoutePrefix.includes(".");
     if (isRootScoped) {
       if (routeMap[lookupName] !== undefined) {
@@ -208,7 +208,9 @@ export function createHandlerContext<TEnv>(
   const variables: any = requestContext?._variables ?? {};
 
   // If route has a search schema, parse URLSearchParams into typed object
-  const searchSchema = routeName ? getSearchSchema(routeName) : undefined;
+  const searchSchema = routeName
+    ? getSearchSchema(routeName, requestContext?._routerId)
+    : undefined;
   const resolvedSearchParams = searchSchema
     ? parseSearchParams(searchParams, searchSchema)
     : searchParams;
@@ -306,7 +308,9 @@ export function createHandlerContext<TEnv>(
       routeMap,
       routeName,
       params,
-      routeName ? isRouteRootScoped(routeName) : undefined,
+      routeName
+        ? isRouteRootScoped(routeName, requestContext?._routerId)
+        : undefined,
     ),
     passthrough: createPrerenderPassthroughFn(false, isPassthroughRoute),
     _responseType: responseType,
@@ -399,7 +403,9 @@ export function createPrerenderContext<TEnv>(
       routeMap,
       routeName,
       params,
-      routeName ? isRouteRootScoped(routeName) : undefined,
+      routeName
+        ? isRouteRootScoped(routeName, _getRequestContext()?._routerId)
+        : undefined,
     ),
     passthrough: createPrerenderPassthroughFn(
       true,
@@ -496,7 +502,9 @@ export function createStaticContext<TEnv>(
       routeMap,
       routeName,
       undefined,
-      routeName ? isRouteRootScoped(routeName) : undefined,
+      routeName
+        ? isRouteRootScoped(routeName, _getRequestContext()?._routerId)
+        : undefined,
     ),
     _routeName: routeName,
   } as InternalHandlerContext<any, TEnv>;

package/src/router/lazy-includes.ts

@@ -171,6 +171,7 @@ function runExpansion<TEnv = any>(
       counters: lazyCounters,
       cacheProfiles: lazyContext?.cacheProfiles,
       rootScoped: lazyContext?.rootScoped,
+      routerId: lazyContext?.routerId,
       includeScope: lazyContext?.includeScope,
     },
     () => {

package/src/router/match-api.ts

@@ -184,9 +184,8 @@ export async function createMatchContextForFull<TEnv>(
     },
     isSameRouteNavigation: false,
     interceptResult: null,
-    // Shell fast path: a capture or an eligible HIT tail may substitute an
-    // implicit doc-level scope (marker-gated; a route-derived scope wins).
-    // Full matches only — partial navigations never serve a shell.
+    // Shell fast path: a capture or an eligible document/navigation HIT may
+    // substitute an implicit doc-level scope (a route-derived scope wins).
     cacheScope: resolveShellImplicitCacheScope(snapshot.cacheScope),
     isIntercept: false,
     actionContext: undefined,
@@ -426,7 +425,12 @@ export async function createMatchContextForPartial<TEnv>(
     interceptSelectorContext,
     isSameRouteNavigation: nav.isSameRouteNavigation,
     interceptResult,
-    cacheScope: snapshot.cacheScope,
+    // A normal-route navigation may replay a PPR shell's canonical segment
+    // snapshot. Intercepts remain source-dependent and always use their normal
+    // cache path.
+    cacheScope: isIntercept
+      ? snapshot.cacheScope
+      : resolveShellImplicitCacheScope(snapshot.cacheScope),
     isIntercept,
     actionContext,
     isAction,

package/src/router/prerender-match.ts

@@ -34,6 +34,9 @@ import type {
 import type { RouteMatchResult } from "./pattern-matching.js";
 
 export interface PrerenderMatchDeps<TEnv = any> {
+  /** Owning router id; scopes bake-time root-scope/search-schema lookups the
+   *  same way reqCtx._routerId does at runtime (issue #762). */
+  routerId?: string;
   findMatch: (
     pathname: string,
   ) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
@@ -244,8 +247,13 @@ export async function matchForPrerender<TEnv = any>(
         deps.mergedRouteMap,
         matched.routeKey,
         matchedParams,
-        matched.routeKey ? isRouteRootScoped(matched.routeKey) : undefined,
+        matched.routeKey
+          ? isRouteRootScoped(matched.routeKey, deps.routerId)
+          : undefined,
       ),
+      // Scope the bake context's own lookups (createPrerenderContext reads it
+      // through the request ALS) per router as well.
+      _routerId: deps.routerId,
     };
 
     return runWithRequestContext(minimalRequestContext, async () => {
@@ -464,6 +472,8 @@ export async function renderStaticSegment<TEnv = any>(
   routeName?: string,
   buildEnv?: TEnv,
   devMode?: boolean,
+  routerId?: string,
+  rootScoped?: boolean,
 ): Promise<{ encoded: string; handles: string } | null> {
   const syntheticUrl = new URL("http://prerender/");
   const syntheticRequest = new Request(syntheticUrl);
@@ -514,8 +524,15 @@ export async function renderStaticSegment<TEnv = any>(
       mergedRouteMap,
       routeName,
       {},
-      routeName ? isRouteRootScoped(routeName) : undefined,
+      // Def-stamped value first: the collector passes the mount-time
+      // root-scope captured on the Static definition (stampStaticDefScope),
+      // which needs no registry lookup and survives name-prefix arguments.
+      rootScoped ??
+        (routeName ? isRouteRootScoped(routeName, routerId) : undefined),
     ),
+    // Scope the bake context's own lookups (createStaticContext reads it
+    // through the request ALS) per router as well.
+    _routerId: routerId,
   };
 
   return runWithRequestContext(minimalRequestContext, async () => {

package/src/router/router-interfaces.ts

@@ -419,6 +419,9 @@ export interface RangoInternal<
   /** @internal basename for runtime manifest generation */
   readonly __basename?: string;
 
+  /** @internal Cloudflare dev worker generation captured at construction. */
+  readonly __devDiscoveryEpoch?: number;
+
   /**
    * @internal Router-level error/notFound fallbacks (`createRouter` options),
    * exposed for the build-time clientChunks discovery so a `"use client"`
@@ -469,6 +472,7 @@ export interface RangoInternal<
     routeName?: string,
     buildEnv?: any,
     devMode?: boolean,
+    rootScoped?: boolean,
   ): Promise<{ encoded: string; handles: string } | null>;
 
   /**

package/src/router/segment-resolution/static-store.ts

@@ -11,14 +11,19 @@ import type { StaticStore } from "../../prerender/store.js";
 import type { SegmentHandleData } from "../../cache/types.js";
 
 // Lazy-initialized static store for production Static handler interception.
-// Remains undefined until first check; null means checked but no manifest.
-// When no __STATIC_MANIFEST exists (dev mode), set to null eagerly to avoid
-// the dynamic import() in ensureStaticDeps() which disrupts AsyncLocalStorage
-// in workerd/Cloudflare runtime.
-let _staticStore: StaticStore | null | undefined =
-  typeof globalThis !== "undefined" && globalThis.__STATIC_MANIFEST
-    ? undefined
-    : null;
+// undefined = not yet checked; null = checked, no manifest (dev mode, or an
+// app without Static handlers) — a permanent SYNCHRONOUS fast path: no await
+// may ever run on that path (an await per lookup disrupts AsyncLocalStorage
+// in workerd/Cloudflare runtime).
+//
+// The check happens on the FIRST LOOKUP, not at module eval: the manifest
+// loader global (__loadStaticManifestModule, bundle-postprocess.ts) is
+// assigned by the RSC entry's BODY, which runs after hoisted module imports
+// evaluate this file — an eval-time read here could never see it. The
+// pre-#760 eager `import "./__static-manifest.js"` existed precisely to beat
+// that hoisting; deferring the manifest module keeps its O(#Static handlers)
+// thunk table off the worker's cold-start path.
+let _staticStore: StaticStore | null | undefined = undefined;
 let _deserializeComponent: ((encoded: string) => Promise<unknown>) | undefined;
 let _decodeHandleValue:
   | typeof import("../../cache/handle-snapshot.js").decodeHandleValue
@@ -26,6 +31,18 @@ let _decodeHandleValue:
 
 async function ensureStaticDeps(): Promise<void> {
   if (_staticStore === undefined) {
+    // Evaluate the deferred manifest module (it assigns __STATIC_MANIFEST);
+    // support a pre-set __STATIC_MANIFEST too (tests, non-postprocess embeds).
+    if (
+      !globalThis.__STATIC_MANIFEST &&
+      globalThis.__loadStaticManifestModule
+    ) {
+      await globalThis.__loadStaticManifestModule();
+    }
+    if (!globalThis.__STATIC_MANIFEST) {
+      _staticStore = null;
+      return;
+    }
     const { createStaticStore } = await import("../../prerender/store.js");
     _staticStore = createStaticStore();
   }
@@ -52,8 +69,17 @@ export async function tryStaticLookup(
   handlerId: string,
   segmentId: string,
 ): Promise<ReactNode | undefined> {
-  // Fast path: already checked and no manifest available (dev mode or no Static handlers).
-  // Avoids await which can disrupt AsyncLocalStorage in workerd/Cloudflare runtime.
+  // Fast path: no manifest available (dev mode or no Static handlers).
+  // Latched SYNCHRONOUSLY — including on the very first call — so this path
+  // never awaits (an await here disrupts AsyncLocalStorage in
+  // workerd/Cloudflare runtime).
+  if (
+    _staticStore === undefined &&
+    !globalThis.__STATIC_MANIFEST &&
+    !globalThis.__loadStaticManifestModule
+  ) {
+    _staticStore = null;
+  }
   if (_staticStore === null) return undefined;
   await ensureStaticDeps();
   if (!_staticStore || !_deserializeComponent) return undefined;