feat(router): intercept() loaders are loader segments of their slot: prefetch: false, per-loader revalidate() and handles reach modals - #1132

devcorner: dc-t6

Summary

An intercept()'s loaders now behave like a route's loaders. loader(Def, { prefetch: false }) inside intercept() keeps that loader out of a prefetch from the source page. Each intercept loader runs its own revalidate(), in urls() and in clientUrls(). The modal keeps the data and handle pushes of every loader the server skipped. Under the hood, intercept loaders are now loader segments of their slot, resolved by the same loader funnel as route loaders. The browser folds them back onto the slot, so the page under the modal never remounts. Ships in 0.25.0.

Problem

From a consumer's seat, an intercept's loaders were second-class in four ways:

1. prefetch: false did nothing in a modal. loader(CommentsLoader, { prefetch: false }) inside intercept() was accepted and ignored. A hover or viewport prefetch of the target from the source page ran every loader of the modal, the expensive one included. On a route, the same flag keeps that loader for the click.
2. revalidate() on a clientUrls() intercept loader never ran. The build hoisted and checked the predicate, then nothing called it: an action from the modal re-ran every loader of the modal, whatever the predicate said.
3. A link in an open modal lost data. A link in a modal to another intercepted route whose modal reads the same loader (or back/forward between two such modals) re-ran only the loaders whose revalidate() allowed it. The browser then dropped the data of the others, and the new modal's useLoader() threw data not found in context.
4. An action from a modal dropped handle pushes. A loader whose revalidate() answered false kept its data, but its handle pushes (a breadcrumb, a title) were counted as the handler's and disappeared when the handler re-ran.

Before and after

// urls()
intercept("@modal", ".photo", PhotoModal, () => [
  loader(PhotoLoader),
  loader(CommentsLoader, { prefetch: false }),
  loading(<ModalSkeleton />),
]);

// clientUrls()
intercept("@modal", ".detail", DetailModal, () => [
  loader(NotesLoader, () => [
    revalidate(({ isAction, actionResult }) =>
      isAction(saveNote) ? actionResult?.ok === true : undefined,
    ),
  ]),
]);

Nothing changes in the consumer's code. The flag and the predicate start doing what they say.

End-to-end example

A photo gallery whose modal defers its comments in prefetches, plus a clientUrls() group whose modal re-runs its notes only when the save succeeded.

// src/photos/urls.tsx
import { urls } from "@rangojs/router";
import { Outlet, ParallelOutlet } from "@rangojs/router/client";
import { PhotoLoader, CommentsLoader } from "./loaders";
import { Gallery, PhotoPage, PhotoModal, ModalSkeleton } from "./components";

function GalleryLayout() {
  return (
    <main>
      <Outlet />
      <ParallelOutlet name="@modal" />
    </main>
  );
}

export const photoPatterns = urls(({ path, layout, intercept, loader, loading }) => [
  layout(<GalleryLayout />, () => [
    path("/photos", Gallery, { name: "photos" }),
    path("/photos/:id", PhotoPage, { name: "photo" }, () => [
      loader(PhotoLoader),
      loader(CommentsLoader),
    ]),
    // Opens over /photos on a soft navigation; a hard load renders PhotoPage.
    intercept("@modal", ".photo", PhotoModal, () => [
      loader(PhotoLoader),
      // A hover or viewport prefetch from /photos skips it; the click that
      // adopts the prefetch opens the modal at once and one fill runs it.
      loader(CommentsLoader, { prefetch: false }),
      loading(<ModalSkeleton />),
    ]),
  ]),
]);

// src/items/items.client-urls.tsx
"use client";
import { clientUrls, useLoader, useOutlet } from "@rangojs/router/client";
import { saveNote } from "./actions"; // "use server": returns { ok: boolean }
import { ItemLoader, NotesLoader, RelatedLoader } from "./loaders";

function ItemsLayout() {
  return <section>{useOutlet().content}</section>;
}

function DetailModal() {
  const { data: item } = useLoader(ItemLoader);
  const { data: notes } = useLoader(NotesLoader);
  const { data: related } = useLoader(RelatedLoader);
  return (
    <dialog open>
      <h2>{item.title}</h2>
      <Notes notes={notes} onSave={(text) => saveNote(item.id, text)} />
      <Related items={related} />
    </dialog>
  );
}

