fix(ppr): reevaluate transition gates on replay - #776

Problem

A consumer can combine ppr with transition({ when }), but a warmed partial navigation currently rejects the captured PPR segment snapshot solely because the shell records that a conditional transition exists. The route handler then reruns even though only the request-specific transition decision changed. On dispatcher-style routes this turns a replay hit into the full CMS/catalog handler path.

Closes #772.

Before vs. after

Before, this valid route captures a shell but partial navigations bypass its segment replay:

path("/*", Dispatcher, { ppr: { ttl: 300, swr: 86400 } }, () => [
  transition({
    when: ({ currentUrl, nextUrl }) =>
      currentUrl?.pathname.split("/")[1] === nextUrl.pathname.split("/")[1],
  }),
]);
// Warm partial navigation: Dispatcher runs again.

After, consumer code is unchanged. The router reuses the captured segment record and evaluates only the server-side predicate for the current request:

path("/*", Dispatcher, { ppr: { ttl: 300, swr: 86400 } }, () => [
  transition({
    when: ({ currentUrl, nextUrl }) =>
      currentUrl?.pathname.split("/")[1] === nextUrl.pathname.split("/")[1],
  }),
]);
// Warm partial navigation: captured handlers replay; `when` runs fresh.

Consumers who do not use ppr or transition({ when }) see no behavior change.

End-to-end example

import { urls } from "@rangojs/router";

export const storefrontUrls = urls(({ path, loading, transition }) => [
  path(
    "/shop/:category/:slug",
    ProductDispatcher,
    { name: "product", ppr: { ttl: 300, swr: 3600 } },
    () => [
      transition({
        when: ({ currentParams, nextParams }) =>
          currentParams?.category === nextParams.category,
      }),
      loading(<ProductSkeleton />),
    ],
  ),
]);

Navigating within one category keeps the transition hold. Navigating across categories drops it and streams ProductSkeleton, while both paths can reuse the warmed PPR handler segments and continue running loaders fresh.

Semantics

Code changes

• src/router/transition-when.ts owns shared context construction and manifest-based PPR predicate evaluation, including route, orphan-layout, and parallel-slot segment IDs.
• src/router/match-handlers.ts evaluates PPR predicates after route middleware has established context but before the segment pipeline performs cache lookup.
• src/router/match-middleware/cache-lookup.ts retains predicate-owning replay segments so a fresh keep/drop decision reaches the client even when the component otherwise needs no update.
• src/rsc/transition-gate.ts applies PPR decisions copy-on-write, preserving reusable cache, prerender, and shell records. Ordinary post-handler gating remains in place.
• src/testing/run-transition-when.ts adds { ppr: true } so consumers can test the production pre-handler timing through @rangojs/router/testing.
• PPR/view-transition skills, API types, execution-model docs, and internal source maps now describe the split timing.

The predicate is evaluated from the already matched manifest rather than forcing normal segment resolution, because rerunning handlers would defeat the PPR replay contract this fixes.

Test plan

• transition-when.test.ts: PPR pre-handler context, keep/drop results, route/orphan/parallel IDs, throwing behavior, and reusable-record immutability through the public testing primitive.
• Semantic matrix [PPR4]: conditional predicates rerun while PPR handlers replay, in dev and production (71 rows passed).
• Router test app: document HIT execution counters, partial replay HIT status, and fresh drop decision, in dev and production (6 focused cases passed).
• cloudflare-basic: the same document, partial replay, and fresh drop contracts on workerd, in dev and production (6 focused cases passed).
• pnpm run typecheck
• pnpm run test:unit:all
• pnpm run lint
• pnpm run format

Notes

• This branch includes the latest main, including feat(ppr): expose navigation replay hits #774's x-rango-ppr-replay signal; the replay e2e now asserts that signal.
• PPR/SWR: stale shell snapshots are rejected on partial navigation, rerunning baked handlers and handles #773 is deliberately out of scope. Stale-within-SWR partial snapshot eligibility, revalidation ownership, and recapture behavior are unchanged.
• PPR predicates cannot read values set by route handlers because they run before handler replay/cache lookup. Use middleware for request context needed by a PPR predicate.