feat(router): dedicated app-fallback chunk for error/notFound boundaries - #537

Problem

A "use client" component registered as an errorBoundary/notFoundBoundary
fallback was co-bundled into whatever client chunk it happened to be reachable
from. For a root/layout-level boundary that wraps a large subtree, that chunk is
the app's big shared chunk — and because a tiny fallback (a ~1 KB error component
is common) often sorts first, rolldown named the whole chunk after it. The
result was an alarming ErrorBoundary-*.js weighing 487 KB that is actually the
theme — the boundary was an innocent bystander that lent its name to it. Worse, the
error UI was physically co-bundled with the very code it exists to catch failures
for: if that chunk fails to load, the boundary that should render the failure can't
load either.

What changes for a consumer

Registered error/notFound fallbacks are now grouped into a dedicated app-fallback
chunk by the built-in strategy (clientChunks: true/default), regardless of where
the component lives. No API change — it just works.

Before vs. after

# before: the small boundary names the big shared chunk it sits in
dist/client/assets/ErrorBoundary-*.js   487 KB   <- actually the theme + the 1KB boundary

# after: the boundary is pulled out; the big chunk is named after a real module
dist/client/assets/<RealThemeModule>-*.js   ~486 KB
dist/client/assets/app-fallback-*.js          ~1 KB   <- the boundary, on its own

End-to-end consumer example

// router.tsx
import { ClientErrorFallback } from "./ClientErrorFallback.js"; // "use client"
import { NotFound } from "./NotFound.js";                       // "use client"

errorBoundary(<ClientErrorFallback />); // -> app-fallback-*.js
notFoundBoundary(<NotFound />);         // -> app-fallback-*.js

app-fallback is fetched only when a fallback actually renders (error/404),
never on a successful navigation — error/notFound fallbacks resolve server-side and
only become client references on the catch path.

Semantics

Verified on a real app (cloudflare host-router, wrapped boundaries)

A consumer app whose boundaries are handler functions wrapping the client boundary
in a server provider — ({ error }) => <FallbackIntl><ThemedError/></FallbackIntl>:

DEBUG=rango:chunks confirms all five boundaries (incl. the FallbackIntl
provider, itself "use client") route to app-fallback. First-load drops ~53 KB;
total client JS is unchanged (relocation + rename, not deletion).

Code change

• generate-manifest.ts — optional collectClientFallbackRef walks the
  EntryData errorBoundary/notFoundBoundary arrays; for each element whose
  .type is a plugin-rsc client reference, reports its $$id (stripping the
  #<exportName> suffix). The otherwise-discarded fallback elements are surfaced
  here and nowhere else.
• discover-routers.ts — during the build-time route-discovery pass, normalizes
  each reported key via computeProductionHash into a ClientChunkContext.fallbackRefs
  set (only when the built-in strategy is active).
• client-chunks.ts — directoryClientChunks checks hashRefKey(meta.normalizedId)
  against fallbackRefs and returns app-fallback. client-ref-hashing.ts exports
  the shared hashRefKey.
• rango.ts / state.ts — create the ClientChunkContext, thread it to both
  resolveClientChunks and the discovery plugin.
• router.ts / router-interfaces.ts — expose the router-level boundary
  defaults (__defaultErrorBoundary / __defaultNotFoundBoundary / __notFound)
  on the instance so discovery can read them: they are createRouter options
  applied at match time and never land in EntryData (the path the reporter's
  app uses — without this the decoupling silently no-op'd).
• collect-fallback-refs.ts (new, build entry) — collectFallbackClientRefs
  handles both registration paths and the common wrapped shape: if the boundary
  is a handler function it invokes it with synthetic props to obtain the JSX tree
  (only constructs elements — inner components are element types, never rendered,
  so no hooks run; fully try/catch-guarded), then recursively walks the tree
  (children + element-valued props, depth-capped) reporting every client reference.
  Used by generate-manifest (EntryData helpers) and discover-routers (router
  defaults, via the build entry so it runs in the RSC-runner realm).

Build-time only (the strategy runs only during vite build); zero runtime/bundle
cost, and it shrinks the happy-path chunk by the fallback's bytes.

Test plan

• Unit — client-chunks.test.ts (fallback grouping, marker precedence, hash
  correlation) + collect-fallback-refs.test.ts (8 cases: direct element,
  server-wrapped, handler fn, throwing handler, slot prop, data-prop safety,
  arrays).
• e2e dev and production (mini.test.ts) — build-graph asserts BOTH the
  route-tree helper (direct element) AND a router-level defaultErrorBoundary
  that is a handler fn wrapping the client boundary in a server component
  land only in app-fallback; runtime asserts the fallback is not fetched
  on a happy route and renders (hydrated) on error.
• Both presets — node (mini) and cloudflare (cloudflare-basic, wrapped
  handler incl. a conditional error ? <Client/> : null, manually verified).
• Real consumer app — see "Verified on a real app".
• typecheck, lint, format; full router unit suite green (3327).

Notes / call-outs

• Considered and dropped: naming the catch-all shared chunk after the router id
  (app-menu). It can't rename a single chunk without either merging others into
  it (collapsing dynamic-import handler splits) or per-chunk hashing, and it only
  targets shared: serverChunks — which single-router apps (mini, vite-rsc-demo,
  55 routes) don't even produce. It never fired on anything testable, so it was
  dropped in favor of the verified app-fallback fix, which removes the alarming
  name for any topology by pulling the boundary out.
• A component used as both a fallback and route UI lands in app-fallback (one
  module, one group). Keep dedicated fallback components separate.
• Limit: a boundary that conditionally renders a different client component
  based on the runtime error, or needs a real render context to return its tree,
  stays on the default grouping; the custom clientChunks fn is the escape hatch
  (documented in docs/client-chunking.md).
• The remaining theme weight (the renamed Search chunk above) is a separate
  per-route/lazy concern, app-side (custom clientChunks fn or lazy()), out of
  scope here.