@rangojs/router 0.0.0-experimental.eb0645d3 → 0.0.0-experimental.f1468e3c

package/src/cache/types.ts

@@ -12,10 +12,6 @@
 import type { ResolvedSegment } from "../types.js";
 import type { RequestContext } from "../server/request-context.js";
 
-// ============================================================================
-// Segment Cache Store (low-level storage interface)
-// ============================================================================
-
 /**
  * Result from cache get() including data and revalidation status
  */
@@ -116,12 +112,6 @@ export interface SegmentCacheStore<TEnv = unknown> {
    */
   clear?(): Promise<void>;
 
-  // ============================================================================
-  // Document Cache Methods (optional)
-  // ============================================================================
-  // These methods are for caching full HTTP responses (document-level caching).
-  // Stores that support response caching should implement these methods.
-
   /**
    * Get a cached Response by key.
    * Returns the response and whether it should be revalidated (SWR).
@@ -136,20 +126,16 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * @param response - Response to cache (will be cloned)
    * @param ttl - Time-to-live in seconds
    * @param swr - Optional stale-while-revalidate window in seconds
+   * @param tags - Optional cache tags for invalidation
    */
   putResponse?(
     key: string,
     response: Response,
     ttl: number,
     swr?: number,
+    tags?: string[],
   ): Promise<void>;
 
-  // ============================================================================
-  // Function Cache Methods (optional, for "use cache" directive)
-  // ============================================================================
-  // These methods cache individual function/component return values.
-  // Stores that support "use cache" should implement these methods.
-
   /**
    * Get a cached function result by key.
    * Returns the serialized value, optional handle data, and staleness flag.
@@ -167,6 +153,16 @@ export interface SegmentCacheStore<TEnv = unknown> {
     value: string,
     options?: CacheItemOptions,
   ): Promise<void>;
+
+  /**
+   * Invalidate every cache entry (segment, response, item) tagged with any of
+   * `tags`. Store-level primitive that the public updateTag()/revalidateTag()
+   * APIs delegate to. Receives ALL of one invalidation call's tags at once so
+   * stores can batch their work (e.g. a single CDN purge request rather than
+   * one per tag). Stores that do not support tags simply omit this method.
+   * @param tags - The cache tags to invalidate
+   */
+  invalidateTags?(tags: string[]): Promise<void>;
 }
 
 /**
@@ -175,18 +171,27 @@ export interface SegmentCacheStore<TEnv = unknown> {
 export interface CacheItemResult {
   /** RSC-serialized return value */
   value: string;
-  /** Handle data captured during execution (breadcrumbs, metadata, etc.) */
-  handles?: Record<string, SegmentHandleData>;
+  /** RSC-encoded handle data captured during execution (breadcrumbs, metadata,
+   *  etc.). Encoded via the Flight codec so Promise/ReactNode handle values
+   *  survive JSON-serializing stores — see handle-snapshot.ts encodeHandles. */
+  handles?: string;
   /** Whether the entry is stale and should be revalidated */
   shouldRevalidate: boolean;
