@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.140

package/src/index.ts

@@ -10,9 +10,6 @@
  *   import from "@rangojs/router/client"
  */
 
-// Universal rendering utilities (work on both server and client)
-export { renderSegments } from "./segment-system.js";
-
 // Error classes (can be used on both server and client)
 export {
   RouteNotFoundError,
@@ -21,26 +18,24 @@ export {
   MiddlewareError,
   HandlerError,
   BuildError,
+  DslContextError,
   InvalidHandlerError,
-  NetworkError,
-  isNetworkError,
-  sanitizeError,
   RouterError,
+  Skip,
+  isSkip,
 } from "./errors.js";
 
 // Types (safe to import anywhere - no runtime code)
 export type {
   // Configuration types
   DocumentProps,
-  RouterEnv,
   DefaultEnv,
   RouteDefinition,
   RouteConfig,
   RouteDefinitionOptions,
   TrailingSlashMode,
   // Handler types
-  Handler,            // Supports params object, path pattern, or route name
-  ScopedRouteMap,     // Scoped view of GeneratedRouteMap for Handler<"localName", ScopedRouteMap<"prefix">>
+  Handler, // Supports params object, path pattern, or route name
   HandlerContext,
   ExtractParams,
   GenericParams,
@@ -49,6 +44,7 @@ export type {
   // Revalidation types
   RevalidateParams,
   Revalidate,
+  ActionRef,
   RouteKeys,
   // Loader types
   LoaderDefinition,
@@ -56,9 +52,6 @@ export type {
   LoaderContext,
   FetchableLoaderOptions,
   LoadOptions,
-  LoaderActionContext,
-  LoaderAction,
-  LoaderMiddlewareFn,
   // Error boundary types
   ErrorInfo,
   ErrorBoundaryFallbackProps,
@@ -75,7 +68,13 @@ export type {
 } from "./types.js";
 
 // Search params schema types
-export type { SearchSchema, SearchSchemaValue, ResolveSearchSchema, RouteSearchParams, RouteParams } from "./search-params.js";
+export type {
+  SearchSchema,
+  SearchSchemaValue,
+  ResolveSearchSchema,
+  RouteSearchParams,
+  RouteParams,
+} from "./search-params.js";
 
 // Client-safe createLoader - only stores the $$id, function is not included
 // Use this when defining loaders that will be imported by client components
@@ -83,6 +82,21 @@ export { createLoader } from "./loader.js";
 
 // Route definition types (safe to import anywhere)
 export type { RouteHelpers, RouteHandlers } from "./route-definition.js";
+export type {
+  TransitionConfig,
+  TransitionWhenFn,
+  TransitionWhenContext,
+  ViewTransitionClass,
+} from "./types.js";
+
+// Composition types for reusable callback factories
+export type {
+  RouteUseItem,
+  LayoutUseItem,
+  AllUseItems,
+  UseItems,
+  HandlerUseItem,
+} from "./route-types.js";
 
 // Response route types (usable in both server and client contexts)
 export type {
@@ -95,126 +109,242 @@ export type {
   JsonResponsePathFn,
   TextResponsePathFn,
   RouteResponse,
-  ResponseError,
-  ResponseEnvelope,
+  ProblemDetails,
 } from "./urls.js";
 
 // Middleware context types
-export type {
-  MiddlewareContext,
-  CookieOptions,
-} from "./router/middleware.js";
+export type { MiddlewareContext, CookieOptions } from "./router/middleware.js";
+
+function serverOnlyStubError(name: string): Error {
+  return new Error(
+    `${name}() is only available from "@rangojs/router" in a react-server/RSC environment. ` +
+      `For client hooks and components, import from "@rangojs/router/client".`,
+  );
+}
 
 /**
  * Error-throwing stub for server-only `urls` function.
  */
 export function urls(): never {
-  throw new Error(
-    'urls() is server-only and requires RSC context.'
-  );
+  throw serverOnlyStubError("urls");
 }
 
 /**
  * Error-throwing stub for server-only `createRouter` function.
  */
 export function createRouter(): never {
-  throw new Error(
-    'createRouter() is server-only and requires RSC context.'
-  );
+  throw serverOnlyStubError("createRouter");
 }
 
 /**
  * Error-throwing stub for server-only `redirect` function.
  */
 export function redirect(): never {
-  throw new Error(
-    'redirect() is server-only and requires RSC context.'
-  );
+  throw serverOnlyStubError("redirect");
 }
 
 // Handle API (universal - works on both server and client)
 export { createHandle, isHandle, type Handle } from "./handle.js";
+export {
+  DEFAULT_DEFER_TIMEOUT_MS,
+  type DeferOptions,
+  type HandlePush,
+  type HandlePushFn,
+} from "./defer.js";
+
+// Context variable API (typed ctx.set/ctx.get tokens)
+export { createVar, type ContextVar } from "./context-var.js";
+
+// CSP nonce token (use with ctx.get(nonce) in middleware/handlers)
+export { nonce } from "./rsc/nonce.js";
 
 /**
- * Error-throwing stub for server-only `Prerender` function.
+ * SSR/client stub for server-only `Prerender` function.
+ *
+ * Returns a lightweight stub object instead of throwing so that the
+ * production SSR build can safely bundle the RSC entry chunk — the SSR
+ * bundler resolves `@rangojs/router` to this (SSR) entry, so Prerender
+ * calls in RSC code must not crash at module-evaluation time.
  */
-export function Prerender(): never {
-  throw new Error(
-    'Prerender() is server-only and requires RSC context.'
-  );
+export function Prerender(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "prerenderHandler" as const, $$id: id };
 }
 
 /**
- * Error-throwing stub for server-only `Static` function.
+ * SSR/client stub for server-only `Passthrough` function.
  */
-export function Static(): never {
-  throw new Error(
-    'Static() is server-only and requires RSC context.'
-  );
+export function Passthrough(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "passthroughHandler" as const, $$id: id };
+}
+
+/**
+ * SSR/client stub for server-only `Static` function.
+ *
+ * Returns a lightweight stub object instead of throwing so that the
+ * production SSR build can safely bundle the RSC entry chunk — the SSR
+ * bundler resolves `@rangojs/router` to this (SSR) entry, so Static
+ * calls in RSC code must not crash at module-evaluation time.
+ */
+export function Static(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "staticHandler" as const, $$id: id };
 }
 
 /**
  * Error-throwing stub for server-only `getRequestContext` function.
  */
 export function getRequestContext(): never {
-  throw new Error(
-    'getRequestContext() is server-only and requires RSC context.'
-  );
+  throw serverOnlyStubError("getRequestContext");
 }
 
 /**
- * Error-throwing stub for server-only `requireRequestContext` function.
+ * Error-throwing stub for server-only `cookies` function.
  */
-export function requireRequestContext(): never {
-  throw new Error(
-    'requireRequestContext() is server-only and requires RSC context.'
-  );
+export function cookies(): never {
+  throw serverOnlyStubError("cookies");
 }
 
 /**
- * Error-throwing stub for server-only `createReverse` function.
+ * Error-throwing stub for server-only `headers` function.
  */
-export function createReverse(): never {
-  throw new Error(
-    'createReverse() is server-only and requires RSC context.'
-  );
+export function headers(): never {
+  throw serverOnlyStubError("headers");
 }
 
 /**
- * Error-throwing stub for server-only `enableMatchDebug` function.
+ * Client/SSR passthrough for `live()` (the PPR hole primitive). Unlike the
+ * cookies()/headers() stubs this is a REAL function: there is no shell capture
+ * off the react-server condition, so live() simply runs the thunk (or returns
+ * the promise). The capture-aware implementation lives in index.rsc.ts
+ * (./server/live.js). See docs/design/ppr-shell-resume.md.
  */
-export function enableMatchDebug(): never {
-  throw new Error(
-    'enableMatchDebug() is server-only and requires RSC context.'
-  );
+export function live<T>(fn: () => Promise<T> | T): Promise<T>;
+export function live<T>(promise: Promise<T>): Promise<T>;
+export function live<T>(
+  input: (() => Promise<T> | T) | Promise<T>,
+): Promise<T> {
+  return typeof input === "function"
+    ? Promise.resolve((input as () => Promise<T> | T)())
+    : input;
 }
 
 /**
- * Error-throwing stub for server-only `getMatchDebugStats` function.
+ * Client implementation of `invalidateClientCache()`. Unlike the server-only
+ * stubs above this is a REAL function under the `default` condition (it marks
+ * the client's caches stale); the `react-server` condition (index.rsc.ts)
+ * selects the server implementation that writes a rotated `Set-Cookie`.
  */
-export function getMatchDebugStats(): never {
-  throw new Error(
-    'getMatchDebugStats() is server-only and requires RSC context.'
-  );
-}
+export {
+  invalidateClientCache,
+  keepClientCache,
+} from "./browser/invalidate-client-cache.js";
 
 /**
- * Error-throwing stub for server-only `track` function.
+ * Error-throwing stub for server-only `createReverse` function.
  */
-export function track(): never {
-  throw new Error(
-    'track() is server-only and requires RSC context.'
-  );
+export function createReverse(): never {
+  throw serverOnlyStubError("createReverse");
+}
+
+// Error-throwing stubs for server-only route helpers
+export function layout(): never {
+  throw serverOnlyStubError("layout");
+}
+export function cache(): never {
+  throw serverOnlyStubError("cache");
+}
+export function middleware(): never {
+  throw serverOnlyStubError("middleware");
+}
+export function revalidate(): never {
+  throw serverOnlyStubError("revalidate");
+}
+// Cache tag APIs are server-only (real implementations in index.rsc.ts). These
+// stubs keep the named-export shape identical under the default/non-react-server
+// condition so SSR/client/default bundles that encounter the import link cleanly.
+export function cacheTag(): never {
+  throw serverOnlyStubError("cacheTag");
+}
+export function updateTag(): never {
+  throw serverOnlyStubError("updateTag");
+}
+export function revalidateTag(): never {
+  throw serverOnlyStubError("revalidateTag");
+}
+export function loader(): never {
+  throw serverOnlyStubError("loader");
+}
+export function loading(): never {
+  throw serverOnlyStubError("loading");
+}
+export function parallel(): never {
+  throw serverOnlyStubError("parallel");
+}
+export function intercept(): never {
+  throw serverOnlyStubError("intercept");
+}
+export function errorBoundary(): never {
+  throw serverOnlyStubError("errorBoundary");
+}
+export function notFoundBoundary(): never {
+  throw serverOnlyStubError("notFoundBoundary");
+}
+export function transition(): never {
+  throw serverOnlyStubError("transition");
 }
 
 // Request context type (safe for client)
-export type { RequestContext } from "./server/request-context.js";
+export type { PublicRequestContext as RequestContext } from "./server/request-context.js";
+
+// Shared base for every user-facing request context.
+export type { RequestScope, ExecutionContext } from "./types/request-scope.js";
+
+// Cookie store types (safe for client)
+export type {
+  CookieStore,
+  Cookie,
+  ReadonlyHeaders,
+} from "./server/cookie-store.js";
+
+// Built-in handles (universal — work on both server and client)
+export { Meta } from "./handles/meta.js";
+export {
+  Script,
+  type ScriptConfig,
+  type ScriptAttributes,
+} from "./handles/script.js";
+export { Breadcrumbs } from "./handles/breadcrumbs.js";
 
 // Meta types
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
 
+// Breadcrumb types
+export type { BreadcrumbItem } from "./handles/breadcrumbs.js";
+
 // Reverse type utilities for type-safe URL generation (Django-style URL reversal)
-export type { ScopedReverseFunction, ReverseFunction, ExtractLocalRoutes, PrefixedRoutes, PrefixRoutePatterns, ParamsFor, SanitizePrefix, MergeRoutes } from "./reverse.js";
+export type {
+  ScopedReverseFunction,
+  ReverseFunction,
+  ExtractLocalRoutes,
+  ParamsFor,
+} from "./reverse.js";
 // scopedReverse() helper for handlers to get locally-typed reverse
 export { scopedReverse } from "./reverse.js";
 
@@ -223,7 +353,61 @@ export {
   createLocationState,
   type LocationStateDefinition,
   type LocationStateEntry,
+  type LocationStateOptions,
 } from "./browser/react/location-state-shared.js";
 
-// Path-based response type lookup from RegisteredRoutes
-export type { PathResponse } from "./href-client.js";
+// Path and response types are ambient on the `Rango` namespace (`Rango.Path`,
+// `Rango.PathResponse`, declared in href-client.ts) — no import needed.
+
+// Telemetry types only — the createConsoleSink/createOTelSink values are
+// server-only and live in index.rsc.ts (the `react-server` condition of the
+// bare `@rangojs/router` import). Re-exporting them as values from this
+// (default/client) entry would pull telemetry.ts and telemetry-otel.ts into
+// the client module graph; both tree-shake to zero bytes but still appear in
+// bundle analysis output and slow build-time module resolution. Consumers
+// who need the values in non-RSC contexts can import from
+// `@rangojs/router/server`.
+export type {
+  OTelTracer,
+  OTelActiveSpanTracer,
+  OTelSpan,
+  OTelTracingOptions,
+} from "./router/telemetry-otel.js";
+// The full TelemetryEvent union PLUS its member types, so a consumer writing a
+// TelemetrySink can annotate a per-`type` handler (or construct an event literal
+// in a test) instead of only narrowing the opaque union.
+export type {
+  TelemetrySink,
+  TelemetryEvent,
+  RequestStartEvent,
+  RequestEndEvent,
+  RequestErrorEvent,
+  LoaderStartEvent,
+  LoaderEndEvent,
+  LoaderErrorEvent,
+  HandlerErrorEvent,
+  CacheSegmentStatus,
+  CacheSegmentSignal,
+  CacheDecisionEvent,
+  RevalidationDecisionEvent,
+  RequestTimeoutEvent,
+  OriginCheckRejectedEvent,
+} from "./router/telemetry.js";
+
+// Span tracing config types a consumer annotates. SpanRunner/TraceSpan are the
+// internal runner contract (consumers go through createOTelTracing /
+// createCloudflareTracing, which return a ready RouterTracingConfig) and are not
+// exported.
+export type {
+  RouterTracingConfig,
+  TracePhase,
+  TracePhaseToggles,
+} from "./router/tracing.js";
+
+// Timeout types and error class
+export { RouterTimeoutError } from "./router/timeout.js";
+export type {
+  RouterTimeouts,
+  TimeoutPhase,
+  TimeoutContext,
+} from "./router/timeout.js";

package/src/internal-debug.ts

@@ -1,5 +1,12 @@
-// Internal debug gate. Enable with INTERNAL_RANGO_DEBUG=1 in the environment.
-// Only checked on the server (Node.js / Bun); on workers process is undefined.
+// Runtime fallback for non-Vite contexts (Node, tests, raw imports). In the Vite
+// pipeline -- dev and build, every environment -- the router discovery plugin's
+// transform replaces this module with the build-time-resolved flag (see
+// vite/inject-client-debug.ts), so the CLIENT debug flag no longer depends on a
+// `__RANGO_DEBUG__` define being delivered to the browser (which dev did only as
+// an injected global whose presence varied across consumer setups).
+//
+// Keep this module to the single INTERNAL_RANGO_DEBUG export: the transform
+// replaces the whole file, so a second export would be dropped from the bundle.
 export const INTERNAL_RANGO_DEBUG: boolean =
   typeof process !== "undefined" &&
   Boolean((process as any).env?.INTERNAL_RANGO_DEBUG);