@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.0

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

@@ -127,7 +127,18 @@ const REVALIDATION_LOCK_MS = 30_000;
 /** Family prefixes that keep the value tiers from colliding in the single Vercel
  *  keyspace. The router's own semantic prefixes (doc:/partial:/use-cache:) become
  *  the suffix; `rg:` namespaces every Rango entry. `h` is the PPR shell tier. */
-type CacheFamily = "s" | "i" | "r" | "h";
+type CacheFamily = "s" | "i" | "r" | "h" | "tm";
+
+/**
+ * TTL for tag-invalidation marker entries ("tm" family), written by
+ * 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.
+ */
+const TAG_MARKER_TTL_SECONDS = 365 * 24 * 60 * 60;
 
 /** Stored envelope for a segment-tree entry (get/set). */
 interface VercelSegmentEnvelope {
@@ -191,6 +202,13 @@ interface VercelShellEnvelope {
   i?: string;
   /** Capture data snapshot: recorded cache-store hits/writes for HIT parity. */
   sn?: ShellSnapshotRecord[];
+  /**
+   * ShellCacheEntry.handlerLiveHoles. Must round-trip: the serve side arms the
+   * handler-free fast path on `!entry.handlerLiveHoles`, so dropping the flag
+   * here silently fast-pathed handler-live entries after a store round trip —
+   * their holes only a handler re-run can fill.
+   */
+  lh?: boolean;
 }
 
 /** Read-path outcome for the debug sink. */
@@ -781,6 +799,7 @@ export class VercelCacheStore<
         buildVersion: env.bv,
         initialTheme: env.i,
         snapshot: env.sn,
+        handlerLiveHoles: env.lh,
         createdAt: env.c,
       },
       shouldRevalidate,
@@ -815,6 +834,7 @@ export class VercelCacheStore<
         t: safeTags.length > 0 ? safeTags : undefined,
         i: entry.initialTheme,
         sn: entry.snapshot,
+        lh: entry.handlerLiveHoles,
       };
       // write() enforces the 2 MB per-item ceiling (withinSizeLimit): an
       // oversized shell prelude is reported and skipped (fail-open to a full
@@ -833,6 +853,40 @@ 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.
+   */
+  async isTagsInvalidatedSince(
+    tags: string[],
+    sinceMs: number,
+  ): Promise<boolean> {
+    try {
+      const markers = await Promise.all(
+        tags.map((tag) => this.cache.get(this.toStoreKey(tag, "tm"))),
+      );
+      for (const raw of markers) {
+        if (raw == null) continue;
+        const decoded = this.decodeRaw(raw) as { at?: unknown } | null;
+        const at =
+          decoded && typeof decoded.at === "number" ? decoded.at : null;
+        if (at !== null && at >= sinceMs) return true;
+      }
+      return false;
+    } catch (error) {
+      reportCacheError(
+        error,
+        "cache-read",
+        "[VercelCacheStore] tag invalidation check",
+      );
+      return false;
+    }
+  }
+
   async invalidateTags(tags: string[]): Promise<void> {
     if (!tags || tags.length === 0) return;
     // No per-item cap here: an invalidation must reach every requested tag.
@@ -842,6 +896,20 @@ export class VercelCacheStore<
       "cache-invalidate",
     );
     if (safe.length === 0) return;
+    // Marker writes FIRST, and strict: isTagsInvalidatedSince() is how an
+    // updateTag() reaches a build-time shell entry (expireTag cannot delete
+    // what lives in the build manifest), so a failed marker write must reject
+    // like a failed expireTag — silently resolving would report success while
+    // the baked shell keeps serving.
+    await Promise.all(
+      safe.map((tag) =>
+        this.cache.set(
+          this.toStoreKey(tag, "tm"),
+          JSON.stringify({ at: Date.now() }),
+          { ttl: TAG_MARKER_TTL_SECONDS },
+        ),
+      ),
+    );
     try {
       await this.cache.expireTag(safe);
     } catch (error) {
@@ -1095,7 +1163,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 } = raw;
+    const { p, po, rv, bv, c, s, e, t, i, sn, lh } = raw;
     if (typeof p !== "string" || typeof rv !== "string") return null;
     if (po !== null && typeof po !== "string") return null;
     if (typeof c !== "number") return null;
