Application-Controlled Route Discovery

[brophdawg11]

Add unstable_useRouteDiscovery() so applications can discover selected destinations, complete their client route tree at a chosen time, and control recovery from manifest mismatches. Keep the existing routeDiscovery.mode values; applications can implement hybrid strategies through the hook without adding new configuration modes.

Motivation

Lazy route discovery reduces the route metadata shipped with the initial document, but introduces discovery requests during eager link discovery and subsequent navigations/fetchers. Applications may prefer to load the full manifest later, preserving lazy startup without paying discovery costs throughout the session.

During rolling deployments, discovery can also encounter a manifest version mismatch. If immutable client assets remain available, loading the client's own full manifest can complete its route tree without a document refresh. Other applications may prefer to preserve drafts or show a reload dialog before recovering.

Proposed API

type RouteDiscoveryEvent = {
  source: "eager" | "navigation" | "fetcher" | "imperative";
  version: string;
  loadAllRoutes(): Promise<void>;
  stopPropagation(): void;
};

type ManifestMismatchEvent = RouteDiscoveryEvent & {
  reloadUrl: string | null;
};

type DiscoveryResult =
  | { type: "success" }
  | { type: "version-mismatch" }
  | { type: "aborted" };

function unstable_useRouteDiscovery(options?: {
  onBeforeDiscovery?: (
    event: RouteDiscoveryEvent,
  ) => void | Promise<void>;
  onManifestMismatch?: (
    event: ManifestMismatchEvent,
  ) => void | Promise<void>;
}): {
  version: string;
  state: "partial" | "loading" | "complete";
  loadAllRoutes(): Promise<void>;
  discoverRoutes(
    paths: string[],
    options?: { signal?: AbortSignal },
  ): Promise<DiscoveryResult>;
};

Initial scope is conventional SSR Framework Mode configured with routeDiscovery.mode: "lazy". The hook remains usable after discovery becomes complete. Existing lazy and initial behavior remains unchanged without opting into the hook's operations or handlers. RSC requires separate evaluation.

Full-manifest loading

loadAllRoutes() loads the running client's existing manifest.url, verifies its version, merges missing metadata into the running manifest, and patches the router. It loads route metadata, not every route module. Only after completion does React Router disable eager and navigation/fetcher discovery for that document.

The state moves from partial to loading to complete. Concurrent calls share one load; calls after completion resolve immediately. Failure rejects and returns the state to partial. An individual navigation abort must not cancel a shared load needed by other operations.

Applications must retain the client's versioned manifest and referenced assets, and keep server routing and loader/action contracts compatible with supported clients. Completing A's route tree does not make B's incompatible backend behavior safe. The client's version does not change.

Selective discovery

discoverRoutes(paths, { signal }) fetches and applies metadata for selected destinations without navigating, executing loaders/actions, or prefetching route assets. This incorporates the selective discovery use case in #14816, such as preparing a wizard or command palette without rendering hidden links.

const { discoverRoutes } = unstable_useRouteDiscovery();

const result = await discoverRoutes([
  "/checkout/shipping",
  "/checkout/billing",
  "/checkout/review",
]);

if (result.type === "version-mismatch") {
  setShowReloadDialog(true);
}

Batch requested paths, skip previously discovered paths, and respect the manifest request URL limit without silently dropping requested discovery. If the full tree is already complete, resolve with success immediately. Selective discovery leaves the shared state partial; loading describes full-manifest loading, not individual selective requests.

The results distinguish completed discovery (success), an unresolved mismatch (version-mismatch), and caller cancellation (aborted). Success means metadata discovery completed, not that every requested pathname matches a route. Actual request or handler failures reject.

These calls use the same before-discovery and mismatch handler chains with source: "imperative" and reloadUrl: null. If a handler completes the full tree, resolve with success unless the caller was aborted. Otherwise report an unresolved mismatch. With no mismatch handler, report version-mismatch without forcing a document reload. Cancellation must not abort a shared full-manifest recovery needed by other operations.

Discovery and mismatch handlers

onBeforeDiscovery runs only when React Router would otherwise make an incremental manifest request, after discovery-cache and request-size checks. React Router awaits the handler chain, then skips the request if the tree is complete; otherwise incremental discovery proceeds.

If full-manifest loading initiated by a before-discovery handler fails, fall back to incremental discovery and report the error through the client-side onError callback where supported. The direct loadAllRoutes() promise still rejects. Mismatch recovery failures must never resume an operation against an incomplete tree.

