@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

package/src/urls/path-helper-types.ts

@@ -28,7 +28,6 @@ import type {
   ParallelUseItem,
   InterceptUseItem,
   LoaderUseItem,
-  WhenItem,
   TypedCacheItem,
   TransitionItem,
   TypedTransitionItem,
@@ -42,7 +41,6 @@ import type {
   PassthroughHandlerDefinition,
 } from "../prerender.js";
 import type { StaticHandlerDefinition } from "../static-handler.js";
-import type { InterceptWhenFn } from "../server/context";
 import type {
   ResponseHandler,
   ResponseHandlerContext,
@@ -114,6 +112,12 @@ export type ResponsePathFn<TEnv> = <
  * Path function for JSON response routes (path.json()).
  * Handler can return plain JSON-serializable values or Response.
  * TData is inferred from the handler's return type (excluding Response/Promise wrappers).
+ *
+ * Note: a nested Promise in the return (a forgotten await) is caught at runtime
+ * by response-route-handler.ts (it throws instead of silently emitting `{}`). A
+ * compile-time JsonValue constraint was evaluated and rejected — it breaks
+ * interface-typed returns (interfaces lack the index signature JsonValue
+ * requires) and preserves literal types in the inferred response shape.
  */
 export type JsonResponsePathFn<TEnv> = <
   const TPattern extends string,
@@ -148,6 +152,30 @@ export type TextResponsePathFn<TEnv> = <
   use?: () => UseItems<ResponseRouteUseItem>,
 ) => TypedRouteItem<TName, TPattern, string, TSearch>;
 
+/**
+ * What an async include() provider resolves to. Route types (`TRoutes`) are
+ * inferred from the resolved `urls()` value so `href()` and named routes stay
+ * type-safe through a code-split module (`() => import("./routes")`).
+ */
+type IncludeResolved<
+  TEnv,
+  TRoutes extends Record<string, any>,
+  TResponses extends Record<string, unknown>,
+> =
+  | UrlPatterns<TEnv, TRoutes, TResponses>
+  | { default: UrlPatterns<TEnv, TRoutes, TResponses> };
+
+/** include() argument: an eager `urls()` value or an async provider thunk. */
+export type IncludeArg<
+  TEnv,
+  TRoutes extends Record<string, any>,
+  TResponses extends Record<string, unknown>,
+> =
+  | UrlPatterns<TEnv, TRoutes, TResponses>
+  | (() =>
+      | IncludeResolved<TEnv, TRoutes, TResponses>
+      | Promise<IncludeResolved<TEnv, TRoutes, TResponses>>);
+
 /**
  * Base include function signature.
  */
@@ -158,7 +186,7 @@ export type IncludeFn<TEnv> = <
   TResponses extends Record<string, unknown> = Record<string, unknown>,
 >(
   prefix: TUrlPrefix,
-  patterns: UrlPatterns<TEnv, TRoutes, TResponses>,
+  patterns: IncludeArg<TEnv, TRoutes, TResponses>,
   options?: IncludeOptions<TNamePrefix>,
 ) => TypedIncludeItem<TRoutes, TNamePrefix, TUrlPrefix, TResponses>;
 
@@ -240,9 +268,16 @@ export type PathHelpers<TEnv> = {
    * `{ handler, use? }` whose `use` is scoped to that slot only. Per-slot
    * merge order is `handler.use` → shared `use` → slot-local `use`, with
    * narrowest scope winning for last-write-wins items like `loading()`.
+   *
+   * Not generic over the slots record: an inferred type parameter makes the
+   * object literal an inference site, which suppresses contextual typing of
+   * arrow slot handlers (`(ctx) => ...` was implicit any). Bare handlers infer
+   * now; a descriptor's `handler:` arrow still needs an explicit ctx annotation
+   * because StaticHandlerDefinition's own `.handler` joins the contextual union
+   * (two callables — see parallel-slot-handler-types.test.ts).
    */
-  parallel: <
-    TSlots extends Record<
+  parallel: (
+    slots: Record<
       `@${string}`,
       | Handler<any, any, TEnv>
       | ReactNode
@@ -255,8 +290,6 @@ export type PathHelpers<TEnv> = {
           use?: () => ParallelUseItem[];
         }
     >,
-  >(
-    slots: TSlots,
     use?: () => ParallelUseItem[],
   ) => ParallelItem;
 
@@ -269,12 +302,18 @@ export type PathHelpers<TEnv> = {
         slotName: `@${string}`,
         routeName: string,
         handler: ReactNode | Handler<any, any, TEnv>,
+        config?:
+          | import("../server/context.js").InterceptConfig<TEnv>
+          | (() => InterceptUseItem[]),
         use?: () => InterceptUseItem[],
       ) => InterceptItem
     : (
         slotName: `@${string}`,
         routeName: (keyof Rango.GeneratedRouteMap & string) | `.${string}`,
         handler: ReactNode | Handler<any, any, TEnv>,
+        config?:
+          | import("../server/context.js").InterceptConfig<TEnv>
+          | (() => InterceptUseItem[]),
         use?: () => InterceptUseItem[],
       ) => InterceptItem;
 
@@ -329,11 +368,6 @@ export type PathHelpers<TEnv> = {
     fallback: ReactNode | NotFoundBoundaryHandler,
   ) => NotFoundBoundaryItem;
 
-  /**
-   * Define a condition for when an intercept should activate
-   */
-  when: (fn: InterceptWhenFn) => WhenItem;
-
   /**
    * Define cache configuration for segments
    */
@@ -342,9 +376,9 @@ export type PathHelpers<TEnv> = {
     <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
       children: () => TChildren,
     ): TypedCacheItem<ExtractRoutes<TChildren>, ExtractResponses<TChildren>>;
-    (options: PartialCacheOptions | false): TypedCacheItem<{}, {}>;
+    (options: PartialCacheOptions<TEnv> | false): TypedCacheItem<{}, {}>;
     <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
-      options: PartialCacheOptions | false,
+      options: PartialCacheOptions<TEnv> | false,
       use: () => TChildren,
     ): TypedCacheItem<ExtractRoutes<TChildren>, ExtractResponses<TChildren>>;
   };
@@ -359,6 +393,10 @@ export type PathHelpers<TEnv> = {
    * `{ viewTransition: false }` to keep #1 without the router boundary. A view
    * transition cannot fire without a startTransition. See
    * skills/view-transitions for the startTransition x ViewTransition matrix.
+   *
+   * Pass `when: (ctx) => boolean` to gate the transition per request: it runs
+   * server-side after the route handler (can read `ctx.get(...)`), and returning
+   * false drops the transition so the navigation streams its loading() skeleton.
    */
   transition: {
     (): TransitionItem;

package/src/urls/path-helper.ts

@@ -39,10 +39,6 @@ import {
   runAndValidateUseItems,
 } from "../route-definition/dsl-helpers.js";
 
-/**
- * Apply URL prefix to a pattern
- * Handles edge cases like "/" patterns and double slashes
- */
 function applyUrlPrefix(prefix: string, pattern: string): string {
   if (!prefix) return pattern;
   if (pattern === "/") return prefix;
@@ -52,29 +48,17 @@ function applyUrlPrefix(prefix: string, pattern: string): string {
   return prefix + pattern;
 }
 
-/**
- * Apply name prefix to a route name
- */
 function applyNamePrefix(prefix: string | undefined, name: string): string {
   if (!prefix) return name;
   return `${prefix}.${name}`;
 }
 
-/**
- * Resolve response type from path options (set by path.json(), path.text(), etc.)
- */
 function resolveResponseType(
   options: PathOptions | undefined,
 ): string | undefined {
   return options?.[RESPONSE_TYPE];
 }
 
-/**
- * Create path() helper
- *
- * The path() function is the key new feature - it combines URL pattern
- * with handler at the definition site.
- */
 export function createPathHelper<TEnv>(): PathFn<TEnv> {
   return ((
     pattern: string,
@@ -91,8 +75,6 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       "path() cannot be used inside parallel()",
     );
 
-    // Walk the parent chain to prevent path() nested under another path(),
-    // even when separated by intermediate layouts (e.g. path(layout(path())))
     {
       let ancestor = ctx.parent;
       while (ancestor) {
@@ -104,7 +86,6 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       }
     }
 
-    // Determine options and use based on argument types
     let options: PathOptions | undefined;
     let use: (() => UseItems<RouteUseItem>) | undefined;
 
@@ -117,49 +98,29 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       use = maybeUse;
     }
 
-    // Merge handler.use() defaults with explicit use()
-    // Response routes (path.json, path.text, etc.) only allow middleware + cache
     const handlerUseFn = resolveHandlerUse(handler);
     const mountSite = resolveResponseType(options) ? "response" : "path";
     const mergedUse = mergeHandlerUse(handlerUseFn, use, mountSite);
 
-    // Get prefixes from context (set by include())
     const urlPrefix = getUrlPrefix();
     const namePrefix = getNamePrefix();
 
-    // Apply URL prefix to pattern
     const prefixedPattern = applyUrlPrefix(urlPrefix, pattern);
 
-    // Generate route name - use provided name or generate from pattern
     const localName =
       options?.name || `$path_${pattern.replace(/[/:*?]/g, "_")}`;
     if (options?.name) {
       validateUserRouteName(options.name);
     }
-    // Apply name prefix if set (from include())
     const routeName = applyNamePrefix(namePrefix, localName);
 
     const namespace = `${ctx.namespace}.${store.getNextIndex("route")}.${routeName}`;
 
-    // Per-request pruning: skip registration for routes that won't be rendered.
-    // forRoute is set by loadManifest() to the matched route name. During
-    // evaluateLazyEntry() (route matching), forRoute is unset so all routes
-    // register normally. We still increment counters to keep shortCodes stable
-    // across different routes (needed for segment reconciliation on navigation).
-    //
-    // include() does not need its own forRoute pruning. include() creates lazy
-    // entries that defer handler execution until route matching. When the lazy
-    // handler eventually runs inside loadManifest(), this path() check already
-    // covers all routes defined inside the include.
     if (ctx.forRoute && routeName !== ctx.forRoute) {
       store.getShortCode("route");
       return { type: "route" } as RouteItem;
     }
 
-    // Ensure handler is always a function (wrap ReactNode or extract from prerender/static def)
-    // For prerender stubs (production builds where handler code is evicted),
-    // handler.handler is undefined — provide a notFound fallback so requests
-    // for non-prerendered params get 404 instead of "handler is not a function".
     const wrappedHandler: Handler<any, any, TEnv> =
       typeof handler === "function"
         ? (handler as Handler<any, any, TEnv>)
@@ -190,7 +151,6 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       type: "route" as const,
       parent: ctx.parent,
       handler: wrappedHandler,
-      // Store the PREFIXED pattern for route matching
       pattern: prefixedPattern,
       ...(urlPrefix ? { mountPath: urlPrefix } : {}),
       ...(isPassthroughHandler(handler)
@@ -215,31 +175,30 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       ...(resolveResponseType(options)
         ? { responseType: resolveResponseType(options) }
         : {}),
+      // PPR shell-caching opt-in (document-level). Stored raw; the integrated
+      // serve path normalizes it via resolvePprConfig (rsc/shell-serve.ts).
+      ...(options?.ppr !== undefined && options.ppr !== false
+        ? { ppr: options.ppr }
+        : {}),
     };
 
-    // Capture namespace prefix on static handler for build-time reverse() resolution
     if (isStaticHandler(handler) && handler.$$id && ctx.namePrefix) {
       (handler as any).$$routePrefix = ctx.namePrefix;
     }
 
-    // Check for duplicate route names (TypeScript should catch this, but runtime check too)
     invariant(
       ctx.manifest.get(routeName) === undefined,
       `Duplicate route name: ${routeName} at ${namespace}`,
     );
 
-    // Register route entry with prefixed name
     ctx.manifest.set(routeName, entry);
 
-    // Register root-scope flag for dot-local reverse resolution
     registerRouteRootScope(routeName, getRootScoped());
 
-    // Also store pattern in a separate map for URL generation
     if (ctx.patterns) {
       ctx.patterns.set(routeName, prefixedPattern);
     }
 
-    // Store pattern grouped by URL prefix for separate entry creation
     if (ctx.patternsByPrefix) {
       const urlPrefix = getUrlPrefix() || "";
       if (!ctx.patternsByPrefix.has(urlPrefix)) {
@@ -248,12 +207,10 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       ctx.patternsByPrefix.get(urlPrefix)!.set(routeName, prefixedPattern);
     }
 
-    // Store trailing slash config if specified
     if (options?.trailingSlash && ctx.trailingSlash) {
       ctx.trailingSlash.set(routeName, options.trailingSlash);
     }
 
-    // Store search schema if specified
     if (options?.search) {
       if (ctx.searchSchemas) {
         ctx.searchSchemas.set(routeName, options.search);
@@ -261,7 +218,6 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       registerSearchSchema(routeName, options.search);
     }
 
-    // Run merged use callback (handler.use defaults + explicit use) if present
     if (mergedUse) {
       const result = runAndValidateUseItems(
         store,
@@ -278,10 +234,6 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
   }) as PathFn<TEnv>;
 }
 
-/**
- * Attach response type tag methods (.json, .text, .html, .xml, .md, .image, .stream, .any) to a path helper.
- * Each tag wraps the original path() call with the RESPONSE_TYPE option set.
- */
 export function attachPathResponseTags<TEnv>(
   pathFn: PathFn<TEnv>,
 ): PathFn<TEnv> & {
@@ -303,7 +255,6 @@ export function attachPathResponseTags<TEnv>(
     ) => {
       let options: PathOptions;
       let use: (() => any[]) | undefined;
-
       if (typeof optionsOrUse === "function") {
         options = { [RESPONSE_TYPE]: responseType };
         use = optionsOrUse;

package/src/urls/pattern-types.ts

@@ -35,12 +35,48 @@ export type LocalOnlyInclude = string & { [LOCAL_ONLY_BRAND]: void };
 /**
  * Options for path() function
  */
+/**
+ * Options for the `ppr` path option (PPR shell caching — Axis 2, see
+ * docs/design/ppr-shell-resume.md and the /ppr skill). Declaring
+ * `ppr: true | PartialPrerenderProps` on a page route opts that DOCUMENT into
+ * shell capture: the rendered HTML shell (everything that is not a live hole) is
+ * cached and, on a later GET, flushed immediately while fizz resumes only the
+ * holes. Serving is integral to the router — there is no middleware to mount;
+ * the shell store is the app-level `createRouter({ cache })` store (which must
+ * implement the `getShell`/`putShell` family).
+ */
+export interface PartialPrerenderProps {
+  /**
+   * Shell time-to-live in seconds. Defaults to 300 (`ppr: true` uses the same
+   * default).
+   */
+  ttl?: number;
+  /**
+   * Stale-while-revalidate window in seconds: a stale shell is still served
+   * while a background recapture refreshes it.
+   */
+  swr?: number;
+  /**
+   * Operational tags attached to the captured shell entry for
+   * `updateTag()`/`revalidateTag()`-driven eviction. UNIONED with the tags the
+   * capture render auto-collects (the shell's own non-loader request tags).
+   */
+  tags?: string[];
+}
+
 export interface PathOptions<
   TName extends string = string,
   TSearch extends SearchSchema = {},
 > {
   /** Route name for href() lookups */
   name?: TName;
+  /**
+   * PPR shell caching opt-in for this page route (document-level). `true` uses
+   * the default policy (ttl 300); an object sets ttl/swr/tags. See
+   * {@link PartialPrerenderProps}. Routes without this option are pure axis 1 —
+   * no capture, no store reads, no logs.
+   */
+  ppr?: boolean | PartialPrerenderProps;
   /** Search param schema for typed query parameters */
   search?: TSearch;
   /** Trailing slash behavior: "never" (redirect /path/ to /path), "always" (redirect /path to /path/), "ignore" (match both) */

package/src/urls/type-extraction.ts

@@ -81,16 +81,26 @@ type ExtractRoutesFromItem<T> =
   // When search schema is non-empty, value becomes { path, search } object
   T extends TypedRouteItem<infer TName, infer TPattern, any, infer TSearch>
     ? TName extends string
-      ? TName extends UnnamedRoute
-        ? {} // Exclude unnamed routes from type map
-        : {} extends TSearch
-          ? { [K in TName]: TPattern }
-          : {
-              [K in TName]: {
-                readonly path: TPattern;
-                readonly search: TSearch;
-              };
-            }
+      ? // Widened-name guard (#642): some name-less call forms — notably the
+        // 3-arg children-fn overload path(pattern, component, () => [...]) —
+        // let TName infer to the bare `string` constraint instead of the
+        // UnnamedRoute sentinel, because the children-fn argument structurally
+        // satisfies the all-optional PathOptions<TName> union member. Mapping
+        // over a bare `string` key would emit `{ [K in string]: TPattern }`, an
+        // index signature that poisons the whole sibling map (Rango.Path
+        // collapses to never). Treat an unresolved name as unnamed.
+        string extends TName
+        ? {}
+        : TName extends UnnamedRoute
+          ? {} // Exclude unnamed routes from type map
+          : {} extends TSearch
+            ? { [K in TName]: TPattern }
+            : {
+                [K in TName]: {
+                  readonly path: TPattern;
+                  readonly search: TSearch;
+                };
+              }
       : {}
     : // TypedIncludeItem: extract prefixed routes (both name and URL prefix)
       T extends TypedIncludeItem<
@@ -128,9 +138,15 @@ type ExtractRoutesFromItems<T extends readonly any[]> = T extends readonly any[]
   ? UnionToIntersection<
       { [K in keyof T]: ExtractRoutesFromItem<T[K]> }[number]
     > extends infer R
-    ? R extends Record<string, any>
-      ? R
-      : {}
+    ? // Blast-radius guard: never let a single malformed item collapse the
+      // whole map. A `never` intersection satisfies `extends Record<string,any>`
+      // (never extends everything), so check it explicitly first and fall back
+      // to `{}` rather than propagating `never`. See #642.
+      [R] extends [never]
+      ? {}
+      : R extends Record<string, any>
+        ? R
+        : {}
     : {}
   : {};
 
@@ -169,9 +185,15 @@ type PrefixKeys<
 type ExtractResponsesFromItem<T> =
   T extends TypedRouteItem<infer TName, any, infer TData>
     ? TName extends string
-      ? TName extends UnnamedRoute
+      ? // Widened-name guard (#642), parallels ExtractRoutesFromItem. A name-less
+        // children-fn path.json(pattern, handler, () => [...]) infers TName as
+        // bare `string`; without this the response map picks up an index
+        // signature { [K in string]: TData } that wipes named siblings.
+        string extends TName
         ? {}
-        : { [K in TName]: TData }
+        : TName extends UnnamedRoute
+          ? {}
+          : { [K in TName]: TData }
       : {}
     : T extends TypedIncludeItem<any, infer TNamePrefix, any, infer TResponses>
       ? TNamePrefix extends LocalOnlyInclude
@@ -206,9 +228,12 @@ type ExtractResponsesFromItems<T extends readonly any[]> =
     ? UnionToIntersection<
         { [K in keyof T]: ExtractResponsesFromItem<T[K]> }[number]
       > extends infer R
-      ? R extends Record<string, unknown>
-        ? R
-        : {}
+      ? // Blast-radius guard (parallels ExtractRoutesFromItems). See #642.
+        [R] extends [never]
+        ? {}
+        : R extends Record<string, unknown>
+          ? R
+          : {}
       : {}
     : {};
 
@@ -220,44 +245,53 @@ export type ExtractResponses<T extends readonly any[]> =
   ExtractResponsesFromItems<T>;
 
 // ============================================================================
-// Response Envelope Types
+// Response Error (RFC 9457 problem+json) Type
 // ============================================================================
 
 /**
- * Error shape returned in the `{ error }` side of a JSON response envelope.
- */
-export interface ResponseError {
-  message: string;
-  code?: string;
-  type?: string;
-  stack?: string;
-}
-
-/**
- * Discriminated union envelope for JSON response routes.
- * Consumers check `result.error` to discriminate between success and failure.
+ * RFC 9457 (problem+json) error body returned by JSON response routes on a
+ * non-2xx status. Sent verbatim as the response body (not wrapped) with
+ * content-type `application/problem+json`.
  *
  * @example
  * ```typescript
- * const result: ResponseEnvelope<Product> = await fetch(url).then(r => r.json());
- * if (result.error) {
- *   console.log(result.error.message, result.error.code);
+ * const res = await fetch(url);
+ * if (!res.ok) {
+ *   const problem: ProblemDetails = await res.json();
+ *   console.log(problem.code, problem.detail); // "NOT_FOUND", "Product not found"
  *   return;
  * }
- * result.data.name // fully typed
+ * const product = await res.json(); // bare value, no envelope
  * ```
  */
-export type ResponseEnvelope<T> =
-  | { data: T; error?: undefined }
-  | { data?: undefined; error: ResponseError };
+export interface ProblemDetails {
+  /**
+   * URI reference identifying the problem type. Omitted in this phase (per RFC
+   * 9457 an absent `type` is treated as `"about:blank"` — no semantics beyond
+   * the HTTP status); per-route problem-type URIs arrive with the
+   * declared-errors map later.
+   */
+  type?: string;
+  /** Short, human-readable summary (the HTTP status reason phrase). */
+  title: string;
+  /** The HTTP status code. */
+  status: number;
+  /** Human-readable explanation specific to this occurrence (the error message). */
+  detail: string;
+  /** Stable machine-readable error code (`RouterError.code`, else `"INTERNAL"`). */
+  code: string;
+  /** Stack trace, included in development only. */
+  stack?: string;
+}
 
 // ============================================================================
 // Response Type Consumer Utilities
 // ============================================================================
 
 /**
- * Extract the response data type for a named route from a UrlPatterns instance.
- * Wraps in ResponseEnvelope since JSON response routes return enveloped data.
+ * Extract the JSON response payload type for a named route from a UrlPatterns
+ * instance. JSON response routes send the handler's return value verbatim
+ * (bare), so this resolves to the wire value a consumer receives — no envelope.
  *
  * @example
  * ```typescript
@@ -266,7 +300,7 @@ export type ResponseEnvelope<T> =
  * ]);
  *
  * type HealthData = RouteResponse<typeof apiPatterns, "health">;
- * // ResponseEnvelope<{ status: string; timestamp: number }>
+ * // { status: string; timestamp: number }
  * ```
  *
  * The payload is the JSON wire shape (via `Rango.JsonSerialize`), matching
@@ -277,6 +311,6 @@ export type RouteResponse<TPatterns, TName extends string> = TPatterns extends {
   readonly _responses?: infer R;
 }
   ? TName extends keyof R
-    ? ResponseEnvelope<JsonSerialize<Exclude<R[TName], Response>>>
+    ? JsonSerialize<Exclude<R[TName], Response>>
     : never
   : never;

package/src/urls/urls-function.ts

@@ -34,24 +34,18 @@ export function urls<
 >(
   builder: (helpers: PathHelpers<TEnv>) => TItems,
 ): UrlPatterns<TEnv, ExtractRoutes<TItems>, ExtractResponses<TItems>> {
-  // Create the handler function that will be called by the router
   const handler = () => {
     invariant(
       typeof builder === "function",
       "urls() expects a builder function as its argument",
     );
 
-    // Get base helpers from the existing route-definition module
     const baseHelpers = createRouteHelpers<any, TEnv>();
 
-    // Create the path helper (with .json, .text, .html, .xml, .image, .stream, .any tags)
     const pathHelper = attachPathResponseTags(createPathHelper<TEnv>());
 
-    // Create the include helper
     const includeHelper = createIncludeHelper<TEnv>();
 
-    // Combine all helpers
-    // Note: layout and cache are cast to their typed versions - phantom types don't affect runtime
     const helpers: PathHelpers<TEnv> = {
       path: pathHelper as any,
       include: includeHelper as any,
@@ -64,25 +58,17 @@ export function urls<
       loading: baseHelpers.loading,
       errorBoundary: baseHelpers.errorBoundary,
       notFoundBoundary: baseHelpers.notFoundBoundary,
-      when: baseHelpers.when,
       cache: baseHelpers.cache as PathHelpers<TEnv>["cache"],
       transition: baseHelpers.transition as PathHelpers<TEnv>["transition"],
     };
 
-    // Execute builder directly - manifest.ts handles RootLayout wrapping
-    // for inline handlers (non-Promise results).
-    // For nested include() calls, routes inherit the outer RootLayout.
     const builderResult = builder(helpers).flat(3) as AllUseItems[];
     return processItems(builderResult);
   };
 
-  // trailingSlash config is populated when handler() runs
-  // We expose it via a getter that reads from the context after handler execution
   return {
     handler,
     get trailingSlash() {
-      // Get the trailingSlash map from the current context
-      // This will be populated after handler() is called
       const store = getContext();
       const ctx = store.context.getStore();
       if (!ctx?.trailingSlash) {