@@ -1111,6 +1179,7 @@ export class VercelCacheStore<
       t: Array.isArray(t) ? (t as string[]) : undefined,
       i: typeof i === "string" ? i : undefined,
       sn: Array.isArray(sn) ? (sn as ShellSnapshotRecord[]) : undefined,
+      lh: lh === true ? true : undefined,
     };
   }
 

package/src/deps/ssr.ts

@@ -1 +1,4 @@
-export { createFromReadableStream } from "@vitejs/plugin-rsc/ssr";
+export {
+  createFromReadableStream,
+  setOnClientReference,
+} from "@vitejs/plugin-rsc/ssr";

package/src/index.rsc.ts

@@ -88,6 +88,12 @@ export type {
   OriginCheckPhase,
 } from "./rsc/origin-guard.js";
 
+// PPR shell-capture debug sink types (RangoOptions.debugShellCapture)
+export type {
+  ShellCaptureDebug,
+  ShellCaptureDebugEvent,
+} from "./rsc/shell-capture.js";
+
 // Server-side createLoader and redirect
 export {
   createLoader,
@@ -317,4 +323,5 @@ export type {
   RouterTimeouts,
   TimeoutPhase,
   TimeoutContext,
+  RenderTimeoutContext,
 } from "./router/timeout.js";

package/src/index.ts

@@ -398,4 +398,5 @@ export type {
   RouterTimeouts,
   TimeoutPhase,
   TimeoutContext,
+  RenderTimeoutContext,
 } from "./router/timeout.js";

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

@@ -0,0 +1,447 @@
+/**
+ * Producer B: build-time PPR shell capture for Prerender+ppr routes (#699).
+ *
+ * Runs in the RSC realm of the build's temp server, AFTER all bundles are
+ * written (the prelude embeds built client asset URLs — bootstrap module,
+ * chunk preloads — that only exist post-client-build). The capture core is
+ * producer A's, verbatim: deriveShellCaptureContext (mask funnel, liveness,
+ * snapshot recording, implicit doc-cache scope) + captureAndStoreShell (gates,
+ * quiesce, tags union, putShell barrier). Build capture first replays global
+ * and route middleware with a synthetic build request context
+ * (`ctx.build === true`, inert `ctx.waitUntil()`); middleware can seed vars or
+ * call `ctx.dynamic()` to skip this URL. The sink is an entry collector instead
+ * of a runtime store.
+ *
+ * The capture's match() re-enters withCacheLookup, HITs the in-realm prerender
+ * store seeded from the just-collected Flight payloads, and REPLAYS the
+ * build-time segments — no handler execution, exactly the runtime composition
+ * path (#697). Live-lane loaders mask into holes; bake-lane loaders execute
+ * under the build context and refuse the capture if they reject or read
+ * identity, the same eligibility rules as at runtime.
+ */
+
+import type { ShellCacheEntry } from "../cache/types.js";
+import { MemorySegmentCacheStore } from "../cache/memory-segment-store.js";
+import {
+  createRequestContext,
+  runWithRequestContext,
+  setRequestContextParams,
+  type RequestContext,
+} from "../server/request-context.js";
+import {
+  deriveShellCaptureContext,
+  captureAndStoreShell,
+  delay,
+  SHELL_CAPTURE_RETRY_DELAY_MS,
+  type ShellCaptureDescriptor,
+} from "../rsc/shell-capture.js";
+import { buildFullPayload } from "../rsc/full-payload.js";
+import { buildRouteMiddlewareEntries } from "../rsc/helpers.js";
+import type { RscPayload, SSRModule } from "../rsc/types.js";
+import type { HandlerContext } from "../rsc/handler-context.js";
+import { renderToReadableStream } from "../deps/rsc.js";
+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 {
+  resolvePprConfig,
+  type ResolvedPprConfig,
+} from "../rsc/shell-serve.js";
+
+/**
+ * Normalize a collected truthy `ppr` path option into the SAME concrete
+ * policy the runtime serve path derives — through resolvePprConfig itself,
+ * over a synthetic route entry — so the build-stamped ttl default can never
+ * drift from the serve-side one.
+ */
+export function resolveBuildPprConfig(
+  ppr:
+    | true
+    | { ttl?: number; swr?: number; tags?: string[]; captureTimeout?: number },
+): ResolvedPprConfig {
+  const resolved = resolvePprConfig({ type: "route", ppr } as any);
+  // resolvePprConfig returns null only for undefined/false ppr; the collector
+  // filtered those out. Guard for the type only.
+  if (!resolved) throw new Error("[rango] unreachable: ppr option was falsy");
+  return resolved;
+}
+
+export interface BuildShellCaptureOptions {
+  /** The router instance (from RouterRegistry in the same realm). */
+  router: any;
+  /** Concrete URL path to capture (e.g. "/pp/alpha"). */
+  urlPath: string;
+  /**
+   * The candidate's trie route key. The capture's match() must land on THIS
+   * route: the phase sweeps every registered router, and a router that does
+   * not own the URL matches something else (its catch-all, a 404 shape) —
+   * that capture must not be baked.
+   */
+  routeName: string;
+  /** Shell store key to stamp into the descriptor (host-free at build). */
+  key: string;
+  ttl?: number;
+  swr?: number;
+  /** The route's static ppr.tags (the capture unions render-recorded tags). */
+  tags?: string[];
+  /**
+   * The route's resolved snapshot size cap (ResolvedPprConfig.maxSnapshotBytes)
+   * — build captures apply the same over-cap skip as runtime captures, so a
+   * raised per-route cap behaves identically across both producers.
+   */
+  maxSnapshotBytes?: number;
+  /**
+   * The route's `ppr.captureTimeout` (ms) — producer B honors the same settle
+   * budget as the runtime capture. Build has no waitUntil lifetime bound, so
+   * the option is the only ceiling here.
+   */
+  captureTimeout?: number;
+  /** Build-time env bindings (rango plugin buildEnv), if configured. */
+  buildEnv?: unknown;
+  /**
+   * The MAIN build's version (the version plugin's value folded into the
+   * shipped worker) — NOT the temp server's own version-plugin value. The
+   * serve-side isValidShellHit gate compares entry.buildVersion against the
+   * running worker's ctx.version; stamping the temp server's would make every
+   * build entry an eternal MISS.
+   */
+  buildVersion: string;
+  /**
+   * The SSR half, composed by the plugin from the temp server's SSR
+   * environment runner (react-dom/static prerender + Flight client), with the
+   * bootstrap script content overridden to the BUILT client entry URL.
+   */
+  captureShellHTML: NonNullable<SSRModule["captureShellHTML"]>;
+  /** Verbose per-attempt breadcrumbs (build log). */
+  debug?: boolean;
+}
+
+export interface BuildShellCaptureResult {
+  outcome:
+    | "stored"
+    | "no-shell"
+    | "redirect"
+    | "refused"
+    /** Middleware/handler opted this URL out of PPR shell capture. */
+    | "dynamic"
+    /** The router swept does not own this URL — try the next one. */
+    | "route-mismatch";
+  /** Present iff outcome === "stored". */
+  entry?: ShellCacheEntry;
+  /** The putShell-barrier tag union (static ppr.tags + render-recorded). */
+  tags?: string[];
+  /** On route-mismatch: what this router's match actually landed on. */
+  matchedRouteName?: string;
+}
+
+/**
+ * Capture the PPR shell for one prerendered URL at build time. Retries once
+ * in place on `no-shell` (the first attempt warms the temp server's SSR/Flight
+ * transform graph, mirroring producer A's cold-start retry — same delay).
+ */
+export async function captureShellForBuild(
+  opts: BuildShellCaptureOptions,
+): Promise<BuildShellCaptureResult> {
+  const first = await attemptBuildCapture(opts);
+  if (first.outcome !== "no-shell") return first;
+  if (opts.debug) {
+    console.log(
+      `[rango] shell capture attempt 1/2 for ${opts.urlPath} produced no shell (cold graph?) — retrying`,
+    );
+  }
+  await delay(SHELL_CAPTURE_RETRY_DELAY_MS);
+  return attemptBuildCapture(opts);
+}
+
+/** One attempt: fresh base context, fresh derivation, fresh render. */
+async function attemptBuildCapture(
+  opts: BuildShellCaptureOptions,
+): Promise<BuildShellCaptureResult> {
+  const router = opts.router;
+  const url = new URL(opts.urlPath, "http://build.invalid");
+  const request = new Request(url, { method: "GET" });
+  const env = (opts.buildEnv ?? {}) as any;
+  const variables: Record<string, any> = {};
+
+  // Synthetic build request context: same factory the runtime handler uses,
+  // so the capture's ALS surface (cookie machinery, variables, waitUntil,
+  // theme resolution) is production-shaped. No cookie header → theme resolves
+  // to the app default, exactly like a first anonymous visitor's capture.
+  const baseCtx = createRequestContext({
+    env,
+    request,
+    url,
+    variables,
+    build: true,
+    // Fresh empty store per attempt: cache()/"use cache" reads MISS, execute,
+    // and are recorded into the snapshot by the derivation's RecordingShell
+    // wrapper — the entry pins its own generation, nothing preexisting leaks.
+    cacheStore: new MemorySegmentCacheStore(),
+    themeConfig: router.themeConfig ?? null,
+    stateCookieName: router.resolvedStateCookieName,
+    version: opts.buildVersion,
+  });
+
+  // Entry collector: captureAndStoreShell's sink. putShell never fails here,
+  // so a "stored" outcome always carries the entry.
+  let collected: { entry: ShellCacheEntry; tags?: string[] } | null = null;
+  const collector = {
+    putShell: async (
+      _key: string,
+      entry: ShellCacheEntry,
+      _ttl?: number,
+      _swr?: number,
+      tags?: string[],
+    ): Promise<void> => {
+      collected = { entry, tags };
+    },
+  };
+
+  const descriptor: ShellCaptureDescriptor = {
+    key: opts.key,
+    buildVersion: opts.buildVersion,
+    ttl: opts.ttl,
+    swr: opts.swr,
+    tags: opts.tags,
+    captureTimeout: opts.captureTimeout,
+    store: collector as any,
+    debug: opts.debug,
+    maxSnapshotBytes: opts.maxSnapshotBytes,
+  };
+
+  let mismatchedRouteName: string | undefined;
+  const result = await runWithRequestContext(baseCtx, async () => {
+    const preview =
+      typeof router.previewMatch === "function"
+        ? await router.previewMatch(request, { env })
+        : undefined;
+    // These preview-based mismatches exit before any middleware/envelope runs,
+    // so nothing consumes a response — only result.outcome is read below.
+    if (preview === null) {
+      return { outcome: "route-mismatch" } as const;
+    }
+    if (preview?.routeKey && preview.routeKey !== opts.routeName) {
+      mismatchedRouteName = preview.routeKey;
+      return { outcome: "route-mismatch" } as const;
+    }
+
+    if (preview?.routeKey) {
+      setRequestContextParams(preview.params ?? {}, preview.routeKey);
+    }
+
+    const routeReverse = createReverseFunction(
+      getGlobalRouteMap(),
+      preview?.routeKey,
+      preview?.params ?? {},
+    );
+
+    const runCapture = () =>
+      runBuildCaptureFinal({
+        baseCtx,
+        descriptor,
+        env,
+        opts,
+        request,
+        router,
+        url,
+        setMismatchedRouteName: (routeName) => {
+          mismatchedRouteName = routeName;
+        },
+      });
+
+    const routeMiddleware =
+      preview?.routeMiddleware && preview.routeMiddleware.length > 0
+        ? buildRouteMiddlewareEntries(preview.routeMiddleware)
+        : [];
+    const runRouteMiddleware = () =>
+      runBuildMiddlewareEnvelope(
+        routeMiddleware,
+        request,
+        env,
+        variables,
+        runCapture,
+        routeReverse,
+        baseCtx,
+      );
+
+    const globalMiddleware = Array.isArray(router.middleware)
+      ? matchMiddleware(url.pathname, router.middleware)
+      : [];
+    return runBuildMiddlewareEnvelope(
+      globalMiddleware,
+      request,
+      env,
+      variables,
+      runRouteMiddleware,
+      routeReverse,
+      baseCtx,
+    );
+  });
+
+  const outcome = result.outcome;
+  if (outcome === "stored" && collected !== null) {
+    const hit: { entry: ShellCacheEntry; tags?: string[] } = collected;
+    return { outcome, entry: hit.entry, tags: hit.tags };
+  }
+  if (outcome === "route-mismatch") {
+    return { outcome, matchedRouteName: mismatchedRouteName };
+  }
+  return { outcome };
+}
+
+type BuildShellCaptureOutcome = BuildShellCaptureResult["outcome"];
+
+interface BuildCaptureRunResult {
+  outcome: BuildShellCaptureOutcome;
+  response: Response;
+}
+
+interface BuildCaptureFinalOptions {
+  baseCtx: RequestContext<any>;
+  descriptor: ShellCaptureDescriptor;
+  env: any;
+  opts: BuildShellCaptureOptions;
+  request: Request;
+  router: any;
+  url: URL;
+  setMismatchedRouteName(routeName: string | undefined): void;
+}
+
+async function runBuildMiddlewareEnvelope<TEnv>(
+  middlewares: Array<{
+    entry: MiddlewareEntry<TEnv>;
+    params: Record<string, string>;
+  }>,
+  request: Request,
+  env: TEnv,
+  variables: Record<string, any>,
+  finalHandler: () => Promise<BuildCaptureRunResult>,
+  reverse: (
+    name: string,
+    params?: Record<string, string>,
+    search?: Record<string, unknown>,
+  ) => string,
+  baseCtx: RequestContext<any>,
+): Promise<BuildCaptureRunResult> {
+  let downstream: BuildCaptureRunResult | undefined;
+  const response = await executeMiddleware(
+    middlewares,
+    request,
+    env,
+    variables,
+    async () => {
+      downstream = baseCtx._dynamic
+        ? {
+            outcome: "dynamic",
+            response: responseForBuildCaptureOutcome("dynamic"),
+          }
+        : await finalHandler();
+      return downstream.response;
+    },
+    reverse,
+  );
+
+  if (baseCtx._dynamic) {
+    return { outcome: "dynamic", response };
+  }
+  if (response.status >= 300 && response.status < 400) {
+    return { outcome: "redirect", response };
+  }
+  return (
+    downstream ?? {
+      outcome: "no-shell",
+      response,
+    }
+  );
+}
+
+async function runBuildCaptureFinal(
+  options: BuildCaptureFinalOptions,
+): Promise<BuildCaptureRunResult> {
+  const { baseCtx, descriptor, env, opts, request, router, url } = options;
+  // No baseCtx._dynamic recheck here: the only caller is the route envelope's
+  // finalHandler wrapper, which already short-circuits to "dynamic" without
+  // invoking this when baseCtx._dynamic is set. A loader/handler opting out
+  // DURING the capture render is caught by the derivedCtx._dynamic check below.
+
+  const { derivedCtx, freshHandleStore } = deriveShellCaptureContext(baseCtx, {
+    ttl: opts.ttl,
+    swr: opts.swr,
+  });
+
+  const outcome = await runWithRequestContext(derivedCtx, async () => {
+    let match;
+    try {
+      match = await router.match(request, { env });
+    } catch (error) {
+      if (isPlainPathMiss(error, opts.urlPath)) {
+        return "route-mismatch" as const;
+      }
+      throw error;
+    }
+    if (match.routeName !== opts.routeName) {
+      options.setMismatchedRouteName(match.routeName);
+      return "route-mismatch" as const;
+    }
+    if (match.redirect) return "redirect" as const;
+
+    setRequestContextParams(match.params, match.routeName);
+
+    const payload = buildFullPayload(
+      match,
+      // buildFullPayload reads only ctx.router.* and ctx.version.
+      { router, version: opts.buildVersion } as unknown as HandlerContext<any>,
+      url,
+      derivedCtx,
+      freshHandleStore,
+    );
+    const rscStream = renderToReadableStream<RscPayload>(payload, {
+      onError: (error: unknown) => {
+        if (opts.debug) {
+          console.warn(
+            `[rango] shell capture render error for ${opts.urlPath}:`,
+            error,
+          );
+        }
+      },
+    });
+
+    const captureOutcome = await captureAndStoreShell(
+      { captureShellHTML: opts.captureShellHTML } as SSRModule,
+      rscStream,
+      freshHandleStore,
+      derivedCtx,
+      descriptor,
+    );
+    return derivedCtx._dynamic ? "dynamic" : captureOutcome;
+  });
+
+  return {
+    outcome,
+    response: responseForBuildCaptureOutcome(outcome),
+  };
+}
+
+function responseForBuildCaptureOutcome(
+  outcome: BuildShellCaptureOutcome,
+): Response {
+  if (outcome === "redirect") {
+    return new Response(null, {
+      status: 302,
+      headers: { location: "http://build.invalid/" },
+    });
+  }
+  return new Response(null, { status: 204 });
+}
+
+function isPlainPathMiss(error: unknown, pathname: string): boolean {
+  if (!isRouteNotFoundError(error)) return false;
+  const cause = (error as { cause?: unknown }).cause;
+  return (
+    cause !== null &&
+    typeof cause === "object" &&
+    (cause as { pathname?: unknown }).pathname === pathname
+  );
+}

package/src/prerender/shell-manifest-key.ts

@@ -0,0 +1,20 @@
+/**
+ * Build shell manifest key, shared by the producer (the build's shell
+ * prerender phase, vite/discovery/shell-prerender-phase.ts) and the consumer
+ * (the runtime read-through, rsc/shell-build-manifest.ts) so the format
+ * cannot drift. Dependency-free: the producer runs node-side in the plugin,
+ * the consumer in the RSC runtime.
+ *
+ * PATHNAME-ONLY by design. Host-free because the build knows no request
+ * host. Router-free because the router id ($$id) is a hash of
+ * filePath:lineNumber of the TRANSFORMED source, which differs between the
+ * discovery temp server's dev-style transform chain and the main build's —
+ * a temp-realm router id can never be looked up by the shipped worker. The
+ * producer instead detects pathname collisions across routers at build time
+ * and declines both entries (loudly), keeping the key unambiguous. This is
+ * a manifest namespace, never a store keyspace: the runtime shell key
+ * (host + pathname + search + ":shell") stays untouched.
+ */
+export function buildShellManifestKey(pathname: string): string {
+  return pathname;
+}

package/src/prerender/store.ts

@@ -73,7 +73,16 @@ export function createDevPrerenderStore(devUrl: string): PrerenderStore {
       if (isIntercept) url += "&intercept=1";
       if (meta.isPassthroughRoute) url += "&passthrough=1";
       try {
-        const res = await fetch(url);
+        // Bounded: this fetch also runs inside the PPR shell capture (a
+        // workerd waitUntil task), where an unsettled fetch does not reject —
+        // it pends until the task is torn down. Unbounded, one pending fetch
+        // wedged the per-isolate capture queue on GH runners (rotating dev
+        // capture failures; endpoint instrumentation showed 3-4ms memo HITs,
+        // so latency was never the issue — settlement was). On timeout the
+        // catch degrades to a store miss and the pipeline falls through to
+        // the live handler render (the documented dev fall-through), so the
+        // capture still lands with live content.
+        const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
         if (!res.ok) return null;
         return res.json();
       } catch {

package/src/prerender.ts

@@ -540,7 +540,7 @@ export interface PassthroughHandlerDefinition<
   /** Live handler for runtime fallback on unknown params. */
   liveHandler: (
     ctx: HandlerContext<TParams, TEnv>,
-  ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>;
+  ) => ReactNode | Response | Promise<ReactNode | Response>;
   /** Composable default DSL items merged when the handler is mounted. */
   use?: () => UseItems<HandlerUseItem>;
 }
@@ -552,7 +552,7 @@ export function Passthrough<
   prerenderDef: PrerenderHandlerDefinition<TParams>,
   liveHandler: (
     ctx: HandlerContext<TParams, TEnv>,
-  ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>,
+  ) => ReactNode | Response | Promise<ReactNode | Response>,
 ): PassthroughHandlerDefinition<TParams, TEnv>;
 
 // Implementation
@@ -563,7 +563,7 @@ export function Passthrough<
   prerenderDef: PrerenderHandlerDefinition<TParams>,
   liveHandler: (
     ctx: HandlerContext<TParams, TEnv>,
-  ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>,
+  ) => ReactNode | Response | Promise<ReactNode | Response>,
 ): PassthroughHandlerDefinition<TParams, TEnv> {
   if (!isPrerenderHandler(prerenderDef)) {
     throw new Error(