onManifestMismatch runs when a discovery response indicates a version mismatch. After awaiting the handler chain:

• If the tree is complete, React Router rematches and continues affected operations, provided they have not been aborted or superseded.
• If the tree is incomplete, React Router cancels affected navigations/fetchers and settles their pending state. It must not continue matching against the unchanged partial tree.
• If no mismatch handlers are registered, existing automatic recovery applies to eager/navigation/fetcher discovery; imperative discovery reports version-mismatch without forcing a document reload.

A handler can await loadAllRoutes() to resolve the mismatch, or display a dialog and return to cancel the operation. It can also remain pending while awaiting a user decision. Completing discovery after an operation has been canceled does not replay that navigation or submission. Rejected handler promises stop propagation and use the discovery error path rather than silently continuing.

Concurrent mismatch recovery

Concurrent mismatches share one pending handler chain. Its event describes the request that initiated recovery, including that request's source and reloadUrl; these values do not change when other requests join.

Each joining operation retains its own destination and abort signal. Aborting or superseding one operation stops its participation without canceling recovery for other operations. After the chain settles, surviving operations rematch and continue if the tree is complete; otherwise they are canceled. Canceled submissions are never replayed.

Once the handler chain settles, a later mismatch may start a new recovery attempt. A handler choosing a manual document reload uses the initiating event's reloadUrl, rather than automatically tracking destinations from later requests.

Composition and temporary overrides

The hook manages registration and cleanup internally. For each event, handlers run in reverse registration order, and each is awaited before the next runs. stopPropagation() prevents earlier handlers from running; it does not itself complete discovery or authorize continuation.

Unmounting removes that component's registration, revealing earlier handlers. Callback updates do not change registration priority. Registrations are removed by identity, so cleanup also works when components unmount out of order or effects are replayed in Strict Mode.

This is registration-order precedence, not a promise of deepest-component-first traversal. Hook calls without handlers simply consume the shared state and operations.

Userland strategies

Keep config at mode: "lazy". Common hybrid strategies can be expressed through the hook:

function useHybridRouteDiscovery(
  strategy: "discovery" | "demand" | "mismatch",
) {
  return unstable_useRouteDiscovery({
    onBeforeDiscovery: async ({ source, loadAllRoutes }) => {
      if (
        strategy === "discovery" ||
        (strategy === "demand" &&
          (source === "navigation" || source === "fetcher"))
      ) {
        await loadAllRoutes();
      }
    },
    onManifestMismatch: async ({ loadAllRoutes }) => {
      await loadAllRoutes();
    },
  });
}

• discovery: complete the tree instead of the first manifest request, including eager or imperative discovery.
• demand: complete it when any navigation/fetcher first needs discovery, regardless of how the operation was triggered. Preparatory imperative discovery does not trigger completion.
• mismatch: continue incremental discovery until a mismatch.

Every strategy attempts full-manifest recovery on a mismatch. Demand mode may otherwise remain lazy indefinitely if eager discovery covers every operation. Discovery mode can begin loading shortly after hydration and may affect startup metrics such as TBT; it is not an idle scheduling guarantee.

Applications can also invoke the returned loadAllRoutes() after authentication, during application-defined idle time, or before a workflow. Loading UI derives from state === "loading".

Preserving application state

A root handler can provide full-manifest recovery. An editor mounted later can temporarily intercept it:

const { state, loadAllRoutes } = unstable_useRouteDiscovery({
  onManifestMismatch: (event) => {
    if (hasUnsavedChanges) {
      event.stopPropagation();
      setShowReloadDialog(true);
    }
    // Otherwise allow earlier recovery handlers to run.
  },
});

The dialog can save drafts and refresh, or call loadAllRoutes() and let the user retry the canceled operation.

Hydration and implementation

Delay eager discovery until router.state.initialized is true and the corresponding route tree has committed. Hook registration must be coordinated with that boundary so a root-level handler can intercept the first eager request. This does not wait for every descendant behind Suspense, nor guarantee an idle main thread.

Discovery before application handlers can mount is not expected in the intended SSR flow. If it occurs, use normal lazy discovery and existing mismatch recovery rather than waiting for registration.

