@rangojs/router 0.1.0 → 0.2.0

package/src/browser/react/Link.tsx

@@ -32,12 +32,12 @@ export type LinkState =
   | LocationStateEntry[]
   | StateOrGetter<Record<string, unknown>>;
 
-import { prefetchDirect, prefetchQueued } from "../prefetch/fetch.js";
-import { getAppVersion } from "../app-version.js";
 import {
   observeForPrefetch,
-  unobserveForPrefetch,
-} from "../prefetch/observer.js";
+  prefetchDirect,
+  prefetchQueued,
+} from "../prefetch/loader.js";
+import { getAppVersion } from "../app-version.js";
 
 // The (hover: none) MediaQueryList, created lazily on first client read and
 // reused across every Link render. matchMedia allocates and registers a live
@@ -394,7 +394,7 @@ export const Link: ForwardRefExoticComponent<
 
     let cancelled = false;
     let unsubIdle: (() => void) | undefined;
-    let observedElement: Element | null = null;
+    let stopObserving: (() => void) | undefined;
 
     const triggerPrefetch = () => {
       if (cancelled) return;
@@ -431,8 +431,7 @@ export const Link: ForwardRefExoticComponent<
     } else if (isViewport) {
       const element = internalRef.current;
       if (!element) return;
-      observedElement = element;
-      observeForPrefetch(element, () => {
+      stopObserving = observeForPrefetch(element, () => {
         scheduleWhenIdle(triggerPrefetch);
       });
     }
@@ -440,9 +439,7 @@ export const Link: ForwardRefExoticComponent<
     return () => {
       cancelled = true;
       unsubIdle?.();
-      if (isViewport && observedElement) {
-        unobserveForPrefetch(observedElement);
-      }
+      stopObserving?.();
     };
   }, [resolvedStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
 

package/src/browser/react/NavigationProvider.tsx

@@ -26,7 +26,7 @@ import type { HandleData } from "../types.js";
 import { ThemeProvider } from "../../theme/ThemeProvider.js";
 import { NonceContext } from "./nonce-context.js";
 import type { ResolvedThemeConfig, Theme } from "../../theme/types.js";
-import { cancelAllPrefetches } from "../prefetch/queue.js";
+import { cancelAllPrefetches } from "../prefetch/loader.js";
 import { handleNavigationEnd } from "../scroll-restoration.js";
 import { createAppShellRef, type AppShellRef } from "../app-shell.js";
 import { startConnectionWarmup } from "../connection-warmup.js";

package/src/browser/react/use-router.ts

@@ -2,7 +2,7 @@
 
 import { useContext, useMemo } from "react";
 import { NavigationStoreContext } from "./context.js";
-import { prefetchDirect } from "../prefetch/fetch.js";
+import { prefetchDirect } from "../prefetch/loader.js";
 import { getAppVersion } from "../app-version.js";
 import type { RouterInstance, RouterNavigateOptions } from "../types.js";
 

package/src/browser/rsc-router.tsx

@@ -26,8 +26,10 @@ import { expandSegmentFragments } from "../segment-fragments.js";
 import { initRangoState } from "./rango-state.js";
 import { registerNavigationStore } from "./navigation-store-handle.js";
 import { initPrefetchCache } from "./prefetch/cache.js";
-import { setPrefetchConcurrency } from "./prefetch/queue.js";
-import { setPrefetchDecoder } from "./prefetch/fetch.js";
+import {
+  setPrefetchConcurrency,
+  setPrefetchDecoder,
+} from "./prefetch/loader.js";
 import { setAppVersion } from "./app-version.js";
 import {
   isInterceptSegment,

package/src/browser/types.ts

@@ -65,6 +65,8 @@ export interface RscMetadata {
    * Used to detect version mismatches after HMR/deployment.
    */
   version?: string;
+  /** Cloudflare dev worker generation used for stale-document convergence. */
+  devDiscoveryEpoch?: number;
   /**
    * TTL in milliseconds for the client-side in-memory prefetch cache.
    * Sent on initial render so the browser can configure its cache duration.
@@ -430,24 +432,10 @@ export type StateListener = () => void;
 /**
  * Navigation store interface
  *
- * Manages both:
- * - NavigationState: Public state exposed via useNavigation hook
- * - SegmentState: Internal segment management for partial updates
+ * Owns segment state, history snapshots, and partial-update notifications.
+ * EventController owns the public navigation lifecycle exposed by hooks.
  */
 export interface NavigationStore {
-  // Public state (for useNavigation hook)
-  getState(): NavigationState;
-  setState(partial: Partial<NavigationState>): void;
-  subscribe(listener: StateListener): () => void;
-
-  // Inflight action management
-  addInflightAction(action: InflightAction): void;
-  removeInflightAction(id: string): void;
-
-  // Action state (for controlling update behavior during server actions)
-  isActionInProgress(): boolean;
-  setActionInProgress(value: boolean): void;
-
   // Internal segment state (for bridges)
   getSegmentState(): SegmentState;
   setPath(path: string): void;
@@ -459,8 +447,6 @@ export interface NavigationStore {
   setHistoryKey(key: string): void;
   /** Monotonic token of the most recently committed navigation. */
   getNavInstance(): number;
-  /** Nav-instance token recorded on a cache entry (undefined if absent). */
-  getCacheEntryInstance(historyKey: string): number | undefined;
   cacheSegmentsForHistory(
     historyKey: string,
     segments: ResolvedSegment[],
@@ -506,7 +492,6 @@ export interface NavigationStore {
     stale?: boolean,
     handlesPending?: boolean,
   ): void;
-  markCacheAsStale(): void;
   markHistoryCacheStale(): void;
   markCacheAsStaleAndBroadcast(): void;
   clearHistoryCache(): void;
@@ -525,14 +510,6 @@ export interface NavigationStore {
   // UI update notifications
   onUpdate(callback: UpdateSubscriber): () => void;
   emitUpdate(update: NavigationUpdate): void;
-
-  // Action state tracking (for useAction hook)
-  getActionState(actionId: string): TrackedActionState;
-  setActionState(actionId: string, state: Partial<TrackedActionState>): void;
-  subscribeToAction(
-    actionId: string,
-    listener: ActionStateListener,
-  ): () => void;
 }
 
 // ============================================================================

package/src/build/generate-manifest.ts

@@ -115,6 +115,7 @@ async function buildPrefixTreeNode(
   passthroughRoutes?: string[],
   responseTypeRoutes?: Record<string, string>,
   routeSearchSchemas?: Record<string, Record<string, string>>,
+  routerId?: string,
 ): Promise<PrefixTreeNode> {
   // Resolve an async include provider (`() => import("./routes")`) so its routes
   // are walked into the build-time manifest/types/href. Runtime matching still
@@ -156,6 +157,7 @@ async function buildPrefixTreeNode(
         parent: null,
         counters: {},
         mountIndex,
+        ...(routerId ? { routerId } : {}),
         trackedIncludes, // Enable nested include tracking
       },
       () => {
@@ -227,6 +229,7 @@ async function buildPrefixTreeNode(
         passthroughRoutes,
         responseTypeRoutes,
         routeSearchSchemas,
+        routerId,
       ),
     );
 
@@ -296,6 +299,12 @@ export async function generateManifestFull<TEnv>(
   mountIndex: number = 0,
   options?: {
     urlPrefix?: string;
+    /**
+     * Owning router id. Threaded into the evaluation store so path() scopes
+     * its search-schema/root-scope registrations per router — same-named
+     * routes in different routers must not clobber each other.
+     */
+    routerId?: string;
     /**
      * Called once per `"use client"` component registered as an
      * errorBoundary/notFoundBoundary fallback, with its client-reference key
@@ -328,6 +337,7 @@ export async function generateManifestFull<TEnv>(
       parent: null,
       counters: {},
       mountIndex,
+      ...(options?.routerId ? { routerId: options.routerId } : {}),
       trackedIncludes, // Enable include tracking
       // basename sets the initial URL prefix for all path() registrations
       ...(options?.urlPrefix ? { urlPrefix: options.urlPrefix } : {}),
@@ -402,6 +412,7 @@ export async function generateManifestFull<TEnv>(
       passthroughRoutes,
       responseTypeRoutes,
       routeSearchSchemas,
+      options?.routerId,
     ),
   );
 

package/src/cache/cache-scope.ts

@@ -89,6 +89,7 @@ function getDefaultRouteCacheKey(
   pathname: string,
   params?: Record<string, string>,
   isIntercept?: boolean,
+  prefixOverride?: "doc",
 ): string {
   const ctx = getRequestContext();
   const isPartial = ctx?.originalUrl?.searchParams.has("_rsc_partial") ?? false;
@@ -96,7 +97,9 @@ function getDefaultRouteCacheKey(
   const host = ctx?.url.host ?? "localhost";
 
   // Intercept navigations get their own cache namespace
-  const prefix = isIntercept ? "intercept" : isPartial ? "partial" : "doc";
+  const prefix = isIntercept
+    ? "intercept"
+    : (prefixOverride ?? (isPartial ? "partial" : "doc"));
 
   return `${prefix}:${cacheKeyBase(host, pathname, searchParams, params)}`;
 }
@@ -105,6 +108,8 @@ function getDefaultRouteCacheKey(
 // CacheScope
 // ============================================================================
 
+const CACHE_HIT_OBSERVERS = new WeakMap<CacheScope, () => void>();
+
 /**
  * CacheScope represents a cache boundary in the route tree.
  *
@@ -131,6 +136,7 @@ export class CacheScope {
   constructor(
     config: PartialCacheOptions | false,
     parent: CacheScope | null = null,
+    private readonly defaultKeyPrefix?: "doc",
   ) {
     this.config = config;
     this.parent = parent;
@@ -209,7 +215,12 @@ export class CacheScope {
     params: Record<string, string>,
     isIntercept?: boolean,
   ): Promise<string> {
-    const defaultKey = getDefaultRouteCacheKey(pathname, params, isIntercept);
+    const defaultKey = getDefaultRouteCacheKey(
+      pathname,
+      params,
+      isIntercept,
+      this.defaultKeyPrefix,
+    );
     const keyFn = this.config !== false ? this.config.key : undefined;
     return resolveCacheKey(keyFn, this.getStore(), defaultKey, "CacheScope");
   }
@@ -339,6 +350,7 @@ export class CacheScope {
         );
       }
 
+      CACHE_HIT_OBSERVERS.get(this)?.();
       return { segments, shouldRevalidate };
     } catch (error) {
       // Covers a store.get() failure AND a throwing consumer key()/keyGenerator
@@ -529,10 +541,11 @@ export function createCacheScope(
 /**
  * Shell fast path: when the route tree derived NO cache scope and the current
  * request context carries the `_shellImplicitCache` marker (a shell capture,
- * or a HIT tail serving an eligible entry), substitute an implicit doc-level
- * scope so withCacheLookup/withCacheStore treat the WHOLE matched route as a
- * cache() boundary — the shell entry IS a cache() of the handler layer, with
- * loaders as the live carve-outs (resolveFreshLoadersAndYield).
+ * an eligible HIT tail, or a normal partial navigation replay), substitute an
+ * implicit doc-level scope so withCacheLookup/withCacheStore treat the WHOLE
+ * matched route as a cache() boundary — the shell entry IS a cache() of the
+ * handler layer, with loaders as the live carve-outs
+ * (resolveFreshLoadersAndYield).
  *
  * An existing scope — including an explicit cache(false) opt-out — always
  * wins: the consumer's cache() semantics (their ttl/swr/store/condition) are
@@ -545,8 +558,11 @@ export function resolveShellImplicitCacheScope(
   if (scope) return scope;
   const marker = getRequestContext()?._shellImplicitCache;
   if (!marker) return null;
-  return new CacheScope(
+  const implicitScope = new CacheScope(
     { ttl: marker.ttl, swr: marker.swr, store: marker.store },
     null,
+    marker.keyPrefix,
   );
+  if (marker.onHit) CACHE_HIT_OBSERVERS.set(implicitScope, marker.onHit);
+  return implicitScope;
 }

package/src/cache/cf/cf-cache-store.ts

@@ -272,7 +272,7 @@ interface KVShellEnvelope {
   rv: string;
   /** Build version captured at prerender time (ShellCacheEntry.buildVersion) */
   bv?: string;
-  /** createdAt (ms epoch) */
+  /** Capture-generation start time (ms epoch), used by tag marker checks. */
   c: number;
   /** When entry becomes stale (ms epoch) */
   s: number;
@@ -293,6 +293,8 @@ interface KVShellEnvelope {
    * their holes only a handler re-run can fill.
    */
   lh?: boolean;
+  /** ShellCacheEntry.transitionWhen; conditional transitions must re-run. */
+  tw?: true;
 }
 
 /**
@@ -323,6 +325,7 @@ interface KVResponseEnvelope {
 // ============================================================================
 
 export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
+  readonly supportsPassiveShellReads: true = true;
   readonly defaults?: CacheDefaults;
   readonly keyGenerator?: (
     ctx: RequestContext<TEnv>,
@@ -1743,7 +1746,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   // per-colo L1 for them is a deliberate follow-up (see the PPR shell-resume
   // design doc). Shell entries live only in KV (the global tier), so the family
   // requires a configured KV namespace; without one, getShell/putShell no-op and
-  // the shell-cache middleware fails open to a full HTML render. Tag invalidation
+  // the integrated PPR serve path fails open to a full HTML render. Tag invalidation
   // still applies: shell entries carry tags/taggedAt and are checked against the
   // same KV markers isGloballyInvalidated() reads for every other tier.
 
@@ -1772,7 +1775,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * Get a cached PPR shell entry by key from KV (no L1). Applies the KV read
    * budget, corrupt-entry eviction, hard-expiry, and tag invalidation exactly
    * like kvGetItem, minus the L1 promote. SWR is a plain staleness flag — KV has
-   * no REVALIDATING herd guard, so the shell-cache middleware's module-level
+   * no REVALIDATING herd guard, so the capture scheduler's module-level
    * in-flight set is the recapture stampede guard.
    */
   async getShell(
@@ -1815,6 +1818,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           initialTheme: envelope.i,
           snapshot: envelope.sn,
           handlerLiveHoles: envelope.lh,
+          transitionWhen: envelope.tw,
           createdAt: envelope.c,
         },
         shouldRevalidate,
@@ -1826,8 +1830,9 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   }
 
   /**
-   * Store a PPR shell entry in KV with TTL and optional SWR window. Non-blocking
-   * (waitUntil) like the other KV writes. The tags/taggedAt ride in the envelope
+   * Store a PPR shell entry in KV with TTL and optional SWR window. The write is
+   * registered with waitUntil and awaited so invalidation rejection can be
+   * acknowledged to the capture scheduler. The tags/taggedAt ride in the envelope
    * so isGloballyInvalidated() can invalidate the shell via the shared KV markers.
    */
   async putShell(
@@ -1836,8 +1841,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     ttlSeconds?: number,
     swrSeconds?: number,
     tags?: string[],
-  ): Promise<void> {
-    // KV-only tier: needs a KV namespace and waitUntil (writes are non-blocking).
+  ): Promise<"stored" | "invalidated" | void> {
+    // KV-only tier: needs a KV namespace and waitUntil. The same write promise is
+    // registered for isolate lifetime and awaited so invalidation rejection can
+    // be acknowledged to the capture scheduler.
     if (!this.kv) {
       this.warnShellFamilyInertOnce();
       return;
@@ -1851,9 +1858,15 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // letting kv.put reject inside waitUntil (mirrors setItem/kvSetSegment).
       if (totalTtl < 60) return;
 
-      const staleAt = Date.now() + ttl * 1000;
+      const retentionTtl =
+        tags && tags.length > 0 && this.tagInvalidationTtl
+          ? Math.min(totalTtl, this.tagInvalidationTtl)
+          : totalTtl;
+      const now = Date.now();
+      const staleAt = now + ttl * 1000;
+      const expiresAt = now + retentionTtl * 1000;
       const taggedAt =
-        Array.isArray(tags) && tags.length > 0 ? Date.now() : undefined;
+        Array.isArray(tags) && tags.length > 0 ? entry.createdAt : undefined;
 
       const kvKey = this.toKVKey(`shell:${key}`);
       // A key over the KV limit makes kv.put reject deep inside waitUntil; report
@@ -1871,31 +1884,43 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         return;
       }
 
-      this.waitUntil(() =>
-        reportingAsync(
-          () => {
-            const envelope: KVShellEnvelope = {
-              p: entry.prelude,
-              po: entry.postponed,
-              rv: entry.reactVersion,
-              bv: entry.buildVersion,
-              c: entry.createdAt,
-              s: staleAt,
-              e: staleAt + swrWindow * 1000,
-              t: tags,
-              ta: taggedAt,
-              i: entry.initialTheme,
-              sn: entry.snapshot,
-              lh: entry.handlerLiveHoles,
-            };
-            return this.kv!.put(kvKey, JSON.stringify(envelope), {
-              expirationTtl: totalTtl,
-            });
-          },
-          "cache-write",
-          "[CFCacheStore] putShell",
-        ),
-      );
+      const write = (async (): Promise<"stored" | "invalidated" | void> => {
+        try {
+          if (
+            tags &&
+            tags.length > 0 &&
+            (await this.isGloballyInvalidated(tags, entry.createdAt))
+          ) {
+            return "invalidated";
+          }
+          const envelope: KVShellEnvelope = {
+            p: entry.prelude,
+            po: entry.postponed,
+            rv: entry.reactVersion,
+            bv: entry.buildVersion,
+            c: entry.createdAt,
+            s: staleAt,
+            e: expiresAt,
+            t: tags,
+            ta: taggedAt,
+            i: entry.initialTheme,
+            sn: entry.snapshot,
+            lh: entry.handlerLiveHoles,
+            tw: entry.transitionWhen,
+          };
+          await this.kv!.put(kvKey, JSON.stringify(envelope), {
+            expirationTtl: retentionTtl,
+          });
+          return "stored";
+        } catch (error) {
+          reportCacheError(error, "cache-write", "[CFCacheStore] putShell");
+          return undefined;
+        }
+      })();
+      this.waitUntil(async () => {
+        await write;
+      });
+      return await write;
     } catch (error) {
       reportCacheError(error, "cache-write", "[CFCacheStore] putShell");
     }
@@ -2610,11 +2635,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * eager purge still fires for the whole batch first (it is additive).
    */
   /**
-   * Build-shell read-through gate (SegmentCacheStore.isTagsInvalidatedSince):
-   * a baked shell entry is immutable in the build manifest, so eviction is
-   * answered by the SAME KV tag markers updateTag() writes, compared against
-   * the entry's build-time createdAt. Thin public wrapper over the private
-   * envelope check (identical semantics: marker >= since, fail open).
+   * Shell tag-generation gate (SegmentCacheStore.isTagsInvalidatedSince): the
+   * SAME KV markers used by runtime envelopes also evict immutable build shells
+   * and captures whose write races updateTag(). Thin public wrapper over the
+   * private envelope check (marker >= since, fail open).
    */
   async isTagsInvalidatedSince(
     tags: string[],

package/src/cache/document-cache.ts

@@ -1,7 +1,9 @@
 /**
  * Document-Level Cache Middleware
  *
- * Caches full HTTP responses at the edge based on Cache-Control headers.
+ * Caches full HTTP responses in the configured app store based on Cache-Control
+ * headers. A deployment CDN may independently consume the same shared-cache
+ * directives; this middleware itself runs inside the worker/function.
  * Routes opt-in to caching by setting s-maxage or stale-while-revalidate headers.
  *
  * Flow:
@@ -58,7 +60,7 @@ function parseCacheControl(header: string | null): CacheDirectives | null {
 
   // RFC 7234: in a SHARED cache, `private` and `no-store` forbid storage and
   // MUST win over `s-maxage` even though `private, s-maxage` is contradictory.
-  // The document cache is a shared edge store, so refuse both regardless of any
+  // The document cache is a shared app store, so refuse both regardless of any
   // s-maxage / stale-while-revalidate also present. Match standalone directive
   // tokens (start/end, whitespace, comma, semicolon, or `=` bounded), not a
   // substring, so a value containing "private" cannot false-veto.

package/src/cache/memory-segment-store.ts

@@ -188,6 +188,7 @@ const DEFAULT_MAX_ENTRIES = 1000;
 export class MemorySegmentCacheStore<
   TEnv = unknown,
 > implements SegmentCacheStore<TEnv> {
+  readonly supportsPassiveShellReads: true = true;
   private cache: Map<string, CachedEntryData>;
   private responseCache: Map<string, CachedResponseEntry>;
   private itemCache: Map<string, CachedItemEntry>;
@@ -197,11 +198,9 @@ export class MemorySegmentCacheStore<
   /** prefixed cache key -> set of tags (reverse index for O(tags) unregister) */
   private keyTags: Map<string, Set<string>>;
   /**
-   * tag -> epoch ms of its latest invalidateTags() call. The build-shell
-   * read-through's isTagsInvalidatedSince gate: baked shell entries are
-   * immutable in the build manifest, so eviction is answered by comparing
-   * these markers against the entry's build-time createdAt. Per-isolate,
-   * like every other map here — matching this store's tag semantics.
+   * tag -> epoch ms of its latest invalidateTags() call. Runtime capture races
+   * and immutable build shells are gated by comparing these markers with the
+   * shell generation start. Per-isolate, like every other map here.
    */
   private tagInvalidatedAt: Map<string, number>;
   readonly defaults?: CacheDefaults;
@@ -459,7 +458,14 @@ export class MemorySegmentCacheStore<
     ttlSeconds?: number,
     swrSeconds?: number,
     tags?: string[],
-  ): Promise<void> {
+  ): Promise<"stored" | "invalidated"> {
+    if (
+      tags &&
+      tags.length > 0 &&
+      this.tagsInvalidatedSince(tags, entry.createdAt)
+    ) {
+      return "invalidated";
+    }
     const ttl = resolveTtl(ttlSeconds, this.defaults, DEFAULT_FUNCTION_TTL);
     const swrWindow = resolveSwrWindow(swrSeconds, this.defaults);
     const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
@@ -470,12 +476,17 @@ export class MemorySegmentCacheStore<
     if (tags && tags.length > 0) {
       this.registerTags(tags, prefixedKey);
     }
+    return "stored";
   }
 
   async isTagsInvalidatedSince(
     tags: string[],
     sinceMs: number,
   ): Promise<boolean> {
+    return this.tagsInvalidatedSince(tags, sinceMs);
+  }
+
+  private tagsInvalidatedSince(tags: string[], sinceMs: number): boolean {
     for (const tag of tags) {
       const at = this.tagInvalidatedAt.get(tag);
       // >= so a same-millisecond invalidation wins (freshness over staleness),