@rangojs/router 0.0.0-experimental.35 → 0.0.0-experimental.358c376d

package/src/urls/pattern-types.ts

@@ -1,12 +1,19 @@
-import type { ReactNode } from "react";
-import type { Handler, TrailingSlashMode } from "../types.js";
-import type {
-  AllUseItems,
-  RouteUseItem,
-  UrlPatternsBrand,
-} from "../route-types.js";
+import type { TrailingSlashMode } from "../types.js";
+import type { AllUseItems, UrlPatternsBrand } from "../route-types.js";
 import type { SearchSchema } from "../search-params.js";
 import { RESPONSE_TYPE } from "./response-types.js";
+import type { DefaultEnv } from "../types.js";
+import type { PathHelpers } from "./path-helper-types.js";
+
+/**
+ * Builder function accepted by urls() and as a shorthand for routes()/urls option.
+ * When passed directly to routes() or createRouter({ urls }), it is wrapped in urls() automatically.
+ */
+export type UrlBuilder<
+  TEnv = DefaultEnv,
+  TItems extends readonly (AllUseItems | readonly AllUseItems[])[] =
+    readonly AllUseItems[],
+> = (helpers: PathHelpers<TEnv>) => TItems;
 
 /**
  * Sentinel type for unnamed routes.
@@ -28,12 +35,77 @@ 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[];
+  /**
+   * Upper bound (serialized UTF-8 bytes) on the capture data snapshot riding
+   * inside the shell entry. The snapshot duplicates every cache-store value
+   * the capture pinned, so a page over a large cache() segment can push the
+   * entry toward store value limits (Cloudflare KV caps a value at 25 MiB).
+   * Over the cap the snapshot is skipped: the shell is still stored and
+   * served, but pinned reads fall back to the live store, so drifted cached
+   * content can hydration-mismatch and be repaired client-side (the
+   * pre-snapshot behavior). Reported once per key. Defaults to 8 MiB.
+   */
+  maxSnapshotBytes?: number;
+  /**
+   * Capture settle budget in MILLISECONDS (default 15000). Bounds the whole
+   * background capture: the wait for deferred shell material — top-level
+   * pushed handle promises (`ctx.use(Meta)(promise.then(...))` and friends)
+   * are AWAITED and their settled values baked into the stored shell — AND
+   * the fizz prerender deadline. Declare it to tighten the budget below the
+   * default or when a route's shell material takes longer than 15s to
+   * settle. A budget that expires with pushes still pending REFUSES the
+   * capture (the route stays MISS with the once-per-key warning) — a shell
+   * with missing head material is never stored. Capture is background work
+   * (waitUntil), so a longer budget costs latency-to-HIT only, never a served
+   * response; the platform waitUntil lifetime (workerd: ~30s past response
+   * completion) is the physical ceiling — the default's derivation lives in
+   * docs/design/ppr-shell-resume.md (Cost model). Build-time captures
+   * (Prerender+ppr, producer B) honor the same budget with no platform
+   * ceiling. Non-finite or sub-1ms values fall back to the default.
+   */
+  captureTimeout?: number;
+}
+
 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) */
@@ -42,16 +114,6 @@ export interface PathOptions<
   [RESPONSE_TYPE]?: string;
 }
 
-/**
- * Internal representation of a URL pattern definition
- */
-export interface PathDefinition {
-  pattern: string;
-  name?: string;
-  handler: ReactNode | Handler<any, any, any>;
-  use?: RouteUseItem[];
-}
-
 /**
  * Result of urls() - contains the route definitions
  */
@@ -60,8 +122,6 @@ export interface UrlPatterns<
   TRoutes extends Record<string, any> = Record<string, string>,
   TResponses extends Record<string, unknown> = Record<string, unknown>,
 > {
-  /** Internal: route definitions */
-  readonly definitions: PathDefinition[];
   /** Internal: compiled handler function */
   readonly handler: () => AllUseItems[];
   /** Internal: trailing slash config per route name */
@@ -76,6 +136,40 @@ export interface UrlPatterns<
   readonly _responses?: TResponses;
 }
 