The existing useFogOFWarDiscovery() remains the internal eager-discovery driver. It, navigation/fetcher discovery, and imperative discovery would share the hook's runtime for handler dispatch, full-manifest loading, and completion state. Multiple consumers must not create duplicate observers. Completion must also safely account for incremental requests already in flight.

Scope and validation

Deployment polling and staleness policy remain application-owned; there is no checkStaleness API. The exposed client version can support an application resource route and polling fetcher. A manifest mismatch establishes differing versions, not which deployment is newer.

Validate initial hydration timing, handler ordering and cleanup, concurrent/aborted operations, cancellation of submissions, selective discovery batching and result states, param/splat matching, retained/unavailable assets, and rolling deployments. Measure initial load and first/subsequent operation latency to evaluate the userland strategies.

Authored by an AI agent on behalf of @brophdawg11

[brophdawg11]

Linking the related proposals for reference. These cover overlapping motivations and complementary APIs around route discovery and deployment/version-skew handling.

Route discovery and manifest performance

• #14816: Programmatic Lazy Route Discovery
• #15374: Custom cache keys for lazy route discovery
• #14811: Proposal: Deduplicate import paths in mode: "initial" manifest
• #15579: Bounded server-side route matching cache for lazy manifest requests

Deployment compatibility and recovery

• #14800: [Framework] Add a way to reload the frontend when the backend changes
• #15343: Proposal: let apps intervene before the RSC clientVersion skew-recovery reload
• #15517: Version skew goes undetected on .data navigations to already-discovered routes in non-RSC framework mode
• #15461: Proposal: fetch prop for HydratedRouter
• #15472: [Proposal] Support a custom fetch function on HydratedRouter for manifest and data requests
• #15184: Feature: hook to transform asset/data URLs at SSR (for version-skew protection on Vercel et al.)

Authored by an AI agent on behalf of @brophdawg11

[brophdawg11]

Preserving the original config-mode proposal for reference. The discussion body is being updated to propose an application-controlled hook instead.

Original proposal: Hybrid Lazy Route Discovery (superseded)

I'd like to explore starting with lazy route discovery, then loading the full client manifest at a chosen point after startup. This would defer the full manifest beyond the initial document payload while removing ongoing discovery requests once the route tree is complete. The chosen transition timing would determine its impact on startup performance.

Motivation

Lazy Route Discovery primarily improves initial document load by shipping less route metadata for the browser to download and process. This can benefit metrics such as Total Blocking Time and Speed Index, especially for large applications.

The tradeoff is additional discovery work on subsequent navigations and fetchers. Param and splat matches need discovery checks because a partial tree may omit a higher-ranking static route. Cached paths avoid repeat requests, and eager discovery often hides the round trip before interaction, but new destinations can still introduce a waterfall. Discovery documentation, matching behavior.

A smaller route tree also saves memory and may match faster. My hypothesis is that, for some applications, discovery costs outweigh those benefits after initial load. We should benchmark that tradeoff, particularly as route matching becomes more efficient.

Rolling deployments

An A client can send a manifest request to a B server, receive a version mismatch, and reload onto another A pod. A subsequent mismatch can then exhaust existing reload recovery. Continuing against the unchanged partial tree is unsafe because an undiscovered route can be shadowed by a catch-all—the issue addressed by #15489.

If immutable client artifacts remain available, we could instead load A's full manifest, complete A's route tree, and disable further discovery requests. This requires neither a document refresh nor knowing which deployment is newer.

Proposed API

Expand routeDiscovery.mode with three opt-in strategies:

// react-router.config.ts
import type { Config } from "@react-router/dev/config";

export default {
  routeDiscovery: {
    mode: "unstable_lazy-until-demand",
  },
} satisfies Config;

Mode	Initial route metadata	Subsequent behavior
initial	Full manifest	No lazy discovery
lazy	Partial manifest	Continue incremental discovery
unstable_lazy-until-discovery	Partial manifest	Load the full manifest instead of the first incremental discovery request, including eager discovery
unstable_lazy-until-demand	Partial manifest	Load the full manifest when a navigation or fetcher first needs on-demand discovery, or on any discovery version mismatch
unstable_lazy-until-mismatch	Partial manifest	Load the full manifest on a discovery version mismatch

All unstable_lazy-until-* modes would load the client's full manifest whenever a discovery request detects a version mismatch, including during eager discovery. Each mode defines an additional trigger for completing discovery; mismatch recovery is shared across all hybrid modes.

