@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.141

package/src/urls/include-helper.ts

@@ -0,0 +1,162 @@
+import type { AllUseItems, IncludeItem } from "../route-types.js";
+import {
+  getUrlPrefix,
+  getNamePrefix,
+  requireDslContext,
+} from "../server/context";
+import {
+  INTERNAL_INCLUDE_SCOPE_PREFIX,
+  validateUserRouteName,
+} from "../route-name.js";
+import type { UrlPatterns, IncludeOptions } from "./pattern-types.js";
+import type { IncludeProvider } from "./include-provider.js";
+import type { IncludeFn } from "./path-helper-types.js";
+
+function hasExplicitNameOption(options: IncludeOptions | undefined): boolean {
+  return !!options && Object.prototype.hasOwnProperty.call(options, "name");
+}
+
+function allocateInternalIncludeScopeId(
+  counters: Record<string, number>,
+): string {
+  const key = "__include_scope__";
+  const index = counters[key] ?? 0;
+  counters[key] = index + 1;
+  return `${INTERNAL_INCLUDE_SCOPE_PREFIX}${index}`;
+}
+
+/**
+ * Recursively walk items, recursing into layout children.
+ *
+ * All includes are lazy and kept as-is; the router expands them on the first
+ * matching request.
+ */
+export function processItems(items: readonly AllUseItems[]): AllUseItems[] {
+  const result: AllUseItems[] = [];
+
+  for (const item of items) {
+    if (!item) continue;
+
+    if (item.type === "include") {
+      result.push(item);
+    } else if (item.type === "layout" && (item as any).uses) {
+      const layoutItem = item as any;
+      layoutItem.uses = processItems(layoutItem.uses);
+      result.push(layoutItem);
+    } else {
+      result.push(item);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Create include() helper for composing URL patterns
+ *
+ * All includes are lazy: the nested patterns are NOT expanded at definition
+ * time. Instead they are evaluated on the first request that matches the
+ * prefix, which improves cold start time for apps with many routes.
+ */
+export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
+  return (
+    prefix: string,
+    // A `urls()` value (eager) OR an async provider thunk
+    // (`() => import("./routes")`) whose evaluation is deferred to the first
+    // request matching `prefix`. The provider is stored unevaluated and
+    // resolved by the runtime lazy-include expansion / build-time discovery.
+    patterns: UrlPatterns<TEnv> | IncludeProvider<TEnv>,
+    options?: IncludeOptions,
+  ): IncludeItem => {
+    const { ctx } = requireDslContext("include() must be called inside urls()");
+
+    const explicitName = options?.name;
+    const hasExplicitName = hasExplicitNameOption(options);
+    if (hasExplicitName && explicitName) {
+      validateUserRouteName(explicitName);
+    }
+    const name = `$include_${prefix.replace(/[/:*?]/g, "_")}`;
+
+    // Capture context for deferred evaluation
+    const capturedUrlPrefix = getUrlPrefix();
+    const capturedNamePrefix = getNamePrefix();
+    const capturedParent = ctx.parent;
+    const fullPrefix = capturedUrlPrefix
+      ? capturedUrlPrefix.endsWith("/") && prefix.startsWith("/")
+        ? capturedUrlPrefix + prefix.slice(1)
+        : capturedUrlPrefix + prefix
+      : prefix;
+    const nextSegment = hasExplicitName
+      ? explicitName
+      : allocateInternalIncludeScopeId(ctx.counters);
+    const fullNamePrefix =
+      nextSegment !== undefined && nextSegment !== ""
+        ? capturedNamePrefix
+          ? `${capturedNamePrefix}.${nextSegment}`
+          : nextSegment
+        : capturedNamePrefix;
+
+    // Track this include for build-time manifest generation
+    if (ctx.trackedIncludes) {
+      ctx.trackedIncludes.push({
+        prefix,
+        fullPrefix,
+        namePrefix: fullNamePrefix,
+        patterns,
+        lazy: true,
+      });
+    }
+
+    // Allocate an include-scope token for this include() call. The token is
+    // appended to the parent's shortCode prefix whenever the include's
+    // direct-descendant shortCodes are generated (see getShortCode in
+    // context.ts), partitioning the parent's counter namespace so routes
+    // inside an include cannot collide with siblings declared outside it.
+    //
+    // Scopes compose: a nested include inside an outer include with scope
+    // "I0" allocates against the `${parent.shortCode}I0_include` counter
+    // and produces scope "I0I0", "I0I1", etc.
+    const parentScope = ctx.includeScope ?? "";
+    let includeScope = parentScope;
+    if (capturedParent?.shortCode) {
+      const includeCounterKey = `${capturedParent.shortCode}${parentScope}_include`;
+      ctx.counters[includeCounterKey] ??= 0;
+      includeScope = `${parentScope}I${ctx.counters[includeCounterKey]++}`;
+    }
+
+    // Snapshot parent's counters AFTER allocating the include scope so lazy
+    // manifest generation starts with the same counter state this include
+    // observed — its descendants still get fresh per-scope counters because
+    // they key off `${parent.shortCode}${includeScope}_*` (not shared with
+    // siblings outside the include).
+    const capturedCounters = { ...ctx.counters };
+
+    // Compute rootScoped at capture time, mirroring the logic in runWithPrefixes.
+    // This ensures lazy evaluation restores the correct scope state.
+    const parentRootScoped = ctx.rootScoped;
+    const capturedRootScoped =
+      nextSegment === ""
+        ? (parentRootScoped ?? true)
+        : nextSegment !== undefined
+          ? (parentRootScoped ?? false)
+          : parentRootScoped;
+
+    return {
+      type: "include",
+      name,
+      prefix,
+      patterns,
+      options,
+      lazy: true,
+      _lazyContext: {
+        urlPrefix: capturedUrlPrefix,
+        namePrefix: fullNamePrefix,
+        parent: capturedParent,
+        counters: capturedCounters,
+        cacheProfiles: ctx.cacheProfiles,
+        rootScoped: capturedRootScoped,
+        includeScope,
+      },
+    } as IncludeItem;
+  };
+}

package/src/urls/include-provider.ts

@@ -0,0 +1,71 @@
+import type { UrlPatterns } from "./pattern-types.js";
+
+/**
+ * What an async `include()` provider may resolve to: a `urls()` value directly,
+ * or a module namespace whose `default` export is a `urls()` value (the shape
+ * produced by `() => import("./routes")` when the route module does
+ * `export default urls(...)`).
+ */
+export type IncludeModule<TEnv = any> =
+  | UrlPatterns<TEnv>
+  | { default: UrlPatterns<TEnv> };
+
+/**
+ * An async/lazy include provider: a thunk returning a `urls()` value (or a
+ * Promise of one). The thunk is stored unevaluated by `include()` and called
+ * once, on the first request that matches the prefix — so the route module and
+ * its (code-split) subtree are not evaluated at startup.
+ *
+ * Forward-compatible: `() => import("./routes")` today (async, separate chunk);
+ * `() => m.routes` with native `import defer` later (sync, deferred eval).
+ */
+export type IncludeProvider<TEnv = any> = () =>
+  | IncludeModule<TEnv>
+  | Promise<IncludeModule<TEnv>>;
+
+/** True when the include() argument is a provider thunk rather than a value. */
+export function isIncludeProvider(value: unknown): value is IncludeProvider {
+  // A `urls()` value is a (branded) object; a provider is a function.
+  return typeof value === "function";
+}
+
+/** A `urls()` value is an object exposing a synchronous `handler()`. */
+function isUrlPatterns(value: unknown): value is UrlPatterns {
+  return (
+    !!value && typeof (value as { handler?: unknown }).handler === "function"
+  );
+}
+
+/**
+ * Normalize an async provider's resolved value to a `UrlPatterns`. Accepts a
+ * `urls()` value directly or a module whose `default` export is one.
+ */
+export function resolveIncludeModule<TEnv = any>(
+  mod: IncludeModule<TEnv>,
+  id?: string,
+): UrlPatterns<TEnv> {
+  // Prefer an explicit `default` export (the `export default urls(...)`
+  // convention) BEFORE duck-typing the namespace. isUrlPatterns() keys on a
+  // `.handler` function, but a routes module can legitimately carry a NAMED
+  // `export function handler(...)` alongside its `export default urls(...)`;
+  // checking the namespace first would then misidentify the whole module as the
+  // urls() value and invoke the user's helper as the DSL handler (the group
+  // 404s with a misleading error). A bare `() => urls(...)` provider (no
+  // module) has no `default`, so it still resolves via the mod-as-value branch.
+  const def = (mod as { default?: unknown })?.default;
+  if (isUrlPatterns(def)) return def as UrlPatterns<TEnv>;
+  if (isUrlPatterns(mod)) return mod as UrlPatterns<TEnv>;
+  // The common failure is a module namespace whose `default` is missing or not a
+  // urls() value (e.g. only named exports); `typeof` alone says "object" and
+  // hides that, so name the keys present. "provider" (not "async provider") —
+  // synchronous providers are supported (see IncludeProvider).
+  const got =
+    mod && typeof mod === "object"
+      ? `a module with keys [${Object.keys(mod).join(", ") || "none"}] but no valid \`default\``
+      : typeof mod;
+  throw new Error(
+    `[@rangojs/router] include() provider${id ? ` for "${id}"` : ""} must ` +
+      `resolve to a urls() value — either returned directly or as the module's ` +
+      `\`default\` export (e.g. \`export default urls(...)\`). Got ${got}.`,
+  );
+}

package/src/urls/index.ts

@@ -0,0 +1,44 @@
+export {
+  RESPONSE_TYPE,
+  type ResponseHandler,
+  type JsonValue,
+  type JsonResponseHandler,
+  type TextResponseHandler,
+  type ResponseHandlerContext,
+} from "./response-types.js";
+
+export type {
+  UnnamedRoute,
+  LocalOnlyInclude,
+  PathOptions,
+  PartialPrerenderProps,
+  UrlPatterns,
+  IncludeOptions,
+} from "./pattern-types.js";
+
+export type {
+  ExtractRoutes,
+  ExtractResponses,
+  ProblemDetails,
+  RouteResponse,
+} from "./type-extraction.js";
+
+export type {
+  PathFn,
+  ResponsePathFn,
+  JsonResponsePathFn,
+  TextResponsePathFn,
+  IncludeFn,
+  PathHelpers,
+} from "./path-helper-types.js";
+
+export { urls } from "./urls-function.js";
+
+export type {
+  AllUseItems,
+  IncludeItem,
+  TypedRouteItem,
+  TypedIncludeItem,
+  TypedLayoutItem,
+  TypedCacheItem,
+} from "../route-types.js";

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

@@ -0,0 +1,413 @@
+import type { ReactNode } from "react";
+import type {
+  ErrorBoundaryHandler,
+  ExtractParams,
+  Handler,
+  HandlerContext,
+  LoaderDefinition,
+  MiddlewareFn,
+  NotFoundBoundaryHandler,
+  PartialCacheOptions,
+  ShouldRevalidateFn,
+  TransitionConfig,
+} from "../types.js";
+import type {
+  AllUseItems,
+  TypedLayoutItem,
+  ParallelItem,
+  InterceptItem,
+  MiddlewareItem,
+  RevalidateItem,
+  LoaderItem,
+  LoadingItem,
+  ErrorBoundaryItem,
+  NotFoundBoundaryItem,
+  LayoutUseItem,
+  RouteUseItem,
+  ResponseRouteUseItem,
+  ParallelUseItem,
+  InterceptUseItem,
+  LoaderUseItem,
+  TypedCacheItem,
+  TransitionItem,
+  TypedTransitionItem,
+  TypedRouteItem,
+  TypedIncludeItem,
+  UseItems,
+} from "../route-types.js";
+import type { SearchSchema } from "../search-params.js";
+import type {
+  PrerenderHandlerDefinition,
+  PassthroughHandlerDefinition,
+} from "../prerender.js";
+import type { StaticHandlerDefinition } from "../static-handler.js";
+import type {
+  ResponseHandler,
+  ResponseHandlerContext,
+  TextResponseHandler,
+} from "./response-types.js";
+import type {
+  UnnamedRoute,
+  LocalOnlyInclude,
+  PathOptions,
+  UrlPatterns,
+  IncludeOptions,
+} from "./pattern-types.js";
+import type { ExtractRoutes, ExtractResponses } from "./type-extraction.js";
+
+/**
+ * Base path function signature for defining routes with URL patterns.
+ */
+export type PathFn<TEnv> = <
+  const TPattern extends string,
+  const TName extends string = UnnamedRoute,
+  const TSearch extends SearchSchema = {},
+  TParams extends Record<string, any> = ExtractParams<TPattern>,
+>(
+  pattern: TPattern,
+  handler:
+    | ReactNode
+    | ((
+        ctx: HandlerContext<TParams, TEnv, TSearch>,
+      ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>)
+    | PrerenderHandlerDefinition<TParams>
+    | PassthroughHandlerDefinition<TParams, TEnv>
+    | StaticHandlerDefinition<TParams>,
+  optionsOrUse?: PathOptions<TName, TSearch> | (() => UseItems<RouteUseItem>),
+  use?: () => UseItems<RouteUseItem>,
+  // Generic handler bypass: when handler uses index-signature params
+  // (e.g. Handler<Record<string, any>>), skip the biconditional.
+  // `string extends keyof TParams` is true for index signatures,
+  // false for concrete params ({id: string}) and empty ({}).
+  //
+  // Subset check: pattern params must be assignable to handler params,
+  // but handler can have MORE params (e.g. from parent include() prefix).
+  // This allows Prerender<"locale.detail"> with {locale, slug} to mount
+  // on path("/blog/:slug") where the pattern only declares {slug}.
+) => string extends keyof TParams
+  ? TypedRouteItem<TName, TPattern, unknown, TSearch>
+  : TParams extends ExtractParams<TPattern>
+    ? TypedRouteItem<TName, TPattern, unknown, TSearch>
+    : { __error: `Handler params do not match pattern "${TPattern}"` };
+
+/**
+ * Path function for response routes that must return Response (image, stream, any).
+ * Handler must return Response, not ReactNode. Uses lighter ResponseHandlerContext.
+ * Use items restricted to middleware() and cache() only.
+ */
+export type ResponsePathFn<TEnv> = <
+  const TPattern extends string,
+  const TName extends string = UnnamedRoute,
+  const TSearch extends SearchSchema = {},
+>(
+  pattern: TPattern,
+  handler: ResponseHandler<ExtractParams<TPattern>, TEnv>,
+  optionsOrUse?:
+    | PathOptions<TName, TSearch>
+    | (() => UseItems<ResponseRouteUseItem>),
+  use?: () => UseItems<ResponseRouteUseItem>,
+) => TypedRouteItem<TName, TPattern, unknown, TSearch>;
+
+/**
+ * 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,
+  const TName extends string = UnnamedRoute,
+  const TSearch extends SearchSchema = {},
+  TData = unknown,
+>(
+  pattern: TPattern,
+  handler: (
+    ctx: ResponseHandlerContext<ExtractParams<TPattern>, TEnv>,
+  ) => TData | Response | Promise<TData | Response>,
+  optionsOrUse?:
+    | PathOptions<TName, TSearch>
+    | (() => UseItems<ResponseRouteUseItem>),
+  use?: () => UseItems<ResponseRouteUseItem>,
+) => TypedRouteItem<TName, TPattern, TData, TSearch>;
+
+/**
+ * Path function for text-based response routes (path.text(), path.html(), path.xml()).
+ * Handler can return a string or Response. TData is always `string`.
+ */
+export type TextResponsePathFn<TEnv> = <
+  const TPattern extends string,
+  const TName extends string = UnnamedRoute,
+  const TSearch extends SearchSchema = {},
+>(
+  pattern: TPattern,
+  handler: TextResponseHandler<ExtractParams<TPattern>, TEnv>,
+  optionsOrUse?:
+    | PathOptions<TName, TSearch>
+    | (() => UseItems<ResponseRouteUseItem>),
+  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.
+ */
+export type IncludeFn<TEnv> = <
+  TRoutes extends Record<string, any>,
+  const TUrlPrefix extends string,
+  const TNamePrefix extends string = LocalOnlyInclude,
+  TResponses extends Record<string, unknown> = Record<string, unknown>,
+>(
+  prefix: TUrlPrefix,
+  patterns: IncludeArg<TEnv, TRoutes, TResponses>,
+  options?: IncludeOptions<TNamePrefix>,
+) => TypedIncludeItem<TRoutes, TNamePrefix, TUrlPrefix, TResponses>;
+
+export type PathHelpers<TEnv> = {
+  /**
+   * Define a route with URL pattern at definition site
+   *
+   * @example
+   * ```typescript
+   * // Pattern and component only
+   * path("/about", AboutPage)
+   *
+   * // With options
+   * path("/:slug", PostPage, { name: "post" })
+   *
+   * // With children (loaders, middleware, etc.)
+   * path("/:slug", PostPage, { name: "post" }, () => [
+   *   loader(PostLoader),
+   * ])
+   * ```
+   */
+  path: PathFn<TEnv> & {
+    json: JsonResponsePathFn<TEnv>;
+    text: TextResponsePathFn<TEnv>;
+    html: TextResponsePathFn<TEnv>;
+    xml: TextResponsePathFn<TEnv>;
+    md: TextResponsePathFn<TEnv>;
+    image: ResponsePathFn<TEnv>;
+    stream: ResponsePathFn<TEnv>;
+    any: ResponsePathFn<TEnv>;
+  };
+
+  /**
+   * Define a layout that wraps child routes
+   */
+  layout: {
+    (
+      component: ReactNode | Handler<any, any, TEnv> | StaticHandlerDefinition,
+    ): TypedLayoutItem<{}, {}>;
+    <
+      const TChildren extends readonly (
+        | LayoutUseItem
+        | readonly LayoutUseItem[]
+      )[],
+    >(
+      component: ReactNode | Handler<any, any, TEnv> | StaticHandlerDefinition,
+      use: () => TChildren,
+    ): TypedLayoutItem<ExtractRoutes<TChildren>, ExtractResponses<TChildren>>;
+  };
+
+  /**
+   * Include nested URL patterns under a URL prefix.
+   *
+   * The `name` option controls how child route names appear in the
+   * global route map and generated types:
+   *
+   * ```typescript
+   * // Named — children become "blog.index", "blog.post", etc.
+   * // Visible in generated types and globally reversible.
+   * include("/blog", blogPatterns, { name: "blog" })
+   *
+   * // Flattened — children merge into the parent namespace as-is.
+   * // Equivalent to defining those routes inline at the include site.
+   * include("/blog", blogPatterns, { name: "" })
+   *
+   * // Local-only (default) — children are scoped privately.
+   * // Hidden from generated types and global reverse resolution.
+   * // Only dot-local reverse (reverse(".child")) works inside.
+   * include("/blog", blogPatterns)
+   * ```
+   */
+  include: IncludeFn<TEnv>;
+
+  /**
+   * Define parallel routes that render simultaneously in named slots.
+   *
+   * A slot value can be a Handler / ReactNode / StaticHandlerDefinition
+   * (legacy form, broadcast use applies to every slot) or a slot descriptor
+   * `{ 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()`.
+   */
+  parallel: <
+    TSlots extends Record<
+      `@${string}`,
+      | Handler<any, any, TEnv>
+      | ReactNode
+      | StaticHandlerDefinition
+      | {
+          handler:
+            | Handler<any, any, TEnv>
+            | ReactNode
+            | StaticHandlerDefinition;
+          use?: () => ParallelUseItem[];
+        }
+    >,
+  >(
+    slots: TSlots,
+    use?: () => ParallelUseItem[],
+  ) => ParallelItem;
+
+  /**
+   * Define an intercepting route for soft navigation
+   * Note: routeName must match a named path() in this urlpatterns
+   */
+  intercept: keyof Rango.GeneratedRouteMap extends never
+    ? (
+        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;
+
+  /**
+   * Attach middleware to the current route/layout, or wrap child segments
+   */
+  middleware: {
+    (fn: MiddlewareFn<TEnv>): MiddlewareItem;
+    (
+      fn: MiddlewareFn<TEnv>,
+      children: () => UseItems<LayoutUseItem>,
+    ): MiddlewareItem;
+    (fns: MiddlewareFn<TEnv>[]): MiddlewareItem;
+    (
+      fns: MiddlewareFn<TEnv>[],
+      children: () => UseItems<LayoutUseItem>,
+    ): MiddlewareItem;
+  };
+
+  /**
+   * Control when a segment should revalidate during navigation
+   */
+  revalidate: (fn: ShouldRevalidateFn<any, TEnv>) => RevalidateItem;
+
+  /**
+   * Attach a data loader to the current route/layout
+   */
+  loader: <TData>(
+    loaderDef: LoaderDefinition<TData>,
+    use?: () => LoaderUseItem[],
+  ) => LoaderItem;
+
+  /**
+   * Attach a loading component to the current route/layout
+   */
+  loading: (
+    component: ReactNode | (() => ReactNode),
+    options?: { ssr?: boolean },
+  ) => LoadingItem;
+
+  /**
+   * Attach an error boundary to catch errors in this segment
+   */
+  errorBoundary: (
+    fallback: ReactNode | ErrorBoundaryHandler,
+  ) => ErrorBoundaryItem;
+
+  /**
+   * Attach a not-found boundary to handle notFound() calls
+   */
+  notFoundBoundary: (
+    fallback: ReactNode | NotFoundBoundaryHandler,
+  ) => NotFoundBoundaryItem;
+
+  /**
+   * Define cache configuration for segments
+   */
+  cache: {
+    (): TypedCacheItem<{}, {}>;
+    <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
+      children: () => TChildren,
+    ): TypedCacheItem<ExtractRoutes<TChildren>, ExtractResponses<TChildren>>;
+    (options: PartialCacheOptions<TEnv> | false): TypedCacheItem<{}, {}>;
+    <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
+      options: PartialCacheOptions<TEnv> | false,
+      use: () => TChildren,
+    ): TypedCacheItem<ExtractRoutes<TChildren>, ExtractResponses<TChildren>>;
+  };
+
+  /**
+   * Opt a route (or group of routes) into transition-driven navigation.
+   *
+   * Two independent layers: (1) startTransition, on all React versions, holds
+   * the previous content across a same-route nav (no skeleton flash) and is the
+   * precondition for any view transition; (2) on experimental React, an
+   * additional `<ViewTransition>` boundary cross-fades/morphs the swap. Pass
+   * `{ 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;
+    (config: TransitionConfig): TransitionItem;
+    <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
+      children: () => TChildren,
+    ): TypedTransitionItem<
+      ExtractRoutes<TChildren>,
+      ExtractResponses<TChildren>
+    >;
+    <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
+      config: TransitionConfig,
+      children: () => TChildren,
+    ): TypedTransitionItem<
+      ExtractRoutes<TChildren>,
+      ExtractResponses<TChildren>
+    >;
+  };
+};