+/**
+ * Extract the phantom env type carried by a UrlPatterns value.
+ */
+export type UrlPatternsEnv<T> =
+  T extends UrlPatterns<infer TEnv, any, any> ? TEnv : never;
+
+/**
+ * Guards `routes()` env compatibility without over-constraining.
+ *
+ * - An env-agnostic block (its env is `unknown` — e.g. a shared urls() module,
+ *   or an app that does not augment `Rango.Env`) attaches to any router.
+ * - A block carrying a concrete env is accepted only when the router env
+ *   (`TRouterEnv`) satisfies it; resolves to `never` otherwise, so a
+ *   `urls<{ DB: D1Database }>()` cannot be mounted on a `createRouter<{}>()`.
+ *
+ * Use as `patterns: T & EnvCompatible<T, TEnv>` so `T` still infers from the
+ * argument — a bare `EnvCompatible<T, TEnv>` parameter sits in a non-inferrable
+ * conditional position and would collapse `T` to its constraint.
+ *
+ * Known limitation: `TRouterEnv extends ...` distributes over a union router env,
+ * so a `urls<A>()` block is accepted on `createRouter<A | B>()` even though the
+ * `B` arm cannot supply `A`'s env. Suppressing distribution with
+ * `[TRouterEnv] extends [...]` would close that edge but breaks the common
+ * generic-`TEnv` call sites (a deferred type parameter can't resolve the tuple
+ * conditional, so the intersection stops reducing to `T`). A router has one env,
+ * so a union env is not a supported pattern; the distributive form is kept.
+ */
+export type EnvCompatible<TPatterns, TRouterEnv> =
+  unknown extends UrlPatternsEnv<TPatterns>
+    ? TPatterns
+    : TRouterEnv extends UrlPatternsEnv<TPatterns>
+      ? TPatterns
+      : never;
+
 /**
  * Options for include()
  */

package/src/urls/response-types.ts

@@ -4,6 +4,8 @@ import type {
   DefaultReverseRouteMap,
   DefaultVars,
 } from "../types/global-namespace.js";
+import type { UseItems, ResponseRouteUseItem } from "../route-types.js";
+import type { RequestScope } from "../types/request-scope.js";
 
 /**
  * Reverse function for response handler contexts.
@@ -30,17 +32,31 @@ type ResponseReverseFunction = [DefaultReverseRouteMap] extends [
  * Symbol marking a route as a response route (non-RSC).
  * Stored on PathOptions and UrlPatterns to signal the trie to short-circuit.
  */
-export const RESPONSE_TYPE: unique symbol = Symbol.for(
-  "rangojs.responseType",
-) as any;
+export const RESPONSE_TYPE: unique symbol = Symbol.for("rangojs.responseType");
+
+/**
+ * Shared shape of a response-route handler: a function returning TReturn (or a
+ * promise of it), plus an optional composable `use` thunk merged at mount time.
+ */
+type ResponseHandlerOf<
+  TReturn,
+  TParams = Record<string, string>,
+  TEnv = any,
+> = ((
+  ctx: ResponseHandlerContext<TParams, TEnv>,
+) => TReturn | Promise<TReturn>) & {
+  /** Composable default DSL items merged when the handler is mounted. */
+  use?: () => UseItems<ResponseRouteUseItem>;
+};
 
 /**
  * Handler that must return Response (not ReactNode).
  * Used by path.image(), path.stream(), path.any() (binary/streaming data).
  */
-export type ResponseHandler<TParams = Record<string, string>, TEnv = any> = (
-  ctx: ResponseHandlerContext<TParams, TEnv>,
-) => Response | Promise<Response>;
+export type ResponseHandler<
+  TParams = Record<string, string>,
+  TEnv = any,
+> = ResponseHandlerOf<Response, TParams, TEnv>;
 
 /**
  * JSON-serializable value type for auto-wrap support.
@@ -60,9 +76,7 @@ export type JsonValue =
 export type JsonResponseHandler<
   TParams = Record<string, string>,
   TEnv = any,
-> = (
-  ctx: ResponseHandlerContext<TParams, TEnv>,
-) => JsonValue | Response | Promise<JsonValue | Response>;
+> = ResponseHandlerOf<JsonValue | Response, TParams, TEnv>;
 
 /**
  * Handler for text-based response routes (text, html, xml).
@@ -71,9 +85,7 @@ export type JsonResponseHandler<
 export type TextResponseHandler<
   TParams = Record<string, string>,
   TEnv = any,
-> = (
-  ctx: ResponseHandlerContext<TParams, TEnv>,
-) => string | Response | Promise<string | Response>;
+> = ResponseHandlerOf<string | Response, TParams, TEnv>;
 
 /**
  * Lighter handler context for response routes.
@@ -83,19 +95,10 @@ export type TextResponseHandler<
 export interface ResponseHandlerContext<
   TParams = Record<string, string>,
   TEnv = any,
-> {
-  request: Request;
+> extends RequestScope<TEnv> {
   params: TParams;
   /** @internal Phantom property for params type invariance. Prevents mounting handlers on wrong routes. */
   readonly _paramCheck?: (params: TParams) => TParams;
