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

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

@@ -0,0 +1,172 @@
+/**
+ * Type definitions for route system items
+ * These are extracted separately to avoid circular dependencies
+ * and to prevent bundling server-only code in client bundles
+ */
+/**
+ * Brand for UrlPatterns nominal typing (see pattern-types.ts). The route-item
+ * types below are discriminated by their `type` literal, so they carry no brand.
+ */
+export declare const UrlPatternsBrand: unique symbol;
+export type LayoutItem = {
+    name: string;
+    type: "layout";
+    uses?: AllUseItems[];
+};
+/**
+ * Phantom inference fields attached to wrapper items (layout/cache/transition)
+ * so the urls() type extractor can read their child routes/responses. The fields
+ * never exist at runtime.
+ */
+type WithChildren<TBase, TChildRoutes extends Record<string, any> = Record<string, string>, TChildResponses extends Record<string, unknown> = Record<string, unknown>> = TBase & {
+    readonly __childRoutes?: TChildRoutes;
+    readonly __childResponses?: TChildResponses;
+};
+/**
+ * Typed layout item that carries child routes as phantom type
+ * Used for type inference in urls() API
+ */
+export type TypedLayoutItem<TChildRoutes extends Record<string, any> = Record<string, string>, TChildResponses extends Record<string, unknown> = Record<string, unknown>> = WithChildren<LayoutItem, TChildRoutes, TChildResponses>;
+export type RouteItem = {
+    name: string;
+    type: "route";
+    uses?: AllUseItems[];
+};
+/**
+ * Typed route item that carries route name and pattern as phantom types
+ * Used for type inference in urls() API
+ */
+export type TypedRouteItem<TName extends string = string, TPattern extends string = string, TData = unknown, TSearch = {}> = RouteItem & {
+    readonly __name?: TName;
+    readonly __pattern?: TPattern;
+    readonly __data?: TData;
+    readonly __search?: TSearch;
+};
+export type ParallelItem = {
+    name: string;
+    type: "parallel";
+    uses?: ParallelUseItem[];
+};
+export type InterceptItem = {
+    name: string;
+    type: "intercept";
+    uses?: InterceptUseItem[];
+};
+export type LoaderItem = {
+    name: string;
+    type: "loader";
+    uses?: LoaderUseItem[];
+};
+export type MiddlewareItem = {
+    name: string;
+    type: "middleware";
+    uses?: AllUseItems[];
+};
+export type RevalidateItem = {
+    name: string;
+    type: "revalidate";
+    uses?: AllUseItems[];
+};
+export type LoadingItem = {
+    name: string;
+    type: "loading";
+};
+export type ErrorBoundaryItem = {
+    name: string;
+    type: "errorBoundary";
+    uses?: AllUseItems[];
+};
+export type NotFoundBoundaryItem = {
+    name: string;
+    type: "notFoundBoundary";
+    uses?: AllUseItems[];
+};
+export type CacheItem = {
+    name: string;
+    type: "cache";
+    uses?: AllUseItems[];
+};
+export type TransitionItem = {
+    name: string;
+    type: "transition";
+};
+/**
+ * Typed transition item that carries child routes as phantom type
+ * Used for type inference when transition() wraps child routes
+ */
+export type TypedTransitionItem<TChildRoutes extends Record<string, any> = Record<string, string>, TChildResponses extends Record<string, unknown> = Record<string, unknown>> = WithChildren<TransitionItem, TChildRoutes, TChildResponses>;
+/**
+ * Typed cache item that carries child routes as phantom type
+ * Used for type inference in urls() API
+ */
+export type TypedCacheItem<TChildRoutes extends Record<string, any> = Record<string, string>, TChildResponses extends Record<string, unknown> = Record<string, unknown>> = WithChildren<CacheItem, TChildRoutes, TChildResponses>;
+/**
+ * Include item for URL pattern composition (used by urls() API)
+ */
+export type IncludeItem = {
+    type: "include";
+    name: string;
+    prefix: string;
+    patterns: unknown;
+    options?: {
+        name?: string;
+        lazy?: boolean;
+    };
+    /** Whether this include should be lazily evaluated on first request */
+    lazy?: boolean;
+    /** Captured context for deferred lazy evaluation */
+    _lazyContext?: {
+        urlPrefix: string;
+        namePrefix: string | undefined;
+        parent: unknown;
+        /** Counter snapshot from pattern extraction for consistent shortCode indices */
+        counters?: Record<string, number>;
+        /** Cache profiles for DSL-time cache("profileName") resolution */
+        cacheProfiles?: Record<string, import("./cache/profile-registry.js").CacheProfile>;
+        /** Root scope flag for dot-local reverse resolution */
+        rootScoped?: boolean;
+        /**
+         * Positional include scope token composed from the parent scope plus this
+         * include's sibling index (`${parentScope}I${idx}`). Applied to direct-
+         * descendant shortCodes during lazy evaluation so routes inside the
+         * include cannot collide with siblings declared outside it.
+         */
+        includeScope?: string;
+    };
+};
+/**
+ * Typed include item that carries nested routes as phantom type
+ * Used for type inference in urls() API
+ */
+export type TypedIncludeItem<TRoutes extends Record<string, any> = Record<string, string>, TNamePrefix extends string = string, TUrlPrefix extends string = string, TResponses extends Record<string, unknown> = Record<string, unknown>> = IncludeItem & {
+    readonly __routes?: TRoutes;
+    readonly __namePrefix?: TNamePrefix;
+    readonly __urlPrefix?: TUrlPrefix;
+    readonly __responses?: TResponses;
+};
+/**
+ * Union types for use() callbacks
+ */
+export type AllUseItems = LayoutItem | RouteItem | MiddlewareItem | RevalidateItem | ParallelItem | InterceptItem | LoaderItem | LoadingItem | ErrorBoundaryItem | NotFoundBoundaryItem | CacheItem | TransitionItem | IncludeItem;
+/** Items that can be used inside a layout callback */
+export type LayoutUseItem = AllUseItems;
+export type RouteUseItem = LayoutItem | ParallelItem | InterceptItem | MiddlewareItem | RevalidateItem | LoaderItem | LoadingItem | ErrorBoundaryItem | NotFoundBoundaryItem | CacheItem | TransitionItem;
+/** Items that can be used inside a response route (path.json(), etc.) */
+export type ResponseRouteUseItem = MiddlewareItem | CacheItem;
+export type ParallelUseItem = RevalidateItem | LoaderItem | LoadingItem | ErrorBoundaryItem | NotFoundBoundaryItem | TransitionItem;
+export type InterceptUseItem = MiddlewareItem | RevalidateItem | LoaderItem | LoadingItem | ErrorBoundaryItem | NotFoundBoundaryItem | LayoutItem | RouteItem | TransitionItem;
+export type LoaderUseItem = RevalidateItem | CacheItem;
+/**
+ * Allow composition factories in use() callbacks.
+ * Factories return T[], which placed inside a use() callback array
+ * creates nested arrays like (T | T[])[]. These are flattened at
+ * runtime via .flat(3).
+ */
+export type UseItems<T> = (T | readonly T[])[];
+/**
+ * Union of all items that handler.use() may return.
+ * A handler doesn't know its mount site at definition time, so the type
+ * is intentionally broad — validation happens per-mount-site at runtime.
+ */
+export type HandlerUseItem = RouteUseItem | LayoutUseItem | ParallelUseItem | InterceptUseItem;
+export {};