Existing modes, the default, and support for custom manifestPath would remain unchanged. Initial scope would be Framework Mode applications using SSR; RSC would need separate evaluation.

unstable_lazy-until-discovery

The first time React Router would make any manifest request, it would load the full manifest instead. This includes eager discovery of rendered links/forms as well as discovery needed by a navigation or fetcher. Operations requiring discovery would await completion before proceeding. If no discovery request is needed, the client would remain lazy.

This replaces incremental discovery with one full-manifest load at the earliest discovery opportunity. Eager discovery may trigger it shortly after hydration while startup work is still running; this is not an idle scheduling guarantee, and downloading and processing the full manifest could affect initial load metrics such as TBT.

unstable_lazy-until-demand

The first navigation or fetcher operation that would otherwise need an on-demand manifest request would load the full manifest instead. This applies to any such operation, regardless of whether it was triggered by user interaction, application code, or an effect. That operation would await completion before proceeding with final route matching, module loading, and data execution. Successful eager discovery of rendered links would not trigger the transition, and operations satisfied by existing route metadata or cached discovery would remain lazy. An eager-discovery version mismatch would still trigger full-manifest loading under the shared recovery policy.

This moves the download cost onto the first operation needing discovery and amortizes it across subsequent interactions. It does not guarantee that operation is faster than loading a small discovery patch.

unstable_lazy-until-mismatch

This mode would continue incremental discovery until a version mismatch occurs, then use the shared full-manifest recovery policy. Across all hybrid modes, once the route tree is complete, waiting navigations/fetchers could resume. Eager-discovery mismatches would initiate the transition in the background.

Loading and compatibility

React Router already emits a full, versioned client manifest, such as /assets/manifest-a1b2c3d4.js. Its URL is retained in the partial manifest and can point to a CDN through Vite's asset base. We would load the client's existing manifest.url and verify its version. No archived server build is needed. Manifest generation.

This loads route metadata; route modules would remain lazy.

Applications opting in would own two requirements:

• Retain versioned manifests and referenced assets for supported clients.
• Keep server route URLs/IDs/matching behavior and loader/action contracts compatible with those clients.

An A client may still execute B's loaders/actions. Completing its route tree does not make incompatible server changes safe.

Concurrent operations would share one manifest load. The implementation would merge metadata into existing manifest references, patch the router, and only then disable eager and navigation/fetcher discovery for that document. Replacing window.__reactRouterManifest alone would not update the running router.

If loading fails, discovery- or demand-triggered attempts would fall back to incremental discovery; mismatch-triggered attempts in any hybrid mode would use existing reload/error recovery. Failed recovery must never continue against an unchanged partial tree as though it succeeded.

Open questions

Are these mode names clear?

We should compare initial load, first/subsequent navigation latency, request counts, memory, and matching cost across representative applications—including those whose eager discovery already hides waterfalls. Correctness coverage should include concurrent/aborted operations, param/splat matching, fetchers, unavailable assets, and rolling deployments.

Future extension: Imperative control

The same full-manifest loading operation could eventually support an imperative API, allowing applications to choose when to complete discovery. A future hook might expose:

const { loadAllRoutes } = unstable_useRouteDiscovery();

An application could call loadAllRoutes() during idle time, after authentication, before entering a complex workflow, or in response to another application-specific event. It could start with mode: "lazy" and control the transition itself.

Idle timing is application-specific: hydration completion or a brief idle period may not mean startup work has finished. An imperative API would let the application choose its own scheduling policy and validate the impact on initial load metrics such as TBT.

The function would return a promise that resolves once the full route tree is available and further discovery requests are disabled. Concurrent calls would share one load, calls after completion would resolve immediately, and failures would reject while leaving discovery incomplete.

This could be a follow-up to the declarative modes, built on the same operation and compatibility contract. The modes would cover common policies, while the imperative API would give applications control over their own timing.

Authored by an AI agent on behalf of @brophdawg11

[wilcoxmd]

Thanks for putting this proposal together! Very excited that you’re thinking about improving lazy route discovery, and overall this seems like a solid next step to try. Would be very happy to help test changes. I’ll post a few other thoughts and rough ideas as separate comments in case it’s helpful to thread discussion.

For context, we have a large framework mode app and could really use this update. Our biggest pain point with lazy mode today is the UX of getting refreshed during client-heavy workflows that require navigation. For example: a user may be working on a form, and then need to open a routed modal on top of that to input more info. If they had the tab open across a time we happen to deploy, they lose their in-progress inputs to the base form when they open the modal.

