@rangojs/router 0.4.0 → 0.4.1

package/skills/ppr/SKILL.md

@@ -192,8 +192,29 @@ replay its eligible snapshot. In both cases `matchPartial()`:
 This is deliberately invisible to the browser: the response is the same
 `RscPayload` shape as any other partial navigation. Captured item/response values
 and loader-container pins are NOT replayed on this path, so loader reads stay
-live. A route's own `cache()` scope still resolves its normal store, key, TTL,
-SWR, tags, and condition; only the implicit PPR scope sees this behavior.
+live.
+
+A route's own `cache()` scope — including one inherited from an ancestor, the
+common app-wide storefront shape — COMPOSES with replay instead of disabling
+it. The explicit tier stays authoritative: its lookup runs first with its
+normal store, key, TTL, SWR, tags, and condition, and when it supplies the
+match the response reports `BYPASS; reason=explicit-cache-hit` (never a false
+replay `HIT`). Only when the explicit tier misses does the shell snapshot's
+canonical doc segment record supply the match and report `HIT`. To make that
+possible, a capture of such a route records the doc segment record into the
+shell snapshot IN ADDITION to the scope's normal store write; the record rides
+only inside the shell entry, never the real store. Two opt-outs stay absolute:
+`cache(false)` and a `condition()` returning false mean "do not serve this
+request's segments from any cache" — no doc record is captured for them and
+the seeded fallback never rescues a refused read. `cache(false)` is static, so
+replay reports `BYPASS; reason=cache-disabled` before performing a single
+shell read; a `condition()` refusal is request-time state, decided at the
+lookup itself and reported as the same `cache-disabled` post-match (the gate
+must not pre-decide a predicate that could flap between the two evaluations).
+An errored explicit read — a throwing `key()`, or a built-in store's swallowed
+backend failure (`CACHE_READ_ERROR`) — also never falls back: it renders
+uncached, exactly as without ppr.
+
 `transition({ when })` is evaluated from the
 matched manifest before route handlers on every PPR match, so it can vary by
 URL/params/action or middleware context without disabling replay; handler-set
@@ -202,6 +223,19 @@ nonce, and an absent/corrupt segment snapshot fall open to the ordinary partial
 path when encountered by the shell capture. A transition already replayed from
 an explicit cache tier remains frozen by that tier's normal semantics.
 
+Two more decisions are made before any shell-store read, so probes and
+prerendered routes never spend passive `getShell` I/O:
+
+- A partial request carrying neither `X-RSC-Router-Client-Path` nor `Referer`
+  (a curl probe, a synthetic monitor) can never produce a partial match; it
+  reports `BYPASS; reason=no-navigation-context`. Alert on replay hit-rate
+  with this in mind — such probes are not cache misses.
+- A `Prerender()` route's partial is served from the build-time prerender
+  store inside matching (a better-than-HIT outcome); it reports
+  `BYPASS; reason=prerender-store`. Its captures never record a doc segment
+  record (the prerender store short-circuits the cache write), so replay
+  seeding would be impossible anyway.
+
 Fresh and stale-within-SWR runtime shells replay. The stale read is passive: it
 uses `getShell(key, { claimRevalidation: false })`, does not claim SWR ownership,
 and cannot recapture HTML. A later document request owns the background
@@ -226,8 +260,23 @@ performance metrics enabled, the same decision appears as
 `ppr-navigation-replay` in `Server-Timing`. `HIT` means matching consumed the
 seeded segment record after it decoded successfully, not merely that a snapshot
 existed. An explicit `cache()` scope that supplies the match cannot produce a