+  /**
+   * The entry's cache tags (including runtime cacheTag() tags), surfaced on read
+   * so a "use cache" HIT can still contribute its tags to the request-scoped tag
+   * set used by document-level caching. On a hit the cached function is not
+   * re-run, so its runtime tags are only available here, not from re-execution.
+   */
+  tags?: string[];
 }
 
 /**
  * Options for setItem() for function-level caching ("use cache").
  */
 export interface CacheItemOptions {
-  /** Handle data to store alongside the value */
-  handles?: Record<string, SegmentHandleData>;
+  /** RSC-encoded handle data to store alongside the value (see encodeHandles). */
+  handles?: string;
   /** Time-to-live in seconds */
   ttl?: number;
   /** Stale-while-revalidate window in seconds */
@@ -227,16 +232,18 @@ export interface SerializedSegmentData {
 export interface CachedEntryData {
   /** Serialized segments for this entry */
   segments: SerializedSegmentData[];
-  /** Handle data keyed by segment ID */
-  handles: Record<string, SegmentHandleData>;
+  /** RSC-encoded handle data keyed by segment ID. Encoded via the Flight codec
+   *  (see handle-snapshot.ts encodeHandles) so Promise/ReactNode handle values
+   *  round-trip through JSON-serializing stores instead of being flattened. */
+  handles: string;
   /** Expiration timestamp (ms since epoch) */
   expiresAt: number;
+  /** Cache tags for invalidation */
+  tags?: string[];
+  /** Timestamp (ms since epoch) when tags were attached, for distributed invalidation */
+  taggedAt?: number;
 }
 
-// ============================================================================
-// Cache Configuration
-// ============================================================================
-
 /**
  * Default cache options applied to all cache() boundaries.
  * Individual cache() calls can override any of these values.
@@ -252,91 +259,21 @@ export interface CacheDefaults {
   /**
    * Default time-to-live in seconds.
    * After TTL expires, cached entry is considered stale.
+   * Must be a finite, non-negative number; an invalid value (NaN/Infinity/
+   * negative) falls back to the default at read time.
    */
   ttl?: number;
   /**
    * Default stale-while-revalidate window in seconds.
    * During SWR window, stale content is served while revalidating in background.
+   * Must be a finite, non-negative number; an invalid value (NaN/Infinity/
+   * negative) falls back to the default at read time.
    */
   swr?: number;
 }
 
-/**
- * Cache configuration for RSC handler
- */
-export interface CacheConfig {
-  /** Cache store implementation (includes defaults) */
-  store: SegmentCacheStore;
-  /** Enable/disable caching (default: true) */
-  enabled?: boolean;
-}
-
-/**
- * Cache configuration - can be static or a function receiving env
- */
-export type CacheConfigOrFactory<TEnv> =
-  | CacheConfig
-  | ((env: TEnv) => CacheConfig);
-
-// ============================================================================
-// Segment Cache Provider (request-level interface)
-// ============================================================================
-
 /**
  * Handle data for a single segment
  * Structure: { handleName: [values...] }
  */
 export type SegmentHandleData = Record<string, unknown[]>;
-
-/**
- * Result from cache get() including segments and their handle data
- * Each entry can produce multiple segments (main + parallels)
- */
-export interface CachedEntryResult {
-  /** All segments for this entry (main segment + parallels) */
-  segments: ResolvedSegment[];
-  /** Handle data keyed by segment ID */
-  handles: Record<string, SegmentHandleData>;
-}
-
-/**
- * Segment cache provider interface
- *
- * Used by router to check/store segment cache during matching.
- * Accessed via request context - if not present, caching is disabled.
- *
- * @internal Not currently implemented - CacheScope is used directly.
- * Reserved for future extensibility.
- */
-export interface SegmentCacheProvider {
-  /** Whether caching is enabled for this request */
-  readonly enabled: boolean;
-
-  /**
-   * Get cached segments and restore handles/loaders.
-   *
-   * Combines cache get with handle replay and loader data restoration.
-   * Returns tuple of [segments, segmentIds] if cache hit, null if miss or disabled.
-   *
-   * @param cacheKey - Cache key to look up
-   * @param params - Route params for cache key generation
-   * @param loaderPromises - Map to restore loader data into
-   * @returns Tuple of [segments, segmentIds] or null if miss
-   */
-  restore(
-    cacheKey: string,
-    params: Record<string, string>,
-    loaderPromises: Map<string, Promise<any>>,
-  ): Promise<[ResolvedSegment[], string[]] | null>;
-
-  /**
-   * Cache entry with automatic handle collection (non-blocking).
-   *
-   * Schedules caching via waitUntil - handles are collected after they settle.
-   * Validates segments have actual components before caching.
-   *
-   * @param cacheKey - The cache key to store under
-   * @param segments - All resolved segments for this entry
-   */
-  cacheEntry(cacheKey: string, segments: ResolvedSegment[]): void;
-}

package/src/client.rsc.tsx

@@ -14,60 +14,81 @@
 export {
   Outlet,
   ParallelOutlet,
-  OutletProvider,
   useOutlet,
   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)
+// "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 +96,13 @@ 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";
+// Type a deferred-aware consumer narrows: an accumulated entry may be a Promise
+// (a `ctx.use(Handle).defer()` slot) until it resolves.
+export type { DeferredHandleEntry } from "./defer.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
@@ -163,6 +168,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,10 +194,9 @@ 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
@@ -210,10 +217,10 @@ export function useOutlet(): ReactNode {
   return context?.content ?? null;
 }
 
-// Loader hooks - re-exported from dedicated file
 export {
   useLoader,
   useFetchLoader,
+  useRefreshLoaders,
   type LoadFunction,
   type UseLoaderResult,
   type UseFetchLoaderResult,
@@ -328,79 +335,75 @@ 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";
+// Type a deferred-aware consumer narrows: an accumulated entry may be a Promise
+// (a `ctx.use(Handle).defer()` slot) until it resolves.
+export type { DeferredHandleEntry } from "./defer.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 +412,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";

package/src/cloudflare/tracing.ts

@@ -0,0 +1,109 @@
+/**
+ * Cloudflare custom-spans integration.
+ *
+ * Bridges the router's performance phases (request, middleware, action,
+ * loaders, handler, render, ssr) onto Cloudflare Workers custom spans so they show
+ * up in the trace waterfall and OpenTelemetry exports next to the platform's
+ * automatic spans (KV reads, D1 queries, fetch calls), with correct nesting.
+ *
+ * Usage (Cloudflare preset only):
+ *
+ *   import { createRouter } from "@rangojs/router";
+ *   import { createCloudflareTracing } from "@rangojs/router/cloudflare";
+ *
+ *   export const router = createRouter({
+ *     tracing: createCloudflareTracing(),
+ *   });
+ *
+ * The runner reads `executionContext.tracing` (the same object as
+ * `import { tracing } from "cloudflare:workers"`) at call time. It is therefore
+ * dependency-free: no `cloudflare:workers` import and no hard dependency on
+ * `@cloudflare/workers-types`, matching the convention in cache/cf. When the
+ * worker is not running on a tracing-enabled Cloudflare runtime — Node, dev
+ * without a tracing destination, an older runtime — `executionContext.tracing`
+ * is undefined and every span call falls through to the work directly, so the
+ * request behaves exactly as if tracing were off. Whether spans are actually
+ * recorded is governed by the `observability`/tracing block in wrangler config.
+ *
+ * Span duration note: enterSpan ends a span when its callback's returned value
+ * (or promise) settles. For the streaming phases (request/render/ssr) that is at
+ * stream CONSTRUCTION, not body-drain. Instrumentation is best-effort and never
+ * wraps or buffers the response body, so it cannot regress streaming or latency.
+ * A loader/Suspense child that resolves mid-stream therefore keeps a rango.loader
+ * span that can extend past its render parent — overlapping spans are valid. Uses
+ * only the typed enterSpan API; spans bound work up to stream-handoff, matching
+ * the co-emitted perf metric.
+ */
+
+import { _getRequestContext } from "../server/request-context.js";
+import {
+  type RouterTracingConfig,
+  type SpanRunner,
+  type TracePhaseToggles,
+  NOOP_TRACE_SPAN,
+} from "../router/tracing.js";
+
+/**
+ * Minimal local view of Cloudflare's `Span`. Declared here (not imported from
+ * `@cloudflare/workers-types`) to avoid a hard type dependency.
+ */
+interface CloudflareSpan {
+  readonly isTraced: boolean;
+  setAttribute(key: string, value?: boolean | number | string): void;
+}
+
+/** Minimal local view of Cloudflare's `Tracing` (only enterSpan is used). */
+interface CloudflareTracing {
+  enterSpan<T>(name: string, callback: (span: CloudflareSpan) => T): T;
+}
+
+/** Options for createCloudflareTracing. */
+export interface CloudflareTracingOptions {
+  /** Master switch. Defaults to true. */
+  enabled?: boolean;
+  /** Per-phase span toggles. Omitted phases default to enabled. */
+  spans?: TracePhaseToggles;
+}
+
+/**
+ * Resolve the per-request Cloudflare tracer from the active execution context.
+ * Returns undefined off-Cloudflare or when tracing is not enabled for the
+ * worker, in which case the caller runs the work without a span.
+ */
+function getRequestTracer(): CloudflareTracing | undefined {
+  const executionContext = _getRequestContext()?.executionContext as
+    | { tracing?: CloudflareTracing }
+    | undefined;
+  const tracing = executionContext?.tracing;
+  return tracing && typeof tracing.enterSpan === "function"
+    ? tracing
+    : undefined;
+}
+
+const cloudflareSpanRunner: SpanRunner = (name, fn) => {
+  const tracer = getRequestTracer();
+  if (!tracer) return fn(NOOP_TRACE_SPAN);
+  // enterSpan runs the callback now and ends the span when its return value
+  // (or returned promise) settles; spans nest by JS async context. fn's param
+  // is the narrower TraceSpan, so the wider CloudflareSpan satisfies it directly.
+  return tracer.enterSpan(name, fn);
+};
+
+/**
+ * Create the tracing config for a Cloudflare router. Pass the result to
+ * `createRouter({ tracing })`. Spans are emitted for the request, middleware,
+ * action, loaders, handler, render, and ssr phases; pass `spans` to turn
+ * individual phases off.
+ *
+ * @see createOTelTracing (`@rangojs/router`) for the same slot on any platform
+ *   with an OpenTelemetry SDK.
+ */
+export function createCloudflareTracing(
+  options: CloudflareTracingOptions = {},
+): RouterTracingConfig {
+  return {
+    runner: cloudflareSpanRunner,
+    enabled: options.enabled ?? true,
+    spans: options.spans,
+  };
+}