A second issue we see is dynamic paths that end up causing repeated discovery requests. For example: items/123/variants/abc must be discovered separately from items/456/variants/def. This leads to a lot of requests if someone’s doing work across a list of some kind, and sometimes slower navigations if we're using navigate().

[brophdawg11]

yeah this proposal should definitely be able to handle the first case - either by saving form state/reloading/refilling form state or more likely completing the route tree via loadAllRoutes, and scheduling a hard reload once they complete the form submission.

The second case is what I was noodling on in #15374 but I don't really love that API so that's still out of scope for this proposal. I have a hunch that for most apps, loadAllRoutes is a fine solution that keeps initial document load fast while also allowing you to prime/complete the client route tree to keep subsequent navigations fast. But still something to keep in mind as a potential future expansion of this new hook.

[wilcoxmd]

Yea I agree; loadAllRoutes seems like a pretty straightforward starting point, and if we're grabbing the whole manifest that might solve most of the discovery duplication we do too. Would be curious to benchmark, but discovering the entire manifest from CDN might still be faster than going back to the server's __manifest endpoint to get a partial tree. We'd also probably end up with users hanging around on stale versions a bit longer, but stale version refresh is probably something we could do in userland.

[wilcoxmd]

loadAllRoutes() loads the running client's existing manifest.url

Requesting the manifest from manifest.url on the client would be a change from how the manifest is fetched today in lazy mode, and cause a few problems for us. We rely on the ability to load the server build dynamically in createRequestHandler, and prefix runtime-dependent info to asset paths there (e.g. the CDN origin or path prefixes relevant to the current environment). Making the request go through the __manifest endpoint on our server keeps that working, but I suppose would open us up to version mismatch on an API meant to ensure that you avoid it…

Maybe we could achieve the same transforms we need on the client, if there was a callback on this API that gave us access to the manifest data before its routes are patched in? Something like loadAllRoutes({ onLoad: (manifest: Manifest) => Manifest }).

[brophdawg11]

What type of runtime dependent info?

[wilcoxmd]

We prefix the CDN origin + base paths that we need to fetch assets from.

We build & deploy a single Docker image + set of assets into different infrastructure environments (e.g. fully separate staging and production infra). Our CDN domain is different than the one we serve the app from, and it also changes based on the current environment that the service is running in, plus a few other pieces of data (think staging.cdn.com and production.cdn.com).

So our build generates relative asset paths, and at runtime on the server we read everything we need to in order to determine the correct correct origin + path prefixes, and then transform the asset manifest + server build before passing it to createRequestHandler, turning /assets/index.js to something like https://correct.cdn.com/assets/index.js.

[brophdawg11]

That feels a bit like a separate concern - basically a way to do at runtime what vite can do at build time using base? I'd rather address that globally somehow instead of provide a manifest-specific hook here

[wilcoxmd]

Yea, that sounds right. We need a runtime integration because Vite's base and experimental.renderBuiltUrl features can't access per-request data required to resolve the correct url (e.g. feature flags, url params like ?preview=$sha, etc). I'd also love a more global approach to this too since it'd let us just handle the concern in one place instead of split between the server and this specific hook (and maybe others?).

Maybe this could be a new feature for createRequestHandler?

createRequestHandler({ 
  build, 
  getAssetBase: async ({ request, context }) => {
    // User-defined `resolveCustomAssetBase` could consider url, headers, environment, region, feature flags, etc.
    const assetBase = await resolveCustomAssetBase(request, context); 
    return assetBase;
  }
})

or a prop on ServerRouter in entry.server maybe:

export function handleRequest(request, status, headers, context, loadContext) {
  const assetBase = await resolveCustomAssetBase(request, loadContext);
  return renderToReadableStream(
    <ServerRouter context={context} url={request.url} assetBase={assetBase} />,
  );
}

Internally we could set up a handoff variable on router context or something else that could be used to resolve urls when rendering links into the DOM or importing route modules.

Looks like there's some prior art to compare from Tanstack Start for this too: Handling Per-Request CDN Selection. Seems like the idea is to just configure Vite to use a relative base in the build, and then enhance entrypoints with runtime data.

