@rangojs/router 0.1.0 → 0.2.0

package/skills/view-transitions/SKILL.md

@@ -209,9 +209,8 @@ interface TransitionConfig {
   default?: string | Record<string, string>; // fallback for any phase
   name?: string; // explicit view-transition-name
   viewTransition?: "auto" | false; // boundary opt-out (see below)
-  // Conditional gate, evaluated server-side AFTER the route handler. Return
-  // false to drop this transition for the request, so the navigation streams its
-  // loading() fallback instead of holding. See the gate section below.
+  // Conditional server-side gate. PPR routes run it before route handlers and
+  // on every replay; other routes run it after handlers on fresh resolution.
   when?: (ctx: TransitionWhenContext) => boolean;
 }
 ```
@@ -223,14 +222,19 @@ interface TransitionConfig {
 
 ## Conditional transitions (`when`)
 
-`transition({ when })` gates the hold per request. The predicate runs **server-side, AFTER the route handler** and outside any cache scope; return `false` to drop this segment's transition for the request (the navigation streams its `loading()` fallback instead of holding).
+`transition({ when })` gates the hold per request. The predicate runs server-side and outside any cache scope; return `false` to drop this segment's transition for the request (the navigation streams its `loading()` fallback instead of holding).
 
-Its context mirrors the `revalidate()` predicate args — the same navigation/action metadata — plus `get`/`env` for post-handler reads:
+Timing follows the route's rendering contract:
+
+- On an ordinary route it runs after the route handler during fresh resolution, so `get()` can read handler- and middleware-set context. Cache/prerender hits replay the stored decision.
+- On a `ppr` route it is automatically hoisted before route handlers and runs on every match, including runtime-cache, prerender, document-shell, and partial-navigation replay. It can read URL/params/action metadata, `env`, and middleware-set context, but not values set by route handlers. This is what keeps the handler-free PPR fast path available without a second API.
+
+Its context mirrors the `revalidate()` predicate args — the same navigation/action metadata — plus `get`/`env` for request-context reads:
 
 ```ts
 import type { TransitionWhenContext } from "@rangojs/router";
 
-// Hold only when the handler marked this request (handler sets, gate reads):
+// Ordinary route: hold only when the handler marked this request:
 transition({ when: (ctx) => ctx.get(KeepScroll) === true });
 
 // Hold only when arriving from a specific page (the navigation SOURCE):
