@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.19

package/src/cache/segment-codec.ts

@@ -142,79 +142,76 @@ export const deserializeComponent: (encoded: string) => Promise<unknown> =
 export async function serializeSegments(
   segments: ResolvedSegment[],
 ): Promise<SerializedSegmentData[]> {
-  const serialized: SerializedSegmentData[] = [];
-
-  for (const segment of segments) {
-    const temporaryReferences = createTemporaryReferenceSet();
-
-    // Await component if it's a Promise (intercepts with loading keep component as Promise)
-    const componentResolved =
-      segment.component instanceof Promise
-        ? await segment.component
-        : segment.component;
-
-    // Serialize the component to RSC stream
-    const stream = renderToReadableStream(componentResolved, {
-      temporaryReferences,
-    });
-
-    // Convert stream to string
-    const encoded = await streamToString(stream);
-
-    // RSC-serialize layout if present (ReactNode)
-    const encodedLayout = segment.layout
-      ? await rscSerialize(segment.layout)
-      : undefined;
-
-    // RSC-serialize loading if present (ReactNode) - preserves tree structure
-    // Use "null" string to distinguish explicit null from undefined
-    const encodedLoading =
-      segment.loading !== undefined
-        ? segment.loading === null
-          ? "null"
-          : await rscSerialize(segment.loading)
-        : undefined;
-
-    // Await and RSC-serialize loaderData if present
-    const loaderDataResolved =
-      segment.loaderData instanceof Promise
-        ? await segment.loaderData
-        : segment.loaderData;
-    const encodedLoaderData = await rscSerialize(loaderDataResolved);
-
-    // Await and RSC-serialize loaderDataPromise if present
-    const loaderDataPromiseResolved =
-      segment.loaderDataPromise instanceof Promise
-        ? await segment.loaderDataPromise
-        : segment.loaderDataPromise;
-    const encodedLoaderDataPromise = await rscSerialize(
-      loaderDataPromiseResolved,
-    );
-
-    serialized.push({
-      encoded,
-      encodedLayout,
-      encodedLoading,
-      encodedLoaderData,
-      encodedLoaderDataPromise,
-      metadata: {
-        id: segment.id,
-        type: segment.type,
-        namespace: segment.namespace,
-        index: segment.index,
-        params: segment.params,
-        slot: segment.slot,
-        belongsToRoute: segment.belongsToRoute,
-        layoutName: segment.layoutName,
-        parallelName: segment.parallelName,
-        loaderId: segment.loaderId,
-        loaderIds: segment.loaderIds,
-        transition: segment.transition,
-      },
-    });
-  }
+  return Promise.all(
+    segments.map(async (segment): Promise<SerializedSegmentData> => {
+      const temporaryReferences = createTemporaryReferenceSet();
+
+      // Await component if it's a Promise (intercepts with loading keep component as Promise)
+      const componentResolved =
+        segment.component instanceof Promise
+          ? await segment.component
+          : segment.component;
+
+      // Serialize the component to RSC stream
+      const stream = renderToReadableStream(componentResolved, {
+        temporaryReferences,
+      });
+
+      // RSC-serialize loading: "null" string distinguishes explicit null from undefined
+      const encodedLoading =
+        segment.loading !== undefined
+          ? segment.loading === null
+            ? "null"
+            : await rscSerialize(segment.loading)
+          : undefined;
+
+      // Await loaderData / loaderDataPromise if they're Promises
+      const loaderDataResolved =
+        segment.loaderData instanceof Promise
+          ? await segment.loaderData
+          : segment.loaderData;
+      const loaderDataPromiseResolved =
+        segment.loaderDataPromise instanceof Promise
+          ? await segment.loaderDataPromise
+          : segment.loaderDataPromise;
+
+      // Parallelize stream-to-string and RSC serialization of sub-fields
+      const [
+        encoded,
+        encodedLayout,
+        encodedLoaderData,
+        encodedLoaderDataPromise,
+      ] = await Promise.all([
+        streamToString(stream),
+        segment.layout ? rscSerialize(segment.layout) : undefined,
+        rscSerialize(loaderDataResolved),
+        rscSerialize(loaderDataPromiseResolved),
+      ]);
 
-  return serialized;
+      return {
+        encoded,
+        encodedLayout,
+        encodedLoading,
+        encodedLoaderData,
+        encodedLoaderDataPromise,
+        metadata: {
+          id: segment.id,
+          type: segment.type,
+          namespace: segment.namespace,
+          index: segment.index,
+          params: segment.params,
+          slot: segment.slot,
+          belongsToRoute: segment.belongsToRoute,
+          layoutName: segment.layoutName,
+          parallelName: segment.parallelName,
+          loaderId: segment.loaderId,
+          loaderIds: segment.loaderIds,
+          transition: segment.transition,
+          mountPath: segment.mountPath,
+        },
+      };
+    }),
+  );
 }
 
 /**
@@ -224,44 +221,36 @@ export async function serializeSegments(
 export async function deserializeSegments(
   data: SerializedSegmentData[],
 ): Promise<ResolvedSegment[]> {
-  const segments: ResolvedSegment[] = [];
-
-  for (const item of data) {
-    const temporaryReferences = createTemporaryReferenceSet();
-
-    // Revive the component from cached string
-    const stream = stringToStream(item.encoded);
-    const component = await createFromReadableStream(stream, {
-      temporaryReferences,
-    });
-
-    // RSC-deserialize layout, loaderData, loaderDataPromise in parallel.
-    // Handle the "null" sentinel for loading before RSC deserialization.
-    // During serialization, loading: null is stored as the string "null" to
-    // distinguish it from undefined. This sentinel must be intercepted here
-    // rather than passed to rscDeserialize, which would try to decode it as
-    // an RSC Flight payload.
-    const loadingIsNullSentinel = item.encodedLoading === "null";
-
-    const [layout, loaderData, loaderDataPromise, loadingData] =
-      await Promise.all([
-        rscDeserialize(item.encodedLayout),
-        rscDeserialize(item.encodedLoaderData),
-        rscDeserialize(item.encodedLoaderDataPromise),
-        loadingIsNullSentinel
-          ? (null as any)
-          : rscDeserialize(item.encodedLoading),
-      ]);
-
-    segments.push({
-      ...item.metadata,
-      component,
-      layout,
-      loading: loadingData,
-      loaderData,
-      loaderDataPromise,
-    } as ResolvedSegment);
-  }
-
-  return segments;
+  return Promise.all(
+    data.map(async (item): Promise<ResolvedSegment> => {
+      const temporaryReferences = createTemporaryReferenceSet();
+
+      // Handle the "null" sentinel for loading before RSC deserialization.
+      // During serialization, loading: null is stored as the string "null" to
+      // distinguish it from undefined.
+      const loadingIsNullSentinel = item.encodedLoading === "null";
+
+      const [component, layout, loaderData, loaderDataPromise, loadingData] =
+        await Promise.all([
+          createFromReadableStream(stringToStream(item.encoded), {
+            temporaryReferences,
+          }),
+          rscDeserialize(item.encodedLayout),
+          rscDeserialize(item.encodedLoaderData),
+          rscDeserialize(item.encodedLoaderDataPromise),
+          loadingIsNullSentinel
+            ? (null as any)
+            : rscDeserialize(item.encodedLoading),
+        ]);
+
+      return {
+        ...item.metadata,
+        component,
+        layout,
+        loading: loadingData,
+        loaderData,
+        loaderDataPromise,
+      } as ResolvedSegment;
+    }),
+  );
 }

package/src/cache/taint.ts

@@ -25,11 +25,37 @@ export function isTainted(value: unknown): boolean {
  * 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, etc.) and cookie mutations.

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;
     }
 
-    return content;
+    // Wrap with MountContextProvider for include() scoped parallel/intercept slots
+    if (segment.mountPath) {
+      return (
+        <MountContextProvider value={segment.mountPath}>
+          {result}
+        </MountContextProvider>
+      );
+    }
+
+    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

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/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

@@ -72,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 {
@@ -230,3 +235,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";

package/src/index.ts

@@ -282,3 +282,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";

package/src/loader.rsc.ts

@@ -52,11 +52,19 @@ export function createLoader<T>(
   // For fetchable loaders, __injectedId is also passed as a parameter
   const loaderId = __injectedId || "";
 
-  // If not fetchable, store fn in registry and return a plain object.
-  // Server-side code looks up fn via getFetchableLoader($$id).
+  if (!loaderId && process.env.NODE_ENV === "development") {
+    throw new Error(
+      "[rsc-router] Loader is missing $$id. " +
+        "Make sure the exposeInternalIds Vite plugin is enabled and " +
+        "the loader is exported with: export const MyLoader = createLoader(...)",
+    );
+  }
+
+  // If not fetchable, store fn in registry (for SSR ctx.use() resolution)
+  // but mark fetchable=false so the _rsc_loader endpoint rejects it.
   if (fetchable === undefined) {
     if (fn && loaderId) {
-      registerFetchableLoader(loaderId, fn, []);
+      registerFetchableLoader(loaderId, fn, [], false);
     }
     return {
       __brand: "loader",
@@ -71,7 +79,7 @@ export function createLoader<T>(
   // Register the function in the internal registry by $$id (server-side only)
   // The loader fetch handler looks it up by $$id when load() is called from the client.
   if (fn && loaderId) {
-    registerFetchableLoader(loaderId, fn, middleware);
+    registerFetchableLoader(loaderId, fn, middleware, true);
   }
 
   return {

package/src/loader.ts

@@ -49,6 +49,14 @@ export function createLoader<T>(
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>> {
   const loaderId = __injectedId || "";
 
+  if (!loaderId && process.env.NODE_ENV === "development") {
+    throw new Error(
+      "[rsc-router] Loader is missing $$id. " +
+        "Make sure the exposeInternalIds Vite plugin is enabled and " +
+        "the loader is exported with: export const MyLoader = createLoader(...)",
+    );
+  }
+
   return {
     __brand: "loader",
     $$id: loaderId,

package/src/prerender/store.ts

@@ -21,7 +21,7 @@ export interface PrerenderStore {
   get(
     routeName: string,
     paramHash: string,
-    meta?: { pathname: string },
+    meta?: { pathname: string; isPassthroughRoute?: boolean },
   ): PrerenderEntry | null | Promise<PrerenderEntry | null>;
 }
 
@@ -58,11 +58,12 @@ declare global {
  */
 export function createDevPrerenderStore(devUrl: string): PrerenderStore {
   return {
-    async get(_routeName, paramHash, meta) {
+    async get(routeName, paramHash, meta) {
       if (!meta?.pathname) return null;
       const isIntercept = paramHash.endsWith("/i");
-      let url = `${devUrl}/__rsc_prerender?pathname=${encodeURIComponent(meta.pathname)}`;
+      let url = `${devUrl}/__rsc_prerender?pathname=${encodeURIComponent(meta.pathname)}&routeName=${encodeURIComponent(routeName)}`;
       if (isIntercept) url += "&intercept=1";
+      if (meta.isPassthroughRoute) url += "&passthrough=1";
       try {
         const res = await fetch(url);
         if (!res.ok) return null;