I think we'd need something like this in order to be able to actually use the loadAllRoutes helper proposed here. I'd be happy to split this out to another proposal if the general idea seems ok, and help PR it. I really like the idea that the loadAllRoutes method is guaranteed to load the current version's manifest right from CDN; it's just a matter of making sure we can properly resolve the where manifest.url should point, and the entrypoints/assets that we grab out of that file.

[wilcoxmd]

In discoverRoutes, what if we could discover based on a route prefix:



discoverRoutes(['/items/*']);

or an explicit option if necessary:



discoverRoutes({ prefix: '/items' }); 


The problems I’m thinking about that bring this to mind are:



a) not having to maintain a list of every child path
b) being able to avoid re-requesting the manifest for dynamic child paths

Maybe separate problems, but for b, after loading a prefix I was wondering if we could cache that we’ve discovered its full namespace, or otherwise mark that part of the route tree ‘complete’ in order to avoid repeated manifest requests for every items/:id path because items/new might exist but is yet undiscovered.

[brophdawg11]

The current matching algorithm doesn't support that but this is the type of thing I'm hoping to unlock with #15374 where we can know ahead of time that we've already discovered and there's no potentially higher ranking but not-yet-discovered path. It's possible if we limited it to strictly prefixes, we could just skip matching and instead walk a portion of the route tree.

[wilcoxmd]

Yea, just opting out of matching for a discovered prefix was what I had in mind too! There'd probably be a little over-fetching of route manifest data in some cases, but my hunch is that in most cases that's probably not a large concern beneath a specific prefix.

[wilcoxmd]

As another option, I wonder whether there’d be a build-time path to segmenting the app into route groups ahead of time, sort of like mini groups of initial mode defined within the otherwise-lazy route tree. Something like:


/* /items + all its child routes would be discovered at once */
route('items', './routes/items.id.tsx', { discovery: 'initial' }, [
  route(':id', './routes/items.id.tsx'), 
  route('new', './routes/items.new.tsx'),
]),

This could be complementary to the runtime APIs. The behavior would be to have the initial manifest include the full subtree of routes on document load, as well as any time one of the paths within the items namespace is discovered. Nesting lazy within initial boundaries would not be allowed. On client-side navigation/discoveries for a route in this group, we could store the entire items namespace as discovered to avoid future manifest requests within it.

The main idea here is to keep the current lazy behavior of refreshing after there’s been a deployment, but control the boundaries of when it happens a bit better and avoid having to show reload notifications. I’d see us using something like this to create boundaries around areas of the app we know are full page / contextual transitions.

[wilcoxmd]

Started discussing this briefly in Discord. @brophdawg11 had a good point; copying it to this thread to keep the full record here:

The build time idea is neat to prevent a round trip, but it's less flexible (can't eager load different routes based on the starting url/current page for example)

I agree its less flexible, and would see something build-time as potentially complementary.

Another thing to figure out here would be what would happen if someone had a sibling route that used the same prefix but was outside the annotated route's own definition tree:

route('items', './routes/items.id.tsx', { discovery: 'initial' }, [
  route(':id', './routes/items.id.tsx'), 
  route('new', './routes/items.new.tsx'),
]),
route('items/foo', './routes/items.foo.tsx'), // does this get discovered too?

Might need to come up with some rules on how this could be used, or maybe a slightly different API would be better for the same general idea.

[brophdawg11]

if we shipped the prefix idea above, maybe we could expand that here too via something like

  routeDiscovery: {
    mode: 'lazy',
    initialPrefixes: ['items/*'],
  }

I think I'd prefer it in the config because routes.ts is what builds the runtime route tree, I don't love adding build-time only info onto there.

[wilcoxmd]

Makes sense. That'd be an interesting option too, though slightly less convenient for us to segment through the react router config file because of the way we split our build config, app shell, and route definitions between platform vs product team owned libraries.

Can noodle on this a bit more to see if another suggestion comes up, but also if we got loadAllRoutes support with the runtime asset path stuff we're talking about in this thread, and it was benchmarking pretty well, further build time splitting might not be necessary or could be done as an enhancement later.

[brophdawg11]

We're dropping onBeforeDiscovery from the initial API to keep it focused on manifest-mismatch recovery and imperative discovery. Apps can still choose when to call loadAllRoutes() or discoverRoutes(); automatic "lazy until discovery/demand" policies can be revisited if concrete needs emerge.

Authored by an AI agent on behalf of @brophdawg11