@rangojs/router 0.0.0-experimental.tapabs2 → 0.1.0

package/dist/types/host/utils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Host Router Utilities
+ *
+ * Helper functions for type-safe pattern definitions.
+ */
+/**
+ * Define hosts with type safety
+ *
+ * @example
+ * ```ts
+ * const hosts = defineHosts({
+ *   admin: 'admin.*',
+ *   api: 'api.*',
+ *   app: ['*', 'www.*']
+ * });
+ *
+ * router.host(hosts.admin).lazy(() => import("./apps/admin")); // Type-safe!
+ * ```
+ */
+export declare function defineHosts<T extends Record<string, string | string[]>>(hosts: T): Readonly<T>;

package/dist/types/href-client.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Client-safe type-safe href function
+ *
+ * This is a compile-time only href that validates paths against registered routes.
+ * No runtime route map lookup - just an identity function with TypeScript validation.
+ *
+ * @example
+ * ```typescript
+ * import { href } from "rsc-router/client";
+ *
+ * href("/blog/my-post");           // ✓ matches /blog/:slug
+ * href("/shop/product/widget");    // ✓ matches /shop/product/:slug
+ * href("/invalid");                // ✗ TypeScript error
+ * ```
+ */
+import type { GetRegisteredRoutes } from "./types.js";
+import type { JsonSerialize } from "./serialize.js";
+/**
+ * Parse constraint values into a union type for paths
+ * "a|b|c" → "a" | "b" | "c"
+ */
+type ParseConstraintPath<T extends string> = T extends `${infer First}|${infer Rest}` ? First | ParseConstraintPath<Rest> : T;
+/**
+ * Convert a route pattern to a template literal type
+ *
+ * Supports:
+ * - Static: /about → "/about"
+ * - Dynamic: /blog/:slug → `/blog/${string}`
+ * - Optional: /:locale?/blog → "/blog" | `/${string}/blog`
+ * - Constrained: /:locale(en|gb)/blog → "/en/blog" | "/gb/blog"
+ * - Optional + Constrained: /:locale(en|gb)?/blog → "/blog" | "/en/blog" | "/gb/blog"
+ *
+ * @example
+ * PatternToPath<"/blog/:slug"> = `/blog/${string}`
+ * PatternToPath<"/:locale?/blog"> = "/blog" | `/${string}/blog`
+ * PatternToPath<"/:locale(en|gb)/blog"> = "/en/blog" | "/gb/blog"
+ * PatternToPath<"/:locale(en|gb)?/blog"> = "/blog" | "/en/blog" | "/gb/blog"
+ */
+export type PatternToPath<T extends string> = T extends `${infer Before}:${infer _Name}(${infer Constraint})?/${infer After}` ? PatternToPath<`${Before}${After}`> | `${Before}${ParseConstraintPath<Constraint>}/${PatternToPath<After>}` : T extends `${infer Before}:${infer _Name}(${infer Constraint})?` ? Before | `${Before}${ParseConstraintPath<Constraint>}` : T extends `${infer Before}:${infer _Name}(${infer Constraint})/${infer After}` ? `${Before}${ParseConstraintPath<Constraint>}/${PatternToPath<After>}` : T extends `${infer Before}:${infer _Name}(${infer Constraint})` ? `${Before}${ParseConstraintPath<Constraint>}` : T extends `${infer Before}:${infer _Param}?/${infer After}` ? PatternToPath<`${Before}${After}`> | `${Before}${string}/${PatternToPath<After>}` : T extends `${infer Before}:${infer _Param}?` ? Before | `${Before}${string}` : T extends `${infer Before}:${infer _Param}/${infer After}` ? `${Before}${string}/${PatternToPath<After>}` : T extends `${infer Before}:${infer _Param}` ? `${Before}${string}` : T;
+/**
+ * Allow optional query string (?...) and/or hash fragment (#...) suffix
+ *
+ * @example
+ * WithSuffix<"/about"> = "/about" | "/about?..." | "/about#..." | "/about?...#..."
+ */
+type WithSuffix<T extends string> = T | `${T}?${string}` | `${T}#${string}` | `${T}?${string}#${string}`;
+/**
+ * Helper type to get pattern from routes, handling string values and { path, response } objects
+ */
+type RoutePattern<TRoutes, K extends keyof TRoutes> = TRoutes[K] extends string ? TRoutes[K] : TRoutes[K] extends {
+    readonly path: infer P extends string;
+} ? P : string;
+/**
+ * Strip a query (`?…`) and/or hash (`#…`) suffix before matching, so a concrete
+ * URL like `/api/health?ts=1` still resolves to its route's response. Removes
+ * from the earliest of `?`/`#`: a `#` before the first `?` (the query is part of
+ * a fragment, e.g. `/health#top?x=1`) is handled, as is a `/:` that only appears
+ * inside the query (e.g. `/health?next=/:id`).
+ */
+type StripPathSuffix<T extends string> = T extends `${infer Base}?${string}` ? Base extends `${infer Frag}#${string}` ? Frag : Base : T extends `${infer Base}#${string}` ? Base : T;
+/** Extract a route entry's response payload (or `never` for RSC routes). */
+type ResponsePayloadOf<TRoutes, K extends keyof TRoutes> = TRoutes[K] extends {
+    readonly response: infer R;
+} ? Exclude<R, Response> : never;
+/**
+ * Look up the response payload for a route, keyed by either a route pattern
+ * (`/api/products/:id`) or a concrete path (`/api/products/123`). The same type
+ * serves a pattern lookup and a typed `fetch` wrapper that forwards a concrete
+ * `Rango.Path`:
+ *
+ *   PathResponse<"/api/products/:id"> → Product   // by pattern
+ *   PathResponse<"/api/products/123"> → Product   // by concrete path
+ *
+ * The query/hash suffix is stripped first; the stripped key is then treated as a
+ * pattern when it contains a `/:param` segment and matched exactly (precise even
+ * for nested dynamic routes), otherwise as a concrete path matched against each
+ * route's `PatternToPath` template. Because those holes are `${string}`
+ * (slash-greedy), a concrete path under a *nested* dynamic route can match several
+ * patterns and union their responses — pattern lookups do not have this
+ * looseness. RSC routes (no response) and unmatched keys resolve to `never`.
+ */
+type ResponsePayloadFor<TPath extends string, TRoutes = GetRegisteredRoutes> = ResponsePayloadForKey<StripPathSuffix<TPath>, TRoutes>;
+type ResponsePayloadForKey<TKey extends string, TRoutes> = TKey extends `${string}/:${string}` ? {
+    [K in keyof TRoutes]: RoutePattern<TRoutes, K> extends TKey ? ResponsePayloadOf<TRoutes, K> : never;
+}[keyof TRoutes] : {
+    [K in keyof TRoutes]: TKey extends PatternToPath<RoutePattern<TRoutes, K>> ? ResponsePayloadOf<TRoutes, K> : never;
+}[keyof TRoutes];
+/**
+ * Public response type for a route, keyed by pattern or concrete path. JSON
+ * response routes send the handler's return value verbatim (bare), so the
+ * payload is wrapped only in `JsonSerialize` to describe the JSON **wire** value
+ * a consumer receives from `fetch().then(r => r.json())` — e.g. a handler
+ * returning `{ createdAt: Date }` resolves here to `{ createdAt: string }`.
+ */
+export type PathResponse<TPath extends string, TRoutes = GetRegisteredRoutes> = JsonSerialize<ResponsePayloadFor<TPath, TRoutes>>;
+/**
+ * Strip trailing slash from a path (e.g., "/blog/" -> "/blog" | "/blog/")
+ * Allows navigation to include() prefixes without requiring trailing slash
+ */
+type OptionalTrailingSlash<T extends string> = T extends `${infer Base}/` ? Base extends "" ? T : Base | T : T;
+/**
+ * Union of all valid paths from registered routes
+ *
+ * Generated from Rango.RegisteredRoutes via module augmentation.
+ * Allows optional query strings and hash fragments.
+ */
+export type ValidPaths<TRoutes = GetRegisteredRoutes> = keyof TRoutes extends never ? `/${string}` : WithSuffix<{
+    [K in keyof TRoutes]: OptionalTrailingSlash<PatternToPath<RoutePattern<TRoutes, K>>>;
+}[keyof TRoutes]>;
+type GlobalPathResponse<TPattern extends string, TRoutes = GetRegisteredRoutes> = PathResponse<TPattern, TRoutes>;
+/**
+ * Ambient path types on the `Rango` namespace.
+ *
+ * These live on the same global namespace consumers already augment for
+ * `Rango.Env` / `Rango.Vars`, so they are reachable with no import wherever the
+ * router's types are in scope. They are the public, recommended surface for
+ * typing anything that wraps `href()`. `ValidPaths` / `PathResponse` stay as the
+ * internal building blocks behind them.
+ */
+declare global {
+    namespace Rango {
+        /**
+         * Union of every valid route path accepted by `href()`.
+         *
+         * Type a wrapper's path parameter as `Rango.Path` so it shares `href()`'s
+         * compile-time validation against the registered routes:
+         *
+         * ```ts
+         * import { href } from "@rangojs/router/client";
+         *
+         * export const appHref = (path: Rango.Path) => href(path);
+         * ```
+         *
+         * Resolves from `Rango.RegisteredRoutes` when augmented, otherwise the
+         * auto-generated `Rango.GeneratedRouteMap`, otherwise a permissive
+         * `/${string}` fallback.
+         */
+        type Path<TRoutes = GetRegisteredRoutes> = ValidPaths<TRoutes>;
+        /**
+         * Response payload for a route, looked up from the global route map by
+         * either a route pattern (`/api/products/:id`) or a concrete path
+         * (`/api/products/123`). Because it accepts a concrete `Rango.Path`, it
+         * doubles as the return type of a typed `fetch` wrapper:
+         *
+         * ```ts
+         * type Product = Rango.PathResponse<"/api/products/:id">; // by pattern
+         * type Same = Rango.PathResponse<"/api/products/42">;     // by concrete path
+         *
+         * const get = async <T extends Rango.Path>(
+         *   path: T,
+         * ): Promise<Rango.PathResponse<T>> =>
+         *   fetch(href(path)).then((r) => r.json());
+         * ```
+         *
+         * The payload is the JSON **wire** shape (via `Rango.JsonSerialize`), not the
+         * handler's raw return — a handler returning `{ createdAt: Date }` resolves
+         * here to `{ createdAt: string }` (bare, no envelope), matching what
+         * `fetch().then(r => r.json())` actually yields.
+         *
+         * Only resolves once `Rango.RegisteredRoutes` carries response metadata (the
+         * generated map has paths and search but no payloads). Pass an explicit route
+         * map as the second argument to look up against a non-global map (rarely
+         * needed in app code).
+         */
+        type PathResponse<TPath extends string, TRoutes = GetRegisteredRoutes> = GlobalPathResponse<TPath, TRoutes>;
+    }
+}
+/**
+ * Type-safe href function for client-side use
+ *
+ * Without mount: identity function, validates absolute paths at compile time.
+ * With mount: prepends mount path, for use with useMount() inside include() scopes.
+ *
+ * @param path - A valid path matching one of the registered route patterns
+ * @param mount - Optional mount prefix from useMount() for include-scoped paths
+ * @returns The resolved path
+ *
+ * @example
+ * ```typescript
+ * // Absolute paths (type-safe)
+ * href("/blog/hello");           // "/blog/hello"
+ * href("/shop/product/widget");  // "/shop/product/widget"
+ *
+ * // With mount (inside an include)
+ * const mount = useMount();      // "/articles"
+ * href("/", mount);              // "/articles/"
+ * href("/my-post", mount);       // "/articles/my-post"
+ *
+ * // Query strings and hashes pass through
+ * href("/blog/hello?page=1");
+ * href("/about#contact");
+ * ```
+ */
+export declare function href<T extends ValidPaths>(path: T, mount?: string): string;
+/**
+ * Props shape returned by href.json() etc. for spreading on <Link>.
+ * Sets data-external to trigger hard navigation (skips RSC fetch).
+ */
+export interface ResponseHrefProps {
+    to: string;
+    "data-external": "";
+}
+type ResponseHrefFn = <T extends ValidPaths>(path: T, mount?: string) => ResponseHrefProps;
+export declare namespace href {
+    const json: ResponseHrefFn;
+    const text: ResponseHrefFn;
+    const html: ResponseHrefFn;
+    const xml: ResponseHrefFn;
+    const md: ResponseHrefFn;
+    const image: ResponseHrefFn;
+    const stream: ResponseHrefFn;
+    const any: ResponseHrefFn;
+}
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @rangojs/router
+ *
+ * Single user-facing entrypoint for all router APIs.
+ *
+ * The "react-server" export condition selects index.rsc.ts (real implementations)
+ * vs this file (client stubs for server-only functions).
+ *
+ * For client-only exports (Outlet, useOutlet, hooks, components):
+ *   import from "@rangojs/router/client"
+ */
+export { RouteNotFoundError, DataNotFoundError, notFound, MiddlewareError, HandlerError, BuildError, DslContextError, InvalidHandlerError, RouterError, Skip, isSkip, } from "./errors.js";
+export type { DocumentProps, DefaultEnv, RouteDefinition, RouteConfig, RouteDefinitionOptions, TrailingSlashMode, Handler, // Supports params object, path pattern, or route name
+HandlerContext, ExtractParams, GenericParams, Middleware, RevalidateParams, Revalidate, ActionRef, RouteKeys, LoaderDefinition, LoaderFn, LoaderContext, FetchableLoaderOptions, LoadOptions, ErrorInfo, ErrorBoundaryFallbackProps, ErrorBoundaryHandler, ClientErrorBoundaryFallbackProps, NotFoundInfo, NotFoundBoundaryFallbackProps, NotFoundBoundaryHandler, ErrorPhase, OnErrorContext, OnErrorCallback, } from "./types.js";
+export type { SearchSchema, SearchSchemaValue, ResolveSearchSchema, RouteSearchParams, RouteParams, } from "./search-params.js";
+export { createLoader } from "./loader.js";
+export type { RouteHelpers, RouteHandlers } from "./route-definition.js";
+export type { TransitionConfig, TransitionWhenFn, TransitionWhenContext, ViewTransitionClass, } from "./types.js";
+export type { RouteUseItem, LayoutUseItem, AllUseItems, UseItems, HandlerUseItem, } from "./route-types.js";
+export type { ResponseHandler, ResponseHandlerContext, JsonResponseHandler, TextResponseHandler, JsonValue, ResponsePathFn, JsonResponsePathFn, TextResponsePathFn, RouteResponse, ProblemDetails, PartialPrerenderProps, } from "./urls.js";
+export type { MiddlewareContext, CookieOptions } from "./router/middleware.js";
+/**
+ * Error-throwing stub for server-only `urls` function.
+ */
+export declare function urls(): never;
+/**
+ * Error-throwing stub for server-only `createRouter` function.
+ */
+export declare function createRouter(): never;
+/**
+ * Error-throwing stub for server-only `redirect` function.
+ */
+export declare function redirect(): never;
+export { createHandle, isHandle, type Handle } from "./handle.js";
+export { DEFAULT_DEFER_TIMEOUT_MS, type DeferOptions, type HandlePush, type HandlePushFn, } from "./defer.js";
+export { createVar, type ContextVar } from "./context-var.js";
+export { nonce } from "./rsc/nonce.js";
+/**
+ * SSR/client stub for server-only `Prerender` function.
+ *
+ * Returns a lightweight stub object instead of throwing so that the
+ * production SSR build can safely bundle the RSC entry chunk — the SSR
+ * bundler resolves `@rangojs/router` to this (SSR) entry, so Prerender
+ * calls in RSC code must not crash at module-evaluation time.
+ */
+export declare function Prerender(_handler?: any, _optionsOrId?: any, __injectedId?: string): any;
+/**
+ * SSR/client stub for server-only `Passthrough` function.
+ */
+export declare function Passthrough(_handler?: any, _optionsOrId?: any, __injectedId?: string): any;
+/**
+ * SSR/client stub for server-only `Static` function.
+ *
+ * Returns a lightweight stub object instead of throwing so that the
+ * production SSR build can safely bundle the RSC entry chunk — the SSR
+ * bundler resolves `@rangojs/router` to this (SSR) entry, so Static
+ * calls in RSC code must not crash at module-evaluation time.
+ */
+export declare function Static(_handler?: any, _optionsOrId?: any, __injectedId?: string): any;
+/**
+ * Error-throwing stub for server-only `getRequestContext` function.
+ */
+export declare function getRequestContext(): never;
+/**
+ * Error-throwing stub for server-only `cookies` function.
+ */
+export declare function cookies(): never;
+/**
+ * Error-throwing stub for server-only `headers` function.
+ */
+export declare function headers(): never;
+/**
+ * Client implementation of `invalidateClientCache()`. Unlike the server-only
+ * stubs above this is a REAL function under the `default` condition (it marks
+ * the client's caches stale); the `react-server` condition (index.rsc.ts)
+ * selects the server implementation that writes a rotated `Set-Cookie`.
+ */
+export { invalidateClientCache, keepClientCache, } from "./browser/invalidate-client-cache.js";
+/**
+ * Error-throwing stub for server-only `createReverse` function.
+ */
+export declare function createReverse(): never;
+export declare function layout(): never;
+export declare function cache(): never;
+export declare function middleware(): never;
+export declare function revalidate(): never;
+export declare function cacheTag(): never;
+export declare function updateTag(): never;
+export declare function revalidateTag(): never;
+export declare function loader(): never;
+export declare function loading(): never;
+export declare function parallel(): never;
+export declare function intercept(): never;
+export declare function errorBoundary(): never;
+export declare function notFoundBoundary(): never;
+export declare function transition(): never;
+export type { PublicRequestContext as RequestContext } from "./server/request-context.js";
+export type { RequestScope, ExecutionContext } from "./types/request-scope.js";
+export type { CookieStore, Cookie, ReadonlyHeaders, } from "./server/cookie-store.js";
+export { Meta } from "./handles/meta.js";
+export { Script, type ScriptConfig, type ScriptAttributes, } from "./handles/script.js";
+export { Breadcrumbs } from "./handles/breadcrumbs.js";
+export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
+export type { BreadcrumbItem } from "./handles/breadcrumbs.js";
+export type { ScopedReverseFunction, ReverseFunction, ExtractLocalRoutes, ParamsFor, } from "./reverse.js";
+export { scopedReverse } from "./reverse.js";
+export { createLocationState, type LocationStateDefinition, type LocationStateEntry, type LocationStateOptions, } from "./browser/react/location-state-shared.js";
+export type { OTelTracer, OTelActiveSpanTracer, OTelSpan, OTelTracingOptions, } from "./router/telemetry-otel.js";
+export type { TelemetrySink, TelemetryEvent, RequestStartEvent, RequestEndEvent, RequestErrorEvent, LoaderStartEvent, LoaderEndEvent, LoaderErrorEvent, HandlerErrorEvent, CacheSegmentStatus, CacheSegmentSignal, CacheDecisionEvent, RevalidationDecisionEvent, RequestTimeoutEvent, OriginCheckRejectedEvent, } from "./router/telemetry.js";
+export type { RouterTracingConfig, TracePhase, TracePhaseToggles, TracingToggleOptions, } from "./router/tracing.js";
+export { RouterTimeoutError } from "./router/timeout.js";
+export type { RouterTimeouts, TimeoutPhase, TimeoutContext, RenderTimeoutContext, } from "./router/timeout.js";

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