@@ -252,13 +256,13 @@ transition({
 | `toRouteName` (and `fromRouteName`)                    | route **name**                               | when the route is named (undefined for unnamed/auto-generated)                        |
 | `actionId` / `actionUrl` / `actionResult` / `formData` | the server action that triggered this render | action-triggered renders only                                                         |
 | `method`                                               | `"GET"` (nav) / `"POST"` (action)            | always                                                                                |
-| `get` / `env`                                          | read handler/middleware vars + app env       | always                                                                                |
+| `get` / `env`                                          | read request vars + app env                  | always; PPR timing exposes middleware vars, not handler writes                        |
 
 A predicate that throws is reported to `router.onError` (phase `"rendering"`) and treated as no-hold (conservative).
 
 **Same-route content-holds need the transition present on the FIRST render.** The same-route hold works by giving the route a param-agnostic key so a param change reconciles instead of remounting — but that key is established when the route first mounts. A source gate that returns `false` on the initial full load (where `currentUrl`/`currentParams`/`fromRouteName` are undefined) drops the transition before the route mounts, so the route mounts _outside_ a transition scope and **every** later same-route param nav remounts (flashing the skeleton) regardless of what the gate decides on those navs. Write source gates so they hold when there is no source — e.g. `({ currentParams }) => currentParams?.tab !== "raw"` (true on the initial load) rather than `=== "details"` (false on the initial load) — when the same-route content-hold must engage. This only affects same-route param navigations; action-only or cross-route gating is unaffected (no shared param key is in play).
 
-**Prefetch / cache caveat.** The gate runs during resolution, so a **prefetched** navigation decides at prefetch time — `currentUrl`/`currentParams`/`fromRouteName` reflect the page the prefetch fired from, not necessarily the click-time source — and a `cache()`/prerender hit replays the stored transition without re-running the predicate. A source-sensitive gate can therefore be frozen to prefetch/store-time state. This covers ~99% of navigations; if yours must reflect the exact click-time source, source-scope the prefetch (`<Link prefetchKey=":source">`) and don't `cache()` that segment.
+**Prefetch / cache caveat.** A **prefetched** navigation still decides at prefetch time — `currentUrl`/`currentParams`/`fromRouteName` reflect the page the prefetch fired from, not necessarily the click-time source. Non-PPR `cache()`/prerender hits also replay the stored transition without rerunning the predicate. PPR routes rerun it on the server for each cache/prerender/PPR match, but a completed browser prefetch still carries its earlier Flight decision. If the exact click-time source matters, source-scope the prefetch (`<Link prefetchKey=":source">`).
 
 ## Opting out of the router boundary (place your own `<ViewTransition>`)
 

package/src/browser/dev-discovery.ts

@@ -0,0 +1,66 @@
+import {
+  DEV_DISCOVERY_QUERY_EVENT,
+  DEV_DISCOVERY_READY_EVENT,
+  isValidDevDiscoveryEpoch,
+} from "../dev-discovery-protocol.js";
+
+export interface DevDiscoveryHot {
+  on(
+    event: typeof DEV_DISCOVERY_READY_EVENT | "vite:ws:connect",
+    listener: (payload: unknown) => void,
+  ): void;
+  send(
+    event: typeof DEV_DISCOVERY_QUERY_EVENT,
+    payload: { epoch: number },
+  ): void;
+}
+
+export interface DevDiscoveryHandshakeOptions {
+  reload?: () => void;
+}
+
+function readEpoch(payload: unknown): number | undefined {
+  if (
+    typeof payload !== "object" ||
+    payload === null ||
+    !("epoch" in payload)
+  ) {
+    return undefined;
+  }
+
+  return isValidDevDiscoveryEpoch(payload.epoch) ? payload.epoch : undefined;
+}
+
+export function startDevDiscoveryHandshake(
+  documentEpoch: unknown,
+  hot: DevDiscoveryHot,
+  options: DevDiscoveryHandshakeOptions = {},
+): void {
+  if (!isValidDevDiscoveryEpoch(documentEpoch)) return;
+  const currentDocumentEpoch = documentEpoch;
+
+  const reload = options.reload ?? (() => window.location.reload());
+  let reloadRequested = false;
+
+  function reloadIfNewer(payload: unknown): void {
+    const readyEpoch = readEpoch(payload);
+    if (
+      reloadRequested ||
+      readyEpoch === undefined ||
+      readyEpoch <= currentDocumentEpoch
+    ) {
+      return;
+    }
+
+    reloadRequested = true;
+    reload();
+  }
+
+  function requestReadyEpoch(): void {
+    hot.send(DEV_DISCOVERY_QUERY_EVENT, { epoch: currentDocumentEpoch });
+  }
+
+  hot.on(DEV_DISCOVERY_READY_EVENT, reloadIfNewer);
+  hot.on("vite:ws:connect", requestReadyEpoch);
+  requestReadyEpoch();
+}

package/src/browser/navigation-client.ts

@@ -28,6 +28,7 @@ import {
   consumePrefetch,
   type DecodedPrefetch,
 } from "./prefetch/cache.js";
+import { cancelAllPrefetches } from "./prefetch/loader.js";
 
 /**
  * Create a navigation client for fetching RSC payloads
@@ -101,6 +102,11 @@ export function createNavigationClient(
         fetchUrl.searchParams.set("_rsc_rid", routerId);
       }
 
+      // If the lazy prefetch runtime has not loaded yet, prevent a deferred
+      // speculative request from starting after this navigation misses the
+      // synchronous cache lookup and begins its own fetch.
+      cancelAllPrefetches(targetUrl);
+
       // Check completed in-memory prefetch cache before making a network
       // request. Try the source-scoped key first (populated when the server
       // tagged the prefetch response as source-sensitive, e.g. intercepts,

package/src/browser/navigation-store.ts

@@ -1,30 +1,14 @@
 import type {
-  NavigationState,
   NavigationLocation,
   SegmentState,
   NavigationStore,
   NavigationUpdate,
   UpdateSubscriber,
-  StateListener,
   ResolvedSegment,
-  InflightAction,
-  TrackedActionState,
-  ActionStateListener,
   HandleData,
 } from "./types.js";
 import { clearPrefetchCache } from "./prefetch/cache.js";
 
-/**
- * Default action state (idle with no payload)
- */
-const DEFAULT_ACTION_STATE: TrackedActionState = {
-  state: "idle",
-  actionId: null,
-  payload: null,
-  error: null,
-  result: null,
-};
-
 // Maximum number of history entries to cache (URLs visited)
 const HISTORY_CACHE_SIZE = 20;
 
@@ -177,11 +161,10 @@ function createLocation(loc: { href: string }): NavigationLocation {
 }
 
 /**
- * Create a navigation store for managing browser-side navigation state
+ * Create a navigation store for browser-side segment and history state.
  *
- * The store manages two types of state:
- * - NavigationState: Public state exposed via useNavigation hook
- * - SegmentState: Internal segment management for partial RSC updates
+ * The public navigation lifecycle lives in EventController; this store owns
+ * segment reconciliation, history snapshots, and cross-tab cache invalidation.
  *
  * @param config - Initial configuration
  * @returns NavigationStore instance
@@ -193,15 +176,6 @@ function createLocation(loc: { href: string }): NavigationLocation {
  *   initialSegmentIds: [],
  * });
  *
- * // Subscribe to state changes (for useNavigation hook)
- * const unsubscribe = store.subscribe(() => {
- *   const state = store.getState();
- *   console.log('Navigation state:', state);
- * });
- *
- * // Update state
- * store.setState({ state: 'loading' });
- *
  * // Subscribe to UI updates (for re-rendering)
  * store.onUpdate((update) => {
  *   console.log('New root:', update.root);
@@ -217,19 +191,6 @@ export function createNavigationStore(
       ? createLocation(window.location)
       : new URL("/", "http://localhost");
 
-  // Public navigation state (for useNavigation hook)
-  // isStreaming starts false to match SSR and avoid hydration mismatch
-  // After hydration, entry.browser.tsx sets it to true if stream is still open
-  let navState: NavigationState = {
-    state: "idle",
-    isStreaming: false,
-    location: config?.initialLocation
-      ? createLocation(config.initialLocation)
-      : defaultLocation,
-    pendingUrl: null,
-    inflightActions: [],
-  };
-
   // Resolve the initial location for segment state
   const initialLoc = config?.initialLocation
     ? createLocation(config.initialLocation)
@@ -251,9 +212,6 @@ export function createNavigationStore(
   let crossTabRefreshCallback: (() => void) | null =
     config?.onCrossTabRefresh ?? null;
 
-  // Track pending cross-tab refresh to prevent duplicate refreshes
-  let pendingCrossTabRefresh = false;
-
   // History-based segment cache: array of [url-key, segments] tuples
   // Each URL gets its own complete snapshot of segments for back/forward and partial merging
   // Oldest entries (at front) are removed when over cacheSize limit
@@ -283,15 +241,9 @@ export function createNavigationStore(
     ]);
   }
 
-  // State change listeners (for useNavigation subscriptions)
-  const stateListeners = new Set<StateListener>();
-
   // UI update subscribers (for re-rendering)
   const updateSubscribers = new Set<UpdateSubscriber>();
 
-  // Internal flag to track if a server action is in progress
-  let actionInProgress = false;
-
   // Intercept source URL - tracks where the intercept was triggered from
   // Used to maintain intercept context during action revalidation
   let interceptSourceUrl: string | null = null;
@@ -301,63 +253,6 @@ export function createNavigationStore(
   // tree replacement instead of reconciling with stale segments.
   let currentRouterId: string | undefined;
 
-  // Action state tracking (for useAction hook)
-  // Maps action function ID to its tracked state
-  const actionStates = new Map<string, TrackedActionState>();
-
-  // Action state listeners (per action ID)
-  // Maps action function ID to set of listeners
-  const actionListeners = new Map<string, Set<ActionStateListener>>();
-
-  /**
-   * Create a debounced function that batches rapid calls
-   */
-  // A non-keyed notifier is the keyed one restricted to a single constant key;
-  // its own keyed instance means the "" key never collides with action keys.
-  function createDebouncedNotifier<T extends (...args: any[]) => void>(
-    fn: T,
-    ms: number = 20,
-  ): T {
-    const keyed = createKeyedDebouncedNotifier(
-      (_key: string, ...args: any[]) => fn(...args),
-      ms,
-    );
-    return ((...args: Parameters<T>) => keyed("", ...args)) as T;
-  }
-
-  /**
-   * Create a keyed debounced function (separate timers per key)
-   */
-  function createKeyedDebouncedNotifier<
-    T extends (key: string, ...args: any[]) => void,
-  >(fn: T, ms: number = 20): T {
-    const timeouts = new Map<string, ReturnType<typeof setTimeout>>();
-    return ((key: string, ...args: any[]) => {
-      const existing = timeouts.get(key);
-      if (existing !== undefined) clearTimeout(existing);
-      timeouts.set(
-        key,
-        setTimeout(() => {
-          timeouts.delete(key);
-          fn(key, ...args);
-        }, ms),
-      );
-    }) as T;
-  }
-
-  const notifyStateListeners = createDebouncedNotifier(() => {
-    stateListeners.forEach((listener) => listener());
-  });
-
-  const notifyActionListeners = createKeyedDebouncedNotifier(
-    (actionId: string, state: TrackedActionState) => {
-      const listeners = actionListeners.get(actionId);
-      if (listeners) {
-        listeners.forEach((listener) => listener(state));
-      }
-    },
-  );
-
   /**
    * Clear the history cache (internal - does not broadcast)
    */
@@ -450,22 +345,7 @@ export function createNavigationStore(
 
           // Auto-refresh if enabled and callback is registered
           if (crossTabAutoRefresh && crossTabRefreshCallback) {
-            // If idle, refresh immediately. If loading, wait for idle then refresh.
-            if (navState.state === "idle") {
-              crossTabRefreshCallback();
-            } else if (!pendingCrossTabRefresh) {
-              // Only queue one refresh, ignore subsequent events while loading
-              pendingCrossTabRefresh = true;
-              // Subscribe to state changes, refresh when idle
-              const listener: StateListener = () => {
-                if (navState.state === "idle") {
-                  stateListeners.delete(listener);
-                  pendingCrossTabRefresh = false;
-                  crossTabRefreshCallback?.();
-                }
-              };
-              stateListeners.add(listener);
-            }
+            crossTabRefreshCallback();
           }
         }
       };
@@ -473,80 +353,6 @@ export function createNavigationStore(
   }
 
   return {
-    // ========================================================================
-    // Public State (for useNavigation hook)
-    // ========================================================================
-
-    /**
-     * Get current navigation state
-     */
-    getState(): NavigationState {
-      return navState;
-    },
-
-    /**
-     * Update navigation state and notify listeners
-     */
-    setState(partial: Partial<NavigationState>): void {
-      navState = { ...navState, ...partial };
-      notifyStateListeners();
-    },
-
-    /**
-     * Subscribe to state changes
-     * Returns unsubscribe function
-     */
-    subscribe(listener: StateListener): () => void {
-      stateListeners.add(listener);
-      return () => {
-        stateListeners.delete(listener);
-      };
-    },
-
-    // ========================================================================
-    // Inflight Action Management
-    // ========================================================================
-
-    /**
-     * Add an inflight action to the list
-     */
-    addInflightAction(action: InflightAction): void {
-      navState = {
-        ...navState,
-        inflightActions: [...navState.inflightActions, action],
-      };
-      notifyStateListeners();
-    },
-
-    /**
-     * Remove an inflight action by ID
-     */
-    removeInflightAction(id: string): void {
-      navState = {
-        ...navState,
-        inflightActions: navState.inflightActions.filter((a) => a.id !== id),
-      };
-      notifyStateListeners();
-    },
-
-    // ========================================================================
-    // Action State (for controlling update behavior during server actions)
-    // ========================================================================
-
-    /**
-     * Check if a server action is currently in progress
-     */
-    isActionInProgress(): boolean {
-      return actionInProgress;
-    },
-
-    /**
-     * Set the action in progress flag
-     */
-    setActionInProgress(value: boolean): void {
-      actionInProgress = value;
-    },
-
     // ========================================================================
     // Internal Segment State (for bridges)
     // ========================================================================
@@ -609,17 +415,6 @@ export function createNavigationStore(
       return navInstance;
     },
 
-    /**
-     * The nav-instance token recorded on a specific cache entry, or undefined if
-     * no entry exists for that key. Because the history key is URL-only, this is
-     * how a late resolution tells "the entry I seeded is still mine" from "a
-     * newer same-URL visit replaced my entry".
-     */
-    getCacheEntryInstance(historyKey: string): number | undefined {
-      const entry = historyCache.find(([key]) => key === historyKey);
-      return entry ? entry[5] : undefined;
-    },
-
     /**
      * Store segments for a history entry
      * Updates existing entry if key exists, otherwise adds new entry
@@ -777,14 +572,6 @@ export function createNavigationStore(
       ];
     },
 
-    /**
-     * Mark all cache entries as stale
-     * Called after server actions to indicate data may be outdated
-     */
-    markCacheAsStale(): void {
-      markCacheAsStaleInternal();
-    },
-
     /**
      * Mark every history entry stale WITHOUT clearing the prefetch caches or
      * rotating the rango state. The jar-divergence observer calls this after an
@@ -871,59 +658,5 @@ export function createNavigationStore(
         callback(update);
       });
     },
-
-    // ========================================================================
-    // Action State Tracking (for useAction hook)
-    // ========================================================================
-
-    /**
-     * Get the current state for a tracked action
-     * Returns default idle state if action hasn't been tracked
-     */
-    getActionState(actionId: string): TrackedActionState {
-      return actionStates.get(actionId) ?? { ...DEFAULT_ACTION_STATE };
-    },
-
-    /**
-     * Update the state for a tracked action
-     * Merges partial state with existing state and notifies listeners
-     */
-    setActionState(
-      actionId: string,
-      partial: Partial<TrackedActionState>,
-    ): void {
-      const current = actionStates.get(actionId) ?? { ...DEFAULT_ACTION_STATE };
-      const updated: TrackedActionState = {
-        ...current,
-        ...partial,
-        actionId, // Always set the actionId
-      };
-      actionStates.set(actionId, updated);
-      notifyActionListeners(actionId, updated);
-    },
-
-    /**
-     * Subscribe to state changes for a specific action
-     * Returns unsubscribe function
-     */
-    subscribeToAction(
-      actionId: string,
-      listener: ActionStateListener,
-    ): () => void {
-      let listeners = actionListeners.get(actionId);
-      if (!listeners) {
-        listeners = new Set();
-        actionListeners.set(actionId, listeners);
-      }
-      listeners.add(listener);
-
-      return () => {
-        listeners!.delete(listener);
-        // Clean up empty listener sets
-        if (listeners!.size === 0) {
-          actionListeners.delete(actionId);
-        }
-      };
-    },
   };
 }

