@rangojs/router 0.0.0-experimental.29 → 0.0.0-experimental.2c0cb8a1

package/src/__internal.ts

@@ -164,6 +164,98 @@ export type {
  */
 export type { InternalHandlerContext } from "./types.js";
 
+// ============================================================================
+// Rendering (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Builds React element trees from route segments.
+ */
+export { renderSegments } from "./segment-system.js";
+
+// ============================================================================
+// Error Utilities (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Error sanitization and network error utilities.
+ */
+export { sanitizeError, NetworkError, isNetworkError } from "./errors.js";
+
+// ============================================================================
+// Type Utilities (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Scoped view of GeneratedRouteMap for Handler<"localName", ScopedRouteMap<"prefix">>.
+ */
+export type { ScopedRouteMap } from "./types.js";
+
+/**
+ * @internal
+ * Type-level utilities for reverse URL generation.
+ */
+export type { MergeRoutes, SanitizePrefix } from "./reverse.js";
+
+/**
+ * @internal
+ * Individual telemetry event types.
+ */
+export type {
+  RequestStartEvent,
+  RequestEndEvent,
+  RequestErrorEvent,
+  RequestTimeoutEvent,
+  LoaderStartEvent,
+  LoaderEndEvent,
+  LoaderErrorEvent,
+  HandlerErrorEvent,
+  CacheDecisionEvent,
+  RevalidationDecisionEvent,
+} from "./router/telemetry.js";
+
+// ============================================================================
+// Pre-render / Static Handler Guards (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Type guard for prerender handler definitions.
+ */
+export { isPrerenderHandler, isPassthroughHandler } from "./prerender.js";
+
+/**
+ * @internal
+ * Type guard for static handler definitions.
+ */
+export { isStaticHandler } from "./static-handler.js";
+
+// ============================================================================
+// URL Pattern Internals
+// ============================================================================
+
+/**
+ * @internal
+ * Sentinel used to tag response-type route entries.
+ */
+export { RESPONSE_TYPE } from "./urls.js";
+
+// ============================================================================
+// Route Match Debug (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Debug utilities for route matching performance analysis.
+ */
+export {
+  enableMatchDebug,
+  getMatchDebugStats,
+} from "./router/pattern-matching.js";
+
 // ============================================================================
 // Debug Utilities (Internal)
 // ============================================================================

package/src/browser/app-shell.ts

@@ -0,0 +1,52 @@
+import type { ComponentType, ReactNode } from "react";
+
+/**
+ * App-shell metadata: the set of per-router fields that describe the
+ * "envelope" around the current app's segment tree. These fields are set
+ * from the initial RSC payload and must be replaced atomically when the
+ * client navigates into a different router (app switch).
+ *
+ * Intentionally NOT part of the shell (all document-lifetime):
+ * - themeConfig / initialTheme: ThemeProvider is mounted above the segment
+ *   tree and must not remount on smooth transitions.
+ * - warmupEnabled: attached to the NavigationProvider's lifetime effect;
+ *   toggling it mid-session would tear down and restart idle listeners.
+ *   Also not serialized on every full-render path (e.g. the not-found
+ *   fallback), so carrying it here would be unreliable.
+ * - prefetchCacheTTL: the not-found full-render payload does not serialize
+ *   it, so a cross-app nav into a 404 would silently erase the setting.
+ *   Mutable shell fields must be serialized on EVERY full-render path,
+ *   otherwise absent fields are indistinguishable from "new app has no
+ *   value" and the old app's value is dropped.
+ *
+ * A new document navigation (hard reload) applies these fields from the
+ * target app's initial payload.
+ */
+export interface AppShell {
+  /** Router identity. Used to namespace per-app client state (e.g. the
+   *  rango-state localStorage key) so sibling apps on the same origin
+   *  cannot observe each other's cache invalidations. */
+  routerId?: string;
+  rootLayout?: ComponentType<{ children: ReactNode }>;
+  basename?: string;
+  version?: string;
+}
+
+/**
+ * Mutable container for the active app shell. Read-through via `get()` so
+ * closures capture the ref, not the shell, and pick up updates at call time.
+ */
+export interface AppShellRef {
+  get(): AppShell;
+  update(next: AppShell): void;
+}
+
+export function createAppShellRef(initial: AppShell): AppShellRef {
+  let current = initial;
+  return {
+    get: () => current,
+    update: (next) => {
+      current = next;
+    },
+  };
+}

package/src/browser/app-version.ts

@@ -0,0 +1,14 @@
+/**
+ * Mutable app version — updated after HMR revalidation.
+ * Read by prefetch, navigation, and context code.
+ */
+
+let currentVersion: string | undefined;
+
+export function getAppVersion(): string | undefined {
+  return currentVersion;
+}
+
+export function setAppVersion(version: string | undefined): void {
+  currentVersion = version;
+}

package/src/browser/event-controller.ts

@@ -79,6 +79,8 @@ export interface DerivedNavigationState {
   state: "idle" | "loading";
   /** Whether any operation is streaming */
   isStreaming: boolean;
+  /** Whether a navigation is active (fetching or streaming, before commit) */
+  isNavigating: boolean;
   /** Current committed location */
   location: NavigationLocation;
   /** URL being navigated to (null if idle) */
@@ -111,11 +113,24 @@ export type ActionStateListener = (state: TrackedActionState) => void;
 export type HandleListener = () => void;
 
 /**
- * Internal handle state stored in controller
+ * Internal handle state stored in controller.
+ *
+ * Two segment lists are exposed because they serve different consumers:
+ *
+ * - `segmentOrder` drives handle collection (collectHandleData). Includes
+ *   parallel slot ids and reorders them after their parent so later-wins
+ *   collect functions (e.g. Meta) get the right precedence.
+ * - `routeSegmentIds` is the layouts-and-routes-only list documented by
+ *   `useSegments().segmentIds`. Parallels and loader sub-ids are stripped;
+ *   raw matched order is preserved.
+ *
+ * Both are derived from the same `matched` input on each setHandleData call
+ * so they stay in sync.
  */
 export interface HandleState {
   data: HandleData;
   segmentOrder: string[];
+  routeSegmentIds: string[];
 }
 
 /**
@@ -200,6 +215,14 @@ export interface EventController {
     data: HandleData,
     matched?: string[],
     isPartial?: boolean,
+    /**
+     * Segment ids that were re-resolved on the server this request (the
+     * partial response's `diff`). On a partial update, any existing bucket
+     * keyed under one of these ids that has no incoming entry is treated as
+     * stale and cleared. Without this, a parallel slot that revalidates but
+     * pushes nothing leaves its previous bucket in place forever.
+     */
+    resolvedIds?: string[],
   ): void;
   getHandleState(): HandleState;
 
@@ -298,6 +321,7 @@ export function createEventController(
   // Handle data from RSC payload
   let handleData: HandleData = {};
   let handleSegmentOrder: string[] = [];
+  let routeSegmentIds: string[] = [];
 
   // Merged route params from current match
   let routeParams: Record<string, string> = {};
@@ -389,6 +413,9 @@ export function createEventController(
     return {
       state,
       isStreaming,
+      // True when a navigation is active (fetching or streaming, before
+      // commit). Broader than pendingUrl which clears during streaming.
+      isNavigating: currentNavigation !== null,
       location,
       // pendingUrl only during fetching phase - once streaming starts (URL changed), not pending.
       // Background revalidations (skipLoadingState) don't expose a pending URL.
@@ -739,8 +766,15 @@ export function createEventController(
     data: HandleData,
     matched?: string[],
     isPartial?: boolean,
+    resolvedIds?: string[],
   ): void {
-    const newSegmentOrder = filterSegmentOrder(matched ?? []);
+    const rawMatched = matched ?? [];
+    const newSegmentOrder = filterSegmentOrder(rawMatched);
+    // Separate list for useSegments(): "layouts and routes only" — strip
+    // parallels (".@") and loader sub-ids (D digit) without reordering.
+    const newRouteSegmentIds = rawMatched.filter(
+      (id) => !id.includes(".@") && !/D\d+\./.test(id),
+    );
 
     if (isPartial && newSegmentOrder.length > 0) {
       // Partial update: merge new data with existing
@@ -752,10 +786,19 @@ export function createEventController(
           handleData[handleName][segmentId] = data[handleName][segmentId];
         }
       }
-      // Clean up data from segments no longer in the matched list
+      const resolvedIdSet =
+        resolvedIds && resolvedIds.length > 0 ? new Set(resolvedIds) : null;
+      // Cleanup pass:
+      //   a) segment dropped from the match list — delete its bucket.
+      //   b) segment was re-resolved this request but pushed nothing for
+      //      this handle — its previous bucket is stale.
+      // (a) is the existing behavior; (b) requires resolvedIds.
       for (const handleName of Object.keys(handleData)) {
         for (const segmentId of Object.keys(handleData[handleName])) {
-          if (!newSegmentOrder.includes(segmentId)) {
+          const droppedFromMatch = !newSegmentOrder.includes(segmentId);
+          const reresolvedWithoutPush =
+            resolvedIdSet?.has(segmentId) && !data[handleName]?.[segmentId];
+          if (droppedFromMatch || reresolvedWithoutPush) {
             delete handleData[handleName][segmentId];
           }
         }
@@ -765,6 +808,7 @@ export function createEventController(
       handleData = data;
     }
     handleSegmentOrder = newSegmentOrder;
+    routeSegmentIds = newRouteSegmentIds;
 
     notifyHandles();
   }
@@ -773,6 +817,7 @@ export function createEventController(
     return {
       data: handleData,
       segmentOrder: handleSegmentOrder,
+      routeSegmentIds,
     };
   }
 

package/src/browser/link-interceptor.ts

@@ -117,6 +117,7 @@ export function setupLinkInterception(
     // Read navigation options from data attributes (set by Link component)
     const scrollAttr = link.getAttribute("data-scroll");
     const replaceAttr = link.getAttribute("data-replace");
+    const revalidateAttr = link.getAttribute("data-revalidate");
 
     const navigateOptions: NavigateOptions = {};
     if (scrollAttr === "false") {
@@ -125,6 +126,9 @@ export function setupLinkInterception(
     if (replaceAttr === "true") {
       navigateOptions.replace = true;
     }
+    if (revalidateAttr === "false") {
+      navigateOptions.revalidate = false;
+    }
 
     onNavigate(href, navigateOptions);
   };