@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.0

package/dist/types/route-definition/helpers-types.d.ts

@@ -0,0 +1,392 @@
+import type { ReactNode } from "react";
+import type { ExtractRouteParams, Handler, PartialCacheOptions, ErrorBoundaryHandler, LoaderDefinition, MiddlewareFn, NotFoundBoundaryHandler, ResolvedRouteMap, RouteDefinition, ShouldRevalidateFn, TransitionConfig } from "../types.js";
+import type { AllUseItems, LayoutItem, RouteItem, ParallelItem, InterceptItem, MiddlewareItem, RevalidateItem, LoaderItem, LoadingItem, ErrorBoundaryItem, NotFoundBoundaryItem, LayoutUseItem, RouteUseItem, ParallelUseItem, InterceptUseItem, LoaderUseItem, CacheItem, TransitionItem, UseItems } from "../route-types.js";
+export type { AllUseItems, LayoutItem, RouteItem, ParallelItem, InterceptItem, MiddlewareItem, RevalidateItem, LoaderItem, ErrorBoundaryItem, NotFoundBoundaryItem, LayoutUseItem, RouteUseItem, ParallelUseItem, InterceptUseItem, CacheItem, } from "../route-types.js";
+export type { InterceptConfig, InterceptSelectorContext, InterceptSegmentsState, InterceptWhenFn, } from "../server/context";
+/**
+ * Route helpers provided by map()
+ * These are the only typed helpers users interact with
+ */
+export type RouteHelpers<T extends RouteDefinition, TEnv> = {
+    /**
+     * Define a route handler for a specific route pattern
+     * ```typescript
+     * route("products.detail", async (ctx) => {
+     *   const product = await getProduct(ctx.params.slug);
+     *   return <ProductPage product={product} />;
+     * })
+     *
+     * // With nested use() for middleware, loaders, etc.
+     * route("products.detail", ProductHandler, () => [
+     *   loader(ProductLoader),
+     *   loading(<ProductSkeleton />),
+     * ])
+     * ```
+     * @param name - Route name matching a key from route definitions
+     * @param handler - Async function that returns JSX for the route
+     * @param use - Optional callback returning middleware, loaders, loading, etc.
+     */
+    route: <K extends keyof ResolvedRouteMap<T> & string>(name: K, handler: Handler<ExtractRouteParams<T, K & string>, {}, TEnv>, use?: () => UseItems<RouteUseItem>) => RouteItem;
+    /**
+     * Define a layout that wraps child routes
+     * ```typescript
+     * layout(<RootLayout />, () => [
+     *   route("home", HomePage),
+     *   route("about", AboutPage),
+     * ])
+     *
+     * // With dynamic layout handler
+     * layout(async (ctx) => {
+     *   const user = ctx.get("user");
+     *   return <DashboardShell user={user} />;
+     * }, () => [
+     *   middleware(authMiddleware),
+     *   route("dashboard", DashboardPage),
+     * ])
+     * ```
+     * @param component - Static JSX or async handler for the layout
+     * @param use - Callback returning child routes, middleware, loaders, etc.
+     */
+    layout: (component: ReactNode | Handler<any, any, TEnv>, use?: () => UseItems<LayoutUseItem>) => LayoutItem;
+    /**
+     * Define parallel routes that render simultaneously in named slots
+     * ```typescript
+     * parallel({
+     *   "@sidebar": <Sidebar />,
+     *   "@main": async (ctx) => <MainContent data={ctx.use(DataLoader)} />,
+     * })
+     *
+     * // With loaders and loading states (broadcast to every slot)
+     * parallel({
+     *   "@analytics": AnalyticsPanel,
+     *   "@metrics": MetricsPanel,
+     * }, () => [
+     *   loader(DashboardLoader),
+     *   loading(<DashboardSkeleton />),
+     * ])
+     *
+     * // Per-slot scoped use via slot descriptor — for single-assignment items
+     * // like loading() that should not broadcast to siblings.
+     * parallel({
+     *   "@meta": MetaSlot,
+     *   "@sidebar": {
+     *     handler: SidebarSlot,
+     *     use: () => [loading(<SidebarSkeleton />)],
+     *   },
+     * })
+     * ```
+     * @param slots - Object with slot names (prefixed with @) mapped to handlers
+     *                or `{ handler, use? }` slot descriptors.
+     * @param use - Optional callback for loaders, loading, revalidate, etc.
+     *              Items here apply to every slot in the call (broadcast).
+     *              For per-slot single-assignment items, use the slot descriptor's
+     *              own `use` callback — slot-local items run after the broadcast,
+     *              so they take precedence on `loading()` and other last-write-wins
+     *              fields.
+     */
+    parallel: (slots: Record<`@${string}`, Handler<any, any, TEnv> | ReactNode | {
+        handler: Handler<any, any, TEnv> | ReactNode;
+        use?: () => UseItems<ParallelUseItem>;
+    }>, use?: () => UseItems<ParallelUseItem>) => ParallelItem;
+    /**
+     * Define an intercepting route for soft navigation
+     *
+     * When soft-navigating to the target route from within the current layout,
+     * the intercept handler renders in the named slot instead of the route's
+     * default handler. Direct navigation uses the route's handler.
+     *
+     * ```typescript
+     * // In a layout - intercept "card" route as modal
+     * layout(<KanbanLayout />, () => [
+     *   intercept("@modal", "card", () => <CardModal />),
+     * ])
+     *
+     * // With loaders and revalidation
+     * intercept("@modal", "card", () => <CardModal />, () => [
+     *   loader(CardModalLoader),
+     *   revalidate(() => false),
+     * ])
+     *
+     * // Conditional activation via the config object's `when` selector
+     * intercept("@modal", "card", <CardModal />, {
+     *   when: ({ from }) => from.pathname.startsWith("/board"),
+     * })
+     *
+     * // Config + other use-items: config is arg 4, use is arg 5
+     * intercept(
+     *   "@modal",
+     *   "card",
+     *   <CardModal />,
+     *   { when: ({ from }) => from.pathname.startsWith("/board") },
+     *   () => [loader(CardDetailLoader)],
+     * )
+     * ```
+     * @param slotName - Named slot (prefixed with @) where intercept renders
+     * @param routeName - Route name to intercept
+     * @param handler - Component or handler for intercepted render
+     * @param config - Optional InterceptConfig (e.g. `{ when }`), or the use
+     *   callback directly when there is no config
+     * @param use - Optional callback for loaders, middleware, revalidate, etc.
+     */
+    intercept: {
+        <K extends keyof ResolvedRouteMap<T> & string>(slotName: `@${string}`, routeName: `.${K}`, handler: ReactNode | Handler<ExtractRouteParams<T, K>, {}, TEnv>, config?: import("../server/context.js").InterceptConfig<TEnv> | (() => UseItems<InterceptUseItem>), use?: () => UseItems<InterceptUseItem>): InterceptItem;
+        <K extends keyof Rango.GeneratedRouteMap & string>(slotName: `@${string}`, routeName: K, handler: ReactNode | Handler<K, Rango.GeneratedRouteMap, TEnv>, config?: import("../server/context.js").InterceptConfig<TEnv> | (() => UseItems<InterceptUseItem>), use?: () => UseItems<InterceptUseItem>): InterceptItem;
+    };
+    /**
+     * Attach middleware to the current route/layout, or wrap child segments
+     *
+     * **Sibling mode** — attaches middleware to the parent entry:
+     * ```typescript
+     * layout(<DashboardShell />, () => [
+     *   middleware(authMiddleware),
+     *   middleware([authMiddleware, loggingMiddleware]),
+     *   path("/", DashboardPage),
+     * ])
+     * ```
+     *
+     * **Wrapping mode** — scopes middleware to the children only:
+     * ```typescript
+     * middleware(authMiddleware, () => [
+     *   path("/dashboard", DashboardPage),
+     *   path("/settings", SettingsPage),
+     * ])
+     *
+     * middleware([authMiddleware, loggingMiddleware], () => [
+     *   path("/admin", AdminPage),
+     * ])
+     * ```
+     */
+    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
+     * ```typescript
+     * // Revalidate when params change
+     * revalidate(({ currentParams, nextParams }) =>
+     *   currentParams.slug !== nextParams.slug
+     * )
+     *
+     * // Revalidate after specific actions (actionId format: "path/to/file.ts#exportName")
+     * // Use `|| undefined` (defer), not `?? false` (hard short-circuit), so the
+     * // chain and the segment default still apply when there is no match.
+     * revalidate(({ actionId }) =>
+     *   actionId?.includes("Cart") || undefined
+     * )
+     *
+     * // Soft decision (suggest but allow override)
+     * revalidate(({ defaultShouldRevalidate }) =>
+     *   ({ defaultShouldRevalidate: true })
+     * )
+     * ```
+     * @param fn - Function returning either:
+     *   - `boolean` (hard decision — short-circuits the chain),
+     *   - `{ defaultShouldRevalidate: boolean }` (soft — updates the suggestion
+     *     for downstream revalidators),
+     *   - or nothing / `null` / `undefined` (defer — leaves the suggestion
+     *     unchanged and continues to the next revalidator).
+     */
+    revalidate: (fn: ShouldRevalidateFn<any, TEnv>) => RevalidateItem;
+    /**
+     * Attach a data loader to the current route/layout
+     * ```typescript
+     * loader(ProductLoader)
+     *
+     * // With loader-specific revalidation (match by file or export name)
+     * loader(CartLoader, () => [
+     *   revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
+     * ])
+     *
+     * // Consume in client components with useLoader()
+     * // (preferred — cache-safe, always fresh)
+     * function ProductDetails() {
+     *   const { data } = useLoader(ProductLoader);
+     *   return <div>{data.name}</div>;
+     * }
+     * ```
+     * @param loaderDef - Loader created with createLoader()
+     * @param use - Optional callback for loader-specific revalidation rules
+     */
+    loader: <TData>(loaderDef: LoaderDefinition<TData>, use?: () => UseItems<LoaderUseItem>) => LoaderItem;
+    /**
+     * Attach a loading component to the current route/layout
+     * ```typescript
+     * // Show loading on all requests (including SSR)
+     * loading(<Skeleton />)
+     *
+     * // Skip loading on SSR, only show on client navigation
+     * loading(<Skeleton />, { ssr: false })
+     * ```
+     * @param component - The loading UI to show during navigation
+     * @param options - Configuration options
+     * @param options.ssr - If false, skip showing loading on document requests (SSR)
+     */
+    loading: (component: ReactNode | (() => ReactNode), options?: {
+        ssr?: boolean;
+    }) => LoadingItem;
+    /**
+     * Attach an error boundary to catch errors in this segment and children
+     * ```typescript
+     * errorBoundary(<ErrorFallback />)
+     *
+     * // With dynamic error handler
+     * errorBoundary(({ error, reset }) => (
+     *   <div>
+     *     <h2>Something went wrong</h2>
+     *     <p>{error.message}</p>
+     *     <button onClick={reset}>Try again</button>
+     *   </div>
+     * ))
+     * ```
+     * @param fallback - Static JSX or handler receiving error info and reset function
+     */
+    errorBoundary: (fallback: ReactNode | ErrorBoundaryHandler) => ErrorBoundaryItem;
+    /**
+     * Attach a not-found boundary to handle notFound() calls in this segment
+     * ```typescript
+     * notFoundBoundary(<ProductNotFound />)
+     *
+     * // With dynamic handler
+     * notFoundBoundary(({ notFound }) => (
+     *   <div>
+     *     <h2>{notFound.message}</h2>
+     *     <a href="/products">Browse all products</a>
+     *   </div>
+     * ))
+     * ```
+     * @param fallback - Static JSX or handler receiving not-found info
+     */
+    notFoundBoundary: (fallback: ReactNode | NotFoundBoundaryHandler) => NotFoundBoundaryItem;
+    /**
+     * Define cache configuration for segments
+     *
+     * Creates a cache boundary that applies to all children unless overridden.
+     * Cache config inherits down the route tree like middleware wrapping.
+     *
+     * When ttl is not specified, uses store defaults (explicit store first,
+     * then app-level store). When store is not specified, uses app-level store.
+     *
+     * Note: Loaders are NOT cached by default. Use cache() inside loader()
+     * to explicitly opt-in to loader caching.
+     *
+     * ```typescript
+     * // Using app-level defaults (ttl inherited from store.defaults)
+     * cache(() => [
+     *   layout(<BlogLayout />),      // cached with default TTL
+     *   route("post/:slug"),         // cached with default TTL
+     * ])
+     *
+     * // Cache all segments with explicit 60s TTL
+     * cache({ ttl: 60 }, () => [
+     *   layout(<BlogLayout />),      // cached
+     *   route("post/:slug"),         // cached
+     * ])
+     *
+     * // With stale-while-revalidate
+     * cache({ ttl: 60, swr: 300 }, () => [
+     *   route("product/:id"),
+     * ])
+     *
+     * // Override for specific section
+     * cache({ ttl: 60 }, () => [
+     *   layout(<RootLayout />),
+     *   cache({ ttl: 300 }, () => [
+     *     route("static-page"),     // longer TTL
+     *   ]),
+     *   cache(false, () => [
+     *     route("admin"),           // not cached
+     *   ]),
+     * ])
+     *
+     * // Use different store for specific routes
+     * cache({ store: kvStore, ttl: 3600 }, () => [
+     *   route("archive/:year"),     // uses KV store
+     * ])
+     *
+     * // Opt-in loader caching
+     * route("product/:id", ProductHandler, () => [
+     *   loader(ProductLoader),               // NOT cached (default)
+     *   loader(StaticMetadata, () => [
+     *     cache({ ttl: 3600 }),              // cached for 1 hour
+     *   ]),
+     * ])
+     * ```
+     * @param optionsOrChildren - Cache options, false to disable, or children callback
+     * @param children - Optional callback returning child segments (when first arg is options)
+     */
+    cache: {
+        (): CacheItem;
+        (children: () => UseItems<AllUseItems>): CacheItem;
+        (options: PartialCacheOptions<TEnv> | false, use?: () => UseItems<AllUseItems>): CacheItem;
+    };
+    /**
+     * Opt a route (or group of routes) into transition-driven navigation.
+     *
+     * `transition()` does two independent things, and you choose how far to go:
+     * 1. startTransition (ALL React versions): the navigation commit is driven
+     *    through React's startTransition, so a same-route nav (same route,
+     *    different params, e.g. /product/1 -> /product/2) holds the previous
+     *    content while the new loader resolves instead of flashing the route's
+     *    loading() skeleton (see segment-system.tsx inTransitionScope). This is
+     *    also the precondition for any view-transition animation.
+     * 2. <ViewTransition> (experimental React only): the segment content is also
+     *    wrapped in React's <ViewTransition>, so the held swap cross-fades/morphs.
+     *    Layered on by default; pass { viewTransition: false } to keep #1 without
+     *    the router boundary (and place your own <ViewTransition> instead).
+     *
+     * A view transition cannot fire without a startTransition, so the meaningful
+     * choices are (see skills/view-transitions for the full matrix):
+     * - no transition()                         -> neither (remount + skeleton)
+     * - transition({ viewTransition: false })   -> startTransition only (hold)
+     * - transition({}) / transition({ enter… })  -> startTransition + ViewTransition
+     *
+     * Precedence: a bare transition({}) inherits createRouter({ viewTransition })
+     * (default "auto"); an explicit per-route `viewTransition` always wins. So
+     * transition({}) is startTransition + ViewTransition under the default and
+     * startTransition only when the router sets viewTransition: false.
+     *
+     * Conditional hold: pass `when: (ctx) => boolean` to gate the transition per
+     * request. It runs server-side AFTER the route handler (so it can read state
+     * the handler set via `ctx.get(...)`); returning false drops this transition
+     * for the request, so the navigation streams its loading() skeleton instead of
+     * holding. This is a post-handler predicate — distinct from intercept()'s
+     * match-time `when` config selector (`intercept(slot, route, Comp, { when })`).
+     *
+     * ```typescript
+     * // Attach to a single route
+     * path("/about", AboutPage, { name: "about" }, () => [
+     *   transition({ enter: "fade-in", exit: "fade-out" }),
+     * ])
+     *
+     * // Wrap a group of routes
+     * transition({ enter: "fade-in", exit: "fade-out" }, () => [
+     *   path("/", HomePage),
+     *   path("/about", AboutPage),
+     * ])
+     *
+     * // Hold content + drive view transitions, but place no router boundary:
+     * path("/product/:id", ProductPage, { name: "product" }, () => [
+     *   transition({ viewTransition: false }),
+     * ])
+     *
+     * // Hold only when the handler decided to (post-handler predicate):
+     * path("/product/:id", ProductPage, { name: "product" }, () => [
+     *   transition({ when: (ctx) => ctx.get(KeepScroll) === true }),
+     * ])
+     * ```
+     * @param config - ViewTransition configuration (enter, exit, update, share,
+     *   default, name), `viewTransition: "auto" | false` to toggle the router
+     *   boundary (createRouter({ viewTransition }) sets the app-wide default), and
+     *   `when: (ctx) => boolean` to gate the transition per request post-handler
+     * @param children - Optional callback returning child routes to wrap
+     */
+    transition: {
+        (): TransitionItem;
+        (children: () => UseItems<AllUseItems>): TransitionItem;
+        (config: TransitionConfig): TransitionItem;
+        (config: TransitionConfig, children: () => UseItems<AllUseItems>): TransitionItem;
+    };
+};

