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

package/src/client-urls/types.ts

@@ -0,0 +1,178 @@
+import type { ComponentType, ReactNode } from "react";
+import type { LoaderDefinition, TransitionConfig } from "../types.js";
+import type { TrieMatchResult } from "../router/trie-matching.js";
+import type { PathOptions } from "../urls/pattern-types.js";
+import type { SearchSchema } from "../search-params.js";
+import type { TypedLayoutItem, TypedRouteItem } from "../route-types.js";
+import type { ExtractRoutes } from "../urls/type-extraction.js";
+import type { UnnamedRoute } from "../urls/pattern-types.js";
+
+declare const CLIENT_URL_ITEM_BRAND: unique symbol;
+declare const CLIENT_URL_PATTERNS_BRAND: unique symbol;
+
+/** Opaque value returned by a clientUrls() helper. */
+export interface ClientUrlItem {
+  readonly [CLIENT_URL_ITEM_BRAND]: void;
+}
+
+export type ClientUrlItemInput = ClientUrlItem | readonly ClientUrlItemInput[];
+
+export type ClientUrlItems = readonly ClientUrlItemInput[];
+
+export type ClientUrlUse = () => ClientUrlItems;
+
+export type ClientPathOptions<
+  TName extends string = string,
+  TSearch extends SearchSchema = SearchSchema,
+> = Pick<PathOptions<TName, TSearch>, "name" | "search" | "trailingSlash">;
+
+export type ClientPathFn = <
+  const TPattern extends string,
+  const TName extends string = UnnamedRoute,
+  const TSearch extends SearchSchema = {},
+>(
+  pattern: TPattern,
+  component: ComponentType,
+  optionsOrUse?: ClientPathOptions<TName, TSearch> | ClientUrlUse,
+  use?: ClientUrlUse,
+) => ClientUrlItem & TypedRouteItem<TName, TPattern, unknown, TSearch>;
+
+export type ClientLayoutFn = <const TItems extends ClientUrlItems>(
+  component: ComponentType,
+  children: () => TItems,
+) => ClientUrlItem & TypedLayoutItem<ExtractRoutes<TItems>>;
+
+/**
+ * Arguments a clientUrls() revalidate() predicate receives. A client-computable
+ * subset of the server ShouldRevalidateFn args — the predicate RUNS IN THE
+ * BROWSER (it is declared in a "use client" module and never crosses the
+ * projection boundary); only its decision is sent to the server. There is no
+ * `context` — no server handler context exists where this executes.
+ */
+export interface ClientRevalidateArgs {
+  /** Full URL of the page being navigated away from (current location). */
+  readonly currentUrl: URL;
+  /** Full URL of the navigation target (equals currentUrl for actions). */
+  readonly nextUrl: URL;
+  /** Route params of the held client route (definition-local match). */
+  readonly currentParams: Record<string, string>;
+  /** Route params for the navigation target (definition-local match). */
+  readonly nextParams: Record<string, string>;
+  /**
+   * The locked default decision for this loader, computed client-side with
+   * the same rules the server would apply: `true` on actions and when
+   * params/search changed, `false` otherwise. Return it for default behavior
+   * plus your own conditions.
+   */
+  readonly defaultShouldRevalidate: boolean;
+  /** True when this is a stale history-entry background revalidation. */
+  readonly stale: boolean;
+  /** True when revalidation is triggered by a server action. */
+  readonly isAction: boolean;
+  /** The triggering server action's id, when isAction. */
+  readonly actionId?: string;
+}
+
+export type ClientRevalidateFn = (args: ClientRevalidateArgs) => boolean;
+
+export interface ClientUrlLoaderRecord {
+  readonly loader: LoaderDefinition<any, any>;
+  /** Client-run per-loader revalidation predicates; empty = locked defaults. */
+  readonly revalidate: readonly ClientRevalidateFn[];
+}
+
+/**
+ * The data-only subset of TransitionConfig a clientUrls() route may declare:
+ * ViewTransition classes/name plus the boundary opt-out. The `when` gate is a
+ * server-executed predicate and stays in the server tree — it cannot cross the
+ * "use client" projection boundary.
+ */
+export type ClientTransitionConfig = Pick<
+  TransitionConfig,
+  "enter" | "exit" | "update" | "share" | "default" | "name" | "viewTransition"
+>;
+
+export interface ClientUrlRouteRecord {
+  readonly id: string;
+  readonly pattern: string;
+  readonly name: string | undefined;
+  readonly options: Readonly<ClientPathOptions> | undefined;
+  readonly component: ComponentType;
+  readonly layouts: readonly ComponentType[];
+  readonly loaders: readonly ClientUrlLoaderRecord[];
+  readonly loading: ReactNode | undefined;
+  readonly transition: Readonly<ClientTransitionConfig> | undefined;
+}
+
+/**
+ * A restricted intercept declared inside clientUrls(). Compared to the server
+ * intercept() there is no `when` selector, no middleware, and the target must
+ * be a dot-local NAMED route in the same definition — every field is
+ * JSON-projectable, which is what makes the declaration legal in a
+ * "use client" module. `targetName` is stored bare (no leading dot).
+ */
+export interface ClientUrlInterceptRecord {
+  readonly slotName: `@${string}`;
+  readonly targetName: string;
+  readonly component: ComponentType;
+  readonly loaders: readonly ClientUrlLoaderRecord[];
+  readonly loading: ReactNode | undefined;
+}
+
+export interface ClientUrlHelpers {
+  readonly path: ClientPathFn;
+  readonly layout: ClientLayoutFn;
+  /**
+   * Attach a projected loader. The optional use callback may contain
+   * revalidate() only — a CLIENT-RUN per-loader predicate; its decision (not
+   * the function) is sent with the revalidation request.
+   */
+  readonly loader: <TData>(
+    definition: LoaderDefinition<TData>,
+    use?: ClientUrlUse,
+  ) => ClientUrlItem;
+  readonly loading: (component: ReactNode) => ClientUrlItem;
+  /**
+   * Per-loader revalidation predicate, valid inside a loader() use callback
+   * only. Runs IN THE BROWSER with client-computable args; return true to
+   * re-run the loader, false to keep held data. Absent predicates (and
+   * requests that carry no decisions: no-JS, PE, prefetch, document loads)
+   * follow the locked server defaults.
+   */
+  readonly revalidate: (fn: ClientRevalidateFn) => ClientUrlItem;
+  /**
+   * Declare an intercept for a named route in THIS definition. The target is
+   * dot-local (`.detail`); scoping is module-local — only navigations whose
+   * origin is inside this clientUrls() group render the intercept. `use` may
+   * contain loader() and loading() only.
+   */
+  readonly intercept: (
+    slotName: `@${string}`,
+    targetName: `.${string}`,
+    component: ComponentType,
+    use?: ClientUrlUse,
+  ) => ClientUrlItem;
+  /**
+   * Opt THIS route into transition-driven navigation: the canonical commit
+   * holds previous content instead of re-streaming the loading() fallback,
+   * and on experimental React the config's ViewTransition classes apply.
+   * Data-only — no `when` gate (server-executed; declare it in the server
+   * tree). Valid inside a path() use callback only.
+   */
+  readonly transition: (config: ClientTransitionConfig) => ClientUrlItem;
+}
+
+export type ClientUrlBuilder<TItems extends ClientUrlItems = ClientUrlItems> = (
+  helpers: ClientUrlHelpers,
+) => TItems;
+
+export interface ClientUrlPatterns<
+  TRoutes extends Record<string, any> = Record<string, any>,
+> {
+  readonly __brand: "client-urls";
+  readonly routes: readonly ClientUrlRouteRecord[];
+  readonly intercepts: readonly ClientUrlInterceptRecord[];
+  readonly [CLIENT_URL_PATTERNS_BRAND]: void;
+  readonly _routes?: TRoutes;
+  match(pathname: string): TrieMatchResult | null;
+}

