@rangojs/router 0.5.1 → 0.6.0

package/dist/types/testing/run-loader.d.ts

@@ -52,6 +52,7 @@ export type TestLoaderContext<TEnv = any> = Omit<LoaderContext<any, TEnv>, "reve
     reverse: (name: string, params?: Record<string, string>, search?: Record<string, unknown>) => string;
     get: {
         <T>(contextVar: ContextVar<T>): T | undefined;
+        <TData, TAccumulated = TData[]>(handle: Handle<TData, TAccumulated>): TAccumulated;
         <T = unknown>(key: string): T | undefined;
     };
 };
@@ -182,5 +183,13 @@ export interface RunLoaderResult<T> {
     locationState: Record<string, unknown>;
     /** The resolved rango state cookie name seeded for the run (default `rango-state_router_0`). */
     stateCookieName: string;
+    /**
+     * Handle writes the loader made via `ctx.use(SomeHandle)({...})`, in push
+     * order. A `.defer()` resolver's value is recorded when the resolver runs.
+     */
+    handlePushes: Array<{
+        handle: Handle<any, any>;
+        value: unknown;
+    }>;
 }
 export declare function runLoaderResult<T>(loader: RunnableLoader<T>, opts?: RunLoaderOptions): Promise<RunLoaderResult<T>>;

package/dist/types/types/boundaries.d.ts