package/dist/types/route-definition/index.d.ts

@@ -0,0 +1,7 @@
+export type { RouteHelpers } from "./helpers-types.js";
+export type { AllUseItems, LayoutItem, RouteItem, ParallelItem, InterceptItem, MiddlewareItem, RevalidateItem, LoaderItem, ErrorBoundaryItem, NotFoundBoundaryItem, LayoutUseItem, RouteUseItem, ParallelUseItem, InterceptUseItem, CacheItem, InterceptConfig, InterceptSelectorContext, InterceptSegmentsState, InterceptWhenFn, } from "./helpers-types.js";
+export { layout, cache, middleware, revalidate, parallel, intercept, errorBoundary, notFoundBoundary, loader, loading, transition, } from "./dsl-helpers.js";
+export { map, createRouteHelpers, type RouteHandlers, } from "./helper-factories.js";
+export { resolveHandlerUse } from "./resolve-handler-use.js";
+export { redirect } from "./redirect.js";
+export { createLoader } from "../loader.rsc.js";

package/dist/types/route-definition/redirect.d.ts

@@ -0,0 +1,48 @@
+import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
+/**
+ * Create a soft redirect Response for middleware short-circuit
+ *
+ * Returns a Response that signals a client-side navigation to the target URL.
+ * Unlike Response.redirect() which causes a full page reload, this redirect
+ * is handled by the router for SPA-style navigation.
+ *
+ * Supports an optional state parameter to carry location state through the
+ * redirect. On the target page, state can be read via useLocationState()
+ * (use { flash: true } in createLocationState for read-once flash messages).
+ *
+ * @param url - The URL to redirect to
+ * @param statusOrOptions - HTTP status code (default: 302) or options object
+ *
+ * @example
+ * ```typescript
+ * // Simple redirect
+ * middleware((ctx, next) => {
+ *   if (!ctx.get('user')) {
+ *     return redirect('/login');
+ *   }
+ *   next();
+ * })
+ *
+ * // Redirect with state
+ * return redirect('/dashboard', {
+ *   state: [Flash({ text: "Item saved!" })],
+ * });
+ *
+ * // Redirect with custom status and state
+ * return redirect('/login', {
+ *   status: 303,
+ *   state: [Flash({ text: "Session expired" })],
+ * });
+ *
+ * // Off-host redirect (opt out of the same-origin guard). Without
+ * // `external: true`, a cross-origin target is blocked and replaced with the
+ * // app root, matching the client's open-redirect protection.
+ * return redirect('https://accounts.example.com/oauth', { external: true });
+ * ```
+ */
+export declare function redirect(url: string, status?: number): Response;
+export declare function redirect(url: string, options: {
+    status?: number;
+    state?: LocationStateEntry | LocationStateEntry[];
+    external?: boolean;
+}): Response;