-false HIT. There is still no Flight resume API; this is segment replay followed
-by normal Flight streaming, not reuse of the HTML `prelude`/`postponed` bytes.
+false HIT — it reports `explicit-cache-hit`. There is still no Flight resume
+API; this is segment replay followed by normal Flight streaming, not reuse of
+the HTML `prelude`/`postponed` bytes.
+
+The bounded bypass tokens, grouped by when they are decided:
+
+| Token                                                                             | Decided           | Meaning                                                                                                                                                                                                                                                                   |
+| --------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `method`, `dynamic`, `nonce`, `store-unavailable`, `passive-read-unsupported`     | pre-read          | request/route/store ineligible for replay                                                                                                                                                                                                                                 |
+| `no-navigation-context`                                                           | pre-read          | no `X-RSC-Router-Client-Path`/`Referer`; a partial match is impossible                                                                                                                                                                                                    |
+| `prerender-store`                                                                 | pre-read or match | `Prerender()` route served by its baked artifact (pre-read probe of the normal variant; reclassified post-match when the store actually served, either variant)                                                                                                           |
+| `intercept`                                                                       | match             | the navigation resolved to an intercept — replay is never armed for intercepts (they keep their normal cache path); no heal capture                                                                                                                                       |
+| `cache-disabled`                                                                  | pre-read or match | `cache(false)` (pre-read, static) or `condition()` false (decided at the lookup); consumer opt-out is absolute                                                                                                                                                            |
+| `read-error`, `no-entry`, `invalid-version`, `corrupt-entry`, `stale-build-entry` | shell read        | no usable shell entry (`no-entry`/`invalid-version`/`corrupt-entry`/`stale-build-entry` schedule the navigation-only heal capture)                                                                                                                                        |
+| `handler-live-holes`, `transition-when`, `no-segment-snapshot`                    | eligibility       | entry exists but its snapshot cannot replay (no canonical doc record, or handler/transition liveness); on a route with an enabled `cache()` scope, `no-segment-snapshot` heals when the lookup did not refuse (a `condition()` false-at-capture entry becomes replayable) |
+| `explicit-cache-hit`                                                              | match             | the route's own `cache()` tier supplied the match                                                                                                                                                                                                                         |
+| `snapshot-miss`                                                                   | match             | an eligible snapshot was seeded but matching did not consume it                                                                                                                                                                                                           |
 
 ### Capture-generation invalidation
 

package/skills/router-setup/SKILL.md

