[ivogt]

Closes #995. Closes #989.

Problem

transition({ when }) ran on the server while the route resolved, so its decision was frozen into whichever response carried it:

• A prefetch decided against the page it fired from, not the page the click actually left. A navigation from page E reused page B's prefetched decision.
• A cache() or prerender hit replayed a stored decision.
• A layout the navigation kept never re-ran its when, so its decision never reached the client (transition: a when() decision for a kept (not re-sent) segment never reaches the client #989).
• The decision changed the rendered tree. A same-route navigation that flipped true -> false -> true remounted the route twice and lost component state (transition: a when() false navigation changes the segment's React key and remounts the route twice #995).

The predicate also could not see what it needed. It had no history state, no reliable source page, and no action result on the client.

Before / after

// Before: server-side, revalidate()-shaped args
transition({ when: ({ currentParams }) => currentParams?.n !== "b" });
transition({ when: (ctx) => ctx.get(KeepScroll) === true });

// After: a browser predicate. Inline in urls() (the build hoists it into a client module)
transition({ when: ({ from }) => from.params.n !== "b" });
// ...or read the location state the Link pushed
transition({ when: ({ to }) => KeepScroll.read(to)?.keep === true });

// intercept({ when }): same from/to shape, without state
// Before
intercept("@modal", ".product", ProductModal, {
  when: ({ from, params }) => from.pathname === "/shop" && params.id !== "gift-card",
});
// After
intercept("@modal", ".product", ProductModal, {
  when: ({ from, to }) => from.url.pathname === "/shop" && to.params.id !== "gift-card",
});

End-to-end consumer example

// location-states.ts: shared by the Link and the predicate
export const ProductTab = createLocationState<{ tab: "details" | "reviews" }>();

// urls.tsx
path("/product/:id", ProductPage, { name: "product" }, () => [
  // Animate between products, but not when switching tabs on the same product
  // or when the Link asked to skip it.
  transition({
    when: ({ kind, from, to }) =>
      kind !== "pop" &&
      !(from.routeName === "product" && from.params.id === to.params.id) &&
      ProductTab.read(to)?.tab !== "reviews",
  }),
  loading(<ProductSkeleton />),
]);

// ProductPage.tsx
<Link to={href("product", { id })} state={[ProductTab({ tab: "reviews" })]}>Reviews</Link>
<Link to={href("product", { id: nextId })} transition={false}>Next (no animation)</Link>

Unit test through @rangojs/router/testing:

const { applied, context } = runTransitionWhen(when, {
  from: { url: "/product/1", params: { id: "1" }, routeName: "product" },
  to: { url: "/product/1", params: { id: "1" }, routeName: "product", state: [ProductTab({ tab: "reviews" })] },
});
expect(applied).toBe(false);

Semantics

	when returns true	when returns false or throws	transition: false on the call
push / replace	held in startTransition, view transition	urgent commit: loading() streams, classes set to "none", no remount	same as false; when is not called
pop (back/forward)	"navigation-back" classes	urgent	not applicable (no per-call options)
action, including the error lane with action.error	"action" classes	urgent	not applicable
refresh() / stale revalidation (kind: "revalidate")	"navigation" / "action" classes	urgent	not applicable
intercept commit	when is not evaluated	when is not evaluated	no effect
document load, PE, server	when never runs	when never runs	no effect

When the predicate is decided:

Navigation	Decided at	to.state
server-route push/replace	the canonical commit	client-pushed state plus server ctx.setLocationState; middleware state also on a PPR replay HIT
clientUrls() cross-route	the optimistic swap; the canonical commit reuses that decision	client-pushed state only
clientUrls() same-route	the canonical commit	as for a server route
pop	the history-cache restore or the popstate commit	the target entry's state. from.state / from.routeName come from per-entry memory and are undefined after a reload.
action	the action commit	current state plus action-set state, and action.*

• Results are ANDed across every committed segment's when, both kept and re-sent segments (transition: a when() decision for a kept (not re-sent) segment never reaches the client #989).
• Predicates are deduped by function identity.
• A throw counts as false and is logged with console.error.

Invalid when	Result
a server function, captured server binding, server-only import, import(), import.meta other than .env, or this/arguments in urls()	dev startup fails, the build exits 1, and HMR shows the Vite overlay. The error names the route and pattern, plus the binding or import.
a route discovered at runtime	the same error is thrown at render; nothing is silently dropped
a non-function in clientUrls()	TypeError at definition time
an intercept when that throws	no intercept (the full page renders), with console.error and the route name. Before, the request failed.

Code changes

1. feat(router)!: transition({ when }) is a browser predicate
   • The server strips when at resolution (applyViewTransitionDefault), records the refs from the static entry chain on every match, and attaches them right before Flight (attachTransitionWhen) on the partial, full/document, PE, action and action-error payloads. Stores never hold a function.
   • browser/transition-when.ts decideCommitGatedOff is the one decision helper, used by the canonical commit, the optimistic clientUrls swap, pop, the action lanes and revalidate.
   • Segment rendering keeps <ViewTransition> with "none" classes when gated off.
   • The navigation store keeps per-history-entry memory (LRU of 200, keyed by history.state.key). Def.write / delete / the flash clear refresh that memory.
   • publicRouteName filters internal route keys out of the payload.
   • Route discovery validates when and gives loud errors.
2. feat(router)!: testing primitives
   • runTransitionWhen(when, { kind, from, to, action }) returns { applied, gatedOff, context }.
   • renderRoute: navigate() is decided as push, and the new refresh() as revalidate.
   • Both use the production decision code.
3. feat(router): inline transition({ when }) via a build hoist (vite/plugins/transition-when-hoist.ts)
   • Only the router's transition is hoisted: the urls() helper, or the @rangojs/router import, aliased or namespaced.
   • Scope analysis rejects captures. Module imports the literal uses are re-emitted in a virtual client module, ?rango-when=N.
   • load serves exactly what transform recorded.
   • Vitest does not run the hoist.
4. feat(router)!: intercept({ when }) selects on from/to
   • ServerRouteLocation = { url, params, routeName }.
   • from.params comes from the source route match (nav.effectiveFromMatch).
   • A throwing selector falls back to the full page.
5. feat(router): per-navigation transition: false: on NavigateOptions, Link (prop and data-transition), the link interceptor and useRouter.
6. test(consumers): cloudflare-basic's transition-when fixtures move to "use client" modules and inline literals.
   • The e2e contract that counted server evaluations (pprExecCounters.transitionWhen) now asserts the browser-side marker.
   • vite-rsc-demo's intercept selectors are migrated.
   • A new cloudflare-basic intercept fixture is added.
7. docs:
   • skills: view-transitions (conditional transitions rewritten, prefetch caveat removed), client-urls, route, testing, ppr, intercept, and rango (the rule "a predicate runs where its effect lands");
   • the docs site;
   • feature-map.md and feature-file-map.md;
   • execution-model.md and the semantic matrix PPR4 row;
   • the CHANGELOG.

Why the browser, and not a server when with more inputs: the decision is only correct against the committed page and history entry the click actually leaves. Only the browser has that at commit time, for every path: prefetch, cache HIT, prerender, kept segments, pop and optimistic swaps.

Test plan

• Userland, through @rangojs/router/testing:
  • runTransitionWhen with a dogfood Def.read(ctx.to) (tests/cloudflare-basic/test/transition-when.test.ts);
  • renderRoute navigate / refresh decisions and mount-count contracts: no when applies, a throw gates off, no remount across true -> false -> true;
  • serveShellRequest for the intercept shape, a throwing selector, and public route names.
• Red on origin/main, green on the branch, e2e dev and production:
  • transition: a when() false navigation changes the segment's React key and remounts the route twice #995: b -> a keeps component state, Expected "clicks:2" Received "clicks:0";
  • transition: a when() decision for a kept (not re-sent) segment never reaches the client #989: c -> b ... nothing animates, Expected 1 Received 2;
  • prefetch source: e -> c does not remount, dev Expected 6 Received 8, production Expected 3 Received 4.
• Review regressions, each red before its fix:
  • unnamed or include-scoped routeName ("$$path__unnamed");
  • pop from.state after Def.write;
  • an urgent commit for gated-off action and revalidate lanes (dev e2e gated-off action commit is urgent on a useActionState form);
  • runTransitionWhen to defaulting to from;
  • no decision for a discarded stale revalidation or an intercept pop;
  • hoist cases (23 red → 47/47);
  • a throwing intercept selector (unit, serveShellRequest, e2e in both apps);
  • routeName typing (@ts-expect-error on a typo).
• E2e:
  • router test-app: dev 1313 passed (3 flaky, passed on retry), production 1109 passed;
  • semantic matrix, dev and production;
  • cloudflare-basic: dev 450, production 512;
  • vite-rsc-demo: 299 passed;
  • react-experimental: 99 passed, 1 failed (the same failure on origin/main, see Notes);
  • route-types HMR: 21/21, flaky as on main.
• pnpm run typecheck, pnpm run test:unit:all (router 7030 + rsc 420; every consumer suite), lint, format, check:docs-api, check:e2e-bucketing and check:e2e-parity --strict. *.gen.ts is committed.

Notes

• Breaking for consumers:
  • A server when reading ctx.get(), env, currentUrl / nextUrl or actionResult must move to the browser. Read location state set by middleware, the handler or a Link from to.state, and action data from action.*.
  • Intercept from.pathname becomes from.url.pathname, and params becomes to.params. There are no deprecated aliases.
• Bundle: the router client chunk grows by 1,459 B gzip (43,698 → 45,157 B, test-app fixture). On cloudflare-basic it is 45,375 → 46,805 B, so the router ratchet in tools/check-bundle-guards.mjs is raised from 45 KB to 46 KB with a documented reason, following feat(router): clientUrls() — client route groups with instant navigation, server authority #812, fix(router): async include() resolves a clientUrls() module directly #848 and feat(router): the default document restores scroll on back/forward #948. Predicate modules land in the client entry chunk, so they should contain only type imports and location-state definitions, and no window at module scope.
• Vitest: in unit-test projects, neither the hoist nor the validation runs, so an inline when stays a plain function. This is documented in the testing skill.
• Failures also on main:
  • react-experimental comments.test.ts "should disable submit button while posting" is a timezone hydration mismatch.
  • The route-types HMR "helper-file fix after broken-import error" test is flaky.
• Follow-ups:
  • a non-boolean return for "hold but do not animate";
  • Partial requests without X-RSC-Router-Client-Path match a cross-origin Referer's pathname as the navigation source #1005, Referer fallback for from, which predates this PR;
  • intercept prefetch source scoping, pending a decision.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@rangojs/router@1006

commit: 5984799