@rangojs/router 0.0.0-experimental.31 → 0.0.0-experimental.33

package/README.md

@@ -275,7 +275,8 @@ All handler typing styles are supported, but they solve different problems:
 Example of a scoped local name inside a mounted module:
 
 ```tsx
-import type { Handler, ScopedRouteMap } from "@rangojs/router";
+import type { Handler } from "@rangojs/router";
+import type { ScopedRouteMap } from "@rangojs/router/__internal";
 
 type BlogRoutes = ScopedRouteMap<"blog">;
 

package/dist/vite/index.js

@@ -1745,7 +1745,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.31",
+  version: "0.0.0-experimental.33",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.31",
+  "version": "0.0.0-experimental.33",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/breadcrumbs/SKILL.md

@@ -204,3 +204,47 @@ export const urlpatterns = urls(({ path, layout }) => [
 ```
 
 Navigating to `/shop/widget` produces: `Home / Shop / widget`
+
+## Custom Handles
+
+Create your own handle with `createHandle()`:
+
+```typescript
+import { createHandle } from "@rangojs/router";
+
+// Default: flatten into array
+export const PageTitle = createHandle<string, string>(
+  (segments) => segments.flat().at(-1) ?? "Default Title",
+);
+
+// No collect function: default flattens into T[]
+export const Warnings = createHandle<string>();
+```
+
+The Vite `exposeInternalIds` plugin auto-injects a stable `$$id` based on
+file path and export name. No manual naming required for project-local code.
+
+### Handles in 3rd-party packages
+
+The `exposeInternalIds` plugin skips `node_modules/`, so handles defined in
+published packages won't get auto-injected IDs. Pass a manual tag as the
+second argument to `createHandle()`:
+
+```typescript
+import { createHandle } from "@rangojs/router";
+
+// With a collect function (reducer): collect is first arg, tag is second
+export const Breadcrumbs = createHandle<BreadcrumbItem, BreadcrumbItem[]>(
+  collectBreadcrumbs,
+  "__my_package_breadcrumbs__",
+);
+
+// Without a collect function: pass undefined, then the tag
+export const Warnings = createHandle<string>(
+  undefined,
+  "__my_package_warnings__",
+);
+```
+
+The tag must be globally unique and stable across builds. Without it,
+`createHandle` throws in development mode.

package/skills/hooks/SKILL.md

@@ -58,6 +58,26 @@ function NavigationControls() {
 }
 ```
 
+#### Skipping revalidation
+
+Pass `revalidate: false` to skip the RSC server fetch for same-pathname navigations (search param or hash changes). The URL updates and all hooks re-render, but server components stay as-is.
+
+```tsx
+// Update search params without server round-trip
+router.push("/products?color=blue", { revalidate: false });
+router.replace("/products?page=3", { revalidate: false });
+```
+
+If the pathname changes, `revalidate: false` is silently ignored and a full navigation occurs. This also works on `<Link>`:
+
+```tsx
+<Link to="/products?color=blue" revalidate={false}>
+  Blue
+</Link>
+```
+
+Plain `<a>` tags can opt in via `data-revalidate="false"`.
+
 ### useSegments()
 
 Access current URL path and matched route segments:

package/skills/loader/SKILL.md

@@ -65,19 +65,24 @@ export const urlpatterns = urls(({ path, loader }) => [
 
 ## Consuming Loader Data
 
-### In Server Components
+Loaders are the **live data layer** — they resolve fresh on every request.
+The way you consume them depends on whether you're in a server component
+(route handler) or a client component.
 
-```typescript
-import { useLoader } from "@rangojs/router/client";
-import { ProductLoader } from "./loaders/product";
+> **IMPORTANT: Prefer consuming loaders in client components.** Keeping data
+> fetching in loaders and consumption in client components creates a clean
+> separation: the server-side handler renders static markup that can be
+> freely cached with `cache()`, while loader data stays fresh on every
+> request. When you consume loaders in server handlers via `ctx.use()`, the
+> handler output depends on the loader data, which means caching the handler
+> also caches the data — defeating the purpose of the live data layer.
 
-async function ProductPage() {
-  const { product } = await useLoader(ProductLoader);
-  return <h1>{product.name}</h1>;
-}
-```
+### In Client Components (Preferred)
 
-### In Client Components
+Client components use `useLoader()` from `@rangojs/router/client`.
+The loader **must** be registered with `loader()` in the route's DSL
+segments so the framework knows to resolve it during SSR and stream
+the data to the client:
 
 ```typescript
 "use client";