export default clientUrls(({ layout, path, intercept, loader, loading, revalidate }) => [
  layout(ItemsLayout, () => [
    path("/", ItemsIndex, { name: "index" }),
    path("/detail/:id", ItemDetail, { name: "detail" }, () => [loader(ItemLoader)]),
    intercept("@modal", ".detail", DetailModal, () => [
      loader(ItemLoader),
      // The build moves this predicate to the server; it now runs there with
      // the action's result.
      loader(NotesLoader, () => [
        revalidate(({ isAction, actionResult }) =>
          isAction(saveNote) ? actionResult?.ok === true : undefined,
        ),
      ]),
      // Deferred by an in-group prefetch of /detail/:id, filled at the click.
      loader(RelatedLoader, { prefetch: false }),
      loading(<DetailModalSkeleton />),
    ]),
  ]),
]);

Semantics

Code changes

Router source vs main, tests excluded: +663 / −669.

Server: one loader funnel. resolveLoadersWithRevalidation becomes resolveOwnerLoaders(owner: LoaderOwner, ...) in router/segment-resolution/revalidation.ts. A LoaderOwner is a route entry (ownerOf(entry)) or an intercept:

// router/intercept-resolution.ts
return resolveOwnerLoaders(
  {
    loaders: interceptEntry.loader,
    namespace: `intercept:${interceptEntry.routeName}`,
    segmentPrefix: interceptSlotId(parentEntry, interceptEntry),
    boundary: parentEntry,
    bakeLane: false,
    traceSource: "intercept-loader",
  },
  context, belongsToRoute, rc.clientSegmentIds, /* ... */
);

The intercept gets deferral, fill skipping, ctx.use() delivery (deliverStartedLoaders), per-loader revalidate() and handle attribution without code of its own. router/intercept-resolution.ts drops its two hand-written loader loops (+148 / −265 in that file). The slot carries no aggregate any more: its loaders follow it as ${parent}.${slot}D${i}.${$$id} segments. Other server changes:

• prefetch-deferral.ts: resolveInterceptDeferralScope builds the scope from the intercept alone, and a prefetch that resolves an intercept is no longer excluded (partialDeferralMode).
• interceptFillSkips holds the fill rule "send only what the client lacks of the intercept" in one predicate, used at the cache-lookup and revalidation sites.
• match-result.ts: an intercept's matched has one order (client ids minus the slot's, then interceptSegmentIds), so a fill's identity check holds (R6).
• match-middleware/intercept-resolution.ts: a cache or prerender hit yields the loader segments after the stored slot. It also strips the aggregate a pre-0.25.0 record carries on the slot. That record is reachable only under a version pinned across the upgrade (createRouter's or the cache store's); build versions hash the router's code.

Browser: fold, don't walk. foldInterceptLoaders (segment-system.tsx) puts the loader segments back on the slot as one memoized aggregate (Suspense contract rules 1, 2 and 6). Walked as plain loaders, they would attach to the slot's parent and remount the page under the modal. A list with nothing to fold comes back synchronously, so renderSegments awaits only when there is something to fold. A slot with no loading() settles before the commit, so a modal without a skeleton commits whole, as before. merge-segment-loaders.ts loses its loader merge (−85): no reconcile actor merges loader data now, because a skipped loader is its own cached segment in matched. partial-update.ts sends an intercept's fill with its source (previousUrl and interceptSourceUrl).

clientUrls(). The DSL records prefetch: false inside intercept(). The projection carries deferrableLoaderIndices and loaderRevalidate on the intercept (ClientUrlProjectionIntercept). Materialization builds route and intercept loaders through one materializeLoaders helper (client-urls/server-projection.ts).

Testing primitive. serveShellRequest({ partial: { interceptSource } }) sends X-RSC-Router-Intercept-Source, the header the browser sends from an open modal and with an intercept's fill. Without it, a test cannot serve an intercept's fill.

Why fold in the browser and not render loader segments natively in segmentTreeWalk? The walk's slot-loader branch is gated on p.loading. Lifting that gate for intercept slots touches every slot's Suspense path. That is filed as dc-t34.

Test plan

• pnpm run typecheck
• pnpm run test:unit:all: router 8725 unit + 840 RSC (2 expected fails, unchanged); cloudflare-basic 85 + 27; mini 25 + 3; vite-rsc-demo 27 + 1; shared-e2e 20. Router unit + RSC also pass on each feat commit alone.
• pnpm run lint, pnpm run format
• check:e2e-bucketing, check-e2e-parity --strict, check:suspense-contract, check:docs-api, check:skills, check:skills-catalog, check:doc-links, check:no-external-store, check:e2e-console-baseline
• node tools/check-bundle-guards.mjs: cloudflare-basic router chunk 49,402 B gzip (max 49,536 B; main is 49,527 B, so 125 B smaller)
• Semantic matrix in the router test-app, with the new row [I3]: "an action inside a modal re-runs only the intercept loaders whose revalidate() says so; the modal keeps the rest" (execution-model.md updated)
• pnpm --filter @rangojs/router test:hmr-routes-local and the hmr-intercept and hmr-client-urls projects: 21, 2 and 3 passed

