@rangojs/router 0.0.0-experimental.136 → 0.0.0-experimental.138

package/src/handles/MetaTags.tsx

@@ -3,8 +3,9 @@
 /**
  * Component to render collected meta descriptors in the document head.
  *
- * Supports both sync and async meta descriptors. Async descriptors
- * (Promise<MetaDescriptorBase>) are resolved using React's use() hook.
+ * Deferred (Promise) meta descriptors are resolved before MetaTags renders
+ * (server-side on the full render, client-side before apply on navigation), so
+ * it only ever receives resolved descriptors and never suspends.
  *
  * When theme is enabled in the router config, MetaTags also renders
  * the theme initialization script to prevent FOUC (flash of unstyled content).
@@ -28,11 +29,9 @@
  * ```
  */
 
-import { use } from "react";
 import { useHandle } from "../browser/react/use-handle.js";
 import { Meta } from "./meta.js";
-import { isThenable } from "./is-thenable.js";
-import type { MetaDescriptor, MetaDescriptorBase } from "../router/types.js";
+import type { MetaDescriptorBase } from "../router/types.js";
 import { useThemeContext } from "../theme/theme-context.js";
 import { generateThemeScript } from "../theme/theme-script.js";
 import { useNonce } from "../browser/react/nonce-context.js";
@@ -96,17 +95,7 @@ function hasTagName(
   );
 }
 
-/**
- * Check if a value is a Promise. Uses the shared thenable predicate (callable
- * `then`) so collect (meta.ts) and render never disagree: an object carrying a
- * non-callable `then` (e.g. `{ then: 5 }`) is a SYNC descriptor on both sides,
- * not a Promise that would crash React's `use()`.
- */
-function isPromise(value: unknown): value is Promise<unknown> {
-  return isThenable(value);
-}
-
-function renderMetaDescriptor(
+export function renderMetaDescriptor(
   descriptor: MetaDescriptorBase,
   index: number,
 ): React.ReactNode {
@@ -189,57 +178,6 @@ function renderMetaDescriptor(
   );
 }
 
-// Sentinel a rejected async descriptor resolves to: renderMetaDescriptor sees
-// no recognized fields and returns nothing renderable (see renderRejected).
-const REJECTED_META: unique symbol = Symbol("rango.rejectedMeta");
-
-// Cache the rejection-swallowing wrapper per source promise so use() gets a
-// stable reference across re-renders (a fresh .then() each render would make
-// React treat it as a new pending promise and never settle). WeakMap keys on
-// the original promise so entries are collected with it.
-const safeMetaPromises = new WeakMap<
-  Promise<MetaDescriptorBase>,
-  Promise<MetaDescriptorBase | typeof REJECTED_META>
->();
-
-function toSafeMetaPromise(
-  promise: Promise<MetaDescriptorBase>,
-): Promise<MetaDescriptorBase | typeof REJECTED_META> {
-  let safe = safeMetaPromises.get(promise);
-  if (!safe) {
-    // Swallow the rejection at the promise boundary, not via an error boundary:
-    // an error boundary above a suspended use() makes React abandon the whole
-    // Suspense subtree (and on the server switch it to client rendering). A
-    // settled-to-sentinel promise degrades the single bad descriptor to nothing
-    // while every sibling descriptor still renders.
-    //
-    // Normalize via Promise.resolve first: a collected async descriptor may be a
-    // non-native thenable (a React wakeable in SSR/RSC) whose .then() returns
-    // void rather than a Promise. Calling .then directly would leave `safe`
-    // undefined and use(undefined) would throw ("unsupported type passed to
-    // use()"), 500-ing the page. Promise.resolve adopts the thenable into a
-    // native Promise whose .then always returns one.
-    safe = Promise.resolve(promise).then(
-      (value) => value,
-      () => REJECTED_META,
-    );
-    safeMetaPromises.set(promise, safe);
-  }
-  return safe;
-}
-
-export function AsyncMetaTag({
-  promise,
-  index,
-}: {
-  promise: Promise<MetaDescriptorBase>;
-  index: number;
-}): React.ReactNode {
-  const resolved = use(toSafeMetaPromise(promise));
-  if (resolved === REJECTED_META) return null;
-  return renderMetaDescriptor(resolved, index);
-}
-
 /**
  * Renders all collected meta descriptors from route handlers.
  *
@@ -249,11 +187,16 @@ export function AsyncMetaTag({
  * When theme is enabled in router config, also renders the theme initialization
  * script to prevent FOUC (flash of unstyled content).
  *
- * Async meta descriptors (Promise<MetaDescriptorBase>) are resolved using
- * React's use() hook. RSC streaming handles the Promise resolution.
+ * Deferred (Promise) meta descriptors are resolved BEFORE MetaTags renders —
+ * server-side on the full/SSR render, client-side before apply on navigation
+ * (resolve-by-default) — so MetaTags only ever receives resolved descriptors and
+ * never suspends.
  */
 export function MetaTags(): React.ReactNode {
-  const descriptors = useHandle(Meta) as MetaDescriptor[];
+  // Deferred descriptors are resolved BEFORE collect runs (resolve-by-default),
+  // and collectMeta strips unset markers, so the collected output is always
+  // resolved base descriptors (never a Promise).
+  const descriptors = useHandle(Meta) as MetaDescriptorBase[];
   const themeConfig = useThemeContext()?.config ?? null;
   const nonce = useNonce();
 
@@ -266,24 +209,9 @@ export function MetaTags(): React.ReactNode {
           dangerouslySetInnerHTML={{ __html: generateThemeScript(themeConfig) }}
         />
       )}
-      {descriptors.map((descriptor, index) => {
-        // A descriptor is only a Promise on the SSR/hydration path, where it is
-        // use()d to stream the tag into the document. On client navigation the
-        // store resolves deferred handle values before applying them (see
-        // processHandles), so MetaTags only ever receives resolved descriptors
-        // there and never suspends — which would otherwise revert the committed
-        // route (MetaTags lives in <head>, above the route's <Suspense>).
-        if (isPromise(descriptor)) {
-          return (
-            <AsyncMetaTag
-              key={`async-${index}`}
-              promise={descriptor}
-              index={index}
-            />
-          );
-        }
-        return renderMetaDescriptor(descriptor, index);
-      })}
+      {descriptors.map((descriptor, index) =>
+        renderMetaDescriptor(descriptor, index),
+      )}
     </>
   );
 }