@@ -63,6 +63,28 @@ export type LoaderDataResult<T = unknown> = {
     ok: false;
     error: ErrorInfo;
     fallback: ReactNode | null;
+    /**
+     * Loader threw notFound() (DataNotFoundError). `fallback` carries the
+     * SERVER-RENDERED not-found UI (nearest notFoundBoundary → router
+     * notFound option → default), so the client swaps to 404 presentation
+     * with zero extra round trips. Routed by decodeLoaderEntry via
+     * LOADER_NOT_FOUND_FALLBACK, not the error-fallback marker.
+     */
+    notFound?: true;
+    /**
+     * Loader threw redirect(...) (a 3xx Response). `to` is resolved through
+     * the soft-redirect same-origin rules BEFORE leaving the server
+     * (resolveSoftRedirectUrl), so unsafe targets never reach the wire. The
+     * client navigates (replace) when the entry decodes. `state` is the
+     * resolved `redirect(url, { state })` record (`__rsc_ls_*` keys) — it
+     * travels on the marker because a streaming loader settles after
+     * payload metadata flushed; the redirect navigation merges it at the
+     * target entry.
+     */
+    redirect?: {
+        to: string;
+        state?: Record<string, unknown>;
+    };
 };
 export declare function isLoaderDataResult(value: unknown): value is LoaderDataResult;
 export interface NotFoundInfo {

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

@@ -6,6 +6,6 @@ export { isLoaderDataResult } from "./boundaries.js";
 export type { MiddlewareFn, ScopedRouteMap, Handler, HandlerContext, InternalHandlerContext, GenericParams, RevalidateParams, ShouldRevalidateFn, ActionRef, RouteKeys, ExtractRouteParams, HandlersForRouteMap, Revalidate, Middleware, } from "./handler-context.js";
 export type { ViewTransitionClass, TransitionConfig, TransitionWhenFn, TransitionWhenContext, ResolvedSegment, SegmentMetadata, SlotState, RootLayoutProps, MatchResult, } from "./segments.js";
 export type { LazyIncludeContext, RouteEntry } from "./route-entry.js";
-export type { LoaderContext, LoaderFn, FetchableLoaderOptions, LoadOptions, LoaderDefinition, } from "./loader-types.js";
+export type { LoaderContext, LoaderFn, FetchableLoaderOptions, LoaderOptions, LoadOptions, LoaderDefinition, } from "./loader-types.js";
 export type { CacheContext, CacheOptions, PartialCacheOptions, EntryCacheConfig, } from "./cache-types.js";
 export type { ErrorPhase, OnErrorContext, OnErrorCallback, } from "./error-types.js";

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

@@ -1,5 +1,6 @@
 import type { ContextVar } from "../context-var.js";
 import type { Handle } from "../handle.js";
+import type { HandlePush } from "../defer.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 import type { ScopedReverseFunction } from "../reverse.js";
 import type { SearchSchema, ResolveSearchSchema } from "../search-params.js";
@@ -41,24 +42,50 @@ export type LoaderContext<TParams = Record<string, string | undefined>, TEnv = D
      */
     routeParams: Record<string, string>;
     search: {} extends TSearch ? {} : ResolveSearchSchema<TSearch>;
+    /**
+     * Read a context variable — or READ collected handle data after
+     * `await ctx.rendered()` (the rendered-barrier contract; handle reads
+     * moved here from ctx.use(handle), which is now the write).
+     */
     get: {
         <T>(contextVar: ContextVar<T>): T | undefined;
+        <TData, TAccumulated = TData[]>(handle: Handle<TData, TAccumulated>): TAccumulated;
     } & (<K extends keyof DefaultVars>(key: K) => DefaultVars[K]);
     /**
-     * Access another loader's data, or read handle data after rendered().
+     * Access another loader's data, or WRITE handle data (meta, breadcrumbs, …)
+     * — handler parity: `ctx.use(Meta)({ title })` pushes exactly like it does
+     * in a handler. Handle READS live on `ctx.get(handle)` (after rendered()).
      *
      * For loaders: returns a promise (loaders run in parallel).
-     * For handles: returns collected data (only after `await ctx.rendered()`).
+     * For handles: returns the push function, legal for the whole body,
+     * streaming loaders included. Delivery is async by the race model: pushes
+     * that settle before the handler barrier ride the SSR handle snapshot;
+     * later ones stream to the client and apply post-hydration (document lane)
+     * or progressively (navigation/action lanes). To guarantee a loader's
+     * handles are in the SSR'd document, register it as
+     * `loader(Def, { stream: "navigation" })` so the document render awaits it
+     * (see {@link LoaderOptions}).
+     *
+     * @example
+     * ```typescript
+     * export const ProductLoader = createLoader(async (ctx) => {
+     *   "use server";
+     *   const product = await getProduct(ctx.params.slug);
+     *   ctx.use(Meta)({ title: product.name });
+     *   ctx.use(Breadcrumbs)({ label: product.name });
+     *   return product;
+     * });
+     * ```
      */
     use: {
         <T, TLoaderParams = any>(loader: LoaderDefinition<T, TLoaderParams>): Promise<T>;
-        <TData, TAccumulated = TData[]>(handle: Handle<TData, TAccumulated>): TAccumulated;
+        <TData, TAccumulated = TData[]>(handle: Handle<TData, TAccumulated>): HandlePush<TData>;
     };
     /**
      * **Experimental.** Wait for all non-loader segments to settle.
      *
      * After the returned promise resolves, handle data is available via
-     * `ctx.use(handle)`. Supported in DSL loaders, including on streaming
+     * `ctx.get(handle)`. Supported in DSL loaders, including on streaming
      * trees that use `loading()` — the barrier waits for the streaming
      * handlers to finish pushing before it resolves. Throws if called from a
      * handler-invoked loader, or if a handler is already awaiting this loader
@@ -70,7 +97,7 @@ export type LoaderContext<TParams = Record<string, string | undefined>, TEnv = D
      * const PricesLoader = createLoader(async (ctx) => {
      *   "use server";
      *   await ctx.rendered();
-     *   const products = ctx.use(Products); // reads handle data
+     *   const products = ctx.get(Products); // reads handle data
      *   return pricing.getLive(products.map(p => p.id));
      * });
      * ```
@@ -121,6 +148,31 @@ export type LoaderContext<TParams = Record<string, string | undefined>, TEnv = D
  * ```
  */
 export type LoaderFn<T, TParams = Record<string, string | undefined>, TEnv = DefaultEnv> = (ctx: LoaderContext<TParams, TEnv>) => Promise<T> | T;
+/**
+ * Delivery mode for a DSL-registered loader: `loader(Def, { stream })`.
+ *
+ * Default (omitted): the loader streams on every render. Its data, its
+ * `ctx.use(Handle)` pushes, and any `notFound()`/`redirect()` it throws may land
+ * AFTER the document Response is constructed, so none of them are guaranteed to
+ * be in the SSR'd HTML.
+ *
+ * `"navigation"` narrows streaming to client navigations only: on a DOCUMENT
+ * request the loader is awaited before first flush. `useLoader` still suspends,
+ * but on an already-settled promise, so no fallback paints. This is the
+ * SSR-completeness opt-in — the name is about WHERE streaming still applies, not
+ * about disabling it. Choose it when the loader feeds something that must exist
+ * in the document: `<head>` meta via a handle, or a real 404 status (an awaited
+ * `notFound()` deterministically precedes Response construction, where the
+ * streamed default only wins that race opportunistically). It does NOT change
+ * PPR capture behavior: capture renders mask loaders and skip this await.
+ *
+ * Scoped per LOADER, not per segment: a baked loader alongside a deliberately
+ * dynamic sibling awaits only itself, and the sibling keeps streaming behind its
+ * `loading()`/Suspense boundary.
+ */
+export type LoaderOptions = {
+    stream?: "navigation";
+};
 /**
  * Options for fetchable loaders
  *

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

@@ -221,6 +221,13 @@ export interface MatchResult {
      * Slots are used for intercepting routes during soft navigation
      */
     slots?: Record<string, SlotState>;
+    /**
+     * Intercept TARGET route names reachable when this location is a navigation
+     * origin (chain walk of the matched entry, when-conditionals included).
+     * Shipped in payload metadata so the browser-local clientUrls matcher can
+     * decline its optimistic presentation for targets an intercept would claim.
+     */
+    interceptTargets?: string[];
     /**
      * Redirect URL for trailing slash normalization.
      * When set, the RSC handler should return a 308 redirect to this URL

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

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import type { ErrorBoundaryHandler, ExtractParams, Handler, HandlerContext, LoaderDefinition, MiddlewareFn, NotFoundBoundaryHandler, PartialCacheOptions, ShouldRevalidateFn, TransitionConfig } from "../types.js";
+import type { ErrorBoundaryHandler, ExtractParams, Handler, HandlerContext, LoaderDefinition, LoaderOptions, MiddlewareFn, NotFoundBoundaryHandler, PartialCacheOptions, ShouldRevalidateFn, TransitionConfig } from "../types.js";
 import type { AllUseItems, TypedLayoutItem, ParallelItem, InterceptItem, MiddlewareItem, RevalidateItem, LoaderItem, LoadingItem, ErrorBoundaryItem, NotFoundBoundaryItem, LayoutUseItem, RouteUseItem, ResponseRouteUseItem, ParallelUseItem, InterceptUseItem, LoaderUseItem, TypedCacheItem, TransitionItem, TypedTransitionItem, TypedRouteItem, TypedIncludeItem, UseItems } from "../route-types.js";
 import type { SearchSchema } from "../search-params.js";
 import type { PrerenderHandlerDefinition, PassthroughHandlerDefinition } from "../prerender.js";
@@ -7,6 +7,7 @@ import type { StaticHandlerDefinition, StaticHandlerRef } from "../static-handle
 import type { ResponseHandler, ResponseHandlerContext, TextResponseHandler } from "./response-types.js";
 import type { UnnamedRoute, LocalOnlyInclude, PathOptions, UrlPatterns, IncludeOptions } from "./pattern-types.js";
 import type { ExtractRoutes, ExtractResponses } from "./type-extraction.js";
+import type { ClientUrlPatterns } from "../client-urls/types.js";
 /**
  * Base path function signature for defining routes with URL patterns.
  */
@@ -45,7 +46,7 @@ type IncludeResolved<TEnv, TRoutes extends Record<string, any>, TResponses exten
     default: UrlPatterns<TEnv, TRoutes, TResponses>;
 };
 /** include() argument: an eager `urls()` value or an async provider thunk. */
