@rangojs/router 0.0.0-experimental.20 → 0.0.0-experimental.204030a9

package/src/router/router-options.ts

@@ -8,6 +8,7 @@ import type {
 import type { NonceProvider } from "../rsc/types.js";
 import type { ExecutionContext } from "../server/request-context.js";
 import type { UrlPatterns } from "../urls.js";
+import type { UrlBuilder } from "../urls/pattern-types.js";
 import type { NamedRouteEntry } from "./content-negotiation.js";
 import type { TelemetrySink } from "./telemetry.js";
 import type { RouterTimeouts, OnTimeoutCallback } from "./timeout.js";
@@ -72,7 +73,7 @@ export interface RootLayoutProps {
 /**
  * Router configuration options
  */
-export interface RSCRouterOptions<TEnv = any> {
+export interface RangoOptions<TEnv = any> {
   /**
    * Unique identifier for this router instance.
    * Used to namespace static output files and route maps.
@@ -95,6 +96,28 @@ export interface RSCRouterOptions<TEnv = any> {
    */
   $$sourceFile?: string;
 
+  /**
+   * URL prefix applied to all routes registered with this router.
+   *
+   * Useful when the app is served under a sub-path (e.g. `/admin` or `/v2`).
+   * All `path()` patterns are automatically prefixed and `reverse()` returns
+   * full paths including the basename. Route names are NOT prefixed.
+   *
+   * @example
+   * ```typescript
+   * const router = createRouter({
+   *   basename: "/admin",
+   * }).routes(({ path }) => [
+   *   path("/", Dashboard, { name: "home" }),       // matches /admin
+   *   path("/users", Users, { name: "users" }),     // matches /admin/users
+   * ]);
+   *
+   * router.reverse("home");   // "/admin"
+   * router.reverse("users");  // "/admin/users"
+   * ```
+   */
+  basename?: string;
+
   /**
    * Enable performance metrics collection
    * When enabled, metrics are output to console and available via Server-Timing header
@@ -109,6 +132,21 @@ export interface RSCRouterOptions<TEnv = any> {
    */
   allowDebugManifest?: boolean;
 
+  /**
+   * DEVELOPMENT/TEST ONLY. Emit an `X-Rango-Cache` response header describing
+   * the cache status of the matched route, for use by testing primitives such
+   * as `assertCacheStatus`.
+   *
+   * Defaults to `false`. When neither this option nor the
+   * `RANGO_TEST_SIGNALS=1` environment flag is set, NO header is emitted and
+   * router output is byte-identical to the default.
+   *
+   * The header encodes per-segment (v1: coarse route-level) status keyed by the
+   * route NAME, e.g. `X-Rango-Cache: product.detail=hit`. Do NOT enable in
+   * production — it exposes internal cache decisions.
+   */
+  debugCacheSignal?: boolean;
+
   /**
    * Document component that wraps the entire application.
    *
@@ -239,7 +277,7 @@ export interface RSCRouterOptions<TEnv = any> {
    *
    * @example Static config
    * ```typescript
-   * import { MemorySegmentCacheStore } from "rsc-router/rsc";
+   * import { MemorySegmentCacheStore } from "@rangojs/router/cache";
    *
    * const router = createRouter({
    *   cache: {
@@ -335,27 +373,54 @@ export interface RSCRouterOptions<TEnv = any> {
   theme?: import("../theme/types.js").ThemeConfig | true;
 
   /**
-   * URL patterns to register with the router.
+   * Default for whether the router wraps `transition()` segments in its own
+   * React `<ViewTransition>` boundary (experimental React only).
+   *
+   * - "auto" (default): every route/layout that opts in via `transition()`
+   *   gets a router-owned cross-fade.
+   * - false: the router never places its own boundary. Routes that use
+   *   `transition()` still drive navigation through startTransition (so loaders
+   *   hold instead of flashing a skeleton) and still let consumer-placed
+   *   `<ViewTransition>` elements animate — the router just contributes no
+   *   cross-fade of its own. This is the "router triggers, you place the
+   *   transitions" model.
    *
-   * Alternative to calling `.routes()` method - allows passing patterns
-   * directly in the config for a more concise setup.
+   * A per-segment `transition({ viewTransition })` overrides this default.
    *
    * @example
    * ```typescript
-   * import { urls } from "@rangojs/router/server";
+   * // App-wide: drive + hold, but never auto-wrap. Place <ViewTransition>
+   * // yourself in components where you want a morph.
+   * const router = createRouter<AppEnv>({ viewTransition: false });
+   * ```
+   */
+  viewTransition?: "auto" | false;
+
+  /**
+   * URL patterns to register with the router.
    *
-   * const urlpatterns = urls(({ path, layout }) => [
-   *   path("/", HomePage, { name: "home" }),
-   *   path("/about", AboutPage, { name: "about" }),
-   * ]);
+   * Accepts either a `UrlPatterns` object from `urls()` or a builder function
+   * directly (urls() is called implicitly).
    *
-   * const router = createRouter<AppEnv>({
+   * @example
+   * ```typescript
+   * // With urls()
+   * createRouter<AppEnv>({
    *   document: Document,
    *   urls: urlpatterns,
    * });
+   *
+   * // With builder function
+   * createRouter<AppEnv>({
+   *   document: Document,
+   *   urls: ({ path }) => [
+   *     path("/", HomePage, { name: "home" }),
+   *     path("/about", AboutPage, { name: "about" }),
+   *   ],
+   * });
    * ```
    */
-  urls?: UrlPatterns<TEnv, any>;
+  urls?: UrlPatterns<TEnv, any> | UrlBuilder<TEnv>;
 
   /**
    * Injected by the Vite transform at compile time.
@@ -415,16 +480,21 @@ export interface RSCRouterOptions<TEnv = any> {
   version?: string;
 
   /**
-   * Cache-Control header value for prefetch responses.
-   * Only applied to non-intercept partial responses that include the
-   * `X-Rango-Prefetch` header (sent by the Link component's prefetch fetch).
-   * Navigation responses are never cached by the browser.
+   * TTL (in seconds) for the in-memory prefetch cache and the
+   * Cache-Control header on prefetch responses.
+   *
+   * Controls how long prefetch responses are kept in the client-side
+   * in-memory cache and sets `Cache-Control: private, max-age=<ttl>`
+   * on server responses for CDN/edge caching.
+   *
+   * The cache is automatically invalidated on server actions regardless
+   * of TTL, so this is primarily a staleness safety net.
    *
-   * Set to `false` to disable browser caching of prefetch responses entirely.
+   * Set to `false` to disable prefetch caching entirely.
    *
-   * @default "private, max-age=300"
+   * @default 300 (5 minutes)
    */
-  prefetchCacheControl?: string | false;
+  prefetchCacheTTL?: number | false;
 
   /**
    * Enable connection warmup to keep TCP+TLS alive after idle periods.

package/src/router/router-registry.ts

@@ -1,4 +1,4 @@
-import type { RSCRouterInternal } from "./router-interfaces.js";
+import type { RangoInternal } from "./router-interfaces.js";
 
 /**
  * Brand marker for identifying router instances at build time.
@@ -12,10 +12,7 @@ export const RSC_ROUTER_BRAND = "__rsc_router__" as const;
  * Used by the Vite plugin at build time to discover routers and extract
  * manifests, prefix trees, and pre-render candidates.
  */
-export const RouterRegistry: Map<
-  string,
-  RSCRouterInternal<any, any>
-> = new Map();
+export const RouterRegistry: Map<string, RangoInternal<any, any>> = new Map();
 
 export let routerAutoId = 0;