package/src/handles/breadcrumbs.ts

@@ -23,7 +23,6 @@
 
 import type { ReactNode } from "react";
 import { createHandle, type Handle } from "../handle.js";
-import { isThenable } from "./is-thenable.js";
 
 /**
  * A single breadcrumb item.
@@ -42,34 +41,33 @@ export interface BreadcrumbItem {
  * Collect function for Breadcrumbs handle.
  * Flattens segments in parent-to-child order with deduplication by href: each
  * href keeps its FIRST position but takes the LAST value (re-pushing a parent
- * href refreshes the label in place without reordering the trail).
- * Deferred slots (`ctx.use(Breadcrumbs).defer()`)
- * arrive as pending Promise entries with no href yet; they are passed through by
- * identity and excluded from the href dedup so concurrent deferred crumbs do not
- * all collapse under a single `undefined` href.
+ * href refreshes the label in place without reordering the trail). Deferred
+ * crumbs (a pushed Promise or `ctx.use(Breadcrumbs).defer()`) are resolved
+ * BEFORE collect runs (resolve-by-default), so collect only ever sees resolved
+ * items. An item without a string `href` is passed through by identity and
+ * excluded from the href dedup.
  */
 function collectBreadcrumbs(segments: BreadcrumbItem[][]): BreadcrumbItem[] {
   const all = segments.flat();
 
-  const isResolvedItem = (item: unknown): item is BreadcrumbItem =>
+  const hasHref = (item: unknown): item is BreadcrumbItem =>
     item != null &&
     typeof item === "object" &&
-    !isThenable(item) &&
     typeof (item as { href?: unknown }).href === "string";
 
-  // Dedup resolved crumbs by href: keep the FIRST position (preserving
-  // parent->child order) but the LAST value (a child re-pushing a parent's href
-  // can refresh its label). Deferred items bypass dedup entirely (they have no
-  // href yet) and are passed through by identity at their original position.
+  // Dedup crumbs by href: keep the FIRST position (preserving parent->child
+  // order) but the LAST value (a child re-pushing a parent's href can refresh
+  // its label). Items without an href pass through by identity at their original
+  // position.
   const valueByHref = new Map<string, BreadcrumbItem>();
   for (const item of all) {
-    if (isResolvedItem(item)) valueByHref.set(item.href, item);
+    if (hasHref(item)) valueByHref.set(item.href, item);
   }
 
   const result: BreadcrumbItem[] = [];
   const emitted = new Set<string>();
   for (const item of all) {
-    if (!isResolvedItem(item)) {
+    if (!hasHref(item)) {
       result.push(item);
       continue;
     }

package/src/handles/deferred-resolution.ts

@@ -0,0 +1,127 @@
+import type { HandleData, HandleStore } from "../server/handle-store.js";
+import { isThenable } from "./is-thenable.js";
+
+/**
+ * Runtime-neutral resolution of deferred (Promise) handle values. Shared by the
+ * server full-render path (resolve before the payload is finalized so SSR sees
+ * resolved values) and the client soft-nav path (NavigationProvider resolves
+ * each yield before applying it). Pure — imports only `isThenable` — so it is
+ * safe in both the RSC server environment AND the browser.
+ *
+ * Resolution is SHALLOW: only an entry that is ITSELF a thenable is awaited. A
+ * value that merely contains a promise (e.g. `{ data: somePromise }`) is a
+ * non-thenable, so the `isThenable` check skips it and it passes through verbatim
+ * — the nested promise is the consumer's responsibility. Resolution runs each
+ * entry through `Promise.all` with a per-entry `try/catch` (NOT `allSettled`), so
+ * one rejecting entry is dropped without rejecting the batch or aborting siblings.
+ */
+
+/**
+ * Handle names ($$id) whose snapshot carries a deferred (top-level Promise)
+ * value. Used by the client to decide which buckets to hold-and-resolve, and
+ * `.size > 0` answers "does this snapshot have any deferred value".
+ */
+export function deferredHandleNames(data: HandleData): Set<string> {
+  const names = new Set<string>();
+  for (const [handleName, segments] of Object.entries(data)) {
+    for (const values of Object.values(segments)) {
+      if (values.some(isThenable)) {
+        names.add(handleName);
+        break;
+      }
+    }
+  }
+  return names;
+}
+
+/**
+ * Snapshot with deferred (Promise) values awaited (shallow — only top-level
+ * thenables). A rejected deferred is dropped, and a deferred that resolves to
+ * `null`/`undefined` is dropped (the `.defer({ else })` skip semantics), so a
+ * nullish deferred slot never reaches a collector. Sync (non-thenable) values —
+ * including a legitimate sync `null` push — pass through unchanged.
+ */
+export async function resolveDeferredHandleValues(
+  data: HandleData,
+): Promise<HandleData> {
+  const out: HandleData = {};
+  await Promise.all(
+    Object.entries(data).flatMap(([handleName, segments]) => {
+      out[handleName] = {};
+      return Object.entries(segments).map(async ([segmentId, values]) => {
+        out[handleName][segmentId] = await resolveValues(values);
+      });
+    }),
+  );
+  return out;
+}
+
+// Resolve each entry IN ORDER. A non-thenable passes through verbatim (including
+// a legitimate sync `null`/`undefined` push — the "await iff thenable" contract).
+// A thenable is awaited and dropped when it rejects OR resolves to null/undefined
+// (the `.defer({ else })` skip semantics: a forgotten resolver times out to
+// `else ?? undefined`), so a nullish deferred slot never reaches a collector.
+async function resolveValues(values: unknown[]): Promise<unknown[]> {
+  const resolved = await Promise.all(
+    values.map(async (v) => {
+      if (!isThenable(v)) return { keep: true, value: v };
+      try {
+        const value = await v;
+        return { keep: value != null, value };
+      } catch {
+        return { keep: false, value: undefined };
+      }
+    }),
+  );
+  return resolved.filter((r) => r.keep).map((r) => r.value);
+}
+
+/**
+ * Full-render handle stream: a one-shot async generator that yields the FINAL
+ * handle snapshot with every top-level deferred value resolved. Drop-in for
+ * `handleStore.stream()` on full / HTML renders (initial load, 404, progressive
+ * enhancement), where the consumer drains the generator to completion before
+ * rendering anyway — so the single final yield is equivalent to the streamed
+ * yields' converged state, and the SSR markup plus the first sync `useHandle`
+ * read see resolved values. `getData()` seals the store and awaits the handler
+ * barrier; `resolveDeferredHandleValues` then awaits the pushed-value promises.
+ * A hung handle promise blocks the full render like any unresolved await (no
+ * handle-specific timeout). Partial / action payloads keep streaming via
+ * `handleStore.stream()`.
+ */
+export async function* resolvedHandleStream(
+  handleStore: HandleStore,
+): AsyncGenerator<HandleData, void, unknown> {
+  // Drain stream() (NOT getData()) for the converged snapshot: stream() sets the
+  // store's `completed` flag on seal+settle, and that flag is what makes a LATE
+  // push throw LateHandlePushError — an async JSX subtree that suspended and later
+  // calls ctx.use(Handle)(...) after collection. getData() never sets `completed`,
+  // so the late push would silently land. Both wait for the same settle barrier, so
+  // the final yielded value is identical; we just keep the late-push guard.
+  let snapshot: HandleData = {};
+  for await (const data of handleStore.stream()) {
+    snapshot = data;
+  }
+  yield await resolveDeferredHandleValues(snapshot);
+}
+
+/**
+ * Resolve the deferred (Promise) values in ONE segment's handle bucket
+ * (`handleName -> entries[]`). Same shallow + drop-rejections rule as
+ * {@link resolveDeferredHandleValues}, but for the segment-keyed shape the
+ * prerender/static collection paths use (`getDataForSegment`). Prerender is a
+ * build-time cache, so the baked artifact must hold resolved values — a hit
+ * replays them into the segment system, where collect/useHandle expect resolved
+ * data.
+ */
+export async function resolveSegmentHandleValues(
+  segHandles: Record<string, unknown[]>,
+): Promise<Record<string, unknown[]>> {
+  const out: Record<string, unknown[]> = {};
+  await Promise.all(
+    Object.entries(segHandles).map(async ([handleName, values]) => {
+      out[handleName] = await resolveValues(values);
+    }),
+  );
+  return out;
+}

package/src/handles/is-thenable.ts

@@ -1,14 +1,13 @@
 /**
- * Single thenable predicate shared by the built-in handles that distinguish a
- * synchronous descriptor/item from a deferred `Promise` one (Meta collect, the
- * MetaTags render side, and Breadcrumbs).
+ * Single thenable predicate for the resolve-by-default handle machinery
+ * (`handles/deferred-resolution.ts`, its sole owner) — it decides which top-level
+ * handle entries are deferred (`Promise`) values to await before any consumer
+ * sees them, and which pass through verbatim.
  *
  * Requires a CALLABLE `then` (`typeof obj.then === "function"`), not merely a
- * `"then" in obj` membership check. The two had drifted: a descriptor carrying a
- * non-callable `then` (e.g. a serialized shape `{ then: 5 }`) was classified as
- * synchronous by collect but as a Promise by render — so render would call
- * React's `use()` on a non-thenable and throw. One owner keeps the collect and
- * render sides from ever disagreeing.
+ * `"then" in obj` membership check, so a non-promise carrying a `then` field
+ * (e.g. a serialized shape `{ then: 5 }`) is treated as a plain sync value rather
+ * than awaited. A single predicate keeps that classification consistent.
  */
 export function isThenable(value: unknown): value is PromiseLike<unknown> {
   return (

package/src/handles/meta.ts

@@ -29,7 +29,6 @@
  */
 
 import { createHandle, type Handle } from "../handle.js";
-import { isThenable } from "./is-thenable.js";
 import type {
   MetaDescriptor,
   MetaDescriptorBase,
@@ -37,12 +36,6 @@ import type {
   UnsetDescriptor,
 } from "../router/types.js";
 
-function isPromiseDescriptor(
-  descriptor: MetaDescriptor,
-): descriptor is Promise<MetaDescriptorBase> {
-  return isThenable(descriptor);
-}
-
 function isUnsetDescriptor(
   descriptor: MetaDescriptor,
 ): descriptor is UnsetDescriptor {
@@ -166,37 +159,9 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
 
   for (const descriptors of segments) {
     for (const descriptor of descriptors) {
-      // Promise descriptors cannot be inspected synchronously (their content is
-      // unknown until resolved in <MetaTags> via React's use()), so they bypass
-      // key-based dedup and title-templating: they are appended verbatim. Warn in
-      // dev when a title template is active so the author knows an async
-      // descriptor will NOT participate in the template/dedup.
-      //
-      // The warning is deliberately a GENERAL note, not a duplicate-<title>
-      // prediction: collectMeta cannot tell whether this Promise resolves to a
-      // title (which would indeed yield a 2nd <title>) or to an ordinary
-      // descriptor like an async og:image (which would not). Asserting a
-      // duplicate <title> here is a false positive for the common og:image case,
-      // so the message states only that async descriptors bypass templating —
-      // not that a duplicate <title> WILL occur.
-      if (isPromiseDescriptor(descriptor)) {
-        if (
-          titleTemplate !== undefined &&
-          process.env.NODE_ENV !== "production"
-        ) {
-          console.warn(
-            `[Meta] A Promise meta descriptor was pushed while a title template is active. ` +
-              `Async descriptors bypass deduplication and title-templating: the template is ` +
-              `not applied to them. If this Promise resolves to a title, resolve the value ` +
-              `before pushing (or push a synchronous descriptor) so it participates in the ` +
-              `template; if it resolves to a non-title descriptor (e.g. og:image), this ` +
-              `note does not apply.`,
-          );
-        }
-        result.push(descriptor);
-        continue;
-      }
-
+      // Deferred (Promise) descriptors are resolved BEFORE collectMeta runs
+      // (resolve-by-default), so every descriptor here is synchronous and
+      // participates in key-based dedup + title-templating like any other.
       if (isUnsetDescriptor(descriptor)) {
         const keyToRemove = descriptor.unset;
         if (keyToIndex.has(keyToRemove)) {
@@ -262,12 +227,10 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
  * Use `ctx.use(Meta)` in route handlers to push meta descriptors.
  * Use `<MetaTags />` component to render them in the document head.
  *
- * Deduplication and title-templating apply only to SYNCHRONOUS descriptors.
- * A Promise descriptor (`Promise<MetaDescriptorBase>`) is appended verbatim —
- * its content is not known until it resolves in `<MetaTags>`, so it cannot be
- * keyed for dedup nor receive a parent title template. If you need a child title
- * to participate in a layout's `%s` template, push the resolved string title
- * synchronously rather than a `Promise<{ title }>`.
+ * Deferred (Promise) descriptors are resolved before collectMeta runs
+ * (resolve-by-default), so they participate in deduplication and `%s`
+ * title-templating identically to synchronous descriptors. A descriptor that
+ * resolves to `null`/`undefined` (or rejects) is dropped.
  */
 export const Meta: Handle<MetaDescriptor, MetaDescriptor[]> = createHandle<
   MetaDescriptor,

package/src/index.rsc.ts

@@ -122,7 +122,6 @@ export { createHandle, isHandle, type Handle } from "./handle.js";
 export {
   DEFAULT_DEFER_TIMEOUT_MS,
   type DeferOptions,
-  type DeferredHandleEntry,
   type HandlePush,
   type HandlePushFn,
 } from "./defer.js";

package/src/index.ts

@@ -148,7 +148,6 @@ export { createHandle, isHandle, type Handle } from "./handle.js";
 export {
   DEFAULT_DEFER_TIMEOUT_MS,
   type DeferOptions,
-  type DeferredHandleEntry,
   type HandlePush,
   type HandlePushFn,
 } from "./defer.js";

package/src/prerender.ts

@@ -33,6 +33,7 @@ import type {
   ExtractParams,
 } from "./types.js";
 import type { Handle } from "./handle.js";
+import type { HandlePush } from "./defer.js";
 import type { ContextVar } from "./context-var.js";
 import type { ReverseFunction } from "./reverse.js";
 import type { DefaultReverseRouteMap } from "./types/global-namespace.js";
@@ -165,8 +166,14 @@ export interface BuildContext<TParams> {
     (key: string, value: any): void;
   };
 
-  /** Push handle data (frozen into pre-rendered output at build time). */
-  use: <T>(handle: Handle<T>) => (data: T) => void;
+  /**
+   * Push handle data (frozen into pre-rendered output at build time). Returns
+   * the full push function, including `.defer()` — a deferred slot resolved by
+   * a deep async component during the prerender render is awaited before the
+   * artifact is baked (resolve-by-default), so the baked output holds the
+   * resolved value.
+   */
+  use: <T>(handle: Handle<T>) => HandlePush<T>;
 
   /** Synthetic URL built from pattern + params (no real request). */
   url: URL;
@@ -222,8 +229,14 @@ export interface StaticBuildContext {
     (key: string, value: any): void;
   };
 
-  /** Push handle data (frozen into pre-rendered output at build time). */
-  use: <T>(handle: Handle<T>) => (data: T) => void;
+  /**
+   * Push handle data (frozen into pre-rendered output at build time). Returns
+   * the full push function, including `.defer()` — a deferred slot resolved by
+   * a deep async component during the prerender render is awaited before the
+   * artifact is baked (resolve-by-default), so the baked output holds the
+   * resolved value.
+   */
+  use: <T>(handle: Handle<T>) => HandlePush<T>;
 
   /** URL generation by route name. */
   reverse: BuildReverseFunction;

package/src/router/find-match.ts

@@ -20,27 +20,39 @@ function cloneMatchResult<TEnv>(
 
 export interface FindMatchDeps<TEnv = any> {
   routesEntries: RouteEntry<TEnv>[];
-  evaluateLazyEntry: (entry: RouteEntry<TEnv>) => void;
+  // Returns a Promise only when it had to resolve an async include provider
+  // (`() => import()`); void for eager/precomputed includes, so the per-entry
+  // match loop pays no microtask in the common case.
+  evaluateLazyEntry: (entry: RouteEntry<TEnv>) => void | Promise<void>;
   routerId: string;
 }
 
 /**
  * Create a findMatch function bound to router state.
  * Includes single-entry cache to avoid redundant matching within the same request.
+ *
+ * Async because a lazy include may be backed by an async provider
+ * (`() => import("./routes")`) that must be resolved before its routes can be
+ * matched. The hot path is unaffected: `await` only suspends on the first
+ * request to a not-yet-loaded dynamic include; eager routes resolve in the same
+ * microtask. Every caller already runs inside an async match pipeline.
  */
 export function createFindMatch<TEnv = any>(
   deps: FindMatchDeps<TEnv>,
-): (pathname: string, ms?: MetricsStore) => RouteMatchResult<TEnv> | null {
+): (
+  pathname: string,
+  ms?: MetricsStore,
+) => Promise<RouteMatchResult<TEnv> | null> {
   // Single-entry cache for findMatch to avoid redundant matching within the same request.
   // previewMatch and match both call findMatch with the same pathname — this ensures
   // the route matching work (which may check thousands of routes) only happens once.
   let lastFindMatchPathname: string | null = null;
   let lastFindMatchResult: RouteMatchResult<TEnv> | null = null;
 
-  return function findMatch(
+  return async function findMatch(
     pathname: string,
     ms?: MetricsStore,
-  ): RouteMatchResult<TEnv> | null {
+  ): Promise<RouteMatchResult<TEnv> | null> {
     if (lastFindMatchPathname === pathname) {
       return cloneMatchResult(lastFindMatchResult);
     }
@@ -71,11 +83,33 @@ export function createFindMatch<TEnv = any>(
         const entryStart = performance.now();
         let entry: RouteEntry<TEnv> | undefined;
         let fallbackEntry: RouteEntry<TEnv> | undefined;
+        let candidateError: unknown;
+        let candidateFailed = false;
 
         for (const e of deps.routesEntries) {
           if (e.staticPrefix !== trieResult.sp) continue;
           if (!fallbackEntry) fallbackEntry = e;
-          deps.evaluateLazyEntry(e);
+          try {
+            const ev = deps.evaluateLazyEntry(e);
+            if (ev) await ev;
+          } catch (err) {
+            // Multiple async includes can share one collapsed static prefix, so
+            // this loop may evaluate a candidate that is NOT the route's owner.
+            // Remember the failure and keep scanning: if another candidate owns
+            // the route, this sibling's failure is correctly isolated (its
+            // _lazyInflight was cleared, so a later request retries). But if NO
+            // candidate ends up owning it, the failing one WAS the owner — a
+            // real, trie-matched route whose module failed to import — and we
+            // rethrow below as a 5xx rather than silently 404ing (see finding 3:
+            // owner failure must stay loud).
+            candidateError = err;
+            candidateFailed = true;
+            console.error(
+              `[@rangojs/router] include at "${e.staticPrefix}" failed to load: ` +
+                `${(err as Error)?.message ?? String(err)}`,
+            );
+            continue;
+          }
           if (
             e.routes &&
             trieResult.routeKey in (e.routes as Record<string, unknown>)
@@ -85,6 +119,14 @@ export function createFindMatch<TEnv = any>(
           }
         }
 
+        // The trie matched this route, so it EXISTS. If no same-prefix candidate
+        // could own it AND one failed to load, the owning module is the one that
+        // threw — surface the module failure as a 5xx, not the misleading 404 a
+        // fallthrough would give.
+        if (!entry && candidateFailed) {
+          throw candidateError;
+        }
+
         if (!entry) entry = fallbackEntry;
 
         if (!entry) {
@@ -95,7 +137,8 @@ export function createFindMatch<TEnv = any>(
           );
           if (parent) {
             const lazyStart = performance.now();
-            deps.evaluateLazyEntry(parent);
+            const ev = deps.evaluateLazyEntry(parent);
+            if (ev) await ev;
             pushMetric?.("match:lazy-eval", lazyStart);
           }
           entry = deps.routesEntries.find(
@@ -141,7 +184,28 @@ export function createFindMatch<TEnv = any>(
         lastFindMatchResult = null;
         return null;
       }
-      deps.evaluateLazyEntry(result.lazyEntry);
+      try {
+        const ev = deps.evaluateLazyEntry(result.lazyEntry);
+        if (ev) await ev;
+      } catch (err) {
+        // If the trie matched this pathname, the route is REAL and this lazy
+        // entry owns (part of) it — a module-load failure is a genuine error, so
+        // propagate it as a 5xx. If the trie did NOT match, this is a
+        // genuinely-unmatched pathname (a typo, a bot probe): its 404 must not be
+        // upgraded to a 500 just because some lazy include — e.g. a failing root
+        // `include("/")` — happened to need evaluating while we probed. Isolate
+        // and fall through to the 404 (finding 4: the two match phases agree —
+        // owner failure is loud, unmatched stays 404).
+        if (trieMatched) throw err;
+        console.error(
+          `[@rangojs/router] include at "${result.lazyEntry.staticPrefix}" ` +
+            `failed to load while resolving unmatched path "${pathname}": ` +
+            `${(err as Error)?.message ?? String(err)}`,
+        );
+        lastFindMatchPathname = pathname;
+        lastFindMatchResult = null;
+        return null;
+      }
       result = findRouteMatch(pathname, deps.routesEntries);
     }
     pushMetric?.("match:regex-fallback", regexStart);