package/dist/types/router/basename.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Normalize a router basename to its canonical form: a single leading slash,
+ * no trailing slash, and `undefined` for an empty or bare-"/" value.
+ *
+ * This is the single source of truth used by both createRouter() (so the RSC
+ * handler stores a canonical basename on the request context) and the testing
+ * primitives (so a consumer can pass the same un-normalized string their
+ * createRouter() accepts and observe the same redirect() prefixing).
+ */
+export declare function normalizeBasename(basename?: string): string | undefined;

package/dist/types/router/content-negotiation.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Content Negotiation Utilities
+ *
+ * Pure functions for HTTP Accept header parsing and response type matching.
+ * Used by previewMatch and classifyRequest for content negotiation between
+ * RSC routes and response routes (JSON, text, image, stream, etc.).
+ */
+import type { EntryData } from "../server/context.js";
+import type { CollectedMiddleware } from "./middleware-types.js";
+import type { RouteSnapshot } from "./route-snapshot.js";
+export declare const RESPONSE_TYPE_MIME: Record<string, string>;
+export declare const MIME_RESPONSE_TYPE: Record<string, string>;
+export type NamedRouteEntry = string | {
+    path: string;
+    search?: Record<string, string>;
+};
+export declare function flattenNamedRoutes(routeNames?: Record<string, NamedRouteEntry>): Record<string, string>;
+export interface AcceptEntry {
+    mime: string;
+    q: number;
+    order: number;
+}
+/**
+ * Parse an Accept header into a sorted array of MIME entries.
+ * Respects q-values (default 1.0) and uses client order as tiebreaker
+ * when q-values are equal (matching Express/Hono behavior).
+ */
+export declare function parseAcceptTypes(accept: string): AcceptEntry[];
+export declare const RSC_RESPONSE_TYPE = "__rsc__";
+/** RSC wire-format MIME type; explicit-opt-in flight transport. */
+export declare const RSC_WIRE_MIME = "text/x-component";
+/**
+ * Rank the RSC route's two representations against a parsed Accept list:
+ * true when the flight wire format outranks the HTML document. Wildcard
+ * entries count for the HTML side — they express "anything", and the
+ * canonical representation of anything is the document. Co-located with
+ * RSC_MIMES so the candidate registration and the representation choice
+ * cannot drift.
+ */
+export declare function prefersFlightRepresentation(acceptEntries: AcceptEntry[]): boolean;
+/**
+ * Pick the best negotiate variant by walking the client's sorted Accept list.
+ * For each accepted MIME type (in q-value/order priority), check if any
+ * candidate serves that type. Wildcards match the first candidate.
+ * Falls back to the first candidate if nothing matches.
+ */
+export declare function pickNegotiateVariant<T extends {
+    routeKey: string;
+    responseType: string;
+}>(acceptEntries: AcceptEntry[], candidates: T[]): T;
+/**
+ * Re-key params from the primary leaf's names to a winning variant's names.
+ *
+ * The trie match builds `params` positionally under the primary leaf's pa, so
+ * `/widgets/:id` matched as the primary yields `{ id }` even when the winning
+ * `/widgets/:file` response variant expects `{ file }`. Both share the same trie
+ * terminal, so they bind the same number of positional named params; we zip the
+ * variant's pa against the named values in insertion order (which is the
+ * primary's pa order). The wildcard key (`*`) is positional-independent and left
+ * untouched.
+ *
+ * Mutates `params` in place. No-op when `variantPa` is absent, when names already
+ * match (the common case), or when the positional count diverges (defensive:
+ * never corrupt params by zipping mismatched lengths).
+ */
+export declare function rekeyParamsForVariant(params: Record<string, string>, variantPa: string[] | undefined): void;
+/**
+ * Result of content negotiation for a route with negotiate variants.
+ */
+export interface NegotiationResult {
+    /** The winning response type */
+    responseType: string;
+    /** Handler function for the winning variant */
+    handler: Function;
+    /** Manifest entry for the winning variant (may differ from primary) */
+    manifestEntry: EntryData;
+    /** Route middleware for the winning variant */
+    routeMiddleware: CollectedMiddleware[];
+    /** True when negotiation selected a variant; false for a plain response route. */
+    negotiated: boolean;
+}
+/**
+ * Perform content negotiation for a route with negotiate variants.
+ *
+ * Returns a NegotiationResult when a response route wins negotiation.
+ * Returns null when RSC wins or no negotiation is needed.
+ *
+ * Shared by previewMatch and classifyRequest to avoid duplicating
+ * the candidate-building and variant-loading logic.
+ */
+export declare function negotiateRoute(request: Request, pathname: string, snapshot: RouteSnapshot): Promise<NegotiationResult | null>;