-  /** Platform bindings (DB, KV, secrets, etc.). */
-  env: TEnv;
-  /** Query parameters from the URL (system params like `_rsc*` are filtered). */
-  searchParams: URLSearchParams;
-  /** The full URL object (with system params filtered). */
-  url: URL;
-  /** The pathname portion of the request URL. */
-  pathname: string;
   reverse: ResponseReverseFunction;
   /** Read a variable set by middleware via ctx.set(key, value) or ctx.set(ContextVar, value). */
   get: {

package/src/urls/type-extraction.ts

@@ -1,4 +1,4 @@
-import type { ExtractParams } from "../types.js";
+import type { JsonSerialize } from "../serialize.js";
 import type {
   TypedRouteItem,
   TypedIncludeItem,
@@ -6,11 +6,7 @@ import type {
   TypedCacheItem,
   TypedTransitionItem,
 } from "../route-types.js";
-import type {
-  LocalOnlyInclude,
-  UnnamedRoute,
-  UrlPatterns,
-} from "./pattern-types.js";
+import type { LocalOnlyInclude, UnnamedRoute } from "./pattern-types.js";
 
 // ============================================================================
 // Route Type Extraction Utilities
@@ -67,62 +63,6 @@ type PrefixPatterns<
       : TRoutes[K];
 };
 
-/**
- * Depth counter for limiting recursion (max 40 levels)
- * Supports up to 40 sibling items at any level of a urls() call
- * Note: Higher values hit TypeScript's internal recursion limits
- */
-type Depth = [
-  never,
-  0,
-  1,
-  2,
-  3,
-  4,
-  5,
-  6,
-  7,
-  8,
-  9,
-  10,
-  11,
-  12,
-  13,
-  14,
-  15,
-  16,
-  17,
-  18,
-  19,
-  20,
-  21,
-  22,
-  23,
-  24,
-  25,
-  26,
-  27,
-  28,
-  29,
-  30,
-  31,
-  32,
-  33,
-  34,
-  35,
-  36,
-  37,
-  38,
-  39,
-];
-
-/**
- * Force TypeScript to eagerly evaluate a type.
- * This helps with interface extension by creating a "concrete" object type.
- */
-type Simplify<T> =
-  T extends Record<string, string> ? { [K in keyof T]: T[K] } : T;
-
 /**
  * Convert a union type to an intersection type.
  * Used to combine route maps from multiple siblings without recursive tuple processing.
@@ -135,24 +75,32 @@ type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
 
 /**
  * Extract routes from a single item (path, include, layout, cache with children)
- * D is the current depth level for nested layouts/caches
  */
-type ExtractRoutesFromItem<T, D extends number = 40> = [D] extends [never]
-  ? {} // Max depth reached, stop recursion
-  : // TypedRouteItem: extract name -> pattern (exclude unnamed routes)
-    // When search schema is non-empty, value becomes { path, search } object
-    T extends TypedRouteItem<infer TName, infer TPattern, any, infer TSearch>
+type ExtractRoutesFromItem<T> =
+  // TypedRouteItem: extract name -> pattern (exclude unnamed routes)
+  // 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<
@@ -185,30 +133,28 @@ type ExtractRoutesFromItem<T, D extends number = 40> = [D] extends [never]
  * Extract routes from an array of items using mapped types.
  * Uses UnionToIntersection to combine routes without recursive tuple processing,
  * removing the sibling limit that was caused by TypeScript recursion limits.
- * D is passed to ExtractRoutesFromItem for nested depth tracking.
  */
-type ExtractRoutesFromItems<
-  T extends readonly any[],
-  D extends number = 40,
-> = T extends readonly any[]
+type ExtractRoutesFromItems<T extends readonly any[]> = T extends readonly any[]
   ? UnionToIntersection<
-      { [K in keyof T]: ExtractRoutesFromItem<T[K], D> }[number]
+      { [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
+        : {}
     : {}
   : {};
 
 /**
  * Main utility: extract route map from urls() callback return type
  * Uses mapped types for sibling processing (no sibling limit).
- * Uses Simplify to force eager evaluation for interface extension compatibility.
  */
-export type ExtractRoutes<T extends readonly any[]> = ExtractRoutesFromItems<
-  T,
-  40
->;
+export type ExtractRoutes<T extends readonly any[]> = ExtractRoutesFromItems<T>;
 
 // ============================================================================
 // Response Type Extraction Utilities
@@ -236,13 +182,18 @@ type PrefixKeys<
  * Extract response data types from a single item.
  * Parallel to ExtractRoutesFromItem but extracts name -> TData mapping.
  */
-type ExtractResponsesFromItem<T, D extends number = 40> = [D] extends [never]
-  ? {}
-  : T extends TypedRouteItem<infer TName, any, infer TData>
+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
@@ -272,86 +223,75 @@ type ExtractResponsesFromItem<T, D extends number = 40> = [D] extends [never]
  * Extract responses from an array of items using mapped types.
  * Parallel to ExtractRoutesFromItems.
  */
-type ExtractResponsesFromItems<
-  T extends readonly any[],
-  D extends number = 40,
-> = T extends readonly any[]
-  ? UnionToIntersection<
-      { [K in keyof T]: ExtractResponsesFromItem<T[K], D> }[number]
-    > extends infer R
-    ? R extends Record<string, unknown>
-      ? R
+type ExtractResponsesFromItems<T extends readonly any[]> =
+  T extends readonly any[]
+    ? UnionToIntersection<
+        { [K in keyof T]: ExtractResponsesFromItem<T[K]> }[number]
+      > extends infer R
+      ? // Blast-radius guard (parallels ExtractRoutesFromItems). See #642.
+        [R] extends [never]
+        ? {}
+        : R extends Record<string, unknown>
+          ? R
+          : {}
       : {}
-    : {}
-  : {};
+    : {};
 
 /**
  * Main utility: extract response data type map from urls() callback return type.
  * Parallel to ExtractRoutes.
  */
 export type ExtractResponses<T extends readonly any[]> =
-  ExtractResponsesFromItems<T, 40>;
-
-// ============================================================================
-// Type Utilities for path()
-// ============================================================================
-
-/**
- * Extract route names from a UrlPatterns result
- * Used for type-safe href() generation
- */
-export type ExtractRouteNames<T extends UrlPatterns<any>> =
-  T extends UrlPatterns<infer _TEnv>
-    ? string // For now, will be refined with full implementation
-    : never;
-
-/**
- * Extract params for a specific route name
- */
-export type ExtractPathParams<
-  T extends UrlPatterns<any>,
-  K extends string,
-> = ExtractParams<string>; // Will be refined with pattern tracking
+  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
@@ -360,13 +300,17 @@ 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
+ * `Rango.PathResponse` and what `fetch().then(r => r.json())` actually yields —
+ * e.g. a `Date` field resolves as `string`.
  */
 export type RouteResponse<TPatterns, TName extends string> = TPatterns extends {
   readonly _responses?: infer R;
 }
   ? TName extends keyof R
-    ? ResponseEnvelope<Exclude<R[TName], Response>>
+    ? JsonSerialize<Exclude<R[TName], Response>>
     : never
   : never;

package/src/urls/urls-function.ts

@@ -3,7 +3,7 @@ import type { AllUseItems } from "../route-types.js";
 import { getContext } from "../server/context";
 import { invariant } from "../errors";
 import { createRouteHelpers } from "../route-definition.js";
-import type { PathDefinition, UrlPatterns } from "./pattern-types.js";
+import type { UrlPatterns } from "./pattern-types.js";
 import type { PathHelpers } from "./path-helper-types.js";
 import type { ExtractRoutes, ExtractResponses } from "./type-extraction.js";
 import { createPathHelper, attachPathResponseTags } from "./path-helper.js";
@@ -34,27 +34,18 @@ export function urls<
 >(
   builder: (helpers: PathHelpers<TEnv>) => TItems,
 ): UrlPatterns<TEnv, ExtractRoutes<TItems>, ExtractResponses<TItems>> {
-  // Collect path definitions during build
-  const definitions: PathDefinition[] = [];
-
-  // 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,
@@ -67,26 +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 {
-    definitions,
     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) {