@@ -120,8 +120,13 @@ interface RangoOptions<TEnv> {
   // Set to false to disable prefetch caching.
   prefetchCacheTTL?: number | false;
 
-  // Default prefetch strategy for Links without a `prefetch` prop
-  // (dev: "none", production: "viewport"). Per-Link props win in both directions.
+  // Default prefetch strategy for Links without a `prefetch` prop and for
+  // intercepted plain anchors inside basename. false/none opts out; true allows
+  // an application route whose path has a common static-resource extension.
+  // data-prefetch-scope="false"/"none" on a container is a hard subtree
+  // opt-out for both Links and plain anchors, including explicit opt-ins.
+  // (dev: "none", production: "viewport").
+  // Per-Link props win over the router default, not a disabled container scope.
   defaultPrefetch?: "hover" | "viewport" | "render" | "adaptive" | "none";
 
   // CSP nonce provider (for router.fetch)

package/skills/testing/client-components.md

@@ -8,20 +8,21 @@ RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter
 
 ### Options — `RenderRouteOptions`
 
-| Field           | Type                                                                   | Meaning                                                                                                                                                                                                              |
-| --------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `request`       | `Request \| string`                                                    | Initial location. Only the URL is read (client render — headers/method ignored). Defaults to the leaf spec's static prefix or `"/"`.                                                                                 |
-| `loaderData`    | `Record<string, unknown>`                                              | Loader data keyed by loader `$$id`. `useLoader(L)` reads `loaderData[L.$$id]`.                                                                                                                                       |
-| `loaders`       | `ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>`             | Seed by REFERENCE: `[loader, data]` pairs. Robust for real `createLoader()` handles whose `$$id` is empty in a bare test. Prefer over `loaderData`.                                                                  |
-| `params`        | `Record<string, string>`                                               | Explicit params, merged over (and overriding) params extracted from the `request` URL.                                                                                                                               |
-| `locationState` | `ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>` | Seed `useLocationState(def)` by REFERENCE: `[def, value]` pairs; written to `history.state`.                                                                                                                         |
-| `handles`       | `ReadonlyArray<readonly [Handle<any, any>, unknown[]]>`                | Seed `useHandle(handle)` by REFERENCE: `[handle, pushedValues[]]`. Accumulated GLOBALLY (not segment-scoped).                                                                                                        |
-| `handle`        | `HandleDataSeed`                                                       | Advanced: raw wire format `{ [handleId]: { [segmentId]: pushedValues[] } }`. Prefer `handles`. Merged with it.                                                                                                       |
-| `routeMap`      | `Record<string, string>`                                               | Name -> pattern map (informational; client `useReverse` takes its map as an argument, so this is not consumed).                                                                                                      |
-| `basename`      | `string`                                                               | `createRouter({ basename })` value. Wired into `NavigationProvider` so `useRouter().basename`, `<Link>` prefixing, `useMount`/`useHref` resolve against the mount. Normalized like `createRouter`. Defaults to root. |
-| `mount`         | `string`                                                               | `include()` mount prefix. Wraps the segment chain in a `MountContext` so `useMount()` returns the prefix. Normalized like a path prefix. Defaults to `"/"`.                                                          |
-| `theme`         | `ThemeConfig \| true`                                                  | Theme config (`createRouter({ theme })` shape) to wrap the tree in a `ThemeProvider`. Defaults to no provider. A component calling `useTheme()` REQUIRES one.                                                        |
-| `nonce`         | `string`                                                               | CSP nonce to seed via `NonceContext`, so a component calling `useNonce()` (e.g. an analytics/GTM head script) sees it — mirroring SSR. Defaults to `undefined` (the browser default).                                |
+| Field             | Type                                                                   | Meaning                                                                                                                                                                                                                                       |
+| ----------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request`         | `Request \| string`                                                    | Initial location. Only the URL is read (client render — headers/method ignored). Defaults to the leaf spec's static prefix or `"/"`.                                                                                                          |
+| `loaderData`      | `Record<string, unknown>`                                              | Loader data keyed by loader `$$id`. `useLoader(L)` reads `loaderData[L.$$id]`.                                                                                                                                                                |
+| `loaders`         | `ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>`             | Seed by REFERENCE: `[loader, data]` pairs. Robust for real `createLoader()` handles whose `$$id` is empty in a bare test. Prefer over `loaderData`.                                                                                           |
+| `params`          | `Record<string, string>`                                               | Explicit params, merged over (and overriding) params extracted from the `request` URL.                                                                                                                                                        |
+| `locationState`   | `ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>` | Seed `useLocationState(def)` by REFERENCE: `[def, value]` pairs; written to `history.state`.                                                                                                                                                  |
+| `handles`         | `ReadonlyArray<readonly [Handle<any, any>, unknown[]]>`                | Seed `useHandle(handle)` by REFERENCE: `[handle, pushedValues[]]`. Accumulated GLOBALLY (not segment-scoped).                                                                                                                                 |
+| `handle`          | `HandleDataSeed`                                                       | Advanced: raw wire format `{ [handleId]: { [segmentId]: pushedValues[] } }`. Prefer `handles`. Merged with it.                                                                                                                                |
+| `routeMap`        | `Record<string, string>`                                               | Name -> pattern map (informational; client `useReverse` takes its map as an argument, so this is not consumed).                                                                                                                               |
+| `basename`        | `string`                                                               | `createRouter({ basename })` value. Wired into `NavigationProvider` so `useRouter().basename`, `<Link>` prefixing, `useMount`/`useHref` resolve against the mount. Normalized like `createRouter`. Defaults to root.                          |
+| `mount`           | `string`                                                               | `include()` mount prefix. Wraps the segment chain in a `MountContext` so `useMount()` returns the prefix. Normalized like a path prefix. Defaults to `"/"`.                                                                                   |
+| `theme`           | `ThemeConfig \| true`                                                  | Theme config (`createRouter({ theme })` shape) to wrap the tree in a `ThemeProvider`. Defaults to no provider. A component calling `useTheme()` REQUIRES one.                                                                                 |
+| `nonce`           | `string`                                                               | CSP nonce to seed via `NonceContext`, so a component calling `useNonce()` (e.g. an analytics/GTM head script) sees it — mirroring SSR. Defaults to `undefined` (the browser default).                                                         |
+| `defaultPrefetch` | `PrefetchStrategy`                                                     | Router default for `<Link>` and eligible plain anchors. `data-prefetch="false"`/`"none"` opts out one anchor; ancestor `data-prefetch-scope="false"`/`"none"` hard-disables the subtree; `"true"` permits routed resource suffixes elsewhere. |
 
 `RenderRouteSpec = { path, Component, layout?, loaderIds?, name? }` — one node of the route definition. The array is the layout chain root-to-leaf; the LAST entry is the leaf route (its pattern is matched against `request` to extract params; layout patterns are informational). `loaderIds` attaches seeded loaders to THIS node's segment; `layout` on the leaf wraps it; `name` is informational.
 

package/skills/vercel/SKILL.md

@@ -56,7 +56,7 @@ Per-function knobs go under `vercel` and are written into `.vc-config.json`:
 rango({
   preset: "vercel",
   vercel: {
-    runtime: "nodejs22.x", // default
+    runtime: "nodejs24.x", // default
     maxDuration: 30, // seconds, default
     memory: 1024, // MB (platform default when omitted)
     regions: ["fra1"], // pin regions (platform default when omitted)

package/src/browser/event-controller.ts

@@ -14,6 +14,7 @@ import {
   filterSegmentOrder,
   filterRouteSegmentIds,
 } from "./react/filter-segment-order.js";
+import { notifyListeners } from "./notify-listeners.js";
 
 // Polyfill Symbol.dispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -269,6 +270,71 @@ export interface EventController {
   hadAnyConcurrentActions(): boolean;
 }
 
+type LocationChangeController = Pick<EventController, "getState" | "subscribe">;
+
+interface LocationChangeSubscription {
+  registrations: Map<
+    symbol,
+    { href: string; listener: (href: string) => void }
+  >;
+  notificationVersion: number;
+  unsubscribe: () => void;
+}
+
+const locationChangeSubscriptions = new WeakMap<
+  LocationChangeController,
+  LocationChangeSubscription
+>();
+
+/** Share one controller subscription across all location-change consumers. */
+export function subscribeToLocationChange(
+  eventController: LocationChangeController,
+  listener: (href: string) => void,
+): () => void {
+  let subscription = locationChangeSubscriptions.get(eventController);
+  if (!subscription) {
+    subscription = {
+      registrations: new Map(),
+      notificationVersion: 0,
+      unsubscribe: () => {},
+    };
+    locationChangeSubscriptions.set(eventController, subscription);
+    const currentSubscription = subscription;
+    subscription.unsubscribe = eventController.subscribe(() => {
+      const notificationVersion = ++currentSubscription.notificationVersion;
+      const nextHref = eventController.getState().location.href;
+      notifyListeners(
+        [...currentSubscription.registrations],
+        ([, registration]) => {
+          if (registration.href === nextHref) return;
+          registration.href = nextHref;
+          registration.listener(nextHref);
+        },
+        ([token, registration]) =>
+          currentSubscription.registrations.get(token) === registration,
+        () => notificationVersion === currentSubscription.notificationVersion,
+      );
+    });
+  }
+
+  const token = Symbol();
+  subscription.registrations.set(token, {
+    href: eventController.getState().location.href,
+    listener,
+  });
+  let active = true;
+  return () => {
+    if (!active) return;
+    active = false;
+    subscription!.registrations.delete(token);
+    if (subscription!.registrations.size > 0) return;
+    if (locationChangeSubscriptions.get(eventController) === subscription) {
+      locationChangeSubscriptions.delete(eventController);
+    }
+    subscription!.unsubscribe();
+  };
+}
+
 const DEFAULT_ACTION_STATE: TrackedActionState = {
   state: "idle",
   actionId: null,
@@ -308,7 +374,11 @@ function makeDebouncedNotifier(listeners: Set<() => void>): () => void {
     if (timeout !== null) clearTimeout(timeout);
     timeout = setTimeout(() => {
       timeout = null;
-      listeners.forEach((listener) => listener());
+      notifyListeners(
+        [...listeners],
+        (listener) => listener(),
+        (listener) => listeners.has(listener),
+      );
     }, 0);
   };
 }
@@ -394,6 +464,39 @@ export function createEventController(
 
   const actionNotifyTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
 
+  function notifyActionListenerSets(
+    subscriptions: Iterable<[string, Set<ActionStateListener>]>,
+  ): void {
+    const subscriptionSnapshots = [...subscriptions].map(
+      ([subscriptionId, listeners]) => ({
+        listenerSnapshot: [...listeners],
+        listeners,
+        subscriptionId,
+      }),
+    );
+    function* notifications(): Generator<{
+      listener: ActionStateListener;
+      listeners: Set<ActionStateListener>;
+      state: TrackedActionState;
+    }> {
+      for (const {
+        listenerSnapshot,
+        listeners,
+        subscriptionId,
+      } of subscriptionSnapshots) {
+        const state = getActionState(subscriptionId);
+        for (const listener of listenerSnapshot) {
+          yield { listener, listeners, state };
+        }
+      }
+    }
+    notifyListeners(
+      notifications(),
+      ({ listener, state }) => listener(state),
+      ({ listener, listeners }) => listeners.has(listener),
+    );
+  }
+
   function notifyAction(actionId: string) {
     const existing = actionNotifyTimeouts.get(actionId);
     if (existing !== undefined) {
@@ -403,12 +506,11 @@ export function createEventController(
       actionId,
       setTimeout(() => {
         actionNotifyTimeouts.delete(actionId);
-        for (const [subscriptionId, listeners] of actionListeners) {
-          if (matchesActionId(subscriptionId, actionId)) {
-            const state = getActionState(subscriptionId);
-            listeners.forEach((listener) => listener(state));
-          }
-        }
+        notifyActionListenerSets(
+          [...actionListeners].filter(([subscriptionId]) =>
+            matchesActionId(subscriptionId, actionId),
+          ),
+        );
       }, 0),
     );
   }
@@ -846,10 +948,7 @@ export function createEventController(
     // "addToCart"), not full entry actionIds. Passing them to notifyAction
     // would fail the suffix matcher — instead, notify each subscriber with
     // its own state.
-    for (const [subscriptionId, listeners] of actionListeners) {
-      const state = getActionState(subscriptionId);
-      listeners.forEach((listener) => listener(state));
-    }
+    notifyActionListenerSets(actionListeners);
   }
 
   // ========================================================================