-export type IncludeArg<TEnv, TRoutes extends Record<string, any>, TResponses extends Record<string, unknown>> = UrlPatterns<TEnv, TRoutes, TResponses> | (() => IncludeResolved<TEnv, TRoutes, TResponses> | Promise<IncludeResolved<TEnv, TRoutes, TResponses>>);
+export type IncludeArg<TEnv, TRoutes extends Record<string, any>, TResponses extends Record<string, unknown>> = UrlPatterns<TEnv, TRoutes, TResponses> | ClientUrlPatterns<TRoutes> | (() => IncludeResolved<TEnv, TRoutes, TResponses> | Promise<IncludeResolved<TEnv, TRoutes, TResponses>>);
 /**
  * Base include function signature.
  */
@@ -145,9 +146,14 @@ export type PathHelpers<TEnv> = {
      */
     revalidate: (fn: ShouldRevalidateFn<any, TEnv>) => RevalidateItem;
     /**
-     * Attach a data loader to the current route/layout
+     * Attach a data loader to the current route/layout.
+     *
+     * Pass `{ stream: "navigation" }` to await this loader before first flush
+     * on DOCUMENT requests (see {@link LoaderOptions}) — the opt-in for loaders
+     * whose data, handle pushes, or thrown notFound()/redirect() must be in the
+     * SSR'd HTML. Per-loader: a dynamic sibling keeps streaming.
      */
-    loader: <TData>(loaderDef: LoaderDefinition<TData>, use?: () => LoaderUseItem[]) => LoaderItem;
+    loader: <TData>(loaderDef: LoaderDefinition<TData>, optionsOrUse?: LoaderOptions | (() => LoaderUseItem[]), use?: () => LoaderUseItem[]) => LoaderItem;
     /**
      * Attach a loading component to the current route/layout
      */

package/dist/types/vite/discovery/client-urls-projection.d.ts

@@ -0,0 +1,53 @@
+import { type ClientUrlProjection } from "../../client-urls/server-projection.js";
+import type { DiscoveryState } from "./state.js";
+interface ClientUrlSsrEnvironment {
+    readonly runner?: {
+        import(id: string): Promise<Record<string, unknown>>;
+    };
+}
+interface ClientUrlProjectionServerModule {
+    clearClientUrlProjections(): void;
+    setClientUrlProjection(referenceId: string, projection: ClientUrlProjection): void;
+}
+export declare function recordClientUrlsModule(state: DiscoveryState, code: string, id: string): void;
+export declare function resolveClientUrlsSource(state: DiscoveryState, referenceId: string): string | undefined;
+/**
+ * Deterministic filesystem discovery of clientUrls modules. Transform-based
+ * recording only sees modules that some environment actually loads — a
+ * clientUrls module not yet reachable from any transformed graph at discovery
+ * time (cold ordering, a mount added before its first import is served) would
+ * never be recorded and its include would fail with empty projections. Walking
+ * the project source (the same walk static route-type generation performs)
+ * makes recording independent of module-graph timing. The transform hooks
+ * still record too — they refresh dev HMR edits between scans.
+ */
+export declare function scanForClientUrlModules(state: DiscoveryState): void;
+/**
+ * Lenient pre-entry projection refresh. Re-serializes every RECORDED clientUrls
+ * module before the discovery pass imports the entry, so routers re-created by
+ * that import materialize against the CURRENT module contents.
+ *
+ * Scar: node-preset HMR served stale client-urls routes after a route-shape
+ * edit — the clientUrls module is an HMR-accepted client boundary in the rsc
+ * graph, and the strict registry-driven pass below only runs AFTER the entry
+ * import, so `.routes(reference)` materialized the previous pass's projection.
+ *
+ * Errors are deliberately swallowed per source (a module mid-edit keeps its
+ * last-known projection); the strict discoverClientUrlProjections() pass still
+ * surfaces real failures afterwards. No-ops on cold start (nothing recorded
+ * yet) and when the SSR runner is unavailable.
+ */
+export declare function refreshRecordedClientUrlProjections(state: DiscoveryState, ssrEnv: ClientUrlSsrEnvironment | undefined, serverMod: ClientUrlProjectionServerModule): Promise<void>;
+/**
+ * Strict projection discovery over every RECORDED clientUrls module. Recorded
+ * modules — not router references — are the source of truth: include() mounts
+ * materialize lazily from the projection registry, so there is no router-level
+ * reference list to consult. Serializes every source before atomically
+ * installing the new projections (a failure preserves last-known state).
+ *
+ * A recorded source whose file no longer exists is dropped silently
+ * (recordClientUrlsModule never un-records, so deletions must self-heal here).
+ * A present-but-broken module is a hard error: it is part of the app graph.
+ */
+export declare function discoverClientUrlProjections(state: DiscoveryState, ssrEnv: ClientUrlSsrEnvironment | undefined, serverMod: ClientUrlProjectionServerModule): Promise<void>;
+export {};

package/dist/types/vite/discovery/discover-routers.d.ts

@@ -14,4 +14,4 @@ import type { DiscoveryState } from "./state.js";
  * Returns the imported `@rangojs/router/server` module so the caller
  * can access the RouterRegistry and manifest setters.
  */
-export declare function discoverRouters(state: DiscoveryState, rscEnv: any): Promise<any>;
+export declare function discoverRouters(state: DiscoveryState, rscEnv: any, ssrEnv?: any): Promise<any>;

package/dist/types/vite/discovery/state.d.ts

@@ -6,6 +6,7 @@
  * to all extracted helper functions.
  */
 import type { ScanFilter } from "../../build/generate-route-types.js";
+import type { ClientUrlProjection } from "../../client-urls/server-projection.js";
 export declare const VIRTUAL_ROUTES_MANIFEST_ID = "virtual:rsc-router/routes-manifest";
 export interface PluginOptions {
     enableBuildPrerender?: boolean;
@@ -81,6 +82,10 @@ export interface ShellPrerenderCandidate {
         captureTimeout?: number;
     };
 }
+export interface ClientUrlDiscoveryState {
+    clientUrlSourceByReferenceId: Map<string, string>;
+    clientUrlProjectionMap: Map<string, ClientUrlProjection>;
+}
 export interface DiscoveryState {
     resolvedEntryPath: string | undefined;
     projectRoot: string;
@@ -107,6 +112,8 @@ export interface DiscoveryState {
     perRouterTrieMap: Map<string, any>;
     perRouterPrecomputedMap: Map<string, PrecomputedEntry[]>;
     perRouterManifestDataMap: Map<string, Record<string, string>>;
+    clientUrlSourceByReferenceId?: Map<string, string>;
+    clientUrlProjectionMap?: Map<string, ClientUrlProjection>;
     prerenderManifestEntries: Record<string, string> | null;
     staticManifestEntries: Record<string, string> | null;
     /**
@@ -160,4 +167,4 @@ export interface DiscoveryState {
         at: number;
     } | null;
 }
-export declare function createDiscoveryState(entryPath: string | undefined, opts: PluginOptions | undefined): DiscoveryState;
+export declare function createDiscoveryState(entryPath: string | undefined, opts: PluginOptions | undefined): DiscoveryState & ClientUrlDiscoveryState;

package/dist/types/vite/encryption-key.d.ts

@@ -0,0 +1,2 @@
+export declare function buildEncryptionKey(): string;
+export declare function defineEncryptionKeyExpr(): string;

package/dist/types/vite/plugins/expose-internal-ids.d.ts

@@ -1,6 +1,16 @@
 import type { Plugin } from "vite";
 export { exposeRouterId } from "./expose-ids/router-transform.js";
 export type { ExposeInternalIdsApi } from "./expose-ids/types.js";
+/**
+ * Stub export-only loader modules before plugin-rsc reduces scan modules to
+ * imports. The regular post transform remains authoritative outside scan builds.
+ *
+ * Handles and location-state definitions are intentionally excluded: handle
+ * collect functions run in the browser, and location-state definitions are
+ * callable browser objects. Their dependencies must remain visible to non-RSC
+ * validation rather than being hidden behind an opaque scan stub.
+ */
+export declare function createLoaderScanStubPlugin(): Plugin;
 export declare function exposeInternalIds(options?: {
     forceBuild?: boolean;
 }): Plugin;

package/dist/types/vite/plugins/server-ref-hashing.d.ts

@@ -0,0 +1,24 @@
+import type { Plugin } from "vite";
+/**
+ * Replace dev-style server-reference ids with their production hashes. The temp
+ * server renders Static/Prerender in a dev/serve Vite server, so plugin-rsc mints
+ * a dev-style id (e.g. "/src/urls/prerender.tsx"); rewriting only the id (group 2)
+ * leaves the hoisted function and its trailing encrypted .bind(...) untouched.
+ * Exported for testing; used by hashServerRefs. Returns null if nothing changed.
+ */
+export declare function transformServerRefs(code: string, projectRoot: string): string | null;
+/**
+ * Server-side analog of hashClientRefs. Runs in the build-discovery temp server
+ * (a dev/serve Vite server, where plugin-rsc mints dev-style ids), rewriting
+ * registerServerReference ids to production hashes AFTER plugin-rsc's
+ * rsc:use-server transform (enforce:"post"), so the Flight serializer bakes the
+ * production hash into the stored prerender/static payloads.
+ *
+ * Without this, a server-created action embedded in a prerendered/static Flight
+ * is stored with a dev-style id that the production hash-keyed server-references
+ * manifest cannot resolve -> "server reference not found" on a build-time-cache
+ * hit. Mirrors hashClientRefs, which already does exactly this for the client
+ * half of the same payload (which is why client refs in stored Flight are
+ * already production hashes while server refs were not).
+ */
+export declare function hashServerRefs(projectRoot: string): Plugin;

package/dist/types/vite/plugins/server-reference-pattern.d.ts

@@ -0,0 +1 @@
+export declare function registerServerReferenceRegex(): RegExp;

package/dist/types/vite/utils/shared-utils.d.ts

@@ -52,4 +52,16 @@ export declare function createVirtualEntriesPlugin(entries: {
  * asset collisions from @vitejs/plugin-rsc copying RSC-env assets to the client bundle.
  */
 export declare function onwarn(warning: Vite.Rollup.RollupLog, defaultHandler: (warning: Vite.Rollup.RollupLog) => void): void;
+/**
+ * All of `browser/prefetch/` belongs to the eager "router" chunk — including
+ * the modules reachable only via loader.ts's dynamic import. #766 split those
+ * into a separate lazy chunk to trim the eager runtime (~2.3 KB gzip), but
+ * production's `defaultPrefetch: "viewport"` loads them on almost every page,
+ * so the split became a document -> router -> runtime request waterfall
+ * (measured 502 ms critical-path latency in a deployed worker). Same-chunk
+ * placement resolves the dynamic import without a network fetch
+ * (`Promise.resolve().then(...)` in the emitted chunk), and the merged chunk
+ * gzips smaller than the two chunks did apart. Do not re-split without new
+ * information (AGENTS.md, Bundle hygiene, rejected optimizations).
+ */
 export declare function getManualChunks(id: string): string | undefined;