npm - @rangojs/router - Versions diffs - 0.0.0-experimental.0f44aca1 - Mend

@rangojs/router 0.0.0-experimental.0f44aca1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (305) hide show

package/AGENTS.md +5 -0
package/README.md +899 -0
package/dist/bin/rango.js +1601 -0
package/dist/vite/index.js +5214 -0
package/package.json +176 -0
package/skills/breadcrumbs/SKILL.md +250 -0
package/skills/cache-guide/SKILL.md +262 -0
package/skills/caching/SKILL.md +220 -0
package/skills/composability/SKILL.md +172 -0
package/skills/debug-manifest/SKILL.md +112 -0
package/skills/document-cache/SKILL.md +182 -0
package/skills/fonts/SKILL.md +167 -0
package/skills/hooks/SKILL.md +704 -0
package/skills/host-router/SKILL.md +218 -0
package/skills/intercept/SKILL.md +313 -0
package/skills/layout/SKILL.md +310 -0
package/skills/links/SKILL.md +239 -0
package/skills/loader/SKILL.md +596 -0
package/skills/middleware/SKILL.md +339 -0
package/skills/mime-routes/SKILL.md +128 -0
package/skills/parallel/SKILL.md +305 -0
package/skills/prerender/SKILL.md +643 -0
package/skills/rango/SKILL.md +118 -0
package/skills/response-routes/SKILL.md +411 -0
package/skills/route/SKILL.md +385 -0
package/skills/router-setup/SKILL.md +439 -0
package/skills/tailwind/SKILL.md +129 -0
package/skills/theme/SKILL.md +79 -0
package/skills/typesafety/SKILL.md +623 -0
package/skills/use-cache/SKILL.md +324 -0
package/src/__internal.ts +273 -0
package/src/bin/rango.ts +321 -0
package/src/browser/action-coordinator.ts +97 -0
package/src/browser/action-response-classifier.ts +99 -0
package/src/browser/event-controller.ts +899 -0
package/src/browser/history-state.ts +80 -0
package/src/browser/index.ts +18 -0
package/src/browser/intercept-utils.ts +52 -0
package/src/browser/link-interceptor.ts +141 -0
package/src/browser/logging.ts +55 -0
package/src/browser/merge-segment-loaders.ts +134 -0
package/src/browser/navigation-bridge.ts +645 -0
package/src/browser/navigation-client.ts +215 -0
package/src/browser/navigation-store.ts +806 -0
package/src/browser/navigation-transaction.ts +295 -0
package/src/browser/network-error-handler.ts +61 -0
package/src/browser/partial-update.ts +550 -0
package/src/browser/prefetch/cache.ts +146 -0
package/src/browser/prefetch/fetch.ts +135 -0
package/src/browser/prefetch/observer.ts +65 -0
package/src/browser/prefetch/policy.ts +42 -0
package/src/browser/prefetch/queue.ts +88 -0
package/src/browser/rango-state.ts +112 -0
package/src/browser/react/Link.tsx +360 -0
package/src/browser/react/NavigationProvider.tsx +386 -0
package/src/browser/react/ScrollRestoration.tsx +94 -0
package/src/browser/react/context.ts +59 -0
package/src/browser/react/filter-segment-order.ts +11 -0
package/src/browser/react/index.ts +52 -0
package/src/browser/react/location-state-shared.ts +162 -0
package/src/browser/react/location-state.ts +107 -0
package/src/browser/react/mount-context.ts +37 -0
package/src/browser/react/nonce-context.ts +23 -0
package/src/browser/react/shallow-equal.ts +27 -0
package/src/browser/react/use-action.ts +218 -0
package/src/browser/react/use-client-cache.ts +58 -0
package/src/browser/react/use-handle.ts +162 -0
package/src/browser/react/use-href.tsx +40 -0
package/src/browser/react/use-link-status.ts +135 -0
package/src/browser/react/use-mount.ts +31 -0
package/src/browser/react/use-navigation.ts +99 -0
package/src/browser/react/use-params.ts +65 -0
package/src/browser/react/use-pathname.ts +47 -0
package/src/browser/react/use-router.ts +63 -0
package/src/browser/react/use-search-params.ts +56 -0
package/src/browser/react/use-segments.ts +171 -0
package/src/browser/response-adapter.ts +73 -0
package/src/browser/rsc-router.tsx +431 -0
package/src/browser/scroll-restoration.ts +400 -0
package/src/browser/segment-reconciler.ts +216 -0
package/src/browser/segment-structure-assert.ts +83 -0
package/src/browser/server-action-bridge.ts +667 -0
package/src/browser/shallow.ts +40 -0
package/src/browser/types.ts +538 -0
package/src/browser/validate-redirect-origin.ts +29 -0
package/src/build/generate-manifest.ts +438 -0
package/src/build/generate-route-types.ts +36 -0
package/src/build/index.ts +35 -0
package/src/build/route-trie.ts +265 -0
package/src/build/route-types/ast-helpers.ts +25 -0
package/src/build/route-types/ast-route-extraction.ts +98 -0
package/src/build/route-types/codegen.ts +102 -0
package/src/build/route-types/include-resolution.ts +411 -0
package/src/build/route-types/param-extraction.ts +48 -0
package/src/build/route-types/per-module-writer.ts +128 -0
package/src/build/route-types/router-processing.ts +469 -0
package/src/build/route-types/scan-filter.ts +78 -0
package/src/build/runtime-discovery.ts +231 -0
package/src/cache/background-task.ts +34 -0
package/src/cache/cache-key-utils.ts +44 -0
package/src/cache/cache-policy.ts +125 -0
package/src/cache/cache-runtime.ts +338 -0
package/src/cache/cache-scope.ts +382 -0
package/src/cache/cf/cf-cache-store.ts +540 -0
package/src/cache/cf/index.ts +25 -0
package/src/cache/document-cache.ts +369 -0
package/src/cache/handle-capture.ts +81 -0
package/src/cache/handle-snapshot.ts +41 -0
package/src/cache/index.ts +43 -0
package/src/cache/memory-segment-store.ts +328 -0
package/src/cache/profile-registry.ts +73 -0
package/src/cache/read-through-swr.ts +134 -0
package/src/cache/segment-codec.ts +256 -0
package/src/cache/taint.ts +98 -0
package/src/cache/types.ts +342 -0
package/src/client.rsc.tsx +85 -0
package/src/client.tsx +601 -0
package/src/component-utils.ts +76 -0
package/src/components/DefaultDocument.tsx +27 -0
package/src/context-var.ts +86 -0
package/src/debug.ts +243 -0
package/src/default-error-boundary.tsx +88 -0
package/src/deps/browser.ts +8 -0
package/src/deps/html-stream-client.ts +2 -0
package/src/deps/html-stream-server.ts +2 -0
package/src/deps/rsc.ts +10 -0
package/src/deps/ssr.ts +2 -0
package/src/errors.ts +365 -0
package/src/handle.ts +135 -0
package/src/handles/MetaTags.tsx +246 -0
package/src/handles/breadcrumbs.ts +66 -0
package/src/handles/index.ts +7 -0
package/src/handles/meta.ts +264 -0
package/src/host/cookie-handler.ts +165 -0
package/src/host/errors.ts +97 -0
package/src/host/index.ts +53 -0
package/src/host/pattern-matcher.ts +214 -0
package/src/host/router.ts +352 -0
package/src/host/testing.ts +79 -0
package/src/host/types.ts +146 -0
package/src/host/utils.ts +25 -0
package/src/href-client.ts +222 -0
package/src/index.rsc.ts +233 -0
package/src/index.ts +277 -0
package/src/internal-debug.ts +11 -0
package/src/loader.rsc.ts +89 -0
package/src/loader.ts +64 -0
package/src/network-error-thrower.tsx +23 -0
package/src/outlet-context.ts +15 -0
package/src/outlet-provider.tsx +45 -0
package/src/prerender/param-hash.ts +37 -0
package/src/prerender/store.ts +185 -0
package/src/prerender.ts +463 -0
package/src/reverse.ts +330 -0
package/src/root-error-boundary.tsx +289 -0
package/src/route-content-wrapper.tsx +196 -0
package/src/route-definition/dsl-helpers.ts +934 -0
package/src/route-definition/helper-factories.ts +200 -0
package/src/route-definition/helpers-types.ts +430 -0
package/src/route-definition/index.ts +52 -0
package/src/route-definition/redirect.ts +93 -0
package/src/route-definition.ts +1 -0
package/src/route-map-builder.ts +275 -0
package/src/route-name.ts +53 -0
package/src/route-types.ts +259 -0
package/src/router/content-negotiation.ts +116 -0
package/src/router/debug-manifest.ts +72 -0
package/src/router/error-handling.ts +287 -0
package/src/router/find-match.ts +158 -0
package/src/router/handler-context.ts +451 -0
package/src/router/intercept-resolution.ts +395 -0
package/src/router/lazy-includes.ts +234 -0
package/src/router/loader-resolution.ts +420 -0
package/src/router/logging.ts +248 -0
package/src/router/manifest.ts +267 -0
package/src/router/match-api.ts +620 -0
package/src/router/match-context.ts +266 -0
package/src/router/match-handlers.ts +440 -0
package/src/router/match-middleware/background-revalidation.ts +223 -0
package/src/router/match-middleware/cache-lookup.ts +634 -0
package/src/router/match-middleware/cache-store.ts +295 -0
package/src/router/match-middleware/index.ts +81 -0
package/src/router/match-middleware/intercept-resolution.ts +306 -0
package/src/router/match-middleware/segment-resolution.ts +192 -0
package/src/router/match-pipelines.ts +179 -0
package/src/router/match-result.ts +219 -0
package/src/router/metrics.ts +282 -0
package/src/router/middleware-cookies.ts +55 -0
package/src/router/middleware-types.ts +222 -0
package/src/router/middleware.ts +748 -0
package/src/router/pattern-matching.ts +563 -0
package/src/router/prerender-match.ts +402 -0
package/src/router/preview-match.ts +170 -0
package/src/router/revalidation.ts +289 -0
package/src/router/router-context.ts +316 -0
package/src/router/router-interfaces.ts +452 -0
package/src/router/router-options.ts +592 -0
package/src/router/router-registry.ts +24 -0
package/src/router/segment-resolution/fresh.ts +570 -0
package/src/router/segment-resolution/helpers.ts +263 -0
package/src/router/segment-resolution/loader-cache.ts +198 -0
package/src/router/segment-resolution/revalidation.ts +1239 -0
package/src/router/segment-resolution/static-store.ts +67 -0
package/src/router/segment-resolution.ts +21 -0
package/src/router/segment-wrappers.ts +289 -0
package/src/router/telemetry-otel.ts +299 -0
package/src/router/telemetry.ts +300 -0
package/src/router/timeout.ts +148 -0
package/src/router/trie-matching.ts +239 -0
package/src/router/types.ts +170 -0
package/src/router.ts +1002 -0
package/src/rsc/handler-context.ts +45 -0
package/src/rsc/handler.ts +1089 -0
package/src/rsc/helpers.ts +198 -0
package/src/rsc/index.ts +36 -0
package/src/rsc/loader-fetch.ts +209 -0
package/src/rsc/manifest-init.ts +86 -0
package/src/rsc/nonce.ts +32 -0
package/src/rsc/origin-guard.ts +141 -0
package/src/rsc/progressive-enhancement.ts +379 -0
package/src/rsc/response-error.ts +37 -0
package/src/rsc/response-route-handler.ts +347 -0
package/src/rsc/rsc-rendering.ts +235 -0
package/src/rsc/runtime-warnings.ts +42 -0
package/src/rsc/server-action.ts +348 -0
package/src/rsc/ssr-setup.ts +128 -0
package/src/rsc/types.ts +263 -0
package/src/search-params.ts +230 -0
package/src/segment-system.tsx +454 -0
package/src/server/context.ts +591 -0
package/src/server/cookie-store.ts +190 -0
package/src/server/fetchable-loader-store.ts +37 -0
package/src/server/handle-store.ts +308 -0
package/src/server/loader-registry.ts +133 -0
package/src/server/request-context.ts +914 -0
package/src/server/root-layout.tsx +10 -0
package/src/server/tsconfig.json +14 -0
package/src/server.ts +51 -0
package/src/ssr/index.tsx +365 -0
package/src/static-handler.ts +114 -0
package/src/theme/ThemeProvider.tsx +297 -0
package/src/theme/ThemeScript.tsx +61 -0
package/src/theme/constants.ts +62 -0
package/src/theme/index.ts +48 -0
package/src/theme/theme-context.ts +44 -0
package/src/theme/theme-script.ts +155 -0
package/src/theme/types.ts +182 -0
package/src/theme/use-theme.ts +44 -0
package/src/types/boundaries.ts +158 -0
package/src/types/cache-types.ts +198 -0
package/src/types/error-types.ts +192 -0
package/src/types/global-namespace.ts +100 -0
package/src/types/handler-context.ts +687 -0
package/src/types/index.ts +88 -0
package/src/types/loader-types.ts +183 -0
package/src/types/route-config.ts +170 -0
package/src/types/route-entry.ts +102 -0
package/src/types/segments.ts +148 -0
package/src/types.ts +1 -0
package/src/urls/include-helper.ts +197 -0
package/src/urls/index.ts +53 -0
package/src/urls/path-helper-types.ts +339 -0
package/src/urls/path-helper.ts +329 -0
package/src/urls/pattern-types.ts +95 -0
package/src/urls/response-types.ts +106 -0
package/src/urls/type-extraction.ts +372 -0
package/src/urls/urls-function.ts +98 -0
package/src/urls.ts +1 -0
package/src/use-loader.tsx +354 -0
package/src/vite/discovery/bundle-postprocess.ts +184 -0
package/src/vite/discovery/discover-routers.ts +344 -0
package/src/vite/discovery/prerender-collection.ts +385 -0
package/src/vite/discovery/route-types-writer.ts +258 -0
package/src/vite/discovery/self-gen-tracking.ts +47 -0
package/src/vite/discovery/state.ts +110 -0
package/src/vite/discovery/virtual-module-codegen.ts +203 -0
package/src/vite/index.ts +16 -0
package/src/vite/plugin-types.ts +131 -0
package/src/vite/plugins/cjs-to-esm.ts +93 -0
package/src/vite/plugins/client-ref-dedup.ts +115 -0
package/src/vite/plugins/client-ref-hashing.ts +105 -0
package/src/vite/plugins/expose-action-id.ts +365 -0
package/src/vite/plugins/expose-id-utils.ts +287 -0
package/src/vite/plugins/expose-ids/export-analysis.ts +296 -0
package/src/vite/plugins/expose-ids/handler-transform.ts +179 -0
package/src/vite/plugins/expose-ids/loader-transform.ts +74 -0
package/src/vite/plugins/expose-ids/router-transform.ts +110 -0
package/src/vite/plugins/expose-ids/types.ts +45 -0
package/src/vite/plugins/expose-internal-ids.ts +569 -0
package/src/vite/plugins/refresh-cmd.ts +65 -0
package/src/vite/plugins/use-cache-transform.ts +323 -0
package/src/vite/plugins/version-injector.ts +83 -0
package/src/vite/plugins/version-plugin.ts +254 -0
package/src/vite/plugins/version.d.ts +12 -0
package/src/vite/plugins/virtual-entries.ts +123 -0
package/src/vite/plugins/virtual-stub-plugin.ts +29 -0
package/src/vite/rango.ts +510 -0
package/src/vite/router-discovery.ts +785 -0
package/src/vite/utils/ast-handler-extract.ts +517 -0
package/src/vite/utils/banner.ts +36 -0
package/src/vite/utils/bundle-analysis.ts +137 -0
package/src/vite/utils/manifest-utils.ts +70 -0
package/src/vite/utils/package-resolution.ts +121 -0
package/src/vite/utils/prerender-utils.ts +189 -0
package/src/vite/utils/shared-utils.ts +169 -0