package/dist/types/router/debug-manifest.d.ts

@@ -0,0 +1,7 @@
+import { type SerializedManifest } from "../debug.js";
+import type { RouteEntry } from "../types";
+/**
+ * Build a serialized manifest from all route entries for debug inspection.
+ * Used by the `debugManifest()` method on the router instance.
+ */
+export declare function buildDebugManifest<TEnv = any>(routesEntries: RouteEntry<TEnv>[]): Promise<SerializedManifest>;

package/dist/types/router/error-handling.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Router Error Handling Utilities
+ *
+ * Error boundary and not-found boundary handling for Rango.
+ * Also includes the shared invokeOnError utility for error callback invocation.
+ */
+import { type ReactNode } from "react";
+import type { EntryData } from "../server/context";
+import type { ResolvedSegment, ErrorInfo, ErrorBoundaryHandler, NotFoundInfo, NotFoundBoundaryHandler, ErrorPhase, OnErrorCallback } from "../types";
+/**
+ * Context required to invoke the onError callback.
+ * This is a subset of OnErrorContext that callers must provide.
+ */
+export interface InvokeOnErrorContext<TEnv = any> {
+    request: Request;
+    url: URL;
+    routeKey?: string;
+    params?: Record<string, string>;
+    segmentId?: string;
+    segmentType?: "layout" | "route" | "parallel" | "loader" | "middleware";
+    loaderName?: string;
+    middlewareId?: string;
+    actionId?: string;
+    env?: TEnv;
+    isPartial?: boolean;
+    handledByBoundary?: boolean;
+    metadata?: Record<string, unknown>;
+    /** Request start time from performance.now() for duration calculation */
+    requestStartTime?: number;
+}
+/**
+ * Invoke the onError callback with comprehensive context.
+ * Catches any errors in the callback itself to prevent masking the original error.
+ *
+ * This is a shared utility used by both the router and RSC handler to ensure
+ * consistent error callback behavior across the codebase.
+ *
+ * @param onError - The onError callback to invoke (may be undefined)
+ * @param error - The error that occurred
+ * @param phase - The phase where the error occurred
+ * @param context - Additional context about the error
+ * @param logPrefix - Prefix for console.error messages (e.g., "Router" or "RSC")
+ */
+export declare function invokeOnError<TEnv = any>(onError: OnErrorCallback<TEnv> | undefined, error: unknown, phase: ErrorPhase, context: InvokeOnErrorContext<TEnv>, logPrefix?: string): void;
+/**
+ * Find the nearest error boundary by walking up the entry chain
+ * Also checks sibling layouts (orphan layouts) for error boundaries
+ * Returns the first fallback found, or the default error boundary if configured
+ */
+export declare function findNearestErrorBoundary(entry: EntryData | null, defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler): ReactNode | ErrorBoundaryHandler | null;
+/**
+ * Find the nearest notFound boundary by walking up the entry chain
+ * Returns the first fallback found, or the default notFound boundary if configured
+ */
+export declare function findNearestNotFoundBoundary(entry: EntryData | null, defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler): ReactNode | NotFoundBoundaryHandler | null;
+/**
+ * Create ErrorInfo from an error object
+ * Sanitizes error details in production
+ */
+export declare function createErrorInfo(error: unknown, segmentId: string, segmentType: ErrorInfo["segmentType"]): ErrorInfo;
+/**
+ * Create an error segment with the fallback component
+ * Renders the fallback with error info and reset function
+ */
+export declare function createErrorSegment(errorInfo: ErrorInfo, fallback: ReactNode | ErrorBoundaryHandler, entry: EntryData, params: Record<string, string>): ResolvedSegment;
+/**
+ * Create NotFoundInfo from a DataNotFoundError
+ */
+export declare function createNotFoundInfo(error: {
+    message: string;
+}, segmentId: string, segmentType: NotFoundInfo["segmentType"], pathname?: string): NotFoundInfo;
+/** Router-level `createRouter({ notFound })` option shape. */
+export type NotFoundComponentOption = ReactNode | ((props: {
+    pathname: string;
+}) => ReactNode);
+/**
+ * Pick the effective notFound fallback: nearest `notFoundBoundary`, else the
+ * router-level `notFound` option, else a plain default.
+ *
+ * The router option is resolved ONLY when no nearer boundary won — it may be a
+ * user render function doing arbitrary work, so computing it eagerly (as three
+ * earlier copies of this policy did) burned a full render on every 404 that a
+ * boundary was going to handle anyway.
+ *
+ * Every 404 origin routes through here — segment resolution
+ * (`segment-resolution/helpers.ts`), loader-thrown `notFound()`
+ * (`loader-resolution.ts`), and the unmatched-route path (`rsc/handler.ts`) —
+ * so the default text and the boundary-wins precedence cannot drift apart.
+ */
+export declare function resolveNotFoundFallback(boundary: ReactNode | NotFoundBoundaryHandler | null | undefined, notFoundComponent: NotFoundComponentOption | undefined, pathname: string | undefined): ReactNode | NotFoundBoundaryHandler;
+/**
+ * The router-level default alone: `createRouter({ notFound })` rendered, or the
+ * plain fallback node. Separate from {@link resolveNotFoundFallback} for the
+ * unmatched-route path, which has no entry chain and therefore no boundary to
+ * consult — it gets a `ReactNode` back rather than a possible handler.
+ */
+export declare function resolveDefaultNotFound(notFoundComponent: NotFoundComponentOption | undefined, pathname: string | undefined): ReactNode;
+/**
+ * Invoke a notFound fallback that may be a boundary handler or a plain node.
+ *
+ * Callers that cannot propagate a throw (the loader envelope) wrap this in
+ * their own try/catch; it deliberately does not swallow, so a throwing boundary
+ * still surfaces where that is the correct behavior.
+ */
+export declare function renderNotFoundFallback(fallback: ReactNode | NotFoundBoundaryHandler, notFoundInfo: NotFoundInfo): ReactNode;
+/**
+ * Create a notFound segment with the fallback component
+ * Renders the fallback with not found info
+ */
+export declare function createNotFoundSegment(notFoundInfo: NotFoundInfo, fallback: ReactNode | NotFoundBoundaryHandler, entry: EntryData, params: Record<string, string>): ResolvedSegment;