@@ -90,6 +95,42 @@ function ProductDetails() {
 }
 ```
 
+```typescript
+// Route definition — loader() registration required for client consumption
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  loader(ProductLoader), // Required for useLoader() in client components
+]);
+```
+
+### In Route Handlers (Server Components)
+
+In server components, use `ctx.use(Loader)` directly in the route handler.
+This doesn't require `loader()` registration in the DSL — it works
+standalone. **However**, prefer client-side consumption when possible (see
+note above).
+
+```typescript
+import { ProductLoader } from "./loaders/product";
+
+// Route handler — server component
+path("/product/:slug", async (ctx) => {
+  const { product } = await ctx.use(ProductLoader);
+  return <h1>{product.name}</h1>;
+}, { name: "product" })
+```
+
+When you do register with `loader()` in the DSL, `ctx.use()` returns the
+same memoized result — loaders never run twice per request.
+
+**Never use `useLoader()` in server components** — it is a client-only API.
+
+### Summary
+
+| Context                      | API                 | `loader()` DSL required? |
+| ---------------------------- | ------------------- | ------------------------ |
+| Client component (preferred) | `useLoader(Loader)` | **Yes**                  |
+| Route handler (server)       | `ctx.use(Loader)`   | No                       |
+
 ## Loader Context
 
 Loaders receive the same context as route handlers:
@@ -538,13 +579,12 @@ export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalid
   ]),
 ]);
 
-// pages/product.tsx
-import { useLoader } from "@rangojs/router/client";
+// pages/product.tsx — server component (route handler)
 import { ProductLoader, CartLoader } from "./loaders/shop";
 
-async function ProductPage() {
-  const { product } = await useLoader(ProductLoader);
-  const { cart } = await useLoader(CartLoader);
+async function ProductPage(ctx) {
+  const { product } = await ctx.use(ProductLoader);
+  const { cart } = await ctx.use(CartLoader);
 
   return (
     <div>

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 } 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/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);
   };

package/src/browser/navigation-bridge.ts

@@ -10,6 +10,12 @@ import {
   createNavigationTransaction,
   resolveNavigationState,
 } from "./navigation-transaction.js";
+import { buildHistoryState } from "./history-state.js";
+import {
+  handleNavigationStart,
+  handleNavigationEnd,
+  ensureHistoryKey,
+} from "./scroll-restoration.js";
 
 // addTransitionType is only available in React experimental
 const addTransitionType: ((type: string) => void) | undefined =
@@ -18,7 +24,6 @@ const addTransitionType: ((type: string) => void) | undefined =
 import { setupLinkInterception } from "./link-interceptor.js";
 import { createPartialUpdater } from "./partial-update.js";
 import { generateHistoryKey } from "./navigation-store.js";
-import { handleNavigationEnd } from "./scroll-restoration.js";
 import type { EventController } from "./event-controller.js";
 import { isInterceptOnlyCache } from "./intercept-utils.js";
 import {
@@ -114,6 +119,85 @@ export function createNavigationBridge(
         return;
       }
 
+      // Shallow navigation: skip RSC fetch when revalidate is false
+      // and the pathname hasn't changed (search param / hash only change).
+      if (
+        options?.revalidate === false &&
+        targetUrl.pathname === new URL(window.location.href).pathname
+      ) {
+        // Preserve intercept context from the current history entry so that
+        // popstate uses the correct cache key (:intercept suffix) and restores
+        // the right full-page vs modal semantics.
+        const currentHistoryState = window.history.state;
+        const isIntercept = currentHistoryState?.intercept === true;
+        const interceptSourceUrl = isIntercept
+          ? currentHistoryState?.sourceUrl
+          : undefined;
+
+        const historyKey = generateHistoryKey(url, { intercept: isIntercept });
+
+        // Copy current segments to the new history key so back/forward restores instantly
+        const currentKey = store.getHistoryKey();
+        const currentCache = store.getCachedSegments(currentKey);
+        if (currentCache?.segments) {
+          const currentHandleData = eventController.getHandleState().data;
+          store.cacheSegmentsForHistory(
+            historyKey,
+            currentCache.segments,
+            currentHandleData,
+          );
+        }
+
+        // Save current scroll position before changing URL
+        handleNavigationStart();
+
+        // Snapshot old state before pushState/replaceState overwrites it
+        const oldState = window.history.state;
+
+        // Update browser URL (carry intercept context into history state)
+        const historyState = buildHistoryState(
+          resolvedState,
+          {
+            intercept: isIntercept || undefined,
+            sourceUrl: interceptSourceUrl,
+          },
+          {},
+        );
+        if (options.replace) {
+          window.history.replaceState(historyState, "", url);
+        } else {
+          window.history.pushState(historyState, "", url);
+        }
+
+        // Ensure new history entry has a scroll restoration key
+        ensureHistoryKey();
+
+        // Notify useLocationState() hooks when state changes
+        const hasOldState =
+          oldState &&
+          typeof oldState === "object" &&
+          ("state" in oldState ||
+            Object.keys(oldState).some((k) => k.startsWith("__rsc_ls_")));
+        const hasNewState =
+          historyState &&
+          ("state" in historyState ||
+            Object.keys(historyState).some((k) => k.startsWith("__rsc_ls_")));
+        if (hasOldState || hasNewState) {
+          window.dispatchEvent(new Event("__rsc_locationstate"));
+        }
+
+        // Update store history key so future navigations reference the right cache
+        store.setHistoryKey(historyKey);
+        store.setCurrentUrl(url);
+
+        // Notify hooks — location updates, state stays idle
+        eventController.setLocation(targetUrl);
+
+        // Handle post-navigation scroll
+        handleNavigationEnd({ scroll: options.scroll });
+        return;
+      }
+
       // Only abort pending requests when navigating to a different route
       // Same-route navigation (e.g., /todos -> /todos) should not cancel in-flight actions
       const currentPath = new URL(window.location.href).pathname;

package/src/browser/react/Link.tsx

@@ -80,6 +80,16 @@ export interface LinkProps extends Omit<
    * Force full document navigation instead of SPA
    */
   reloadDocument?: boolean;
+  /**
+   * Whether to revalidate server data on navigation.
+   * Set to `false` to skip the RSC server fetch and only update the URL.
+   *
+   * Only takes effect when the pathname stays the same (search param / hash changes).
+   * If the pathname changes, this option is ignored and a full navigation occurs.
+   *
+   * @default true
+   */
+  revalidate?: boolean;
   /**
    * Prefetch strategy for the link destination
    * @default "none"
@@ -170,6 +180,7 @@ export const Link: ForwardRefExoticComponent<
     replace = false,
     scroll = true,
     reloadDocument = false,
+    revalidate,
     prefetch = "none",
     state,
     children,
@@ -262,9 +273,9 @@ export const Link: ForwardRefExoticComponent<
         resolvedState = currentState;
       }
 
-      ctx.navigate(to, { replace, scroll, state: resolvedState });
+      ctx.navigate(to, { replace, scroll, state: resolvedState, revalidate });
     },
-    [to, isExternal, reloadDocument, replace, scroll, ctx, onClick],
+    [to, isExternal, reloadDocument, replace, scroll, revalidate, ctx, onClick],
   );
 
   const handleMouseEnter = useCallback(() => {
@@ -340,6 +351,7 @@ export const Link: ForwardRefExoticComponent<
       data-external={isExternal ? "" : undefined}
       data-scroll={scroll === false ? "false" : undefined}
       data-replace={replace ? "true" : undefined}
+      data-revalidate={revalidate === false ? "false" : undefined}
       {...props}
     >
       <LinkContext.Provider value={to}>{children}</LinkContext.Provider>

package/src/browser/types.ts

@@ -232,6 +232,25 @@ export type HistoryState =
 export interface NavigateOptions {
   replace?: boolean;
   scroll?: boolean;
+  /**
+   * Whether to revalidate server data on navigation.
+   * Set to `false` to skip the RSC server fetch and only update the URL.
+   *
+   * Only takes effect when the pathname stays the same (search param / hash changes).
+   * If the pathname changes, this option is ignored and a full navigation occurs.
+   *
+   * All location-aware hooks (`useSearchParams`, `useNavigation`, etc.) still update.
+   * Server components do not re-render.
+   *
+   * @default true
+   *
+   * @example
+   * ```tsx
+   * router.push("/products?color=blue", { revalidate: false });
+   * router.replace("/products?page=3", { revalidate: false });
+   * ```
+   */
+  revalidate?: boolean;
   /**
    * State to pass to history.pushState/replaceState
    * Accessible via useLocationState() hook.

package/src/index.rsc.ts

@@ -11,8 +11,6 @@
 
 // Re-export all universal exports from index.ts
 export {
-  // Universal rendering utilities
-  renderSegments,
   // Error classes
   RouteNotFoundError,
   DataNotFoundError,
@@ -21,9 +19,6 @@ export {
   HandlerError,
   BuildError,
   InvalidHandlerError,
-  NetworkError,
-  isNetworkError,
-  sanitizeError,
   RouterError,
   Skip,
   isSkip,
@@ -40,7 +35,6 @@ export type {
   TrailingSlashMode,
   // Handler types
   Handler,
-  ScopedRouteMap,
   HandlerContext,
   ExtractParams,
   GenericParams,
@@ -120,7 +114,6 @@ export { nonce } from "./rsc/nonce.js";
 // Pre-render handler API
 export {
   Prerender,
-  isPrerenderHandler,
   type PrerenderHandlerDefinition,
   type PrerenderPassthroughContext,
   type PrerenderOptions,
@@ -130,16 +123,11 @@ export {
 } from "./prerender.js";
 
 // Static handler API
-export {
-  Static,
-  isStaticHandler,
-  type StaticHandlerDefinition,
-} from "./static-handler.js";
+export { Static, type StaticHandlerDefinition } from "./static-handler.js";
 
 // Django-style URL patterns (RSC/server context)
 export {
   urls,
-  RESPONSE_TYPE,
   type PathHelpers,
   type PathOptions,
   type UrlPatterns,
@@ -207,8 +195,6 @@ export type {
   ReverseFunction,
   ExtractLocalRoutes,
   ParamsFor,
-  SanitizePrefix,
-  MergeRoutes,
 } from "./reverse.js";
 export { scopedReverse, createReverse } from "./reverse.js";
 
@@ -221,12 +207,6 @@ export type {
   RouteParams,
 } from "./search-params.js";
 
-// Debug utilities for route matching (development only)
-export {
-  enableMatchDebug,
-  getMatchDebugStats,
-} from "./router/pattern-matching.js";
-
 // Location state (universal)
 export {
   createLocationState,
@@ -242,20 +222,7 @@ export type { PathResponse } from "./href-client.js";
 export { createConsoleSink } from "./router/telemetry.js";
 export { createOTelSink } from "./router/telemetry-otel.js";
 export type { OTelTracer, OTelSpan } from "./router/telemetry-otel.js";
-export type {
-  TelemetrySink,
-  TelemetryEvent,
-  RequestStartEvent,
-  RequestEndEvent,
-  RequestErrorEvent,
-  RequestTimeoutEvent,
-  LoaderStartEvent,
-  LoaderEndEvent,
-  LoaderErrorEvent,
-  HandlerErrorEvent,
-  CacheDecisionEvent,
-  RevalidationDecisionEvent,
-} from "./router/telemetry.js";
+export type { TelemetrySink, TelemetryEvent } from "./router/telemetry.js";
 
 // Timeout types and error class
 export { RouterTimeoutError } from "./router/timeout.js";

package/src/index.ts

@@ -10,9 +10,6 @@
  *   import from "@rangojs/router/client"
  */
 
-// Universal rendering utilities (work on both server and client)
-export { renderSegments } from "./segment-system.js";
-
 // Error classes (can be used on both server and client)
 export {
   RouteNotFoundError,
@@ -22,9 +19,6 @@ export {
   HandlerError,
   BuildError,
   InvalidHandlerError,
-  NetworkError,
-  isNetworkError,
-  sanitizeError,
   RouterError,
   Skip,
   isSkip,
@@ -41,7 +35,6 @@ export type {
   TrailingSlashMode,
   // Handler types
   Handler, // Supports params object, path pattern, or route name
-  ScopedRouteMap, // Scoped view of GeneratedRouteMap for Handler<"localName", ScopedRouteMap<"prefix">>
   HandlerContext,
   ExtractParams,
   GenericParams,
@@ -194,20 +187,6 @@ export function createReverse(): never {
   throw serverOnlyStubError("createReverse");
 }
 
-/**
- * Error-throwing stub for server-only `enableMatchDebug` function.
- */
-export function enableMatchDebug(): never {
-  throw serverOnlyStubError("enableMatchDebug");
-}
-
-/**
- * Error-throwing stub for server-only `getMatchDebugStats` function.
- */
-export function getMatchDebugStats(): never {
-  throw serverOnlyStubError("getMatchDebugStats");
-}
-
 // Error-throwing stubs for server-only route helpers
 export function layout(): never {
   throw serverOnlyStubError("layout");
@@ -268,8 +247,6 @@ export type {
   ReverseFunction,
   ExtractLocalRoutes,
   ParamsFor,
-  SanitizePrefix,
-  MergeRoutes,
 } from "./reverse.js";
 // scopedReverse() helper for handlers to get locally-typed reverse
 export { scopedReverse } from "./reverse.js";
@@ -289,20 +266,7 @@ export type { PathResponse } from "./href-client.js";
 export { createConsoleSink } from "./router/telemetry.js";
 export { createOTelSink } from "./router/telemetry-otel.js";
 export type { OTelTracer, OTelSpan } from "./router/telemetry-otel.js";
-export type {
-  TelemetrySink,
-  TelemetryEvent,
-  RequestStartEvent,
-  RequestEndEvent,
-  RequestErrorEvent,
-  RequestTimeoutEvent,
-  LoaderStartEvent,
-  LoaderEndEvent,
-  LoaderErrorEvent,
-  HandlerErrorEvent,
-  CacheDecisionEvent,
-  RevalidationDecisionEvent,
-} from "./router/telemetry.js";
+export type { TelemetrySink, TelemetryEvent } from "./router/telemetry.js";
 
 // Timeout types and error class
 export { RouterTimeoutError } from "./router/timeout.js";

package/src/router/match-api.ts

@@ -591,7 +591,7 @@ export async function matchError<TEnv>(
 
   const reqCtx = getRequestContext();
   if (reqCtx) {
-    reqCtx.setStatus(500);
+    reqCtx._setStatus(500);
   }
 
   const effectiveFallback = fallback || DefaultErrorFallback;

package/src/router/prerender-match.ts

@@ -117,6 +117,7 @@ export async function matchForPrerender<TEnv = any>(
       deleteCookie: () => {},
       header: () => {},
       setStatus: () => {},
+      _setStatus: () => {},
       use: (() => {
         throw new Error("use() not available during pre-rendering");
       }) as any,
@@ -346,6 +347,7 @@ export async function renderStaticSegment<TEnv = any>(
     deleteCookie: () => {},
     header: () => {},
     setStatus: () => {},
+    _setStatus: () => {},
     use: (() => {
       throw new Error("use() not available during static pre-rendering");
     }) as any,

package/src/router/segment-resolution/helpers.ts

@@ -174,7 +174,7 @@ export function catchSegmentError<TEnv>(
   const setResponseStatus = (status: number) => {
     const reqCtx = getRequestContext();
     if (reqCtx) {
-      reqCtx.setStatus(status);
+      reqCtx._setStatus(status);
     }
   };
 

package/src/server/request-context.ts

@@ -95,6 +95,8 @@ export interface RequestContext<
   header(name: string, value: string): void;
   /** Set the response status code */
   setStatus(status: number): void;
+  /** @internal Set status bypassing cache-exec guard (for framework error handling) */
+  _setStatus(status: number): void;
 
   /**
    * Access loader data or push handle data.
@@ -301,6 +303,7 @@ export type PublicRequestContext<
   | "_reportBackgroundError"
   | "_debugPerformance"
   | "_metricsStore"
+  | "_setStatus"
   | "res"
 >;
 
@@ -629,8 +632,13 @@ export function createRequestContext<TEnv>(
 
     setStatus(status: number): void {
       assertNotInsideCacheExec(ctx, "setStatus");
-      // Response.status is read-only, so we must create a new Response.
-      // Headers are passed by reference — no cookie cache invalidation needed.
+      stubResponse = new Response(null, {
+        status,
+        headers: stubResponse.headers,
+      });
+    },
+
+    _setStatus(status: number): void {
       stubResponse = new Response(null, {
         status,
         headers: stubResponse.headers,