Red before green. The three bugs were run against origin/main in the router test-app, dev and production, with 3 retries each. All three fail there and pass on this branch:

Userland, through @rangojs/router/testing.

• src/testing/__tests__/prefetch-false-intercept.rsc-test.tsx (serveShellRequest) pins four things:
  • a prefetch from the source defers the flagged intercept loader and runs the unflagged one and the handler;
  • its fill, with the intercept source, runs only the flagged loader;
  • with the modal open, nothing is deferred, and a handler's ctx.use() of the flagged loader is one run;
  • a navigation inside the modal keeps a skipped loader's data, and an action keeps a skipped loader's handle pushes.
• tests/cloudflare-basic/test/prefetch-false-intercept.rsc-test.tsx runs the same prefetch-then-fill contract against the consumer app's own fixture.
• prefetch-false-unflagged.rsc-test.tsx adds an intercept to the R9 pin: no flag means no deferred segment and no fill. prefetch-false-client-urls.rsc-test.tsx adds a clientUrls() intercept with a flagged loader.

E2e, dev and production, both apps. New cases:

• intercept(): in tests/shared-e2e/src/prefetch-false.ts, run by both apps:
  • a prefetch skips the flagged loader and the click fills it;
  • the adopted click shows the modal at the click, never later than a plain click, at a 300 ms server;
  • the page under the modal is not remounted, prefetched or not, flagged or not;
  • with no loading(), the slot is empty until the fill;
  • back and forward keep the filled modal;
  • a newer navigation during the fill wins;
  • a hard load runs every loader.
• Two clientUrls() cases in e2e/client-urls.test.ts in both apps.
• The intercept-held scenario.

Runs on this branch:

Suites in the router test-app run:

• suspense-cases, held-boundary, intercept-held, prefetch-false (326 per mode) and semantic-matrix (31 dev, 34 production);
• every client-urls* file;
• intercept-when-shape, prefetch-intercept-source and prerender-intercept;
• loading-fn, loading-redirect, navigation-loading and prerender-loading;
• the parallel-* files;
• stream-mode, streamed-boundary-adoption, streaming-actions, suspense-stream and use-cache-streaming.

In cloudflare-basic: suspense-cases, held-boundary, intercept-held, prefetch-false, every client-urls* file, intercept-when-shape, parallel-new-slot-reval, prefetch-intercept-source, stream-idle, stream-suspense, streamed-boundary-adoption and streamed-handler-boundary.

The one failure is in cloudflare-basic dev, while another session's e2e suite shared the machine: "a click that adopts a prefetch is never worse than a plain click: hub to vt-inner, loaders 300 ms slower, the server 500 ms away". The plain navigation of pair 1 committed in two steps and ran 3 view transitions to the adopted click's 2 (view transitions that change the page: the plain navigation 3, the adopted click 2); pair 2 was on time. The route has no intercept. Rerun alone with --repeat-each=3, it passed 3 of 3.

Notes

• onError change. A live intercept loader's error on a navigation now reports isPartial: true, as a route loader's does; it was unset. It comes from the shared funnel's error context. The CHANGELOG says so.
• Wire shape. Every intercept response changes shape, flagged or not. Intercept loaders travel as loader segments rather than an aggregate on the slot. A pre-0.25.0 segment-cache record is unreachable after the upgrade unless a version is pinned across it; the cache-hit path strips the old aggregate for that case.
• Known gap, not changed here (dc-t30). Intercept middleware never runs on a runtime cache() hit or a Prerender() target. Only the live path calls executeInterceptMiddleware. This is pre-existing, the same on origin/main, and execution-model.md states it.
• Follow-ups, filed under dc-t6:
  • dc-t34: render intercept loader segments natively in segmentTreeWalk and drop foldInterceptLoaders.
  • dc-t35: thread matchedIds from the funnel instead of re-deriving them with interceptSegmentIds.
  • dc-t36: one output filter for an intercept's fill instead of the per-source interceptFillSkips checks.
• Release. Ships in 0.25.0. The CHANGELOG entries are under ## Unreleased.