@@ -0,0 +1,51 @@
+/**
+ * @rangojs/router (react-server environment)
+ *
+ * This file is used when importing "@rangojs/router" from RSC (server components).
+ * It re-exports everything from the universal index.ts plus adds server-side
+ * implementations that replace the client-side error stubs.
+ *
+ * The bundler uses the "react-server" export condition to select this file
+ * in RSC context, while the regular index.ts is used in client components.
+ */
+export { RouteNotFoundError, DataNotFoundError, notFound, MiddlewareError, HandlerError, BuildError, DslContextError, InvalidHandlerError, RouterError, Skip, isSkip, } from "./index.js";
+export type { DocumentProps, DefaultEnv, RouteDefinition, RouteConfig, RouteDefinitionOptions, TrailingSlashMode, Handler, HandlerContext, ExtractParams, GenericParams, Middleware, RevalidateParams, Revalidate, ActionRef, RouteKeys, LoaderDefinition, LoaderFn, LoaderContext, FetchableLoaderOptions, LoadOptions, ErrorInfo, ErrorBoundaryFallbackProps, ErrorBoundaryHandler, ClientErrorBoundaryFallbackProps, NotFoundInfo, NotFoundBoundaryFallbackProps, NotFoundBoundaryHandler, ErrorPhase, OnErrorContext, OnErrorCallback, TransitionConfig, TransitionWhenFn, TransitionWhenContext, ViewTransitionClass, } from "./types.js";
+export type { RangoOptions, SSRStreamMode, SSROptions, ResolveStreamingContext, } from "./router.js";
+export type { OriginCheckConfig, OriginCheckContext, OriginCheckPhase, } from "./rsc/origin-guard.js";
+export type { ShellCaptureDebug, ShellCaptureDebugEvent, } from "./rsc/shell-capture.js";
+export { createLoader, redirect, type RouteHelpers, type RouteHandlers, layout, cache, middleware, revalidate, loader, loading, parallel, intercept, errorBoundary, notFoundBoundary, transition, } from "./route-definition.js";
+export type { RouteUseItem, LayoutUseItem, AllUseItems, UseItems, HandlerUseItem, } from "./route-types.js";
+export { createHandle, isHandle, type Handle } from "./handle.js";
+export { DEFAULT_DEFER_TIMEOUT_MS, type DeferOptions, type HandlePush, type HandlePushFn, } from "./defer.js";
+export { createVar, type ContextVar } from "./context-var.js";
+export { nonce } from "./rsc/nonce.js";
+export { Prerender, Passthrough, type PrerenderHandlerDefinition, type PassthroughHandlerDefinition, type PrerenderOptions, type BuildContext, type StaticBuildContext, type GetParamsContext, type PrerenderPassthroughResult, } from "./prerender.js";
+export { Static, type StaticHandlerDefinition, type StaticHandlerOptions, } from "./static-handler.js";
+export { urls, type PathHelpers, type PathOptions, type PartialPrerenderProps, type UrlPatterns, type IncludeOptions, type IncludeItem, type RouteResponse, type ProblemDetails, type ResponseHandler, type ResponseHandlerContext, type JsonResponseHandler, type TextResponseHandler, type JsonValue, type ResponsePathFn, type JsonResponsePathFn, type TextResponsePathFn, } from "./urls.js";
+export { createRouter, type Rango, type RootLayoutProps, type RouterRequestInput, } from "./router.js";
+export type { HandlerCacheConfig } from "./rsc/types.js";
+export { Meta } from "./handles/meta.js";
+export { Script, type ScriptConfig, type ScriptAttributes, } from "./handles/script.js";
+export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
+export type { PublicRequestContext as RequestContext } from "./server/request-context.js";
+import type { PublicRequestContext } from "./server/request-context.js";
+import type { DefaultEnv } from "./types/global-namespace.js";
+export type { RequestScope, ExecutionContext } from "./types/request-scope.js";
+export declare const getRequestContext: <TEnv = DefaultEnv>() => PublicRequestContext<TEnv>;
+export { cookies, headers, invalidateClientCache, keepClientCache, type CookieStore, type Cookie, type ReadonlyHeaders, } from "./server/cookie-store.js";
+export { cacheTag } from "./cache/cache-tag.js";
+export { updateTag, revalidateTag } from "./cache/tag-invalidation.js";
+export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
+export type { MiddlewareContext, CookieOptions, MiddlewareFn, } from "./router/middleware.js";
+export type { ScopedReverseFunction, ReverseFunction, ExtractLocalRoutes, ParamsFor, } from "./reverse.js";
+export { scopedReverse, createReverse } from "./reverse.js";
+export type { SearchSchema, SearchSchemaValue, ResolveSearchSchema, RouteSearchParams, RouteParams, } from "./search-params.js";
+export { createLocationState, type LocationStateDefinition, type LocationStateEntry, type LocationStateOptions, } from "./browser/react/location-state-shared.js";
+export { createConsoleSink } from "./router/telemetry.js";
+export { createOTelSink } from "./router/telemetry-otel.js";
+export { createOTelTracing } from "./router/telemetry-otel.js";
+export type { OTelTracer, OTelActiveSpanTracer, OTelSpan, OTelTracingOptions, } from "./router/telemetry-otel.js";
+export type { TelemetrySink, TelemetryEvent, RequestStartEvent, RequestEndEvent, RequestErrorEvent, LoaderStartEvent, LoaderEndEvent, LoaderErrorEvent, HandlerErrorEvent, CacheSegmentStatus, CacheSegmentSignal, CacheDecisionEvent, RevalidationDecisionEvent, RequestTimeoutEvent, OriginCheckRejectedEvent, } from "./router/telemetry.js";
+export type { RouterTracingConfig, TracePhase, TracePhaseToggles, TracingToggleOptions, } from "./router/tracing.js";
+export { RouterTimeoutError } from "./router/timeout.js";
+export type { RouterTimeouts, TimeoutPhase, TimeoutContext, RenderTimeoutContext, } from "./router/timeout.js";