package/src/client.rsc.tsx

@@ -14,60 +14,88 @@
 export {
   Outlet,
   ParallelOutlet,
-  OutletProvider,
   useOutlet,
+  type OutletState,
   useLoader,
   ErrorBoundary,
   type ErrorBoundaryProps,
 } from "./client.js";
 
-// Re-export the server's createLoader for RSC context
-// This version includes the actual loader function
+export {
+  useFetchLoader,
+  useRefreshLoaders,
+  type LoadFunction,
+  type UseLoaderResult,
+  type UseFetchLoaderResult,
+  type UseLoaderOptions,
+} from "./use-loader.js";
+
 export { createLoader } from "./route-definition.js";
 
-// Re-export Link component (can be used in server components)
+export { clientUrls } from "./client-urls/client-urls.js";
+export type {
+  ClientUrlPatterns,
+  ClientUrlRouteRecord,
+} from "./client-urls/client-urls.js";
+
+// "use client" hooks the default ./client entry exports. They are client
+// references in the RSC graph, identical in kind to useHref/useReverse/
+// useHandle already forwarded below; forward them so the RSC client entry's
+// hook surface matches the default entry. useNavigation/useAction stay omitted
+// (they drive client-only navigation/action state — see note below).
+export { useRouter } from "./browser/react/use-router.js";
+export { usePathname } from "./browser/react/use-pathname.js";
+export { useSearchParams } from "./browser/react/use-search-params.js";
+export { useParams } from "./browser/react/use-params.js";
+// CSP nonce for userland head-script components (analytics/GTM/inline init);
+// forwarded so the RSC client entry's hook surface matches the default entry.
+export { useNonce } from "./browser/react/nonce-context.js";
+export { useMount } from "./browser/react/use-mount.js";
+export {
+  useSegments,
+  type SegmentsState,
+} from "./browser/react/use-segments.js";
+export {
+  useLinkStatus,
+  type LinkStatus,
+} from "./browser/react/use-link-status.js";
+export { useScrollRestoration } from "./browser/react/ScrollRestoration.js";
+
 export {
   Link,
   type LinkProps,
   type PrefetchStrategy,
 } from "./browser/react/Link.js";
 
