@rangojs/router 0.0.0-experimental.c65e9248 → 0.0.0-experimental.c7e2ee4c

package/src/cache/cache-scope.ts

@@ -328,22 +328,59 @@ export class CacheScope {
     // Check if this is a partial request (navigation) vs document request
     const isPartial = requestCtx.originalUrl.searchParams.has("_rsc_partial");
 
+    if (INTERNAL_RANGO_DEBUG) {
+      debugCacheLog(
+        `[CacheScope] cacheRoute: scheduling waitUntil for ${key} (${nonLoaderSegments.length} segments, isPartial=${isPartial})`,
+      );
+    }
+
     requestCtx.waitUntil(async () => {
+      if (INTERNAL_RANGO_DEBUG) {
+        debugCacheLog(
+          `[CacheScope] waitUntil: awaiting handleStore.settled for ${key}`,
+        );
+      }
+
       await handleStore.settled;
 
-      // For document requests: only cache if ALL segments have components (complete render)
-      // For partial requests: null components are expected (client already has them)
+      if (INTERNAL_RANGO_DEBUG) {
+        debugCacheLog(`[CacheScope] waitUntil: handleStore settled for ${key}`);
+      }
+
+      // For document requests: only cache if layout segments have components
+      // (complete render). Parallel and route segments may legitimately have
+      // null components — UI-less @meta parallels return null, and void route
+      // handlers produce null when the UI lives in parallel slots/layouts.
+      // Partial requests always allow null components (client already has them).
       if (!isPartial) {
-        const hasAllComponents = nonLoaderSegments.every(
-          (s) => s.component !== null,
+        const hasIncompleteLayouts = nonLoaderSegments.some(
+          (s) => s.component === null && s.type === "layout",
         );
-        if (!hasAllComponents) return;
+        if (hasIncompleteLayouts) {
+          const nullSegments = nonLoaderSegments
+            .filter((s) => s.component === null && s.type === "layout")
+            .map((s) => s.id);
+          const error = new Error(
+            `[CacheScope] Cache write skipped: layout segments have null components ` +
+              `(${nullSegments.join(", ")}). This indicates an incomplete render — ` +
+              `layout handlers must return JSX for document requests to be cacheable.`,
+          );
+          error.name = "CacheScopeInvariantError";
+          console.error(error.message);
+          return;
+        }
       }
 
       // Collect handle data for non-loader segments only
       const handles = captureHandles(nonLoaderSegments, handleStore);
 
       try {
+        if (INTERNAL_RANGO_DEBUG) {
+          debugCacheLog(
+            `[CacheScope] waitUntil: serializing ${nonLoaderSegments.length} segments for ${key}`,
+          );
+        }
+
         // Serialize non-loader segments only
         const serializedSegments = await serializeSegments(nonLoaderSegments);
 
@@ -353,6 +390,10 @@ export class CacheScope {
           expiresAt: Date.now() + ttl * 1000,
         };
 
+        if (INTERNAL_RANGO_DEBUG) {
+          debugCacheLog(`[CacheScope] waitUntil: calling store.set for ${key}`);
+        }
+
         await store.set(key, data, ttl, swr);
 
         if (INTERNAL_RANGO_DEBUG) {

package/src/cache/cf/cf-cache-store.ts

@@ -67,13 +67,11 @@ export const MAX_REVALIDATION_INTERVAL = 30;
 // Types
 // ============================================================================
 
-/**
- * Cloudflare Workers ExecutionContext (subset we need)
- */
-export interface ExecutionContext {
-  waitUntil(promise: Promise<any>): void;
-  passThroughOnException(): void;
-}
+// Re-exported from the canonical home so cf-cache-store consumers keep
+// importing `ExecutionContext` from this module without a second interface
+// drifting over time.
+export type { ExecutionContext } from "../../types/request-scope.js";
+import type { ExecutionContext } from "../../types/request-scope.js";
 
 /**
  * Minimal Cloudflare KV Namespace interface.

package/src/cache/document-cache.ts

@@ -13,6 +13,7 @@
 
 import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
 import { getRequestContext } from "../server/request-context.js";
+import { mayNeedSSR } from "../rsc/ssr-setup.js";
 import { sortedSearchString } from "./cache-key-utils.js";
 import { runBackground } from "./background-task.js";
 
@@ -204,18 +205,24 @@ export function createDocumentCacheMiddleware<TEnv = any>(
   ): Promise<Response> {
     const url = ctx.url;
 
+    // Use the original request URL for _rsc* param detection and cache key
+    // differentiation. ctx.url is stripped of _rsc* params by the middleware
+    // pipeline (stripInternalParams), so _rsc_partial, _rsc_segments, etc.
+    // are not visible on ctx.url in production.
+    const rawUrl = new URL(ctx.request.url);
+
     // Only cache GET requests — mutations and other methods must not be cached
     if (ctx.request.method !== "GET") {
       return next();
     }
 
     // Skip RSC action requests (mutations shouldn't be cached)
-    if (url.searchParams.has("_rsc_action")) {
+    if (rawUrl.searchParams.has("_rsc_action")) {
       return next();
     }
 
     // Skip loader requests (have their own caching)
-    if (url.searchParams.has("_rsc_loader")) {
+    if (rawUrl.searchParams.has("_rsc_loader")) {
       return next();
     }
 
@@ -241,9 +248,12 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       return next();
     }
 
-    // Determine request type for cache key differentiation
-    const isPartial = url.searchParams.has("_rsc_partial");
-    const typeLabel = isPartial ? "RSC" : "HTML";
+    // Determine request type for cache key differentiation.
+    // Uses rawUrl for _rsc* param checks and mayNeedSSR for Accept-based
+    // detection. Full-document RSC fetches must not share the HTML cache slot.
+    const isPartial = rawUrl.searchParams.has("_rsc_partial");
+    const isRscRequest = !mayNeedSSR(ctx.request, rawUrl);
+    const typeLabel = isRscRequest ? "RSC" : "HTML";
 
     // Track whether next() has been called so the catch block knows
     // whether it is safe to fall through to the handler.
@@ -254,10 +264,10 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       // gracefully to the origin handler instead of rejecting the request.
       // This is a deliberate fail-open-to-origin policy: the fallback is
       // "serve uncached from origin", not "use a different cache key".
-      const clientSegments = url.searchParams.get("_rsc_segments") || "";
+      const clientSegments = rawUrl.searchParams.get("_rsc_segments") || "";
       const segmentHash =
         isPartial && clientSegments ? `:${hashSegmentIds(clientSegments)}` : "";
-      const typeSuffix = isPartial ? ":rsc" : ":html";
+      const typeSuffix = isRscRequest ? ":rsc" : ":html";
 
       let searchSuffix = "";
       if (!keyGenerator) {

package/src/cache/taint.ts

@@ -81,6 +81,61 @@ export function assertNotInsideCacheExec(
   }
 }
 
+/**
+ * Symbol stamped on ctx when resolving handlers inside a cache() DSL boundary.
+ * Separate from INSIDE_CACHE_EXEC ("use cache") because cache() allows
+ * ctx.set() (children are also cached) but blocks response-level side effects
+ * (headers, cookies, status) which are lost on cache hit.
+ */
+export const INSIDE_CACHE_SCOPE: unique symbol = Symbol.for(
+  "rango:inside-cache-scope",
+) as any;
+
+/**
+ * Mark ctx as inside a cache() scope. Must be paired with unstampCacheScope.
+ */
+export function stampCacheScope(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_SCOPE] ?? 0;
+  (obj as any)[INSIDE_CACHE_SCOPE] = current + 1;
+}
+
+/**
+ * Remove cache() scope mark.
+ */
+export function unstampCacheScope(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_SCOPE] ?? 0;
+  if (current <= 1) {
+    delete (obj as any)[INSIDE_CACHE_SCOPE];
+  } else {
+    (obj as any)[INSIDE_CACHE_SCOPE] = current - 1;
+  }
+}
+
+/**
+ * Throw if ctx is inside a cache() DSL boundary.
+ * Call from response-level side effects (header, setCookie, setStatus, etc.)
+ * which are lost on cache hit because the handler body is skipped.
+ * ctx.set() is allowed inside cache() — children are also cached and can
+ * read the value.
+ */
+export function assertNotInsideCacheScope(
+  ctx: unknown,
+  methodName: string,
+): void {
+  if (
+    ctx !== null &&
+    ctx !== undefined &&
+    typeof ctx === "object" &&
+    (INSIDE_CACHE_SCOPE as symbol) in (ctx as Record<symbol, unknown>)
+  ) {
+    throw new Error(
+      `ctx.${methodName}() cannot be called inside a cache() boundary. ` +
+        `On cache hit the handler is skipped, so this side effect would be lost. ` +
+        `Move ctx.${methodName}() to a middleware or layout outside the cache() scope.`,
+    );
+  }
+}
+
 /**
  * Brand symbol for functions wrapped by registerCachedFunction().
  * Used at runtime to detect when a "use cache" function is misused

package/src/client.tsx

@@ -13,7 +13,6 @@ import {
   type ClientErrorBoundaryFallbackProps,
   type ErrorInfo,
   type LoaderDefinition,
-  type LoaderFn,
   type ResolvedSegment,
 } from "./types";
 import {
@@ -22,6 +21,83 @@ import {
 } from "./route-content-wrapper.js";
 import { OutletProvider } from "./outlet-provider.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
+import { getMemoizedContentPromise } from "./segment-content-promise.js";
+
+/**
+ * Render the content for a named parallel/intercept slot segment.
+ *
+ * Shared by Outlet (with `name` prop) and ParallelOutlet — both resolve a
+ * segment from context.parallel by slot name and then render it through the
+ * same layout/loader/mountPath wrapping pipeline.
+ */
+function renderSlotContent(segment: ResolvedSegment | null): ReactNode {
+  if (!segment) return null;
+
+  const content: ReactNode =
+    segment.loading || segment.component instanceof Promise ? (
+      <RouteContentWrapper
+        content={getMemoizedContentPromise(segment.component)}
+        fallback={segment.loading}
+        segmentId={segment.id}
+      />
+    ) : (
+      (segment.component ?? null)
+    );
+
+  const hasOwnLoaders = !!(segment.loaderDataPromise && segment.loaderIds);
+  const loaderWrapped = hasOwnLoaders ? (
+    <LoaderBoundary
+      loaderDataPromise={segment.loaderDataPromise!}
+      loaderIds={segment.loaderIds!}
+      fallback={segment.loading}
+      outletKey={segment.id + "-loader"}
+      outletContent={null}
+      segment={segment}
+    >
+      {content}
+    </LoaderBoundary>
+  ) : null;
+
+  let result: ReactNode;
+  if (segment.layout) {
+    // Layout renders immediately; if loaders exist, the LoaderBoundary becomes
+    // the outlet content so layout's <Outlet /> suspends until loaders resolve.
+    result = (
+      <OutletProvider
+        content={hasOwnLoaders ? loaderWrapped : content}
+        segment={segment}
+      >
+        {segment.layout}
+      </OutletProvider>
+    );
+  } else if (hasOwnLoaders) {
+    // No layout but has loaders — wrap content with LoaderBoundary for useLoader context.
+    // Common for intercept routes that use useLoader without a custom layout.
+    result = loaderWrapped;
+  } else {
+    result = content;
+  }
+
+  if (segment.mountPath) {
+    return (
+      <MountContextProvider value={segment.mountPath}>
+        {result}
+      </MountContextProvider>
+    );
+  }
+
+  return result;
+}
+
+function useSlotSegment(
+  context: OutletContextValue | null,
+  name: `@${string}` | undefined,
+): ResolvedSegment | null {
+  return useMemo(() => {
+    if (!name || !context?.parallel) return null;
+    return context.parallel.find((seg) => seg.slot === name) ?? null;
+  }, [context, name]);
+}
 
 /**
  * Outlet component - renders child content in layouts
@@ -62,95 +138,10 @@ import { MountContextProvider } from "./browser/react/mount-context.js";
  */
 export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
   const context = useContext(OutletContext);
+  const namedSegment = useSlotSegment(context, name);
 
-  // If name provided, render parallel/intercept content for that slot
   if (name) {
-    const segment = context?.parallel?.find((seg) => seg.slot === name) ?? null;
-
-    if (!segment) return null;
-
-    // Determine the content to render
-    let content: ReactNode;
-    if (segment.loading || segment.component instanceof Promise) {
-      // Use RouteContentWrapper to handle Suspense wrapping properly
-      content = (
-        <RouteContentWrapper
-          content={
-            segment.component instanceof Promise
-              ? segment.component
-              : Promise.resolve(segment.component)
-          }
-          fallback={segment.loading}
-          segmentId={segment.id}
-        />
-      );
-    } else {
-      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
-      // The layout renders immediately, LoaderBoundary becomes the outlet content
-      // When layout renders <Outlet />, it gets the LoaderBoundary which suspends
-      if (segment.loaderDataPromise && segment.loaderIds) {
-        const loaderAwareContent = (
-          <LoaderBoundary
-            loaderDataPromise={segment.loaderDataPromise}
-            loaderIds={segment.loaderIds}
-            fallback={segment.loading}
-            outletKey={segment.id + "-loader"}
-            outletContent={null}
-            segment={segment}
-          >
-            {content}
-          </LoaderBoundary>
-        );
-
-        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>
-        );
-      }
-    } 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}
-          fallback={segment.loading}
-          outletKey={segment.id + "-loader"}
-          outletContent={null}
-          segment={segment}
-        >
-          {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 result;
+    return renderSlotContent(namedSegment);
   }
 
   // Default: render child content
@@ -164,6 +155,7 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
 
   return content;
 }
+
 /**
  * ParallelOutlet component - renders content for a named parallel slot
  *
@@ -188,94 +180,9 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
  */
 export function ParallelOutlet({ name }: { name: `@${string}` }): ReactNode {
   const context = useContext(OutletContext);
-  const segment = useMemo(() => {
-    if (!context?.parallel) return null;
-    return context.parallel.find((seg) => seg.slot === name) ?? null;
-  }, [context, name]);
+  const segment = useSlotSegment(context, name);
 
-  if (!segment) return null;
-
-  // Determine the content to render
-  let content: ReactNode;
-  if (segment.loading || segment.component instanceof Promise) {
-    // Use RouteContentWrapper to handle Suspense wrapping properly
-    content = (
-      <RouteContentWrapper
-        content={
-          segment.component instanceof Promise
-            ? segment.component
-            : Promise.resolve(segment.component)
-        }
-        fallback={segment.loading}
-        segmentId={segment.id}
-      />
-    );
-  } else {
-    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
-    // The layout renders immediately, LoaderBoundary becomes the outlet content
-    if (segment.loaderDataPromise && segment.loaderIds) {
-      const loaderAwareContent = (
-        <LoaderBoundary
-          loaderDataPromise={segment.loaderDataPromise}
-          loaderIds={segment.loaderIds}
-          fallback={segment.loading}
-          outletKey={segment.id + "-loader"}
-          outletContent={null}
-          segment={segment}
-        >
-          {content}
-        </LoaderBoundary>
-      );
-
-      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>
-      );
-    }
-  } 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}
-        fallback={segment.loading}
-        outletKey={segment.id + "-loader"}
-        outletContent={null}
-        segment={segment}
-      >
-        {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 result;
+  return renderSlotContent(segment);
 }
 
 // OutletProvider is defined in outlet-provider.tsx to break a circular
@@ -313,57 +220,6 @@ export {
   type UseLoaderOptions,
 } from "./use-loader.js";
 
-/**
- * Client-safe createLoader factory
- *
- * Creates a loader definition that can be used with useLoader().
- * This is the client-side version that only stores the $$id - the function
- * is ignored since loaders only execute on the server.
- *
- * The $$id is injected by the exposeLoaderId Vite plugin. In most cases,
- * you should import the loader directly from the server file rather than
- * creating a reference manually.
- *
- * @param fn - Loader function (ignored on client, kept for API compatibility)
- * @param _fetchable - Optional fetchable flag (ignored on client)
- * @param __injectedId - $$id injected by Vite plugin
- *
- * @example
- * ```tsx
- * "use client";
- * import { useLoader } from "rsc-router/client";
- * import { CartLoader } from "../loaders/cart"; // Import from server file
- *
- * export function CartIcon() {
- *   const cart = useLoader(CartLoader);
- *   return <span>Cart ({cart?.items.length ?? 0})</span>;
- * }
- * ```
- */
-// Overload 1: With function only (not fetchable)
-export function createLoader<T>(
-  fn: LoaderFn<T, Record<string, string | undefined>, any>,
-): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
-
-// Overload 2: With function and fetchable flag
-export function createLoader<T>(
-  fn: LoaderFn<T, Record<string, string | undefined>, any>,
-  fetchable: true,
-): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
-
-// Implementation - function is ignored at runtime on client
-// The $$id is injected by Vite plugin as hidden third parameter
-export function createLoader(
-  _fn: LoaderFn<any, Record<string, string | undefined>, any>,
-  _fetchable?: true,
-  __injectedId?: string,
-): LoaderDefinition<any, Record<string, string | undefined>> {
-  return {
-    __brand: "loader",
-    $$id: __injectedId || "",
-  };
-}
-
 /**
  * Props for the ErrorBoundary component
  */
@@ -534,10 +390,8 @@ export {
   type ScrollRestorationProps,
 } from "./browser/react/ScrollRestoration.js";
 
-// Handle API - for accumulating data across route segments
-export { createHandle, isHandle, type Handle } from "./handle.js";
-
-// Handle data hook
+// Handle data hook (client-side only — createHandle/isHandle are server APIs from the root export)
+export { type Handle } from "./handle.js";
 export { useHandle } from "./browser/react/use-handle.js";
 
 // Built-in handles