package/dist/types/router/find-match.d.ts

@@ -0,0 +1,19 @@
+import { type RouteMatchResult } from "./pattern-matching.js";
+import type { MetricsStore } from "../server/context";
+import type { RouteEntry } from "../types";
+export interface FindMatchDeps<TEnv = any> {
+    routesEntries: RouteEntry<TEnv>[];
+    evaluateLazyEntry: (entry: RouteEntry<TEnv>) => void | Promise<void>;
+    routerId: string;
+}
+/**
+ * Create a findMatch function bound to router state.
+ * Includes single-entry cache to avoid redundant matching within the same request.
+ *
+ * Async because a lazy include may be backed by an async provider
+ * (`() => import("./routes")`) that must be resolved before its routes can be
+ * matched. The hot path is unaffected: `await` only suspends on the first
+ * request to a not-yet-loaded dynamic include; eager routes resolve in the same
+ * microtask. Every caller already runs inside an async match pipeline.
+ */
+export declare function createFindMatch<TEnv = any>(deps: FindMatchDeps<TEnv>): (pathname: string, ms?: MetricsStore) => Promise<RouteMatchResult<TEnv> | null>;

package/dist/types/router/handler-context.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Router Handler Context
+ *
+ * Creates the handler context object passed to route handlers, middleware, and loaders.
+ */
+import type { InternalHandlerContext } from "../types";
+/**
+ * Strip internal _rsc* query params from a URL.
+ * Returns a new URL with only user-facing params.
+ */
+export declare function stripInternalParams(url: URL): URL;
+/**
+ * Create a reverse function for URL generation from route names.
+ * Used by both HandlerContext and MiddlewareContext.
+ *
+ * When currentParams is provided, those params are used as defaults for URL
+ * generation. This enables auto-filling mount params from include() prefixes:
+ * inner handlers can call ctx.reverse(".sibling") without explicitly passing
+ * params that are already known from the current URL match.
+ * Explicitly passed hrefParams take priority over currentParams.
+ */
+export declare function createReverseFunction(routeMap: Record<string, string>, currentRoutePrefix?: string, currentParams?: Record<string, string>, rootScoped?: boolean): (name: string, hrefParams?: Record<string, string>, search?: Record<string, unknown>) => string;
+/**
+ * Create HandlerContext with typed env/var/get/set
+ */
+export declare function createHandlerContext<TEnv>(params: Record<string, string>, request: Request, searchParams: URLSearchParams, pathname: string, url: URL, bindings?: TEnv, routeMap?: Record<string, string>, routeName?: string, responseType?: string, isPassthroughRoute?: boolean): InternalHandlerContext<any, TEnv>;
+/**
+ * Create a PrerenderContext for Prerender() handlers at build time.
+ *
+ * Returns an InternalHandlerContext where params, pathname, url, searchParams,
+ * search, reverse, and use(handle) work. Request-time properties
+ * (request, env, headers, cookies, get, set, res) throw with a clear error.
+ */
+export declare function createPrerenderContext<TEnv>(params: Record<string, string>, pathname: string, routeMap: Record<string, string>, routeName?: string, buildVars?: Record<string, any>, isPassthroughRoute?: boolean, buildEnv?: TEnv, devMode?: boolean): InternalHandlerContext<any, TEnv>;
+/**
+ * Create a StaticContext for Static() handlers at build time.
+ *
+ * Returns an InternalHandlerContext where only reverse and use(handle) work.
+ * Static handlers have no URL, no params, no pathname — everything else throws.
+ */
+export declare function createStaticContext<TEnv>(routeMap: Record<string, string>, routeName?: string, buildEnv?: TEnv, devMode?: boolean): InternalHandlerContext<any, TEnv>;