package/src/browser/partial-update.ts

@@ -550,20 +550,13 @@ export function createPartialUpdater(
           });
         });
       } else {
-        // Normal commit (cold/partial nav AND fully-prefetched nav). For a
-        // fully-prefetched nav, renderOptions.forceAwait (above) unwrapped the
-        // already-resolved ROUTER loader data AND route content during render, so
-        // the new tree carries it inline with no loading()/fallback frame — yet we
-        // still commit NORMALLY here rather than in a transition. A transition
-        // holds the OLD UI until ALL suspense in the new tree settles, including a
-        // CLIENT component that starts its own data request only when mounted
-        // (post-commit) under a persistent boundary; that would retain the
-        // previous page indefinitely with no feedback. A normal commit lets such
-        // client-initiated suspense reveal a fallback (correct) while the router
-        // data — genuinely ready — never flashes. Cold/partial navs
-        // (fullyPrefetched=false) do not forceAwait, so they stream their
-        // fallbacks. Explicit transition() routes keep the broader content-hold
-        // via the hasTransition branch above (the documented opt-in).
+        // Normal commit for ALL navs here, never a transition (see the
+        // forceAwait comment above for why prefetched router data lands
+        // without fallback frames). A transition would hold the OLD UI until
+        // every suspense in the new tree settles — including a client
+        // component that only starts fetching post-mount, retaining the
+        // previous page indefinitely. Explicit transition() routes keep the
+        // content-hold via the hasTransition branch above (the opt-in).
         onUpdate({
           root: newTree,
           metadata: payload.metadata!,

package/src/browser/prefetch/cache.ts

@@ -39,7 +39,7 @@
  * effectively per-document. Unit tests reset them via clearPrefetchCache().
  */
 
-import { abortAllPrefetches } from "./queue.js";
+import { abortAllPrefetches } from "./loader.js";
 import { invalidateRangoState } from "../rango-state.js";
 import type { RscPayload } from "../types.js";
 

package/src/browser/prefetch/loader.ts

@@ -0,0 +1,110 @@
+import type { RscPayload } from "../types.js";
+
+type PrefetchDecoder = (response: Promise<Response>) => Promise<RscPayload>;
+
+type PrefetchRuntime = typeof import("./runtime.js");
+
+let runtime: PrefetchRuntime | null = null;
+let runtimePromise: Promise<PrefetchRuntime> | null = null;
+let decoder: PrefetchDecoder | null = null;
+let concurrency: number | undefined;
+let requestGeneration = 0;
+
+function loadRuntime(): Promise<PrefetchRuntime> {
+  if (runtime) return Promise.resolve(runtime);
+  if (!runtimePromise) {
+    runtimePromise = import("./runtime.js").then(
+      (loaded) => {
+        runtime = loaded;
+        if (decoder) loaded.setPrefetchDecoder(decoder);
+        if (concurrency !== undefined) {
+          loaded.setPrefetchConcurrency(concurrency);
+        }
+        return loaded;
+      },
+      (error: unknown) => {
+        runtimePromise = null;
+        throw error;
+      },
+    );
+  }
+  return runtimePromise;
+}
+
+function withRuntime(run: (loaded: PrefetchRuntime) => void): void {
+  if (runtime) {
+    run(runtime);
+    return;
+  }
+  const generation = requestGeneration;
+  void loadRuntime()
+    .then((loaded) => {
+      if (generation === requestGeneration) run(loaded);
+    })
+    .catch(() => {});
+}
+
+export function setPrefetchDecoder(fn: PrefetchDecoder): void {
+  decoder = fn;
+  runtime?.setPrefetchDecoder(fn);
+}
+
+export function setPrefetchConcurrency(value: number): void {
+  concurrency = value;
+  runtime?.setPrefetchConcurrency(value);
+}
+
+export function prefetchDirect(
+  url: string,
+  segmentIds: string[],
+  version?: string,
+  routerId?: string,
+  prefetchKey?: ":source",
+): void {
+  withRuntime((loaded) =>
+    loaded.prefetchDirect(url, segmentIds, version, routerId, prefetchKey),
+  );
+}
+
+export function prefetchQueued(
+  url: string,
+  segmentIds: string[],
+  version?: string,
+  routerId?: string,
+  prefetchKey?: ":source",
+): void {
+  withRuntime((loaded) =>
+    loaded.prefetchQueued(url, segmentIds, version, routerId, prefetchKey),
+  );
+}
+
+export function observeForPrefetch(
+  element: Element,
+  callback: () => void,
+): () => void {
+  if (typeof IntersectionObserver === "undefined") return () => {};
+  let active = true;
+  if (runtime) {
+    runtime.observeForPrefetch(element, callback);
+  } else {
+    void loadRuntime()
+      .then((loaded) => {
+        if (active) loaded.observeForPrefetch(element, callback);
+      })
+      .catch(() => {});
+  }
+  return () => {
+    active = false;
+    runtime?.unobserveForPrefetch(element);
+  };
+}
+
+export function cancelAllPrefetches(keepUrl?: string | null): void {
+  requestGeneration++;
+  runtime?.cancelAllPrefetches(keepUrl);
+}
+
+export function abortAllPrefetches(): void {
+  requestGeneration++;
+  runtime?.abortAllPrefetches();
+}

package/src/browser/prefetch/runtime.ts

@@ -0,0 +1,7 @@
+export { prefetchDirect, prefetchQueued, setPrefetchDecoder } from "./fetch.js";
+export {
+  abortAllPrefetches,
+  cancelAllPrefetches,
+  setPrefetchConcurrency,
+} from "./queue.js";
+export { observeForPrefetch, unobserveForPrefetch } from "./observer.js";