package/dist/types/route-definition/resolve-handler-use.d.ts

@@ -0,0 +1,19 @@
+import type { AllUseItems } from "../route-types.js";
+/**
+ * Extract the .use callback from any handler shape.
+ *
+ * Checks definition brands first (objects with __brand), then plain functions.
+ * ReactNode handlers return undefined (no .use possible).
+ */
+export declare function resolveHandlerUse(handler: unknown): (() => any[]) | undefined;
+/**
+ * Validate that items from handler.use() are valid for the given mount site.
+ * Throws a descriptive error if any item is not allowed.
+ */
+export declare function validateHandlerUseItems(items: AllUseItems[], mountSite: string): void;
+/**
+ * Create a merged use callback from handler.use and explicit use.
+ * handler.use items come first (defaults), explicit items second (overrides).
+ * Returns undefined if both are absent.
+ */
+export declare function mergeHandlerUse(handlerUse: (() => any[]) | undefined, explicitUse: (() => any[]) | undefined, mountSite: string): (() => any[]) | undefined;

package/dist/types/route-definition/use-item-types.d.ts

@@ -0,0 +1 @@
+export declare const ALL_USE_ITEM_TYPES: ReadonlySet<string>;

package/dist/types/route-definition.d.ts

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

package/dist/types/route-map-builder.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Route manifest storage and retrieval.
+ *
+ * The route manifest maps route names to URL patterns. It is populated
+ * by the virtual module (which imports from .named-routes.gen.ts files)
+ * and consumed by reverse() and href() at runtime.
+ *
+ * See docs/manifests.md for the full data flow.
+ */
+declare let cachedPrecomputedEntries: Array<{
+    staticPrefix: string;
+    routes: Record<string, string>;
+}> | null;
+/**
+ * Register routes into the global route map.
+ * Routes are merged with any existing registered routes.
+ * Called by createRouter() during module evaluation, and by lazy-include
+ * expansion (src/router/lazy-includes.ts) with each expansion's route delta.
+ *
+ * Merges IN PLACE — O(|map|), not O(total routes). The previous
+ * `globalRouteMap = { ...globalRouteMap, ...map }` copy made every
+ * lazy-include first hit O(total routes) on the request path: with a 26k-route
+ * manifest the spread measured 8.9ms/call (M4, node), paid once per level of a
+ * nested async-include chain (3 calls on a 3-level chain — the 464ms edge
+ * cold-hit in issue #666).
+ *
+ * In-place mutation is safe because every getGlobalRouteMap() consumer reads
+ * it fresh per call (server/request-context.ts, rsc/loader-fetch.ts,
+ * router/intercept-resolution.ts, testing/generated-routes.ts,
+ * rsc/manifest-init.ts) — none memoizes the returned reference. If you add a
+ * consumer that caches the map object, it will now observe later
+ * registrations; snapshot it yourself if you need frozen contents.
+ */
+export declare function registerRouteMap(map: Record<string, string>): void;
+/**
+ * Get the globally registered route map
+ *
+ * Used internally by reverse to resolve route names to URLs at runtime.
+ * Returns the cached manifest if available (complete with lazy includes),
+ * otherwise returns the runtime-accumulated route map.
+ *
+ * @returns The registered route map
+ * @internal
+ */
+export declare function getGlobalRouteMap(): Record<string, string>;
+/**
+ * Set the cached manifest (for runtime cache integration)
+ *
+ * This sets the complete route manifest from a runtime cache.
+ * The cached manifest includes all routes (including lazy includes)
+ * and takes precedence over the incrementally-built globalRouteMap.
+ *
+ * @param manifest - The complete route manifest to cache
+ */
+export declare function setCachedManifest(manifest: Record<string, string>): void;
+/**
+ * Check if a cached manifest is loaded
+ *
+ * @returns true if a complete manifest is available
+ */
+export declare function hasCachedManifest(): boolean;
+/**
+ * Clear the cached manifest (for testing)
+ */
+export declare function clearCachedManifest(): void;
+/**
+ * Set pre-computed route entries from build-time data.
+ *
+ * Each entry corresponds to a leaf node in the prefix tree (no nested includes).
+ * evaluateLazyEntry() checks these before running the handler, avoiding the
+ * 5-50ms cost of handler evaluation for route matching on the first request.
+ *
+ * @param entries - Array of { staticPrefix, routes } from build-time prefix tree leaves
+ */
+export declare function setPrecomputedEntries(entries: Array<{
+    staticPrefix: string;
+    routes: Record<string, string>;
+}> | null): void;
+/**
+ * Get pre-computed route entries (if available)
+ */
+export declare function getPrecomputedEntries(): typeof cachedPrecomputedEntries;
+declare let cachedRouteTrie: import("./build/route-trie.js").TrieNode | null;
+export declare function setRouteTrie(trie: typeof cachedRouteTrie): void;
+export declare function getRouteTrie(): typeof cachedRouteTrie;
+/**
+ * Clear all cached route data (global and per-router).
+ * Called during HMR when route definitions change so the handler rebuilds
+ * the trie from the updated router.urlpatterns on the next request.
+ *
+ * The virtual module calls this before repopulating with fresh data,
+ * preventing stale entries from removed routes from accumulating.
+ */
+export declare function clearAllRouterData(): void;
+export declare function setRouterManifest(routerId: string, manifest: Record<string, string>): void;
+/** @internal */
+export declare function getRouterManifest(routerId: string): Record<string, string> | undefined;
+export declare function setRouterTrie(routerId: string, trie: import("./build/route-trie.js").TrieNode): void;
+export declare function markRouterTrieAuthoritative(routerId: string): void;
+export declare function isRouterTrieAuthoritative(routerId: string): boolean;
+export declare function getRouterTrie(routerId: string): import("./build/route-trie.js").TrieNode | undefined;
+export declare function setRouterPrecomputedEntries(routerId: string, entries: Array<{
+    staticPrefix: string;
+    routes: Record<string, string>;
+}>): void;
+export declare function getRouterPrecomputedEntries(routerId: string): Array<{
+    staticPrefix: string;
+    routes: Record<string, string>;
+}> | undefined;
+export declare function registerRouterManifestLoader(routerId: string, loader: () => Promise<any>): void;
+export declare function ensureRouterManifest(routerId: string): Promise<void>;
+export declare function setManifestReadyPromise(promise: Promise<void>): void;
+export declare function waitForManifestReady(): Promise<void> | null;
+/**
+ * Register whether a route is at root scope.
+ * Called by path() during route evaluation.
+ */
+export declare function registerRouteRootScope(routeName: string, rootScoped: boolean): void;
+/**
+ * Check if a route is at root scope.
+ * Returns undefined if the route has not been registered (e.g. in unit tests).
+ */
+export declare function isRouteRootScoped(routeName: string): boolean | undefined;
+import type { SearchSchema } from "./search-params.js";
+export declare function registerSearchSchema(routeName: string, schema: SearchSchema): void;
+export declare function getSearchSchema(routeName: string): SearchSchema | undefined;
+export {};

package/dist/types/route-name.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Route name utilities for filtering internal route names.
+ *
+ * Internal names stay active in the runtime manifest for matching and local
+ * reverse() resolution, but they must not leak into public APIs or generated
+ * route maps.
+ */
+export declare const AUTO_GENERATED_ROUTE_PREFIX = "$path_";
+export declare const INTERNAL_INCLUDE_SCOPE_PREFIX = "$prefix_";
+/**
+ * Check if a route name is internal.
+ * Internal names include:
+ * - unnamed path() routes like "$path__health" or "docs.$path__health"
+ * - hidden include scopes like "$prefix_0.index" or "blog.$prefix_1.post"
+ *
+ * User-defined names containing "$" (e.g. "docs.$admin") are valid and must
+ * be preserved.
+ */
+export declare function isAutoGeneratedRouteName(name: string): boolean;
+/**
+ * Validate that a user-provided route name does not collide with
+ * reserved internal prefixes. Checks every dot-separated segment,
+ * mirroring the same rule used by isAutoGeneratedRouteName().
+ *
+ * Throws with a clear message when a reserved prefix is detected.
+ */
+export declare function validateUserRouteName(name: string): void;