@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80daa23e

package/dist/types/types/segments.d.ts

@@ -0,0 +1,254 @@
+import type { ReactNode } from "react";
+import type { ErrorInfo, NotFoundInfo } from "./boundaries.js";
+import type { RevalidateParams, HandlerContext } from "./handler-context.js";
+/**
+ * CSS class(es) for a ViewTransition phase.
+ * Can be a simple string or an object mapping transition types to class names
+ * for direction-aware transitions (e.g., { "navigation": "slide-right", "navigation-back": "slide-left" }).
+ */
+export type ViewTransitionClass = Record<string, string> | string;
+/**
+ * The context a transition({ when }) predicate receives.
+ *
+ * It mirrors the {@link ShouldRevalidateFn} args a `revalidate()` predicate
+ * gets — the same navigation/action metadata — so the two read the same shape,
+ * plus `get`/`env` for request-context reads. There is no full `HandlerContext`
+ * here: the gate runs at the RSC-payload layer with the request context, not a
+ * handler context, so handler-only sugar (`search`/`build`/`dev`/`headers`) is
+ * absent by design. On ordinary routes, `get` can read what handlers or
+ * middleware set via `ctx.set(...)`. On `ppr` routes the gate runs before route
+ * handlers, so only middleware-established values are available.
+ *
+ * Field availability (all source fields are optional — never fabricated):
+ * - `currentUrl` / `currentParams` / `fromRouteName` (the navigation SOURCE) are
+ *   populated on soft navigations and action-success revalidations. They are
+ *   undefined on an initial full document load and on action-error / no-JS error
+ *   paths that skip the navigation snapshot — there is no prior page to name.
+ * - `nextUrl` / `nextParams` / `get` / `env` / `method` are always present;
+ *   `toRouteName` is present only when the target route is named (undefined for
+ *   unnamed/auto-generated routes, like `fromRouteName`).
+ * - `actionId` / `actionUrl` / `actionResult` / `formData` are populated only
+ *   when a server action triggered the render; `method` is "POST" then, "GET"
+ *   otherwise. On no-JS (progressive-enhancement) action paths `actionId` may be
+ *   undefined when React cannot surface the action's stable id: the success
+ *   re-render still sets `actionUrl`/`formData` for a recognized action, but the
+ *   error-boundary re-render exposes `actionUrl` only when `actionId` resolved.
+ *   Malformed form bodies that fail before action detection expose no action
+ *   fields. Treat `actionId` as "the action, if known", not as "was this an
+ *   action".
+ *
+ * PREFETCH / CACHE CAVEAT (read this before gating on the source): the gate runs
+ * server-side during resolution. A PREFETCHED navigation renders at prefetch
+ * time, so `currentUrl`/`currentParams`/`fromRouteName` reflect the page the
+ * prefetch fired from, NOT necessarily the page the user actually navigates from
+ * — the decision is baked into the stored Flight payload and replayed verbatim.
+ * A non-PPR `cache()`/prerender hit replays the stored transition with the
+ * predicate NOT re-run. A `ppr` route instead evaluates the predicate before
+ * handlers on every match, including cache, prerender, and PPR replay. Prefetch
+ * still freezes the server decision into its Flight payload. If the gate must
+ * reflect the exact click-time source, source-scope the prefetch
+ * (`<Link prefetchKey=":source">`).
+ */
+export type TransitionWhenContext<TParams = Record<string, string>, TEnv = unknown> = Partial<Pick<RevalidateParams<TParams, TEnv>, "currentUrl" | "currentParams" | "fromRouteName">> & Pick<RevalidateParams<TParams, TEnv>, "nextUrl" | "nextParams" | "toRouteName" | "actionId" | "actionUrl" | "actionResult" | "formData" | "method"> & Pick<HandlerContext<any, TEnv>, "get" | "env">;
+/**
+ * Predicate that gates whether a transition() applies for the current request.
+ *
+ * Evaluated server-side outside any cache scope. On ordinary routes it runs
+ * AFTER the route's handler, so `get(...)` can read handler/middleware state. A
+ * route with `ppr` automatically hoists it before route handlers and reevaluates
+ * it on every cache/prerender/PPR replay; there `get(...)` can read middleware
+ * state, but not values set by route handlers. Return false to drop this
+ * segment's transition for the request; return true to apply it. The
+ * context ({@link TransitionWhenContext}) carries the same navigation/action
+ * metadata a `revalidate()` predicate sees plus `get`/`env`. If it throws, the
+ * error is reported to the router's onError (phase "rendering") and the
+ * transition is dropped (the navigation does not hold).
+ *
+ * Distinct from intercept()'s `when` config selector, which runs at MATCH time
+ * over `{ from, to, params, segments, … }`.
+ *
+ * Scope: dropping a transition removes only THIS segment's contribution to the
+ * navigation's hold. The startTransition hold is navigation-wide — it engages if
+ * any matched segment still has a transition — so `when: false` makes the
+ * navigation stream its loading fallback only when no other matched segment
+ * keeps a transition (the common case: a single transition on the route).
+ *
+ * On non-PPR routes it runs only during fresh resolution. On PPR routes it runs
+ * before handlers for every match, including runtime cache, build-time
+ * prerender, and PPR segment replay. A prefetched navigation still freezes the
+ * result to prefetch time; see {@link TransitionWhenContext}.
+ */
+export type TransitionWhenFn = (ctx: TransitionWhenContext) => boolean;
+/**
+ * Configuration for React's <ViewTransition> component.
+ *
+ * The phase fields (enter/exit/update/share/default/name) map directly to
+ * ViewTransitionProps (minus children/ref/callbacks). The `viewTransition`
+ * field is router-specific and is stripped before the config reaches React.
+ */
+export interface TransitionConfig {
+    enter?: ViewTransitionClass;
+    exit?: ViewTransitionClass;
+    update?: ViewTransitionClass;
+    share?: ViewTransitionClass;
+    default?: ViewTransitionClass;
+    name?: string;
+    /**
+     * Whether the router wraps this segment's content in its own
+     * <ViewTransition> boundary.
+     *
+     * - "auto" (default): the router places the boundary, producing the
+     *   router-owned cross-fade described by the phase fields above.
+     * - false: the router places no boundary. The navigation commit is still
+     *   driven through startTransition (so loaders hold instead of flashing a
+     *   skeleton, and consumer-placed <ViewTransition> elements still animate),
+     *   but the router contributes no cross-fade of its own.
+     *
+     * When unset, inherits the createRouter({ viewTransition }) default.
+     */
+    viewTransition?: "auto" | false;
+    /**
+     * Optional server-side predicate that gates this transition per request. When
+     * present and it returns false, the router drops this segment's transition for
+     * the request, so the navigation streams its loading fallback instead of
+     * holding. PPR routes evaluate it before route handlers and on every replay;
+     * other routes evaluate it after handlers on fresh resolution. The predicate
+     * is server-only and never serialized to the client; only its resolved effect
+     * crosses. See {@link TransitionWhenFn}.
+     */
+    when?: TransitionWhenFn;
+}
+/**
+ * Resolved segment with component
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface ResolvedSegment {
+    id: string;
+    namespace: string;
+    type: "layout" | "route" | "parallel" | "loader" | "error" | "notFound";
+    index: number;
+    component: ReactNode;
+    loading?: ReactNode;
+    transition?: TransitionConfig;
+    layout?: ReactNode;
+    params?: Record<string, string>;
+    slot?: string;
+    belongsToRoute?: boolean;
+    layoutName?: string;
+    parallelName?: string;
+    loaderId?: string;
+    _inherited?: boolean;
+    loaderData?: any;
+    /**
+     * True when this loader was awaited before first flush on a document render
+     * (loader(Def, { ssr: false })). Stamped by resolveLoaders (fresh.ts) on the
+     * document lane only — never during shell capture, where live loaders are
+     * deliberately masked and would false-positive the SSR suspension warning
+     * this field feeds (ssr-suspension-warning.ts).
+     */
+    awaitBeforeFlush?: true;
+    parallelLoading?: ReactNode;
+    loaderDataPromise?: Promise<any[]> | any[];
+    loaderIds?: string[];
+    error?: ErrorInfo;
+    notFoundInfo?: NotFoundInfo;
+    mountPath?: string;
+    /**
+     * @internal Server-side marker: true when the segment's handler actually ran
+     * this request (not skipped via the revalidate cache path). Used by
+     * match-result.ts to populate `MatchResult.resolvedIds` for client-side
+     * handle-bucket cleanup. Stripped from the wire payload before serialization
+     * — never reaches the client.
+     */
+    _handlerRan?: boolean;
+}
+export interface SegmentMetadata {
+    id: string;
+    type: "layout" | "route" | "parallel" | "loader" | "error" | "notFound";
+    index: number;
+    params?: Record<string, string>;
+    slot?: string;
+    loaderId?: string;
+    error?: ErrorInfo;
+    notFoundInfo?: NotFoundInfo;
+}
+/**
+ * State of a named slot (e.g., @modal, @sidebar)
+ * Used for intercepting routes where slots render alternative content
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface SlotState {
+    /**
+     * Whether the slot is currently active (has content to render)
+     */
+    active: boolean;
+    /**
+     * Segments for this slot when active
+     */
+    segments?: ResolvedSegment[];
+}
+/**
+ * Props passed to the root layout component
+ */
+export interface RootLayoutProps {
+    children: ReactNode;
+}
+/**
+ * Router match result
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface MatchResult {
+    segments: ResolvedSegment[];
+    matched: string[];
+    diff: string[];
+    /**
+     * Every segment id whose handler actually ran on the server this request,
+     * including ones with `component === null` that get filtered out of
+     * `segments`/`diff` to avoid wasted bytes. Drives the client's handle-
+     * cleanup pass — a slot that re-resolves and pushes nothing must clear
+     * its previous handle bucket, but `diff` doesn't carry it because the
+     * segment payload doesn't either. A superset of `diff`.
+     */
+    resolvedIds: string[];
+    /**
+     * Merged route params from all matched segments
+     * Available for use by the handler after route matching
+     */
+    params: Record<string, string>;
+    /**
+     * The matched route name (includes name prefix from include()).
+     * Used by ctx.reverse() for local name resolution.
+     */
+    routeName?: string;
+    /**
+     * State of named slots for this route match
+     * Key is slot name (e.g., "@modal"), value is slot state
+     * Slots are used for intercepting routes during soft navigation
+     */
+    slots?: Record<string, SlotState>;
+    /**
+     * Intercept TARGET route names reachable when this location is a navigation
+     * origin (chain walk of the matched entry, when-conditionals included).
+     * Shipped in payload metadata so the browser-local clientUrls matcher can
+     * decline its optimistic presentation for targets an intercept would claim.
+     */
+    interceptTargets?: string[];
+    /**
+     * Redirect URL for trailing slash normalization.
+     * When set, the RSC handler should return a 308 redirect to this URL
+     * instead of rendering the page.
+     */
+    redirect?: string;
+    /**
+     * Route-level middleware collected from the matched entry tree.
+     * These run with the same onion-style execution as app-level middleware,
+     * wrapping the entire RSC response creation.
+     */
+    routeMiddleware?: Array<{
+        handler: import("../router/middleware.js").MiddlewareFn;
+        params: Record<string, string>;
+    }>;
+}

