@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

package/src/cache/taint.ts

@@ -22,16 +22,43 @@ export function isTainted(value: unknown): boolean {
 
 /**
  * Symbol stamped on tainted ctx during "use cache" function execution.
- * ctx.set(), ctx.header(), ctx.setCookie(), etc. check this flag and
- * throw if present — those side effects would be lost on cache hit.
+ * cookies(), headers(), ctx.set(), ctx.header(), etc. check this flag and
+ * throw if present — reads would cache per-request data under a shared key,
+ * and side effects would be lost on cache hit.
+ *
+ * The value is a numeric reference count, not a boolean. Multiple concurrent
+ * cached functions sharing the same ctx/requestCtx each increment on entry
+ * and decrement on exit. Guards fire when count > 0.
  */
 export const INSIDE_CACHE_EXEC: unique symbol = Symbol.for(
   "rango:inside-cache-exec",
 ) as any;
 
+/**
+ * Increment the INSIDE_CACHE_EXEC ref count on an object.
+ */
+export function stampCacheExec(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_EXEC] ?? 0;
+  (obj as any)[INSIDE_CACHE_EXEC] = current + 1;
+}
+
+/**
+ * Decrement the INSIDE_CACHE_EXEC ref count on an object.
+ * Deletes the symbol when the count reaches zero so the `in` check
+ * used by guards no longer fires.
+ */
+export function unstampCacheExec(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_EXEC] ?? 0;
+  if (current <= 1) {
+    delete (obj as any)[INSIDE_CACHE_EXEC];
+  } else {
+    (obj as any)[INSIDE_CACHE_EXEC] = current - 1;
+  }
+}
+
 /**
  * Throw if ctx is inside a "use cache" execution.
- * Call from side-effecting ctx methods (set, header, setCookie, etc.).
+ * Call from side-effecting ctx methods (set, header, etc.) and cookie mutations.
  */
 export function assertNotInsideCacheExec(
   ctx: unknown,

package/src/cache/types.ts

@@ -75,7 +75,7 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * @example Using cookies for locale
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
-   *   const locale = ctx.cookie('locale') || 'en';
+   *   const locale = cookies().get('locale')?.value || 'en';
    *   return `${locale}:${defaultKey}`;
    * }
    * ```
@@ -340,117 +340,3 @@ export interface SegmentCacheProvider {
    */
   cacheEntry(cacheKey: string, segments: ResolvedSegment[]): void;
 }
-
-// ============================================================================
-// Generic Cache Store (for future extensibility)
-// ============================================================================
-// These types support a general-purpose cache interface that can be used
-// for caching arbitrary values (responses, streams, objects). Currently,
-// the segment caching system uses SegmentCacheStore directly, but these
-// types enable future use cases like response caching or data caching.
-
-/**
- * Supported cache value types for the generic CacheStore interface.
- * @internal Reserved for future extensibility
- */
-export type CacheValue =
-  | ReadableStream<Uint8Array>
-  | Response
-  | ArrayBuffer
-  | string
-  | unknown[] // JSON-serializable array
-  | Record<string, unknown>; // JSON-serializable object
-
-/**
- * Cache entry returned by match().
- * @internal Reserved for future extensibility
- */
-export interface CacheEntry<T = CacheValue> {
-  /** The cached value */
-  value: T;
-  /** Optional metadata stored with the entry */
-  metadata?: CacheMetadata;
-}
-
-/**
- * Original value type for reconstruction.
- * @internal Reserved for future extensibility
- */
-export type CacheValueType =
-  | "stream"
-  | "response"
-  | "arraybuffer"
-  | "string"
-  | "object";
-
-/**
- * Metadata associated with a cache entry.
- * @internal Reserved for future extensibility
- */
-export interface CacheMetadata {
-  /** Timestamp when entry expires (ms since epoch) */
-  expiresAt?: number;
-  /** Tags for bulk invalidation */
-  tags?: string[];
-  /** Original value type for reconstruction on read */
-  valueType?: CacheValueType;
-  /** Response headers (preserved when caching Response) */
-  responseHeaders?: Record<string, string>;
-  /** Response status (preserved when caching Response) */
-  responseStatus?: number;
-  /** Custom metadata */
-  [key: string]: unknown;
-}
-
-/**
- * Options for put().
- * @internal Reserved for future extensibility
- */
-export interface CachePutOptions {
-  /** Time-to-live in seconds */
-  ttl?: number;
-  /** Metadata to store with entry */
-  metadata?: Omit<CacheMetadata, "expiresAt">;
-}
-
-/**
- * Generic cache store interface for arbitrary value types.
- *
- * This interface is designed for future extensibility to support caching
- * responses, streams, and other values. Currently, segment caching uses
- * the SegmentCacheStore interface directly.
- *
- * Implementations must handle:
- * - Stream values (clone before storing, streams can only be read once)
- * - Promise values (await before storing)
- * - Expiration/TTL
- *
- * @internal Reserved for future extensibility
- */
-export interface CacheStore {
-  /**
-   * Retrieve a cached entry by key.
-   * @param key - Cache key
-   * @returns The cached entry or undefined if not found/expired
-   */
-  match<T = CacheValue>(key: string): Promise<CacheEntry<T> | undefined>;
-
-  /**
-   * Store a value in the cache.
-   * @param key - Cache key
-   * @param value - Value to cache (stream, response, string, object, etc.)
-   * @param options - TTL, metadata, etc.
-   */
-  put<T extends CacheValue>(
-    key: string,
-    value: T,
-    options?: CachePutOptions,
-  ): Promise<void>;
-
-  /**
-   * Delete a cached entry.
-   * @param key - Cache key
-   * @returns true if entry was deleted, false if not found
-   */
-  delete(key: string): Promise<boolean>;
-}

package/src/client.rsc.tsx

@@ -17,7 +17,6 @@ export {
   OutletProvider,
   useOutlet,
   useLoader,
-  useLoaderData,
   ErrorBoundary,
   type ErrorBoundaryProps,
 } from "./client.js";

package/src/client.tsx

@@ -21,6 +21,7 @@ import {
   LoaderBoundary,
 } from "./route-content-wrapper.js";
 import { OutletProvider } from "./outlet-provider.js";
+import { MountContextProvider } from "./browser/react/mount-context.js";
 
 /**
  * Outlet component - renders child content in layouts
@@ -87,6 +88,8 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
       content = segment.component ?? null;
     }
 
+    let result: ReactNode;
+
     // If segment has a layout, wrap appropriately
     if (segment.layout) {
       // Check if this segment has loaders that need streaming
@@ -106,25 +109,23 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
           </LoaderBoundary>
         );
 
-        return (
+        result = (
           <OutletProvider content={loaderAwareContent} segment={segment}>
             {segment.layout}
           </OutletProvider>
         );
+      } else {
+        // No loaders - wrap in OutletProvider so layout can use <Outlet />
+        result = (
+          <OutletProvider content={content} segment={segment}>
+            {segment.layout}
+          </OutletProvider>
+        );
       }
-
-      // No loaders - wrap in OutletProvider so layout can use <Outlet />
-      return (
-        <OutletProvider content={content} segment={segment}>
-          {segment.layout}
-        </OutletProvider>
-      );
-    }
-
-    // No layout but has loaders - wrap content with LoaderBoundary for useLoader context
-    // This is common for intercept routes that use useLoader without a custom layout
-    if (segment.loaderDataPromise && segment.loaderIds) {
-      return (
+    } else if (segment.loaderDataPromise && segment.loaderIds) {
+      // No layout but has loaders - wrap content with LoaderBoundary for useLoader context
+      // This is common for intercept routes that use useLoader without a custom layout
+      result = (
         <LoaderBoundary
           loaderDataPromise={segment.loaderDataPromise}
           loaderIds={segment.loaderIds}
@@ -136,9 +137,20 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
           {content}
         </LoaderBoundary>
       );
+    } else {
+      result = content;
+    }
+
+    // Wrap with MountContextProvider for include() scoped parallel/intercept slots
+    if (segment.mountPath) {
+      return (
+        <MountContextProvider value={segment.mountPath}>
+          {result}
+        </MountContextProvider>
+      );
     }
 
-    return content;
+    return result;
   }
 
   // Default: render child content
@@ -202,6 +214,8 @@ export function ParallelOutlet({ name }: { name: `@${string}` }): ReactNode {
     content = segment.component ?? null;
   }
 
+  let result: ReactNode;
+
   // If segment has a layout, wrap appropriately
   if (segment.layout) {
     // Check if this segment has loaders that need streaming
@@ -220,25 +234,23 @@ export function ParallelOutlet({ name }: { name: `@${string}` }): ReactNode {
         </LoaderBoundary>
       );
 
-      return (
+      result = (
         <OutletProvider content={loaderAwareContent} segment={segment}>
           {segment.layout}
         </OutletProvider>
       );
+    } else {
+      // No loaders - wrap in OutletProvider so layout can use <Outlet />
+      result = (
+        <OutletProvider content={content} segment={segment}>
+          {segment.layout}
+        </OutletProvider>
+      );
     }
-
-    // No loaders - wrap in OutletProvider so layout can use <Outlet />
-    return (
-      <OutletProvider content={content} segment={segment}>
-        {segment.layout}
-      </OutletProvider>
-    );
-  }
-
-  // No layout but has loaders - wrap content with LoaderBoundary for useLoader context
-  // This is common for intercept routes that use useLoader without a custom layout
-  if (segment.loaderDataPromise && segment.loaderIds) {
-    return (
+  } else if (segment.loaderDataPromise && segment.loaderIds) {
+    // No layout but has loaders - wrap content with LoaderBoundary for useLoader context
+    // This is common for intercept routes that use useLoader without a custom layout
+    result = (
       <LoaderBoundary
         loaderDataPromise={segment.loaderDataPromise}
         loaderIds={segment.loaderIds}
@@ -250,9 +262,20 @@ export function ParallelOutlet({ name }: { name: `@${string}` }): ReactNode {
         {content}
       </LoaderBoundary>
     );
+  } else {
+    result = content;
   }
 
-  return content;
+  // Wrap with MountContextProvider for include() scoped parallel/intercept slots
+  if (segment.mountPath) {
+    return (
+      <MountContextProvider value={segment.mountPath}>
+        {result}
+      </MountContextProvider>
+    );
+  }
+
+  return result;
 }
 
 // OutletProvider is defined in outlet-provider.tsx to break a circular
@@ -290,52 +313,6 @@ export {
   type UseLoaderOptions,
 } from "./use-loader.js";
 
-/**
- * Hook to access all loader data in the current context
- *
- * Returns a record of all loader data available in the current outlet context
- * and all parent contexts. Useful for debugging or when you need access to
- * multiple loaders.
- *
- * @returns Record of loader name to data, or empty object if no loaders
- *
- * @example
- * ```tsx
- * "use client";
- * import { useLoaderData } from "rsc-router/client";
- *
- * export function DebugPanel() {
- *   const loaderData = useLoaderData();
- *   return <pre>{JSON.stringify(loaderData, null, 2)}</pre>;
- * }
- * ```
- */
-export function useLoaderData(): Record<string, any> {
-  const context = useContext(OutletContext);
-
-  // Collect all loader data from the context chain
-  // Child loaders override parent loaders with the same name
-  const result: Record<string, any> = {};
-  const stack: OutletContextValue[] = [];
-
-  // Build stack from current to root
-  let current: OutletContextValue | null | undefined = context;
-  while (current) {
-    stack.push(current);
-    current = current.parent;
-  }
-
-  // Apply from root to current (so children override parents)
-  for (let i = stack.length - 1; i >= 0; i--) {
-    const ctx = stack[i];
-    if (ctx.loaderData) {
-      Object.assign(result, ctx.loaderData);
-    }
-  }
-
-  return result;
-}
-
 /**
  * Client-safe createLoader factory
  *

package/src/errors.ts

@@ -327,7 +327,12 @@ export function sanitizeError(error: unknown): Response {
     return error;
   }
 
-  const isDev = (import.meta as any).env?.DEV ?? true;
+  // Vite replaces import.meta.env.DEV at compile time. The fallback covers
+  // non-Vite environments (plain Node, test runners without Vite transforms).
+  // SECURITY: fail closed — default to production when the environment is ambiguous.
+  const isDev =
+    (import.meta as any).env?.DEV ??
+    globalThis.process?.env?.NODE_ENV === "development";
 
   if (isDev) {
     // Development: Send full error details for debugging

package/src/handle.ts

@@ -95,7 +95,7 @@ export function createHandle<TData, TAccumulated = TData[]>(
 ): Handle<TData, TAccumulated> {
   const handleId = __injectedId ?? "";
 
-  if (!handleId && process.env.NODE_ENV !== "production") {
+  if (!handleId && process.env.NODE_ENV === "development") {
     throw new Error(
       "[rsc-router] Handle is missing $$id. " +
         "Make sure the exposeInternalIds Vite plugin is enabled and " +

package/src/handles/MetaTags.tsx

@@ -28,8 +28,9 @@ import { use } from "react";
 import { useHandle } from "../browser/react/use-handle.js";
 import { Meta } from "./meta.js";
 import type { MetaDescriptor, MetaDescriptorBase } from "../router/types.js";
-import { getSSRThemeConfig } from "../theme/theme-context.js";
+import { useThemeContext } from "../theme/theme-context.js";
 import { generateThemeScript } from "../theme/theme-script.js";
+import { useNonce } from "../browser/react/nonce-context.js";
 
 // Type guards for MetaDescriptorBase variants
 function hasCharSet(d: MetaDescriptorBase): d is { charSet: "utf-8" } {
@@ -216,13 +217,15 @@ function AsyncMetaTag({
  */
 export function MetaTags(): React.ReactNode {
   const descriptors = useHandle(Meta) as MetaDescriptor[];
-  const themeConfig = getSSRThemeConfig();
+  const themeConfig = useThemeContext()?.config ?? null;
+  const nonce = useNonce();
 
   return (
     <>
       {/* Theme script must be first to prevent FOUC */}
       {themeConfig && (
         <script
+          nonce={nonce}
           dangerouslySetInnerHTML={{ __html: generateThemeScript(themeConfig) }}
         />
       )}

package/src/host/cookie-handler.ts

@@ -26,9 +26,14 @@ export function parseCookies(request: Request): Record<string, string> {
   const pairs = cookieHeader.split(";");
 
   for (const pair of pairs) {
-    const [key, value] = pair.trim().split("=");
-    if (key && value) {
-      cookies[key] = decodeURIComponent(value);
+    const [name, ...rest] = pair.trim().split("=");
+    if (name && rest.length > 0) {
+      const value = rest.join("=");
+      try {
+        cookies[name] = decodeURIComponent(value);
+      } catch {
+        cookies[name] = value;
+      }
     }
   }
 

package/src/host/index.ts

@@ -25,9 +25,6 @@
 // Core router
 export { createHostRouter } from "./router.js";
 
-// Host router registry for build-time discovery
-export { HostRouterRegistry, type HostRouterRegistryEntry } from "./router.js";
-
 // Utilities
 export { defineHosts } from "./utils.js";
 

package/src/host/router.ts

@@ -149,7 +149,20 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
         return finalHandler();
       }
 
-      return mw(request, input, next);
+      // Guard against double next() calls — a second call would
+      // re-enter the downstream chain and run handlers/side-effects twice.
+      let nextCalled = false;
+      const guardedNext = (): Promise<Response> => {
+        if (nextCalled) {
+          throw new Error(
+            `[HostRouter] Middleware called next() more than once.`,
+          );
+        }
+        nextCalled = true;
+        return next();
+      };
+
+      return mw(request, input, guardedNext);
     }
 
     return next();

package/src/href-client.ts

@@ -182,7 +182,9 @@ export type ValidPaths<TRoutes = GetRegisteredRoutes> =
  */
 export function href<T extends ValidPaths>(path: T, mount?: string): string {
   if (mount && mount !== "/") {
-    return mount + path;
+    // Strip trailing slash from mount to avoid double-slash when joining
+    const normalizedMount = mount.endsWith("/") ? mount.slice(0, -1) : mount;
+    return normalizedMount + path;
   }
   return path;
 }

package/src/index.rsc.ts

@@ -33,7 +33,6 @@ export {
 export type {
   // Configuration types
   DocumentProps,
-  RouterEnv,
   DefaultEnv,
   RouteDefinition,
   RouteConfig,
@@ -73,7 +72,12 @@ export type {
 } from "./types.js";
 
 // Router options type (server-only, so import directly)
-export type { RSCRouterOptions } from "./router.js";
+export type {
+  RSCRouterOptions,
+  SSRStreamMode,
+  SSROptions,
+  ResolveStreamingContext,
+} from "./router.js";
 
 // Server-side createLoader and redirect
 export {
@@ -168,12 +172,27 @@ export type { HandlerCacheConfig } from "./rsc/types.js";
 // Built-in handles (server-side)
 export { Meta } from "./handles/meta.js";
 
-// Request context (for accessing request data in server actions/components)
+// Request context (for accessing request data in server actions/components).
+// Re-exported with a narrowed return type so that public consumers only see
+// public members. Internal code imports from "./server/request-context.js"
+// directly and gets the full type.
+import { getRequestContext as _getRequestContextInternal } from "./server/request-context.js";
+export type { PublicRequestContext as RequestContext } from "./server/request-context.js";
+import type { PublicRequestContext } from "./server/request-context.js";
+import type { DefaultEnv } from "./types/global-namespace.js";
+
+export const getRequestContext: <
+  TEnv = DefaultEnv,
+>() => PublicRequestContext<TEnv> = _getRequestContextInternal;
+
+// Request-scoped shorthands
 export {
-  getRequestContext,
-  requireRequestContext,
-  type RequestContext,
-} from "./server/request-context.js";
+  cookies,
+  headers,
+  type CookieStore,
+  type Cookie,
+  type ReadonlyHeaders,
+} from "./server/cookie-store.js";
 
 // Meta types
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
@@ -201,9 +220,6 @@ export type {
   RouteParams,
 } from "./search-params.js";
 
-// Performance tracking (server-only)
-export { track } from "./server/context.js";
-
 // Debug utilities for route matching (development only)
 export {
   enableMatchDebug,
@@ -220,3 +236,30 @@ export {
 
 // Path-based response type lookup from RegisteredRoutes
 export type { PathResponse } from "./href-client.js";
+
+// Telemetry sink
+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";
+
+// Timeout types and error class
+export { RouterTimeoutError } from "./router/timeout.js";
+export type {
+  RouterTimeouts,
+  TimeoutPhase,
+  TimeoutContext,
+} from "./router/timeout.js";