-// Re-export ScrollRestoration (can be used in server components)
 export {
   ScrollRestoration,
   type ScrollRestorationProps,
 } from "./browser/react/ScrollRestoration.js";
 
-// Re-export NavigationProvider (needed for setup)
 export {
   NavigationProvider,
   type NavigationProviderProps,
 } from "./browser/react/NavigationProvider.js";
 
-// Re-export href function (can be used in server components)
 export { href } from "./href-client.js";
 
-// Mount context re-exports (useMount is client-only, but MountContext can be referenced)
 export { MountContext } from "./browser/react/mount-context.js";
 
-// Note: useNavigation, useAction, useClientCache are NOT re-exported here
-// because they use client-side state and should only be used in client components
+// useNavigation and useAction are NOT re-exported here because they use client-side state
 
-// Handle API - for accumulating data across route segments
-// Works in both RSC and client contexts
 export { createHandle, isHandle, type Handle } from "./handle.js";
 
-// Built-in handles
-// Meta handle works in RSC context
 export { Meta } from "./handles/meta.js";
-// MetaTags is a "use client" component that can be imported from RSC
 export { MetaTags } from "./handles/MetaTags.js";
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
-// Breadcrumbs handle works in RSC context
+export {
+  Script,
+  type ScriptConfig,
+  type ScriptAttributes,
+} from "./handles/script.js";
+export { Scripts } from "./handles/Scripts.js";
 export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
 