package/dist/types/types.d.ts

@@ -0,0 +1 @@
+export * from "./types/index.js";

package/dist/types/urls/include-helper.d.ts

@@ -0,0 +1,17 @@
+import type { AllUseItems } from "../route-types.js";
+import type { IncludeFn } from "./path-helper-types.js";
+/**
+ * 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 declare function processItems(items: readonly AllUseItems[]): AllUseItems[];
+/**
+ * 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 declare function createIncludeHelper<TEnv>(): IncludeFn<TEnv>;

package/dist/types/urls/include-provider.d.ts

@@ -0,0 +1,27 @@
+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 declare function isIncludeProvider(value: unknown): value is IncludeProvider;
+/**
+ * Normalize an async provider's resolved value to a `UrlPatterns`. Accepts a
+ * `urls()` value directly or a module whose `default` export is one.
+ */
+export declare function resolveIncludeModule<TEnv = any>(mod: IncludeModule<TEnv>, id?: string): UrlPatterns<TEnv>;

package/dist/types/urls/index.d.ts

@@ -0,0 +1,6 @@
+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/dist/types/urls/path-helper-types.d.ts

@@ -0,0 +1,207 @@
+import type { ReactNode } from "react";
+import type { ErrorBoundaryHandler, ExtractParams, Handler, HandlerContext, LoaderDefinition, LoaderOptions, 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, StaticHandlerRef } 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";
+import type { ClientUrlPatterns } from "../client-urls/types.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 | Response | Promise<ReactNode | Response>) | PrerenderHandlerDefinition<TParams> | PassthroughHandlerDefinition<TParams, TEnv> | StaticHandlerDefinition<TParams>, optionsOrUse?: PathOptions<TName, TSearch> | (() => UseItems<RouteUseItem>), use?: () => UseItems<RouteUseItem>) => 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> | ClientUrlPatterns<TRoutes> | (() => 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()`.
+     *
+     * 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). Static() values use
+     * an opaque handler-less reference here so their own `.handler` cannot
+     * contribute a second call signature or expose internal fields in completion.
+     */
+    parallel: (slots: Record<`@${string}`, Handler<any, any, TEnv> | ReactNode | StaticHandlerRef | {
+        handler: Handler<any, any, TEnv> | ReactNode | StaticHandlerRef;
+        use?: () => ParallelUseItem[];
+    }>, 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.
+     *
+     * Pass `{ ssr: false }` — the same knob as loading(fallback, { ssr:
+     * false }) — to await this loader before first flush on DOCUMENT requests
+     * (see {@link LoaderOptions}): the opt-in for loaders whose data, handle
+     * pushes, or thrown notFound()/redirect() must be in the SSR'd HTML.
+     * Per-loader: a streaming sibling keeps streaming. Under a `ppr` route the
+     * flag BAKES: the loader executes at shell capture and its settled return
+     * freezes into the shell (nested promises stay live holes) — the pre-flush
+     * promise applied to the prelude.
+     */
+    loader: <TData>(loaderDef: LoaderDefinition<TData>, optionsOrUse?: LoaderOptions | (() => LoaderUseItem[]), 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 normally
+     * runs after the route handler; `ppr` routes automatically run it before route
+     * handlers and on every replay, where `ctx.get(...)` sees middleware state but
+     * not handler-set values.
+     */
+    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>>;
+    };
+};
+export {};

package/dist/types/urls/path-helper.d.ts

@@ -0,0 +1,12 @@
+import type { PathFn, ResponsePathFn, JsonResponsePathFn, TextResponsePathFn } from "./path-helper-types.js";
+export declare function createPathHelper<TEnv>(): PathFn<TEnv>;
+export declare function attachPathResponseTags<TEnv>(pathFn: PathFn<TEnv>): 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>;
+};