package/dist/types/internal-debug.d.ts

@@ -0,0 +1 @@
+export declare const INTERNAL_RANGO_DEBUG: boolean;

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

@@ -0,0 +1,193 @@
+/**
+ * LoaderStore — shared subscription model for `useLoader` / `useFetchLoader`.
+ *
+ * Each bucket key gets one entry that holds the latest committed snapshot plus a
+ * set of listeners. Snapshots are frozen and replaced atomically on mutation, so
+ * subscribers can compare snapshot identity and avoid unnecessary updates
+ * between real changes.
+ *
+ * The bucket key is `loader.$$id` by default, or `loader.$$id + key` when the
+ * hook is given an explicit client refresh `key`. Multiple buckets belonging to
+ * the same loader form a family (indexed by `loader.$$id`) so a navigation /
+ * route-context reset can clear them all at once via `clearFamily`.
+ *
+ * Mutations that come in for an old request id (e.g. a slow response that
+ * resolves after a newer load() was issued, or after a navigation cleared the
+ * entry) are silently dropped. `reserveRequestId` is the only way to claim the
+ * "latest" slot; `clear` bumps it too so pre-navigation in-flight loads cannot
+ * commit into the new route's context.
+ *
+ * Bucket lifecycle differs by registration:
+ *   - Sticky buckets (a route-registered reader subscribed at least once) keep
+ *     their entry after the last subscriber leaves so an in-flight load() can
+ *     still commit on remount; they reset on navigation via `clearFamily`.
+ *   - Ephemeral buckets (only ever subscribed by readers with no route context,
+ *     i.e. keyed `useFetchLoader` of an unregistered loader) have no
+ *     route-context reset trigger, so they are reference-counted: dropped once
+ *     the last subscriber unsubscribes. The drop is deferred to a microtask and
+ *     cancelled on resubscribe so a StrictMode / transition remount does not
+ *     reclaim a bucket that is about to be reused, and is held until any
+ *     in-flight load settles.
+ *
+ * The store is intentionally module-level: each browser tab is its own JS
+ * realm, so there is no cross-request pollution. Server renders never mutate
+ * the store — the hook falls back to `OutletContext.loaderData`.
+ */
+export interface LoaderEntry<T = unknown> {
+    readonly value: T | undefined;
+    /**
+     * Whether a load has committed a value to this bucket. Distinguishes a
+     * committed `null`/`undefined` result from "never loaded", so a loader that
+     * resolves to a falsy value is not mistaken for an empty bucket and is not
+     * overridden by the server-seeded context value.
+     */
+    readonly hasValue: boolean;
+    readonly error: Error | null;
+    readonly isLoading: boolean;
+    /** Identifies the request that produced this snapshot. 0 means "no request". */
+    readonly requestId: number;
+}
+/**
+ * Options for `subscribe`.
+ */
+export interface SubscribeOptions {
+    /**
+     * Family id (`loader.$$id`) this bucket belongs to. `clearFamily` uses it to
+     * reach every keyed bucket of the same loader. Defaults to the bucket key.
+     */
+    loaderId?: string;
+    /**
+     * When true, this subscription is from a reader with no route context (keyed
+     * `useFetchLoader` of an unregistered loader). Such buckets have no
+     * route-context reset trigger and are reference-counted instead. A bucket
+     * becomes sticky for the rest of its life as soon as any non-ephemeral
+     * subscriber attaches, and from then on resets via `clearFamily`.
+     */
+    ephemeral?: boolean;
+    /**
+     * Cross-loader refresh group name(s). Tags this bucket so `refreshGroups(name)`
+     * can refresh it alongside buckets of other loaders. A bucket may be tagged
+     * with several group names at once (pass an array); it is then refreshed when
+     * ANY of its groups is refreshed. Group membership follows subscriber presence:
+     * a bucket leaves a group when that group's last subscriber unsubscribes.
+     */
+    group?: string | string[];
+    /**
+     * Plain-GET refresh thunk used by `refreshGroups`. Provided alongside `group`.
+     * Refreshes this bucket in place (no params/body) and rejects on failure.
+     */
+    refetch?: () => Promise<void>;
+}
+export declare class LoaderStore {
+    private readonly entries;
+    /** loader.$$id -> set of bucket keys, so clearFamily() can reach every bucket. */
+    private readonly families;
+    /** refresh group name -> set of bucket keys, for refreshGroups(). */
+    private readonly groups;
+    private getOrCreate;
+    private registerFamily;
+    /**
+     * Subscribe to entry changes for `bucketKey`.
+     * Returns an unsubscribe function. A sticky bucket's entry is kept around even
+     * after the last subscriber leaves so that an in-flight `load()` can still
+     * commit if the consumer remounts. An ephemeral bucket is dropped once its
+     * last subscriber leaves (deferred, see maybeScheduleRefcountClear).
+     */
+    subscribe(bucketKey: string, cb: () => void, options?: SubscribeOptions): () => void;
+    private addToGroup;
+    private releaseGroup;
+    /** Remove a bucket from every group it belongs to (used when it is dropped). */
+    private removeFromAllGroups;
+    /**
+     * Refresh every currently-mounted bucket tagged with ANY of the given group
+     * names, with a plain GET (no params/body). Accepts a single name or an array
+     * of names. A bucket that belongs to more than one of the named groups is
+     * refreshed exactly once (members are unioned and deduped by bucket key), as
+     * are multiple reads of one bucket. Resolves when all refreshes settle; rejects
+     * with an `AggregateError` of the failures if any member fails — each failing
+     * member also records its error on its own snapshot.
+     */
+    refreshGroups(groups: string | string[]): Promise<void>;
+    /**
+     * Schedule a deferred drop for an ad-hoc (never-sticky) bucket whose last
+     * subscriber just left. Deferred to a microtask so a StrictMode / transition
+     * remount that resubscribes in the same tick cancels it.
+     */
+    private maybeScheduleRefcountClear;
+    /** Remove a bucket entry entirely and prune it from its family/group indexes. */
+    private dropBucket;
+    /** Drop an ephemeral bucket that settled with no subscribers left. */
+    private dropIfSettled;
+    /**
+     * Returns the current snapshot for `bucketKey`. Stable reference between
+     * mutations — subscribers rely on this to avoid spurious re-renders.
+     * Returns `EMPTY_SNAPSHOT` (a singleton) when the entry has never been
+     * mutated or has been cleared.
+     */
+    getSnapshot(bucketKey: string): LoaderEntry;
+    /**
+     * Reserve a fresh request id for an upcoming `load()` call. The returned id
+     * is the new "latest"; any older in-flight requests will fail their gating
+     * check on `finishData` / `finishError` / `finishLoading` and be dropped.
+     *
+     * Callers should follow with `beginRequest(id, requestId)` to flip the
+     * loading flag on AND clear any leftover error from a previous attempt
+     * — the latter matters for `throwOnError: false` consumers, which would
+     * otherwise keep showing the stale error throughout the retry.
+     */
+    reserveRequestId(bucketKey: string): number;
+    /**
+     * Mark the request as in-flight: `isLoading = true`, `error = null`.
+     * Combines the two operations so a retry doesn't render the previous
+     * error during the new request. Gated on `requestId === latestRequestId`
+     * for symmetry with the other mutators.
+     */
+    beginRequest(bucketKey: string, requestId: number): void;
+    /**
+     * Commit a successful result. No-op if `requestId` is not the latest
+     * (a newer `load()` was issued or `clear()` ran). Clearing `error` is
+     * intentional: a successful refetch should hide the previous failure.
+     */
+    finishData<T>(bucketKey: string, requestId: number, value: T): void;
+    /**
+     * Commit an error. Preserves the last good `value` so consumers can keep
+     * showing previous data while displaying the error if they choose. No-op
+     * if `requestId` is not the latest.
+     */
+    finishError(bucketKey: string, requestId: number, error: Error): void;
+    /**
+     * Update loading flag. Gated on `requestId` to fix the race where an old
+     * load() finishes after a new one started — its `setLoading(false)` would
+     * otherwise hide the new request's spinner.
+     */
+    setLoading(bucketKey: string, requestId: number, isLoading: boolean): void;
+    /**
+     * Reset a single bucket entry. Bumps `latestRequestId` so any in-flight
+     * `load()` whose promise is still pending will fail its gate when it resolves
+     * and be dropped — prevents pre-navigation loads from clobbering the new
+     * route's context. The entry itself is kept (sticky-bucket semantics).
+     */
+    clear(bucketKey: string): void;
+    /**
+     * Reset every sticky bucket belonging to `loaderId`. Called on navigation /
+     * route-context change: all route-registered reads of the loader (keyed or
+     * not) drop back to seeding from fresh `loaderData`. Ephemeral buckets are
+     * intentionally left alone — they are governed by subscriber refcount, so a
+     * persistent keyed reader outside the outlet keeps its value across a
+     * navigation rather than blanking out.
+     */
+    clearFamily(loaderId: string): void;
+    private notify;
+    /**
+     * Test-only escape hatch. Drops every entry. Production code should never
+     * call this; the store is process-scoped and lives for the tab's lifetime.
+     * @internal
+     */
+    reset(): void;
+}
+/**
+ * Module-level singleton. Each browser tab gets its own; SSR never mutates it.
+ * The hook falls through to `OutletContext.loaderData` during the server render.
+ */
+export declare const loaderStore: LoaderStore;
+export declare const EMPTY_LOADER_SNAPSHOT: LoaderEntry;