-// Location state - createLocationState works in RSC (just creates definition)
-// useLocationState is NOT exported here as it uses client hooks
 export {
   createLocationState,
   type LocationStateDefinition,
@@ -75,11 +103,10 @@ export {
   type LocationStateOptions,
 } from "./browser/react/location-state-shared.js";
 
-// Re-export useHref - it's a "use client" hook
 export { useHref } from "./browser/react/use-href.js";
 
-// Re-export useHandle - it's a "use client" hook
+export { useReverse } from "./browser/react/use-reverse.js";
+
 export { useHandle } from "./browser/react/use-handle.js";
 
-// Re-export useLocationState - it's a "use client" hook
 export { useLocationState } from "./browser/react/location-state.js";

package/src/client.tsx

@@ -111,6 +111,11 @@ function useSlotSegment(
  * the parallel segment with that slot name instead of the default content.
  * This is used for parallel routes and intercepting routes.
  *
+ * For a named slot, `<Outlet name="@x" />` is equivalent to
+ * `<ParallelOutlet name="@x" />` — both run the same resolution + wrapping
+ * pipeline. Convention: use bare `<Outlet />` for default content and
+ * `<ParallelOutlet name="@x" />` for named slots.
+ *
  * @param name - Optional slot name for parallel/intercept content (must start with @)
  *
  * @example
@@ -136,17 +141,41 @@ function useSlotSegment(
  * }
  * ```
  */
-export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
+export function Outlet({
+  name,
+  fallback,
+}: { name?: `@${string}`; fallback?: ReactNode } = {}): ReactNode {
   const context = useContext(OutletContext);
   const namedSegment = useSlotSegment(context, name);
 
   if (name) {
-    return renderSlotContent(namedSegment);
+    const slot = renderSlotContent(namedSegment);
+    // EXPERIMENT (Outlet fallback): layout-declared pending UI for a named
+    // slot — an outer Suspense catching whatever the slot's content leaves
+    // unhandled.
+    return fallback !== undefined ? (
+      <Suspense fallback={fallback}>{slot}</Suspense>
+    ) : (
+      slot
+    );
   }
 
   // Default: render child content
   const content = context?.content ?? null;
 
+  // EXPERIMENT (Outlet fallback): the layout owns the outlet position, so it
+  // may declare the placeholder for pending child content right where it
+  // renders — a plain Suspense boundary, no DSL wiring, no segment-resolution
+  // threading. With read-site useLoader suspension this covers loading()'s
+  // roles by construction: document SSR streams the fallback then the
+  // content; PPR postpones unresolved readers here (the outlet becomes the
+  // hole); same-route re-renders are held before commit so the fallback does
+  // NOT flash; cross-route navs show it as destination feedback. An explicit
+  // prop wins over the child segment's loading().
+  if (fallback !== undefined) {
+    return <Suspense fallback={fallback}>{content}</Suspense>;
+  }
+
   // If this segment defines a loading component, wrap outlet content with Suspense
   // The loading component becomes the Suspense fallback, shown during streaming/navigation
   if (context?.loading) {
@@ -163,6 +192,9 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
  * is wrapped in Suspense with the loading component as fallback.
  * This enables streaming and navigation loading states for parallels.
  *
+ * Equivalent to `<Outlet name="@x" />` for a named slot; ParallelOutlet
+ * requires `name` and is named-slot-only, which reads clearer at the call site.
+ *
  * @param name - The slot name (must start with @, e.g., "@modal", "@sidebar")
  *
  * @example
@@ -186,13 +218,12 @@ export function ParallelOutlet({ name }: { name: `@${string}` }): ReactNode {
 }
 
 // OutletProvider is defined in outlet-provider.tsx to break a circular
-// dependency between client.tsx and route-content-wrapper.tsx.
-// Imported at the top of this file for local use in Outlet/ParallelOutlet,
-// and re-exported here for backwards compatibility.
-export { OutletProvider };
+// dependency between client.tsx and route-content-wrapper.tsx. It is imported
+// at the top of this file for local use in Outlet/ParallelOutlet only; it is an
+// internal component and is intentionally not part of the public ./client API.
 
 /**
- * Hook to access outlet content programmatically
+ * Hook to access outlet content and descendant pending state programmatically.
  *
  * Alternative to using <Outlet /> component. Useful when you need
  * direct access to the outlet content in your logic.
@@ -201,25 +232,39 @@ export { OutletProvider };
  * ```tsx
  * function BlogLayout() {
  *   const outlet = useOutlet();
- *   return <div><h1>Blog</h1>{outlet}</div>;
+ *   return <div aria-busy={outlet.pending}><h1>Blog</h1>{outlet.content}</div>;
  * }
  * ```
  */
-export function useOutlet(): ReactNode {
+export interface OutletState {
+  readonly content: ReactNode;
+  readonly pending: boolean;
+}
+
+export function useOutlet(): OutletState {
   const context = useContext(OutletContext);
-  return context?.content ?? null;
+  return {
+    content: context?.content ?? null,
+    pending: context?.pending ?? false,
+  };
 }
 
-// Loader hooks - re-exported from dedicated file
 export {
   useLoader,
   useFetchLoader,
+  useRefreshLoaders,
   type LoadFunction,
   type UseLoaderResult,
   type UseFetchLoaderResult,
   type UseLoaderOptions,
 } from "./use-loader.js";
 
+export { clientUrls } from "./client-urls/client-urls.js";
+export type {
+  ClientUrlPatterns,
+  ClientUrlRouteRecord,
+} from "./client-urls/client-urls.js";
+
 /**
  * Props for the ErrorBoundary component
  */
@@ -328,79 +373,72 @@ export class ErrorBoundary extends Component<
   }
 }
 
-// ============================================================================
-// Re-exports from browser/react for convenience
-// These are the most commonly used client-side navigation utilities
-// ============================================================================
-
-// Navigation hooks
 export { useNavigation } from "./browser/react/use-navigation.js";
 export { useRouter } from "./browser/react/use-router.js";
 export { usePathname } from "./browser/react/use-pathname.js";
 export { useSearchParams } from "./browser/react/use-search-params.js";
 export { useParams } from "./browser/react/use-params.js";
+// CSP nonce for the active request, for userland components that inject their
+// own <script>/<style> into the document head (analytics, GTM, inline init).
+// Returns the nonce during SSR and undefined in the browser; render the tag
+// server-side so the nonce lands in the SSR HTML and hydration stays clean.
+export { useNonce } from "./browser/react/nonce-context.js";
 export type {
   RouterInstance,
   RouterNavigateOptions,
   ReadonlyURLSearchParams,
+  ActionState,
+  ActionLifecycleState,
 } from "./browser/types.js";
 
-// Action state tracking hook
 export {
   useAction,
   type ServerActionFunction,
 } from "./browser/react/use-action.js";
 
-// Segments state hook
 export {
   useSegments,
   type SegmentsState,
 } from "./browser/react/use-segments.js";
 
-// Client cache controls hook
-export {
-  useClientCache,
-  type ClientCacheControls,
-} from "./browser/react/use-client-cache.js";
-
-// Provider
 export {
   NavigationProvider,
   type NavigationProviderProps,
 } from "./browser/react/NavigationProvider.js";
 
-// Link component
 export {
   Link,
   type LinkProps,
   type PrefetchStrategy,
   type StateOrGetter,
+  type LinkState,
 } from "./browser/react/Link.js";
 
-// Link status hook
 export {
   useLinkStatus,
   type LinkStatus,
 } from "./browser/react/use-link-status.js";
 
-// Scroll restoration
 export {
   ScrollRestoration,
   useScrollRestoration,
   type ScrollRestorationProps,
 } from "./browser/react/ScrollRestoration.js";
 
-// Handle data hook (client-side only — createHandle/isHandle are server APIs from the root export)
 export { type Handle } from "./handle.js";
 export { useHandle } from "./browser/react/use-handle.js";
 
-// Built-in handles
 export { Meta } from "./handles/meta.js";
 export { MetaTags } from "./handles/MetaTags.js";
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
+export {
+  Script,
+  type ScriptConfig,
+  type ScriptAttributes,
+} from "./handles/script.js";
+export { Scripts } from "./handles/Scripts.js";
 export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
 
-// Location state - type-safe navigation state
 export {
   createLocationState,
   useLocationState,
@@ -409,47 +447,19 @@ export {
   type LocationStateOptions,
 } from "./browser/react/location-state.js";
 
-// Type-safe href for client-side path validation
-export {
-  href,
-  type ValidPaths,
-  type PatternToPath,
-  type PathResponse,
-} from "./href-client.js";
-
-// Response envelope types for consuming JSON response routes
-export type { ResponseEnvelope, ResponseError } from "./urls.js";
+// Ambient Rango.Path / Rango.PathResponse types (declared in href-client.ts)
+export { href, type PatternToPath } from "./href-client.js";
 
-/**
- * Type guard for checking if a response envelope contains an error.
- *
- * @example
- * ```typescript
- * const result: ResponseEnvelope<Product> = await fetch(url).then(r => r.json());
- * if (isResponseError(result)) {
- *   console.log(result.error.message, result.error.code);
- *   return;
- * }
- * result.data // fully typed as Product
- * ```
- */
-export function isResponseError<T>(
-  result: import("./urls.js").ResponseEnvelope<T>,
-): result is import("./urls.js").ResponseEnvelope<T> & {
-  error: import("./urls.js").ResponseError;
-} {
-  return result.error !== undefined;
-}
+// RFC 9457 error type for JSON response routes
+export type { ProblemDetails } from "./urls.js";
 
-// Mount context for include() scoped components
 export { useMount } from "./browser/react/use-mount.js";
 export { MountContext } from "./browser/react/mount-context.js";
 
-// Mount-aware href hook - auto-prefixes paths with include() mount
 export { useHref } from "./browser/react/use-href.js";
 
-// Type-safe scoped reverse function for scopedReverse<typeof patterns>()
-export type { ScopedReverseFunction } from "./reverse.js";
+export { useReverse } from "./browser/react/use-reverse.js";
+
+export type { ScopedReverseFunction, LocalReverseFunction } from "./reverse.js";
 
-// Loader definition type - for typing loader props in client components
 export type { LoaderDefinition } from "./types.js";

package/src/cloudflare/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Cloudflare preset integration surface for @rangojs/router.
+ *
+ * Imported via `@rangojs/router/cloudflare`. Cloudflare-only helpers live here
+ * so Node/other-platform consumers never pull them in.
+ */
+
+export {
+  createCloudflareTracing,
+  type CloudflareTracingOptions,
+} from "./tracing.js";