package/src/router/router-options.ts ADDED Viewed

@@ -0,0 +1,592 @@
+import type { ComponentType, ReactNode } from "react";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type {
+  ErrorBoundaryHandler,
+  NotFoundBoundaryHandler,
+  OnErrorCallback,
+} from "../types";
+import type { NonceProvider } from "../rsc/types.js";
+import type { ExecutionContext } from "../server/request-context.js";
+import type { UrlPatterns } from "../urls.js";
+import type { NamedRouteEntry } from "./content-negotiation.js";
+import type { TelemetrySink } from "./telemetry.js";
+import type { RouterTimeouts, OnTimeoutCallback } from "./timeout.js";
+/**
+ * SSR stream mode returned by resolveStreaming.
+ *
+ * - `"stream"` — start flushing HTML as soon as the shell is ready
+ *   (default React SSR behavior via `renderToReadableStream`).
+ * - `"allReady"` — wait for every Suspense boundary to resolve before
+ *   sending any bytes (equivalent to awaiting `stream.allReady`).
+ */
+export type SSRStreamMode = "stream" | "allReady";
+/**
+ * Context passed to the resolveStreaming callback.
+ */
+export interface ResolveStreamingContext<TEnv = unknown> {
+  request: Request;
+  env: TEnv;
+  url: URL;
+}
+/**
+ * SSR configuration options.
+ */
+export interface SSROptions<TEnv = unknown> {
+  /**
+   * Determine whether an HTML response should stream progressively or
+   * wait for full readiness before flushing.
+   *
+   * Called once per HTML request, before the HTML response is produced.
+   * Does NOT apply to RSC responses (`__rsc`, partial navigation, prefetch).
+   *
+   * Return `"stream"` (default) for progressive streaming or `"allReady"`
+   * to buffer the complete HTML before sending.
+   *
+   * @example Bot detection
+   * ```ts
+   * createRouter({
+   *   ssr: {
+   *     resolveStreaming: async ({ request, env }) => {
+   *       const bot = await detectBot(request, env);
+   *       return bot.isBot && !bot.supportsStreaming ? "allReady" : "stream";
+   *     },
+   *   },
+   * });
+   * ```
+   */
+  resolveStreaming?: (
+    context: ResolveStreamingContext<TEnv>,
+  ) => SSRStreamMode | Promise<SSRStreamMode>;
+}
+/**
+ * Props passed to the root layout component
+ */
+export interface RootLayoutProps {
+  children: ReactNode;
+}
+/**
+ * Router configuration options
+ */
+export interface RSCRouterOptions<TEnv = any> {
+  /**
+   * Unique identifier for this router instance.
+   * Used to namespace static output files and route maps.
+   * Auto-generated if not provided.
+   */
+  id?: string;
+  /**
+   * Injected by the Vite transform at compile time.
+   * Hash of filename + line number for stable cross-environment ID.
+   * @internal
+   */
+  $$id?: string;
+  /**
+   * Injected by the Vite transform at compile time.
+   * Absolute path of the source file that defines this router,
+   * relative to project root. Eliminates runtime stack trace parsing.
+   * @internal
+   */
+  $$sourceFile?: string;
+  /**
+   * Enable performance metrics collection
+   * When enabled, metrics are output to console and available via Server-Timing header
+   */
+  debugPerformance?: boolean;
+  /**
+   * Allow the `?__debug_manifest` query parameter to return route manifest data as JSON.
+   * In development mode this is always enabled regardless of this setting.
+   * Defaults to false. Set to true to enable in production.
+   * @internal
+   */
+  allowDebugManifest?: boolean;
+  /**
+   * Document component that wraps the entire application.
+   *
+   * This component provides the HTML structure for your app and wraps
+   * both normal route content AND error states, preventing the app shell
+   * from unmounting during errors (avoids FOUC).
+   *
+   * Must be a client component ("use client") that accepts { children }.
+   *
+   * If not provided, a default document with basic HTML structure is used:
+   * `<html><head><meta charset/viewport></head><body>{children}</body></html>`
+   *
+   * @example
+   * ```typescript
+   * // components/Document.tsx
+   * "use client";
+   * export function Document({ children }: { children: ReactNode }) {
+   *   return (
+   *     <html lang="en">
+   *       <head>
+   *         <link rel="stylesheet" href="/styles.css" />
+   *       </head>
+   *       <body>
+   *         <nav>...</nav>
+   *         {children}
+   *       </body>
+   *     </html>
+   *   );
+   * }
+   *
+   * // router.tsx
+   * const router = createRouter<AppEnv>({
+   *   document: Document,
+   * });
+   * ```
+   */
+  document?: ComponentType<RootLayoutProps>;
+  /**
+   * Default error boundary fallback used when no error boundary is defined in the route tree
+   * If not provided, errors will propagate and crash the request
+   */
+  defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler;
+  /**
+   * Default not-found boundary fallback used when no notFoundBoundary is defined in the route tree
+   * If not provided, DataNotFoundError will be treated as a regular error
+   */
+  defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler;
+  /**
+   * Component to render when no route matches the requested URL.
+   *
+   * This is rendered within your document/app shell with a 404 status code.
+   * Use this for a custom 404 page that maintains your app's look and feel.
+   *
+   * If not provided, a default "Page not found" component is rendered.
+   *
+   * Can be a static ReactNode or a function receiving the pathname.
+   *
+   * @example
+   * ```typescript
+   * // Simple static component
+   * const router = createRouter<AppEnv>({
+   *   document: Document,
+   *   notFound: <NotFound404 />,
+   * });
+   *
+   * // Dynamic component with pathname
+   * const router = createRouter<AppEnv>({
+   *   document: Document,
+   *   notFound: ({ pathname }) => (
+   *     <div>
+   *       <h1>404 - Not Found</h1>
+   *       <p>No page exists at {pathname}</p>
+   *       <a href="/">Go home</a>
+   *     </div>
+   *   ),
+   * });
+   * ```
+   */
+  notFound?: ReactNode | ((props: { pathname: string }) => ReactNode);
+  /**
+   * Callback invoked when an error occurs during request handling.
+   *
+   * This callback is for notification/logging purposes - it cannot modify
+   * the error handling flow. Use errorBoundary() in route definitions to
+   * customize error UI.
+   *
+   * The callback receives comprehensive context about the error including:
+   * - The error itself
+   * - Phase where it occurred (routing, middleware, loader, handler, etc.)
+   * - Request info (URL, method, params)
+   * - Route info (routeKey, segmentId)
+   * - Environment/bindings
+   * - Duration from request start
+   *
+   * @example
+   * ```typescript
+   * const router = createRouter<AppEnv>({
+   *   onError: (context) => {
+   *     // Send to error tracking service
+   *     Sentry.captureException(context.error, {
+   *       tags: {
+   *         phase: context.phase,
+   *         route: context.routeKey,
+   *       },
+   *       extra: {
+   *         url: context.url.toString(),
+   *         params: context.params,
+   *         duration: context.duration,
+   *       },
+   *     });
+   *   },
+   * });
+   * ```
+   */
+  onError?: OnErrorCallback<TEnv>;
+  /**
+   * Cache store for segment caching.
+   *
+   * When provided, enables route-level caching via cache() boundaries.
+   * The store handles persistence (memory, KV, Redis, etc.).
+   *
+   * Can be a static config or a function receiving env for runtime bindings.
+   *
+   * @example Static config
+   * ```typescript
+   * import { MemorySegmentCacheStore } from "@rangojs/router/cache";
+   *
+   * const router = createRouter({
+   *   cache: {
+   *     store: new MemorySegmentCacheStore({ defaults: { ttl: 60 } }),
+   *   },
+   * });
+   * ```
+   *
+   * @example Dynamic config with env (e.g., Cloudflare Workers with ExecutionContext)
+   * ```typescript
+   * const router = createRouter<AppBindings>({
+   *   cache: (_env, ctx) => ({
+   *     store: new CFCacheStore({
+   *       defaults: { ttl: 60 },
+   *       ctx: ctx!, // ExecutionContext for non-blocking writes
+   *     }),
+   *   }),
+   * });
+   * ```
+   */
+  cache?:
+    | { store: SegmentCacheStore; enabled?: boolean }
+    | ((
+        env: TEnv,
+        ctx?: ExecutionContext,
+      ) => {
+        store: SegmentCacheStore;
+        enabled?: boolean;
+      });
+  /**
+   * Named cache profiles for "use cache" directive.
+   * Profile names map to TTL/SWR configuration.
+   *
+   * - `"use cache"` (no name) resolves to the `default` profile.
+   * - `"use cache: short"` resolves to the `short` profile.
+   *
+   * @example
+   * ```typescript
+   * createRouter({
+   *   cacheProfiles: {
+   *     default: { ttl: 900, swr: 1800 },
+   *     short:   { ttl: 60, swr: 120 },
+   *     long:    { ttl: 3600, swr: 7200 },
+   *     products: { ttl: 300, swr: 600, tags: ['products'] },
+   *   },
+   * });
+   * ```
+   */
+  cacheProfiles?: Record<
+    string,
+    import("../cache/profile-registry.js").CacheProfile
+  >;
+  /**
+   * Theme configuration for automatic theme management.
+   *
+   * When provided, enables:
+   * - ctx.theme and ctx.setTheme() in route handlers
+   * - useTheme() hook for client components
+   * - FOUC prevention via inline script in MetaTags
+   * - Automatic ThemeProvider wrapping in NavigationProvider
+   *
+   * @example
+   * ```typescript
+   * const router = createRouter<AppEnv>({
+   *   theme: {
+   *     defaultTheme: "system",
+   *     themes: ["light", "dark"],
+   *   }
+   * });
+   *
+   * // In route handler:
+   * route("settings", (ctx) => {
+   *   const theme = ctx.theme;     // "light" | "dark" | "system"
+   *   ctx.setTheme("dark");        // Sets cookie
+   *   return <SettingsPage />;
+   * });
+   *
+   * // In client component:
+   * import { useTheme } from "@rangojs/router/theme";
+   *
+   * function ThemeToggle() {
+   *   const { theme, setTheme, themes } = useTheme();
+   *   return <select value={theme} onChange={e => setTheme(e.target.value)}>
+   *     {themes.map(t => <option key={t}>{t}</option>)}
+   *   </select>;
+   * }
+   * ```
+   *
+   * Use `theme: true` to enable with all defaults.
+   */
+  theme?: import("../theme/types.js").ThemeConfig | true;
+  /**
+   * URL patterns to register with the router.
+   *
+   * Alternative to calling `.routes()` method - allows passing patterns
+   * directly in the config for a more concise setup.
+   *
+   * @example
+   * ```typescript
+   * import { urls } from "@rangojs/router/server";
+   *
+   * const urlpatterns = urls(({ path, layout }) => [
+   *   path("/", HomePage, { name: "home" }),
+   *   path("/about", AboutPage, { name: "about" }),
+   * ]);
+   *
+   * const router = createRouter<AppEnv>({
+   *   document: Document,
+   *   urls: urlpatterns,
+   * });
+   * ```
+   */
+  urls?: UrlPatterns<TEnv, any>;
+  /**
+   * Injected by the Vite transform at compile time.
+   * Static import of NamedRoutes from the generated named-routes file.
+   * Used to seed reverse() with the full named route map.
+   * @internal
+   */
+  $$routeNames?: Record<string, NamedRouteEntry>;
+  /**
+   * Nonce provider for Content Security Policy (CSP).
+   *
+   * Can be:
+   * - A function that returns a nonce string
+   * - A function that returns `true` to auto-generate a nonce
+   * - Undefined to disable nonce (default)
+   *
+   * The nonce will be applied to inline scripts injected by the RSC payload.
+   * It's also available to middleware via the typed `nonce` token:
+   * `import { nonce } from "@rangojs/router"; ctx.get(nonce)`
+   *
+   * @example Auto-generate nonce
+   * ```tsx
+   * createRouter({
+   *   nonce: () => true,
+   * });
+   * ```
+   *
+   * @example Custom nonce from request context
+   * ```tsx
+   * createRouter({
+   *   nonce: (request, env) => env.nonce,
+   * });
+   * ```
+   *
+   * @example Access nonce in middleware
+   * ```tsx
+   * import { nonce } from "@rangojs/router";
+   *
+   * const cspMiddleware: Middleware = async (ctx, next) => {
+   *   const value = ctx.get(nonce); // string | undefined
+   *   await next();
+   * };
+   * ```
+   */
+  nonce?: NonceProvider<TEnv>;
+  /**
+   * RSC version string included in metadata.
+   * The browser sends this back on partial requests to detect version mismatches.
+   *
+   * Defaults to the auto-generated VERSION from `@rangojs/router:version` virtual module.
+   * Only set this if you need a custom versioning strategy.
+   *
+   * @default VERSION from @rangojs/router:version
+   */
+  version?: string;
+  /**
+   * TTL (in seconds) for the in-memory prefetch cache and the
+   * Cache-Control header on prefetch responses.
+   *
+   * Controls how long prefetch responses are kept in the client-side
+   * in-memory cache and sets `Cache-Control: private, max-age=<ttl>`
+   * on server responses for CDN/edge caching.
+   *
+   * The cache is automatically invalidated on server actions regardless
+   * of TTL, so this is primarily a staleness safety net.
+   *
+   * Set to `false` to disable prefetch caching entirely.
+   *
+   * @default 300 (5 minutes)
+   */
+  prefetchCacheTTL?: number | false;
+  /**
+   * Enable connection warmup to keep TCP+TLS alive after idle periods.
+   *
+   * When enabled, the client sends a HEAD request after the user returns
+   * from an idle period (60s+), prewarming the TLS connection before
+   * the next navigation.
+   *
+   * @default true
+   */
+  warmup?: boolean;
+  /**
+   * Shorthand timeout (ms) applied to both action execution and render start.
+   * Does NOT apply to streamIdleMs.
+   * Overridden by individual values in `timeouts`.
+   *
+   * @example
+   * ```typescript
+   * createRouter({ timeout: 10_000 });
+   * ```
+   */
+  timeout?: number;
+  /**
+   * Structured timeout configuration per phase.
+   * Values here override the `timeout` shorthand.
+   *
+   * @example
+   * ```typescript
+   * createRouter({
+   *   timeouts: {
+   *     actionMs: 10_000,
+   *     renderStartMs: 8_000,
+   *   },
+   * });
+   * ```
+   */
+  timeouts?: RouterTimeouts;
+  /**
+   * Custom handler invoked when a timeout occurs.
+   * Receives context about which phase timed out and must return a Response.
+   * If not provided, returns a plain 504 with "Request timed out" body
+   * and X-Rango-Timeout-Phase header.
+   *
+   * If the callback throws, the default 504 response is used as fallback.
+   *
+   * @example
+   * ```typescript
+   * createRouter({
+   *   timeout: 10_000,
+   *   onTimeout: (ctx) => {
+   *     return new Response(
+   *       JSON.stringify({ error: "timeout", phase: ctx.phase }),
+   *       { status: 504, headers: { "Content-Type": "application/json" } },
+   *     );
+   *   },
+   * });
+   * ```
+   */
+  onTimeout?: OnTimeoutCallback<TEnv>;
+  /**
+   * Telemetry sink for structured lifecycle events.
+   *
+   * When provided, the router emits events for request start/end,
+   * loader start/end/error, handler errors, cache decisions, and
+   * revalidation decisions.
+   *
+   * No-op when not configured (zero overhead).
+   *
+   * @example Console logging
+   * ```typescript
+   * import { createConsoleSink } from "@rangojs/router";
+   *
+   * const router = createRouter({
+   *   telemetry: createConsoleSink(),
+   * });
+   * ```
+   *
+   * @example Custom sink
+   * ```typescript
+   * const router = createRouter({
+   *   telemetry: {
+   *     emit(event) {
+   *       myTracer.record(event);
+   *     },
+   *   },
+   * });
+   * ```
+   */
+  telemetry?: TelemetrySink;
+  /**
+   * SSR configuration options.
+   *
+   * @example
+   * ```typescript
+   * createRouter({
+   *   ssr: {
+   *     resolveStreaming: async ({ request, env }) => {
+   *       const bot = await detectBot(request, env);
+   *       return bot.isBot ? "allReady" : "stream";
+   *     },
+   *   },
+   * });
+   * ```
+   */
+  ssr?: SSROptions<TEnv>;
+  /**
+   * Cross-origin request protection for server actions, loader fetches,
+   * and progressive enhancement form submissions.
+   *
+   * When enabled, the router validates that the request's Origin header
+   * (or Referer fallback) matches the Host before executing actions,
+   * loaders, or PE submissions. Requests without Origin/Referer are
+   * allowed (same-origin navigations, non-browser clients).
+   *
+   * The built-in check compares Origin against the Host header and
+   * url.protocol. It does NOT trust X-Forwarded-Host/Proto headers
+   * (they are client-controllable without a trusted proxy). On standard
+   * deployments (Cloudflare Workers, Node behind nginx/caddy) the Host
+   * header is already set to the public-facing host by the platform or
+   * proxy. For non-standard proxy setups where Host differs from the
+   * public origin, use a custom function that reads the appropriate
+   * forwarded headers from your trusted proxy.
+   *
+   * - `true` (default) -- enable built-in origin validation
+   * - `false` -- disable
+   * - function -- full custom control with access to env, phase,
+   *   and the built-in check via `ctx.defaultCheck()`
+   *
+   * The callback receives `OriginCheckContext` with `request`, `url`,
+   * `env`, `routerId`, `phase` ("action" | "loader" | "pe-form"),
+   * and `defaultCheck()`. Return `true` to allow, `false` for default
+   * 403 rejection, or a `Response` for custom rejection.
+   *
+   * @default true
+   *
+   * @example Trusted proxy with X-Forwarded-Host
+   * ```ts
+   * createRouter({
+   *   originCheck({ request, url, env, defaultCheck }) {
+   *     if (env.TRUST_PROXY) {
+   *       const origin = request.headers.get("origin");
+   *       if (!origin) return true;
+   *       if (origin === "null") return false;
+   *       const host = request.headers.get("x-forwarded-host")
+   *         ?? request.headers.get("host") ?? url.host;
+   *       return origin.toLowerCase() === `${url.protocol}//${host}`.toLowerCase();
+   *     }
+   *     return defaultCheck();
+   *   },
+   * });
+   * ```
+   */
+  originCheck?: import("../rsc/origin-guard.js").OriginCheckConfig<TEnv>;
+}

package/src/router/router-registry.ts ADDED Viewed

@@ -0,0 +1,24 @@
+import type { RSCRouterInternal } from "./router-interfaces.js";
+/**
+ * Brand marker for identifying router instances at build time.
+ * Used by the Vite plugin to auto-discover routers from module exports.
+ */
+export const RSC_ROUTER_BRAND = "__rsc_router__" as const;
+/**
+ * Global registry of all router instances created via createRouter().
+ * Each router is keyed by its id (auto-generated or user-provided).
+ * Used by the Vite plugin at build time to discover routers and extract
+ * manifests, prefix trees, and pre-render candidates.
+ */
+export const RouterRegistry: Map<
+  string,
+  RSCRouterInternal<any, any>
+> = new Map();
+export let routerAutoId = 0;
+export function nextRouterAutoId(): number {
+  return routerAutoId++;
+}