package/dist/types/router/instrument.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Phase + event instrumentation — the single internal API for observing router
+ * work.
+ *
+ * The router exposes the same work on three surfaces, and the rule is: each
+ * surface has exactly one owner here, so they cannot drift.
+ *
+ *   - observePhase(): a span of work. From one wrap site, emits the platform
+ *     span (tracing runner -> Cloudflare custom spans / OTel) and, when the
+ *     phase has one, its `debugPerformance` metric (metrics store -> [RSC Perf]
+ *     timeline + Server-Timing). Phases that meter their own perf metric with a
+ *     finer decomposition, or are deliberately span-only, pass `metric: false`.
+ *   - observeEvent(): a discrete fact (TelemetrySink): cache decisions,
+ *     revalidation decisions, handler errors, timeouts, origin rejections.
+ *     Event-shaped, not phase-shaped — derived from the same call sites but a
+ *     separate surface from spans.
+ *
+ * Why phases, not events, are the parent abstraction: Cloudflare's span API is
+ * callback-bound (enterSpan wraps the actual work), so the callback boundary is
+ * the source of truth — async-context nesting (a loader's KV/D1/fetch spans
+ * landing under rango.loader) cannot be faithfully reconstructed from
+ * after-the-fact start/end events. Spans drive; events are emitted alongside.
+ *
+ * Phase identity lives in the PHASES registry below, so the raw `rango.*` span
+ * names, perf-metric labels, and span attributes have a single definition each.
+ *
+ * When neither perf surface nor tracing is active on the request, observePhase
+ * is a direct call — no wrapper, no timestamp, no allocation.
+ */
+import { type TelemetryEvent } from "./telemetry.js";
+import { type TracePhase, type TraceSpan } from "./tracing.js";
+/**
+ * Perf-metric boundary for a phase, or `false` for span-only. `false` means the
+ * caller records its own perf metric with a finer decomposition than a single
+ * wrap (request: a grand total incl. pre-context bootstrap; middleware: pre/post
+ * own-time), so observePhase opens the span but records no metric of its own.
+ */
+export type PhaseMetric = {
+    label: string | (() => string);
+    depth?: number;
+} | false;
+/** Describes one observable phase across the perf and span surfaces. */
+export interface PhaseSpec {
+    /** Perf timeline label + Server-Timing name, or false for span-only. */
+    metric: PhaseMetric;
+    /** Span phase gate (per-phase toggle in the tracing config). */
+    tracePhase: TracePhase;
+    /** Span name (rango.*). */
+    spanName: string;
+    /** Span attributes set automatically when the span opens. */
+    attributes?: Record<string, string | number | boolean>;
+    /**
+     * Span attributes resolved AFTER the wrapped work runs (so they can read state
+     * that only exists once the work is underway, e.g. the matched route name).
+     * Applied for streaming phases once fn has constructed its value. Return
+     * undefined to add nothing.
+     */
+    lazyAttributes?: () => Record<string, string | number | boolean> | undefined;
+}
+/**
+ * The detached background lanes wrapped by the rango.background span (the
+ * `rango.background.kind` attribute). One name per task execution boundary.
+ */
+export type BackgroundTaskKind = "shell-capture" | "document-revalidation" | "loader-revalidation" | "use-cache-revalidation";
+/**
+ * The router's observable phases. One definition per phase keeps the `rango.*`
+ * span names, perf-metric labels, and identifying attributes from spreading
+ * across call sites.
+ */
+export declare const PHASES: {
+    /** Whole request pipeline. Span only — handler:total is metered directly. */
+    readonly request: PhaseSpec;
+    /** One middleware (incl. its downstream onion). Span only — the perf metric
+     * is the middleware's exclusive pre/post own-time, recorded directly.
+     * `metricLabel` is that metric's label (e.g. "middleware:auth@*"); it doubles
+     * as the rango.middleware_name span attribute. */
+    readonly middleware: (metricLabel: string) => PhaseSpec;
+    /** The server-action execution (decode args + run the action body), before
+     * the revalidation render. The metric label carries the action id (the
+     * _rsc_action / action $$id) so the perf timeline shows WHICH action ran, not
+     * just "an action"; the span also gets it as rango.action_id. */
+    readonly action: (id: string) => PhaseSpec;
+    /**
+     * One loader execution. `depth` is the perf-timeline indentation: 2 (default)
+     * for render-time loaders that nest under the render phase; 1 for a standalone
+     * fetchable `_rsc_loader` request, which has no render parent.
+     */
+    readonly loader: (id: string, depth?: number) => PhaseSpec;
+    /** One segment route/layout handler execution (the component/handler that
+     * produces a segment). Span only — the perf metric (handler:<id>) is owned by
+     * the legacy track() at the same call site, so observePhase here adds the
+     * rango.handler span without double-recording. `id` is the HANDLER id (the
+     * entry.id used in the handler:<id> perf row), carried as rango.handler_id —
+     * NOT the emitted segment's id (shortCode), which differs; the *_id naming
+     * mirrors rango.loader_id / rango.action_id. */
+    readonly handler: (id: string) => PhaseSpec;
+    /** Whole render phase: match + serialize + SSR. The metric label is resolved
+     * lazily at record time (after match has set the route name) so the perf
+     * timeline shows WHICH route rendered: `render:total:<routeName>`, falling back
+     * to `render:total` when there is no named route (unmatched / auto-generated). */
+    readonly render: PhaseSpec;
+    /** SSR HTML render from the RSC stream. Colon-delimited like the other ssr:*
+     * setup metrics (ssr:module-load / ssr:stream-mode). */
+    readonly ssr: PhaseSpec;
+    /**
+     * One detached background task (waitUntil work that outlives the response):
+     * a PPR shell capture or an SWR background revalidation. The wrapper is the
+     * explanatory parent for everything the task does — the platform's automatic
+     * KV/fetch/cache spans, and (for the revalidation lanes) the re-run's own
+     * rango.* phase spans — so post-handoff work never appears as orphan spans
+     * dangling under an ended foreground phase. `kind` identifies the lane.
+     * Span only (metric:false): the perf timeline is finalized with the
+     * response, so a background metric could never reach it. The shell-capture
+     * lane keeps its INNER phase spans suppressed (derived context strips
+     * _tracing — a capture re-render duplicating the foreground's span set was
+     * the original #670 leak); the revalidation lanes keep theirs, nested here.
+     */
+    readonly background: (kind: BackgroundTaskKind) => PhaseSpec;
+    /** Final response construction + host handoff: opened AFTER downstream
+     * middleware/core execution returns a Response, wrapping only finalization
+     * (redirect interception/guarding, Server-Timing mutation, final response
+     * selection) and ending immediately before the router handler returns the
+     * response to the host. Handoff-bound, never drain-bound — it must never
+     * read, tee, buffer, or await response.body, so it cannot regress streaming.
+     * At most one per traced request; absent when the request throws before a
+     * response exists. Span only (metric:false) — a co-emitted metric would
+     * circularly mutate the Server-Timing header this phase itself finalizes.
+     * On Cloudflare it may report 0 ms (non-I/O timers are frozen); its position
+     * and attributes (status/mode/body kind, set by the handler) are the value. */
+    readonly response: PhaseSpec;
+};
+/**
+ * Instrument one unit of work: open its span AND (unless `metric: false`) record
+ * its perf metric, from a single wrap site. fn is invoked exactly once with the
+ * span (a no-op span when tracing is off); its return value is returned
+ * unchanged and thrown errors / rejected promises propagate unchanged. When fn
+ * returns a promise both the metric duration and the span end when it settles.
+ *
+ * This is the ONLY phase primitive: every phase (request/middleware/action/
+ * loader/handler/render/ssr/response/background) settles when fn's own work
+ * completes. For streaming phases that means when the RSC/HTML stream is
+ * constructed, NOT when the body drains; for response, when finalization hands
+ * the stream to the host. Instrumentation is strictly best-effort: it never
+ * wraps or buffers the response and adds no work on the streaming path, so it
+ * cannot regress response latency or streaming. A loader that resolves while
+ * the body streams therefore keeps a rango.loader span that may extend past its
+ * render parent — overlapping spans are valid; the loader really did take that
+ * long.
+ *
+ * Reads the metrics store + tracing off the RequestContext ALS, which is active
+ * for the WHOLE request — contrast observeEvent, which reads the RouterContext
+ * ALS (entered later, during match).
+ */
+export declare function observePhase<T>(spec: PhaseSpec, fn: (span: TraceSpan) => T): T;
+/**
+ * Open a rango.handler span around one segment route/layout handler call. The
+ * segment-resolution hot path runs this PER SEGMENT, so it gates on the SPAN
+ * surface alone and calls the handler directly otherwise — building neither the
+ * PhaseSpec (PHASES.handler allocates) nor the wrapper closure on the off path.
+ * The handler:<id> perf metric is owned by the track() at the call site, so the
+ * span is the only surface this adds (metric:false); a debugPerformance-only
+ * request (no tracing) or a disabled handler phase (spans:{handler:false}) has
+ * nothing to record here and short-circuits.
+ */
+export declare function observeHandler<C, R>(id: string, handler: (ctx: C) => R, ctx: C): R;
+/**
+ * Emit one discrete telemetry event (the event-shaped counterpart to
+ * observePhase). Resolves the sink from the active router context and stamps the
+ * request id when the event omits it. No-op (and total — never throws) when no
+ * sink is configured.
+ *
+ * This is the canonical emitter for SYNCHRONOUS facts that fire inside the
+ * request's ALS scope (revalidation decisions, cache-lookup decisions). A few
+ * emitters deliberately stay on the lower-level resolveSink + safeEmit because
+ * observeEvent's lazy, per-call getRouterContext() read does not fit them — keep
+ * this the complete list:
+ *   - router.ts wrapLoaderPromise (loader.start/end/error) and
+ *     segment-resolution/streamed-handler-telemetry.ts (streamed handler.error)
+ *     capture the sink + request id EAGERLY and emit from a fire-and-forget
+ *     continuation that runs after the ALS scope may have unwound.
+ *   - router/match-handlers.ts resolves the sink ONCE for the hot match-pipeline
+ *     loop (request.start/end/error, cache.decision, ...).
+ *   - segment-resolution/helpers.ts emits via a caller-provided report.telemetry
+ *     sink rather than the ALS router context.
+ *   - rsc/handler.ts handleTimeoutResponse (request.timeout), the origin guard
+ *     (request.origin-rejected), and handleStore.onError (late-handle
+ *     handler.error) emit via router.telemetry directly — they run outside the
+ *     RouterContext ALS (only match()/matchPartial() enter it), so a
+ *     getRouterContext() read there throws and the event would vanish.
+ */
+export declare function observeEvent(event: TelemetryEvent): void;