@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

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

@@ -107,7 +107,6 @@ async function buildPrefixTreeNode(
   namePrefix: string | undefined,
   patternsOrProvider: UrlPatterns<any> | IncludeProvider<any>,
   routeManifest: Record<string, string>,
-  routeAncestry: Record<string, string[]>, // internal: feeds trie building, not exported
   mountIndex: number,
   visited: Set<unknown> = new Set(),
   routeTrailingSlash?: Record<string, string>,
@@ -116,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
@@ -157,6 +157,7 @@ async function buildPrefixTreeNode(
         parent: null,
         counters: {},
         mountIndex,
+        ...(routerId ? { routerId } : {}),
         trackedIncludes, // Enable nested include tracking
       },
       () => {
@@ -189,9 +190,6 @@ async function buildPrefixTreeNode(
       }
     }
 
-    // Capture ancestry from manifest entries' parent chains
-    captureAncestry(manifest, routeAncestry);
-
     // Collect prerender route names and handler definitions from manifest entries
     if (prerenderRoutes) {
       for (const [name, entry] of manifest) {
@@ -223,7 +221,6 @@ async function buildPrefixTreeNode(
         include.namePrefix,
         include.patterns as UrlPatterns<any> | IncludeProvider<any>,
         routeManifest,
-        routeAncestry,
         mountIndex,
         visited,
         routeTrailingSlash,
@@ -232,6 +229,7 @@ async function buildPrefixTreeNode(
         passthroughRoutes,
         responseTypeRoutes,
         routeSearchSchemas,
+        routerId,
       ),
     );
 
@@ -250,32 +248,11 @@ async function buildPrefixTreeNode(
   }
 }
 
-/**
- * Walk parent chains of route entries to extract ancestry shortCodes.
- */
-function captureAncestry(
-  manifest: Map<string, EntryData>,
-  routeAncestry: Record<string, string[]>,
-): void {
-  for (const [routeName, entry] of manifest) {
-    if (entry.type === "route") {
-      const ancestry: string[] = [];
-      let current: EntryData | null = entry;
-      while (current) {
-        ancestry.unshift(current.shortCode);
-        current = current.parent;
-      }
-      routeAncestry[routeName] = ancestry;
-    }
-  }
-}
-
 /**
  * Internal manifest result including build-pipeline-only fields.
  * Not part of the public API — use generateManifest() for the public surface.
  */
 export interface FullManifest extends GeneratedManifest {
-  _routeAncestry: Record<string, string[]>;
   _prerenderDefs?: Record<string, any>;
 }
 
@@ -283,8 +260,7 @@ export interface FullManifest extends GeneratedManifest {
  * Generate manifest from UrlPatterns (public API).
  *
  * Returns only the public GeneratedManifest fields. Internal build pipeline
- * consumers that need _routeAncestry or _prerenderDefs should use
- * generateManifestFull() instead.
+ * consumers that need _prerenderDefs should use generateManifestFull() instead.
  *
  * @example
  * ```typescript
@@ -304,8 +280,10 @@ export async function generateManifest<TEnv>(
   urlpatterns: UrlPatterns<TEnv, any>,
   mountIndex: number = 0,
 ): Promise<GeneratedManifest> {
-  const { _routeAncestry, _prerenderDefs, ...publicManifest } =
-    await generateManifestFull(urlpatterns, mountIndex);
+  const { _prerenderDefs, ...publicManifest } = await generateManifestFull(
+    urlpatterns,
+    mountIndex,
+  );
   return publicManifest;
 }
 
@@ -321,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
@@ -332,7 +316,6 @@ export async function generateManifestFull<TEnv>(
   },
 ): Promise<FullManifest> {
   const routeManifest: Record<string, string> = {};
-  const routeAncestry: Record<string, string[]> = {};
   const prefixTree: Record<string, PrefixTreeNode> = {};
 
   // Run the root patterns handler with tracking enabled
@@ -354,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 } : {}),
@@ -392,9 +376,6 @@ export async function generateManifestFull<TEnv>(
     Record<string, string>
   > = Object.fromEntries(searchSchemasMap);
 
-  // Capture ancestry from manifest entries' parent chains
-  captureAncestry(manifest, routeAncestry);
-
   // Collect prerender route names and handler definitions across all levels
   const prerenderRoutes: string[] = [];
   const prerenderDefs: Record<string, any> = {};
@@ -423,7 +404,6 @@ export async function generateManifestFull<TEnv>(
       include.namePrefix,
       include.patterns as UrlPatterns<any> | IncludeProvider<any>,
       routeManifest,
-      routeAncestry,
       mountIndex,
       visited,
       routeTrailingSlash,
@@ -432,6 +412,7 @@ export async function generateManifestFull<TEnv>(
       passthroughRoutes,
       responseTypeRoutes,
       routeSearchSchemas,
+      options?.routerId,
     ),
   );
 
@@ -453,7 +434,6 @@ export async function generateManifestFull<TEnv>(
       Object.keys(routeSearchSchemas).length > 0
         ? routeSearchSchemas
         : undefined,
-    _routeAncestry: routeAncestry,
     // Internal: prerender handler definitions for build-time getParams() access
     _prerenderDefs:
       Object.keys(prerenderDefs).length > 0 ? prerenderDefs : undefined,

package/src/build/route-trie.ts

@@ -2,8 +2,7 @@
  * Build-time Route Trie Construction
  *
  * Builds a serializable trie from the route manifest for O(path_length)
- * route matching at runtime. Each trie leaf embeds the route's ancestry
- * shortCodes for layout pruning.
+ * route matching at runtime.
  */
 
 import {
@@ -33,8 +32,6 @@ export interface TrieLeaf {
   n: string;
   /** Static prefix of the entry (e.g., "/site") */
   sp: string;
-  /** Ancestry shortCodes from root to route [M0L0, M0L0L0, M0L0L0R499] */
-  a: string[];
   /** Constraint validation: paramName -> allowed values */
   cv?: Record<string, string[]>;
   /** Ordered param names for this route (positional) */
@@ -75,7 +72,6 @@ export interface TrieNode {
  * Build a route trie from build-time manifest data.
  *
  * @param routeManifest - Map of route name to full URL pattern
- * @param routeAncestry - Map of route name to ancestry shortCodes
  * @param routeToStaticPrefix - Map of route name to its entry's staticPrefix
  * @param routeTrailingSlash - Optional map of route name to trailing slash mode
  * @param prerenderRouteNames - Optional set of prerendered route names (sets leaf.pr)
@@ -84,7 +80,6 @@ export interface TrieNode {
  */
 export function buildRouteTrie(
   routeManifest: Record<string, string>,
-  routeAncestry: Record<string, string[]>,
   routeToStaticPrefix: Record<string, string>,
   routeTrailingSlash?: Record<string, string>,
   prerenderRouteNames?: Set<string>,
@@ -94,7 +89,6 @@ export function buildRouteTrie(
   const root: TrieNode = {};
 
   for (const [routeName, pattern] of Object.entries(routeManifest)) {
-    const ancestry = routeAncestry[routeName] || [];
     const staticPrefix = routeToStaticPrefix[routeName] || "";
     const trailingSlash = routeTrailingSlash?.[routeName];
     const responseType = responseTypeRoutes?.[routeName];
@@ -107,7 +101,6 @@ export function buildRouteTrie(
     insertRoute(root, segments, 0, {
       n: routeName,
       sp: staticPrefix,
-      a: ancestry,
       ...(trailingSlash ? { ts: trailingSlash } : {}),
       ...(prerenderRouteNames?.has(routeName) ? { pr: true } : {}),
       ...(passthroughRouteNames?.has(routeName) ? { pt: true } : {}),
@@ -161,15 +154,13 @@ function sortSuffixParams(node: TrieNode): void {
  * construction path shared by build/discovery (discover-routers.ts, serialized
  * into the production chunk) and the dev/HMR runtime rebuild
  * (rsc/manifest-init.ts). Keeping one code path is what guarantees the dev
- * runtime trie and the production serialized trie are byte-for-byte identical
- * (modulo `leaf.a` ancestry, which embeds the mount index and is debug-only).
+ * runtime trie and the production serialized trie are byte-for-byte identical.
  *
- * Returns null when the manifest has no route ancestry (no routes), matching
- * the prior guard at both call sites.
+ * Returns null when the manifest has no routes, matching the prior guard at
+ * both call sites.
  */
 export function buildPerRouterTrie(manifest: FullManifest): TrieNode | null {
-  const ancestry = manifest._routeAncestry;
-  if (!ancestry || Object.keys(ancestry).length === 0) {
+  if (Object.keys(manifest.routeManifest).length === 0) {
     return null;
   }
 
@@ -186,7 +177,6 @@ export function buildPerRouterTrie(manifest: FullManifest): TrieNode | null {
 
   return buildRouteTrie(
     manifest.routeManifest,
-    ancestry,
     routeToStaticPrefix,
     manifest.routeTrailingSlash,
     manifest.prerenderRoutes ? new Set(manifest.prerenderRoutes) : undefined,
@@ -233,41 +223,6 @@ function insertRoute(
   insertSegments(node, segments, index, leafBase, []);
 }
 
-/**
- * Extract ancestry map from a built trie by visiting all leaf nodes.
- * Returns { routeName: ancestryShortCodes[] } for every route in the trie.
- */
-export function extractAncestryFromTrie(
-  root: TrieNode,
-): Record<string, string[]> {
-  const result: Record<string, string[]> = {};
-
-  function visit(node: TrieNode): void {
-    if (node.r) {
-      result[node.r.n] = node.r.a;
-    }
-    if (node.w) {
-      result[node.w.n] = node.w.a;
-    }
-    if (node.s) {
-      for (const child of Object.values(node.s)) {
-        visit(child);
-      }
-    }
-    if (node.xp) {
-      for (const child of Object.values(node.xp)) {
-        visit(child.c);
-      }
-    }
-    if (node.p) {
-      visit(node.p.c);
-    }
-  }
-
-  visit(root);
-  return result;
-}
-
 /**
  * Merge a new leaf with an existing leaf, handling content negotiation.
  * When an RSC route and response-type routes share the same URL pattern,

package/src/cache/cache-key-utils.ts

@@ -23,7 +23,6 @@ const RESERVED_SEARCH_PARAMS = new Set([
   "__no_cache",
   "__rsc",
   "__html",
-  "__debug_manifest",
   "__prerender_collect",
 ]);
 

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)}`;
 }
@@ -131,6 +134,7 @@ export class CacheScope {
   constructor(
     config: PartialCacheOptions | false,
     parent: CacheScope | null = null,
+    private readonly defaultKeyPrefix?: "doc",
   ) {
     this.config = config;
     this.parent = parent;
@@ -209,7 +213,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");
   }
@@ -285,10 +294,19 @@ export class CacheScope {
       // partial: evict the entry (self-heal - the re-render re-caches under the
       // same key) and report it as corruption, distinct from a transient infra
       // error (handled by the outer catch).
+      //
+      // Shell-HIT tail (_shellFragmentPayload, issue #700): skip the decode and
+      // carry the stored fragment strings verbatim — the payload consumers
+      // expand them (segment-fragments.ts). Read off the ambient context at the
+      // same point the cache key was resolved (getDefaultRouteCacheKey), so the
+      // flag shares fate with the key: a disrupted ALS already missed the
+      // seeded record and degraded to the full tail.
       let segments: ResolvedSegment[];
       try {
-        const { deserializeSegments } = await import("./segment-codec.js");
-        segments = await deserializeSegments(cached.segments);
+        const codec = await import("./segment-codec.js");
+        segments = _getRequestContext()?._shellFragmentPayload
+          ? await codec.fragmentSegments(cached.segments)
+          : await codec.deserializeSegments(cached.segments);
       } catch (error) {
         reportCacheError(
           error,
@@ -452,7 +470,11 @@ export class CacheScope {
       }
 
       // Collect handle data for non-loader segments only
-      const handles = captureHandles(nonLoaderSegments, handleStore);
+      const handles = captureHandles(
+        nonLoaderSegments,
+        handleStore,
+        requestCtx._shellCaptureLoaderHandleValues,
+      );
 
       try {
         if (INTERNAL_RANGO_DEBUG) {
@@ -512,3 +534,30 @@ export function createCacheScope(
   if (!config) return parent; // No config, inherit parent
   return new CacheScope(config.options, parent);
 }
+
+/**
+ * Shell fast path: when the route tree derived NO cache scope and the current
+ * request context carries the `_shellImplicitCache` marker (a shell capture,
+ * 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
+ * never overridden, and cache(false) keeps the tail on the full handler
+ * re-run path.
+ */
+export function resolveShellImplicitCacheScope(
+  scope: CacheScope | null,
+): CacheScope | null {
+  if (scope) return scope;
+  const marker = getRequestContext()?._shellImplicitCache;
+  if (!marker) return null;
+  return new CacheScope(
+    { ttl: marker.ttl, swr: marker.swr, store: marker.store },
+    null,
+    marker.keyPrefix,
+  );
+}