@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f4a8e8de

package/dist/types/urls/pattern-types.d.ts

@@ -0,0 +1,166 @@
+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.
+ * Using a branded string instead of `never` prevents TypeScript from
+ * widening array type inference when mixing named and unnamed routes.
+ */
+export type UnnamedRoute = "$unnamed";
+/**
+ * Sentinel type for include() mounts that stay local to the mounted module.
+ * This keeps child route names out of the parent/global type map while still
+ * allowing the mounted module to use its own local route names internally.
+ *
+ * Branded with a symbol key so it cannot be accidentally produced by user code.
+ */
+declare const LOCAL_ONLY_BRAND: unique symbol;
+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) */
+    trailingSlash?: TrailingSlashMode;
+    /** Response type marker (set by path.json(), etc.) */
+    [RESPONSE_TYPE]?: string;
+}
+/**
+ * Result of urls() - contains the route definitions
+ */
+export interface UrlPatterns<TEnv = any, TRoutes extends Record<string, any> = Record<string, string>, TResponses extends Record<string, unknown> = Record<string, unknown>> {
+    /** Internal: compiled handler function */
+    readonly handler: () => AllUseItems[];
+    /** Internal: trailing slash config per route name */
+    readonly trailingSlash: Record<string, TrailingSlashMode>;
+    /** Brand for type checking */
+    readonly [UrlPatternsBrand]: void;
+    /** Environment type brand (phantom) */
+    readonly _env?: TEnv;
+    /** Routes type brand (phantom) - carries route name -> pattern mapping */
+    readonly _routes?: TRoutes;
+    /** Responses type brand (phantom) - carries route name -> response data type mapping */
+    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()
+ */
+export interface IncludeOptions<TNamePrefix extends string = string> {
+    /**
+     * Name prefix for all routes in this pattern set.
+     *
+     * - `{ name: "blog" }` — children become `blog.index`, `blog.detail`, etc.
+     *   Visible in generated route types and resolvable globally via `reverse("blog.index")`.
+     * - `{ name: "" }` — children merge into the parent namespace with no prefix.
+     *   Equivalent to defining the routes inline at the include site.
+     * - Omitted — children live in a private local scope, hidden from the
+     *   generated route map and global reverse resolution. Only dot-local
+     *   reverse (e.g. `reverse(".child")`) works from inside the module.
+     */
+    name?: TNamePrefix;
+}
+export {};

package/dist/types/urls/response-types.d.ts

@@ -0,0 +1,67 @@
+import type { ContextVar } from "../context-var.js";
+import type { ReverseFunction } from "../reverse.js";
+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.
+ * Global names get autocomplete and param validation from the generated route map.
+ * Local `.name` calls are accepted but not validated (scope unknown at type level).
+ */
+type ResponseReverseFunction = [DefaultReverseRouteMap] extends [
+    Record<string, string>
+] ? (name: string, params?: Record<string, string>, search?: Record<string, unknown>) => string : ReverseFunction<DefaultReverseRouteMap> & {
+    (name: `.${string}`, params?: Record<string, string>, search?: Record<string, unknown>): string;
+};
+/**
+ * Symbol marking a route as a response route (non-RSC).
+ * Stored on PathOptions and UrlPatterns to signal the trie to short-circuit.
+ */
+export declare const RESPONSE_TYPE: unique symbol;
+/**
+ * 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> = ResponseHandlerOf<Response, TParams, TEnv>;
+/**
+ * JSON-serializable value type for auto-wrap support.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Handler for JSON response routes.
+ * Can return a plain JSON-serializable value (auto-wrapped) or Response (pass-through).
+ */
+export type JsonResponseHandler<TParams = Record<string, string>, TEnv = any> = ResponseHandlerOf<JsonValue | Response, TParams, TEnv>;
+/**
+ * Handler for text-based response routes (text, html, xml).
+ * Can return a string (auto-wrapped) or Response (pass-through).
+ */
+export type TextResponseHandler<TParams = Record<string, string>, TEnv = any> = ResponseHandlerOf<string | Response, TParams, TEnv>;
+/**
+ * Lighter handler context for response routes.
+ * No ctx.use() (no loaders). Supports setting response headers via ctx.header().
+ * Use the standalone cookies() function for cookie mutations.
+ */
+export interface ResponseHandlerContext<TParams = Record<string, string>, TEnv = any> extends RequestScope<TEnv> {
+    params: TParams;
+    /** @internal Phantom property for params type invariance. Prevents mounting handlers on wrong routes. */
+    readonly _paramCheck?: (params: TParams) => TParams;
+    reverse: ResponseReverseFunction;
+    /** Read a variable set by middleware via ctx.set(key, value) or ctx.set(ContextVar, value). */
+    get: {
+        <T>(contextVar: ContextVar<T>): T | undefined;
+    } & (<K extends keyof DefaultVars>(key: K) => DefaultVars[K]);
+    /** Set a response header. Merged into the auto-wrapped or pass-through Response. */
+    header: (name: string, value: string) => void;
+}
+export {};

package/dist/types/urls/type-extraction.d.ts

@@ -0,0 +1,157 @@
+import type { JsonSerialize } from "../serialize.js";
+import type { TypedRouteItem, TypedIncludeItem, TypedLayoutItem, TypedCacheItem, TypedTransitionItem } from "../route-types.js";
+import type { LocalOnlyInclude, UnnamedRoute } from "./pattern-types.js";
+/**
+ * Prefix route names with a given prefix (e.g., "blog" + "post" = "blog.post")
+ *
+ * Filters out plain `string` index signatures to prevent dynamically-generated
+ * routes from poisoning the route map. When TypeScript encounters very large
+ * route sets (5000+ routes via Array.from), it may give up computing specific
+ * types and fall back to Record<string, string>. Without filtering, PrefixRoutes
+ * would map `string` to `${prefix}.${string}`, creating an index signature that
+ * accepts ANY prefixed name and defeats type-safe route checking.
+ *
+ * Uses `string extends K` (conservative filter):
+ * - Drops `string` keys (TypeScript fallback) -> prevents `[x: `site.${string}`]`
+ * - Keeps template literal patterns like `item${number}` from Array.from loops,
+ *   which are imprecise but still allow writing paths like `/shop/product/1`
+ *
+ * A more aggressive alternative (`{} extends Record<K, 1>`) would also drop
+ * template literal patterns. We chose conservative because loop-generated routes
+ * with `${number}` patterns still provide some value: they don't appear in
+ * named-routes.gen.ts or IDE autocomplete, but they do let you manually write
+ * valid paths without type errors.
+ */
+type PrefixRoutes<TRoutes extends Record<string, any>, TPrefix extends string> = TPrefix extends "" ? TRoutes : {
+    [K in keyof TRoutes as K extends string ? string extends K ? never : `${TPrefix}.${K}` : never]: TRoutes[K];
+};
+/**
+ * Prefix route patterns with a URL prefix (e.g., "/blog" + "/:slug" = "/blog/:slug")
+ */
+type PrefixPatterns<TRoutes extends Record<string, any>, TUrlPrefix extends string> = {
+    [K in keyof TRoutes]: TRoutes[K] extends string ? `${TUrlPrefix}${TRoutes[K]}` : TRoutes[K] extends {
+        readonly path: infer P extends string;
+        readonly search: infer S;
+    } ? {
+        readonly path: `${TUrlPrefix}${P}`;
+        readonly search: S;
+    } : TRoutes[K];
+};
+/**
+ * Convert a union type to an intersection type.
+ * Used to combine route maps from multiple siblings without recursive tuple processing.
+ */
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Extract routes from a single item (path, include, layout, cache with children)
+ */
+type ExtractRoutesFromItem<T> = T extends TypedRouteItem<infer TName, infer TPattern, any, infer TSearch> ? TName extends string ? string extends TName ? {} : TName extends UnnamedRoute ? {} : {} extends TSearch ? {
+    [K in TName]: TPattern;
+} : {
+    [K in TName]: {
+        readonly path: TPattern;
+        readonly search: TSearch;
+    };
+} : {} : T extends TypedIncludeItem<infer TRoutes, infer TNamePrefix, infer TUrlPrefix> ? TNamePrefix extends LocalOnlyInclude ? {} : TNamePrefix extends string ? TUrlPrefix extends string ? PrefixRoutes<PrefixPatterns<TRoutes, TUrlPrefix>, TNamePrefix> : PrefixRoutes<TRoutes, TNamePrefix> : TUrlPrefix extends string ? PrefixPatterns<TRoutes, TUrlPrefix> : TRoutes : T extends TypedLayoutItem<infer TChildRoutes> ? TChildRoutes : T extends TypedCacheItem<infer TChildRoutes> ? TChildRoutes : T extends TypedTransitionItem<infer TChildRoutes> ? TChildRoutes : {};
+/**
+ * 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.
+ */
+type ExtractRoutesFromItems<T extends readonly any[]> = T extends readonly any[] ? UnionToIntersection<{
+    [K in keyof T]: ExtractRoutesFromItem<T[K]>;
+}[number]> extends infer R ? [
+    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).
+ */
+export type ExtractRoutes<T extends readonly any[]> = ExtractRoutesFromItems<T>;
+/**
+ * Prefix keys of a Record<string, unknown> with a dot-separated prefix.
+ * Used for response type maps through include().
+ * Same index signature filter as PrefixRoutes (see comment there).
+ */
+type PrefixKeys<T extends Record<string, unknown>, TPrefix extends string> = TPrefix extends "" ? T : {
+    [K in keyof T as K extends string ? string extends K ? never : `${TPrefix}.${K}` : never]: T[K];
+};
+/**
+ * Extract response data types from a single item.
+ * Parallel to ExtractRoutesFromItem but extracts name -> TData mapping.
+ */
+type ExtractResponsesFromItem<T> = T extends TypedRouteItem<infer TName, any, infer TData> ? TName extends string ? string extends TName ? {} : TName extends UnnamedRoute ? {} : {
+    [K in TName]: TData;
+} : {} : T extends TypedIncludeItem<any, infer TNamePrefix, any, infer TResponses> ? TNamePrefix extends LocalOnlyInclude ? {} : TNamePrefix extends string ? TResponses extends Record<string, unknown> ? PrefixKeys<TResponses, TNamePrefix> : {} : TResponses extends Record<string, unknown> ? TResponses : {} : T extends TypedLayoutItem<any, infer TChildResponses> ? TChildResponses extends Record<string, unknown> ? TChildResponses : {} : T extends TypedCacheItem<any, infer TChildResponses> ? TChildResponses extends Record<string, unknown> ? TChildResponses : {} : T extends TypedTransitionItem<any, infer TChildResponses> ? TChildResponses extends Record<string, unknown> ? TChildResponses : {} : {};
+/**
+ * Extract responses from an array of items using mapped types.
+ * Parallel to ExtractRoutesFromItems.
+ */
+type ExtractResponsesFromItems<T extends readonly any[]> = T extends readonly any[] ? UnionToIntersection<{
+    [K in keyof T]: ExtractResponsesFromItem<T[K]>;
+}[number]> extends infer R ? [
+    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>;
+/**
+ * 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 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;
+ * }
+ * const product = await res.json(); // bare value, no envelope
+ * ```
+ */
+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;
+}
+/**
+ * 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
+ * const apiPatterns = urls(({ path }) => [
+ *   path.json("/health", (ctx) => ({ status: "ok", timestamp: Date.now() }), { name: "health" }),
+ * ]);
+ *
+ * type HealthData = RouteResponse<typeof apiPatterns, "health">;
+ * // { 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 ? JsonSerialize<Exclude<R[TName], Response>> : never : never;
+export {};

package/dist/types/urls/urls-function.d.ts

@@ -0,0 +1,24 @@
+import type { DefaultEnv } from "../types.js";
+import type { AllUseItems } from "../route-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";
+/**
+ * Define URL patterns with Django-inspired syntax
+ *
+ * Replaces map() as the entry point for route definitions.
+ * URL patterns are now visible at the definition site via path().
+ *
+ * @example
+ * ```typescript
+ * export const blogPatterns = urls(({ path, layout, loader }) => [
+ *   layout(BlogLayout, () => [
+ *     path("/", BlogIndex, { name: "index" }),
+ *     path("/:slug", BlogPost, { name: "post" }, () => [
+ *       loader(PostLoader),
+ *     ]),
+ *   ]),
+ * ]);
+ * ```
+ */
+export declare function urls<TEnv = DefaultEnv, const TItems extends readonly (AllUseItems | readonly AllUseItems[])[] = readonly AllUseItems[]>(builder: (helpers: PathHelpers<TEnv>) => TItems): UrlPatterns<TEnv, ExtractRoutes<TItems>, ExtractResponses<TItems>>;

package/dist/types/urls.d.ts

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

package/dist/types/use-loader.d.ts

@@ -0,0 +1,150 @@
+import type { LoaderDefinition, LoadOptions } from "./types.js";
+export type LoadFunction<T> = (options?: LoadOptions) => Promise<T>;
+export interface UseLoaderResult<T> {
+    data: T;
+    isLoading: boolean;
+    error: Error | null;
+    load: LoadFunction<T>;
+    refetch: LoadFunction<T>;
+}
+export interface UseFetchLoaderResult<T> {
+    data: T | undefined;
+    isLoading: boolean;
+    error: Error | null;
+    load: LoadFunction<T>;
+    refetch: LoadFunction<T>;
+}
+export interface UseLoaderOptions {
+    throwOnError?: boolean;
+    key?: string;
+    refreshGroup?: string | string[];
+}
+/**
+ * Hook to access loader data from route context (strict version)
+ *
+ * Use this when the loader is registered on the route via `loader()`.
+ * The data is guaranteed to exist - throws an error if not found.
+ *
+ * For on-demand fetching or when loader might not be in context,
+ * use `useFetchLoader` instead.
+ *
+ * @param loader - The loader definition (must be registered on route)
+ * @param options - Optional configuration
+ * @returns Object with data (guaranteed), isLoading, error, load, and refetch
+ * @throws Error if loader data is not found in context
+ *
+ * @example Basic usage - accessing route loader data
+ * ```tsx
+ * "use client";
+ * import { useLoader } from "rsc-router/client";
+ * import { CartLoader } from "../loaders/cart";
+ *
+ * // In route definition: loader(CartLoader)
+ *
+ * export function CartIcon() {
+ *   const { data } = useLoader(CartLoader);
+ *   // data is guaranteed to be CartData, not CartData | undefined
+ *   return <span>Cart ({data.items.length})</span>;
+ * }
+ * ```
+ */
+export declare function useLoader<T>(loader: LoaderDefinition<T>, options?: UseLoaderOptions): UseLoaderResult<Rango.FlightSerialize<T>>;
+/**
+ * Hook to access loader data with optional fetching (flexible version)
+ *
+ * Use this when:
+ * - The loader might not be registered on the route
+ * - You want to fetch data on-demand from the client
+ * - You're building a reusable component that doesn't assume route context
+ *
+ * If the loader IS registered on the route, it will still get the initial
+ * data from context - you just have to handle the `undefined` case in types.
+ *
+ * @param loader - The loader definition
+ * @param options - Optional configuration
+ * @returns Object with data (may be undefined), isLoading, error, load, and refetch
+ *
+ * @example On-demand fetching
+ * ```tsx
+ * "use client";
+ * import { useFetchLoader } from "rsc-router/client";
+ * import { SearchLoader } from "../loaders/search";
+ *
+ * export function SearchResults() {
+ *   const { data, load, isLoading } = useFetchLoader(SearchLoader);
+ *
+ *   const handleSearch = async (query: string) => {
+ *     await load({ params: { query } });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => handleSearch("test")}>Search</button>
+ *       {isLoading && <span>Loading...</span>}
+ *       {data?.results.map(r => <div key={r.id}>{r.name}</div>)}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example With route context (hybrid usage)
+ * ```tsx
+ * // Loader registered on route: loader(UserLoader)
+ * // useFetchLoader still works - gets initial data from context
+ * const { data, load } = useFetchLoader(UserLoader);
+ * // data is UserData | undefined (even though it will have initial value)
+ * ```
+ */
+export declare function useFetchLoader<T>(loader: LoaderDefinition<T>, options?: UseLoaderOptions): UseFetchLoaderResult<Rango.FlightSerialize<T>>;
+/**
+ * Get a stable function that refreshes loaders by cross-loader group tag.
+ *
+ * The returned `refresh(groups)` takes one group name or an array of names and
+ * re-runs every currently-mounted read tagged with ANY of them, with a plain GET
+ * against the current route URL. This is the cross-loader counterpart to the
+ * single-loader `key`: use it to refresh a set of DIFFERENT loaders together
+ * (e.g. profile + orders after an account switch). Members are tagged via
+ * `useLoader(Loader, { refreshGroup })` / `useFetchLoader(Loader, { refreshGroup })`,
+ * where `refreshGroup` is one name or several.
+ *
+ * Passing the group(s) to the returned function rather than to the hook lets a
+ * single `useRefreshLoaders()` instance refresh different groups depending on
+ * context, and lets one call refresh several groups at once — their members are
+ * unioned and deduped, so a loader tagged into two of the named groups is fetched
+ * exactly once.
+ *
+ * Group refresh never render-throws: a failing member surfaces its error via
+ * that read's `error` state, and the returned promise rejects with an
+ * `AggregateError` of the failures so the caller can handle them at the await
+ * site. Each loader is refreshed in place — no params, no body, no mutations.
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useLoader, useRefreshLoaders } from "rsc-router/client";
+ *
+ * function Profile() {
+ *   const { data } = useLoader(ProfileLoader, { key: userId, refreshGroup: "account" });
+ *   return <span>{data.name}</span>;
+ * }
+ * function Orders() {
+ *   // Tagged into two groups: refreshed by "account" (the whole set) or "orders".
+ *   const { data } = useLoader(OrdersLoader, {
+ *     key: userId,
+ *     refreshGroup: ["account", "orders"],
+ *   });
+ *   return <span>{data.count} orders</span>;
+ * }
+ * function RefreshButtons() {
+ *   const refresh = useRefreshLoaders();
+ *   return (
+ *     <>
+ *       <button onClick={() => refresh("account")}>Refresh account</button>
+ *       <button onClick={() => refresh("orders")}>Refresh orders</button>
+ *       <button onClick={() => refresh(["account", "orders"])}>Refresh both</button>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare function useRefreshLoaders(): (groups: string | string[]) => Promise<void>;

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

@@ -0,0 +1,10 @@
+/**
+ * Vercel preset integration surface for @rangojs/router.
+ *
+ * Imported via `@rangojs/router/vercel`. Vercel-only helpers live here so
+ * Node/other-platform consumers never pull them in. The Vercel cache store
+ * (`VercelCacheStore`) is exported from `@rangojs/router/cache`, mirroring the
+ * Cloudflare split where the store lives in `/cache` and the tracing helper in
+ * the platform subpath.
+ */
+export { createVercelTracing, type VercelTracingOptions } from "./tracing.js";

package/dist/types/vercel/tracing.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Vercel OpenTelemetry tracing integration.
+ *
+ * Bridges the router's observable phases (request, middleware, action, loaders,
+ * handler, render, ssr, response, background) onto OpenTelemetry spans so they
+ * show up in Vercel's trace waterfall next to the platform's automatic spans,
+ * with correct nesting. Vercel exposes tracing through OpenTelemetry (not a
+ * native import-free API like Cloudflare), so this is a thin convenience over
+ * `createOTelTracing`: it reads the global OTel tracer that `@vercel/otel`'s
+ * `registerOTel()` installs.
+ *
+ * Usage (vercel preset). A Rango/Vite app does NOT auto-load `instrumentation.ts`
+ * the way Next.js does, so export the tracing config from there and import it —
+ * the import is what runs `registerOTel()`. A standalone `registerOTel()` that
+ * nothing imports is a silent no-op (the tracer never registers, spans drop):
+ *
+ *   // instrumentation.ts
+ *   import { registerOTel } from "@vercel/otel";
+ *   import { createVercelTracing } from "@rangojs/router/vercel";
+ *   registerOTel({ serviceName: "my-app" });
+ *   export const tracing = createVercelTracing();
+ *
+ *   // router.tsx — importing `tracing` runs instrumentation.ts (and registerOTel)
+ *   import { createRouter } from "@rangojs/router";
+ *   import { tracing } from "./instrumentation.js";
+ *   export const router = createRouter({ tracing });
+ *
+ * Two runtime caveats inherited from the platform:
+ *   - Node.js runtime only. Vercel custom spans are unsupported on the Edge
+ *     runtime; `startActiveSpan` also needs an AsyncLocalStorage context manager
+ *     (which @vercel/otel configures on Node) for spans to nest correctly.
+ *   - `registerOTel()` must run before the first request. Reading the tracer via
+ *     `trace.getTracer` here is safe even if it runs first — the API's proxy
+ *     tracer delegates to the provider once registered — but no provider means
+ *     every span is a no-op (the request behaves exactly as if tracing were off).
+ *
+ * Whether spans are actually exported is governed by your OTel setup / Vercel
+ * tracing destination, not by this adapter.
+ */
+import { type OTelActiveSpanTracer } from "../router/telemetry-otel.js";
+import type { RouterTracingConfig, TracingToggleOptions } from "../router/tracing.js";
+/**
+ * Options for createVercelTracing. Extends the shared
+ * {@link TracingToggleOptions} (`enabled` + per-phase `spans`) with the
+ * Vercel-specific tracer selectors.
+ */
+export interface VercelTracingOptions extends TracingToggleOptions {
+    /**
+     * OTel instrumentation-scope name passed to `trace.getTracer()`. Defaults to
+     * `"rango"`. Ignored when `tracer` is provided.
+     */
+    tracerName?: string;
+    /**
+     * Explicit tracer override. Defaults to the global OTel tracer
+     * (`trace.getTracer(tracerName)`) — the provider `@vercel/otel`'s
+     * `registerOTel()` installs. Pass this to bridge onto a tracer you own.
+     */
+    tracer?: OTelActiveSpanTracer;
+}
+/**
+ * Create the tracing config for a Vercel router. Pass the result to
+ * `createRouter({ tracing })`. Spans are emitted for the request, middleware,
+ * action, loaders, handler, render, ssr, response, and background phases; pass
+ * `spans` to turn individual phases off.
+ *
+ * @see createOTelTracing (`@rangojs/router`) for the underlying adapter on any
+ *   platform with an OpenTelemetry SDK.
+ * @see createCloudflareTracing (`@rangojs/router/cloudflare`) for the same slot
+ *   using Cloudflare Workers native custom spans.
+ */
+export declare function createVercelTracing(options?: VercelTracingOptions): RouterTracingConfig;