package/dist/types/loader.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @rangojs/router/loader (client version)
+ *
+ * Client-only stub for createLoader. Returns a minimal loader definition
+ * ({ __brand, $$id }) that can be passed to hooks like useLoader.
+ * The actual loader function is not included -- it only exists on the server.
+ *
+ * For export-only loader files, the Vite plugin replaces the entire file with
+ * object literals (bypassing this function). Those stubs only contain
+ * { __brand, $$id }.
+ * This function only runs when loaders are in mixed files (not export-only).
+ *
+ * The $$id is injected by the Vite exposeInternalIds plugin.
+ */
+import type { FetchableLoaderOptions, LoaderDefinition, LoaderFn } from "./types.js";
+export declare function createLoader<T>(fn: LoaderFn<T, Record<string, string | undefined>, any>): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+export declare function createLoader<T>(fn: LoaderFn<T, Record<string, string | undefined>, any>, fetchable: true): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+export declare function createLoader<T>(fn: LoaderFn<T, Record<string, string | undefined>, any>, options: FetchableLoaderOptions): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;

package/dist/types/loader.rsc.d.ts

@@ -0,0 +1,18 @@
+/**
+ * rsc-router/loader (RSC/server version)
+ *
+ * Server-side createLoader implementation with full loader functionality.
+ * Only used in react-server context via export conditions.
+ *
+ * For non-fetchable loaders: returns a loader definition with fn included
+ * For fetchable loaders: stores fn in registry and returns a serializable loader
+ *
+ * The $$id is injected by the Vite exposeInternalIds plugin as a hidden parameter.
+ * Users don't need to pass any name - IDs are auto-generated from file path.
+ */
+import type { FetchableLoaderOptions, LoaderDefinition, LoaderFn } from "./types.js";
+import { getFetchableLoader } from "./server/fetchable-loader-store.js";
+export { getFetchableLoader };
+export declare function createLoader<T>(fn: LoaderFn<T, Record<string, string | undefined>, any>): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+export declare function createLoader<T>(fn: LoaderFn<T, Record<string, string | undefined>, any>, fetchable: true): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+export declare function createLoader<T>(fn: LoaderFn<T, Record<string, string | undefined>, any>, options: FetchableLoaderOptions): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;

package/dist/types/missing-id-error.d.ts

@@ -0,0 +1 @@
+export declare function missingInjectedIdError(kind: "Loader" | "Handle", fnName: "createLoader" | "createHandle"): Error;

package/dist/types/outlet-context.d.ts

@@ -0,0 +1,12 @@
+import { type Context, type ReactNode } from "react";
+import type { ResolvedSegment } from "./types";
+export interface OutletContextValue {
+    content: ReactNode;
+    parallel?: ResolvedSegment[];
+    segment?: ResolvedSegment;
+    loaderData?: Record<string, any>;
+    parent?: OutletContextValue | null;
+    /** Loading component for Suspense fallback (from segment's loading() definition) */
+    loading?: ReactNode;
+}
+export declare const OutletContext: Context<OutletContextValue | null>;