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

package/dist/types/router/telemetry-otel.d.ts

@@ -0,0 +1,113 @@
+/**
+ * OpenTelemetry adapters for the router.
+ *
+ * Two adapters, two surfaces — matching the split in instrument.ts:
+ *
+ *   - createOTelTracing(tracer): the OTel adapter for the `tracing` SLOT — the
+ *     canonical phase-span layer. It bridges observePhase's callback boundary
+ *     onto OTel's callback-bound `startActiveSpan`, so the router's phase spans
+ *     (rango.request/middleware/action/loader/handler/render/ssr/response/
+ *     background) nest by async context and the loader's own OTel spans
+ *     (db/fetch) land under rango.loader. This is the OTel equivalent of
+ *     createCloudflareTracing — pass it to `createRouter({ tracing })`.
+ *
+ *   - createOTelSink(tracer): the OTel adapter for the `telemetry` SLOT — a
+ *     TelemetrySink for the EVENT-shaped facts (handler errors, cache decisions,
+ *     revalidation decisions, timeouts, origin rejections). It emits one instant
+ *     OTel span per fact. It deliberately does NOT emit request/loader phase
+ *     spans: those are owned by the tracing slot (createOTelTracing) so the two
+ *     layers don't produce duplicate rango.request / rango.loader spans.
+ *
+ * The core router stays OTel-agnostic — these adapters accept a standard OTel
+ * Tracer (structurally typed, no import needed) and bridge the gap.
+ *
+ * Usage:
+ *   import { trace } from "@opentelemetry/api";
+ *   import { createRouter, createOTelTracing, createOTelSink } from "@rangojs/router";
+ *
+ *   const tracer = trace.getTracer("my-app");
+ *   const router = createRouter({
+ *     tracing: createOTelTracing(tracer),   // phase spans (callback-bound)
+ *     telemetry: createOTelSink(tracer),     // discrete-fact instant spans
+ *   });
+ *
+ * Faithful nesting requires an OTel async context manager
+ * (AsyncLocalStorageContextManager) configured in your OTel setup — standard for
+ * any startActiveSpan-based instrumentation.
+ */
+import type { TelemetrySink } from "./telemetry.js";
+import type { RouterTracingConfig, TracingToggleOptions } from "./tracing.js";
+/**
+ * Minimal Span interface compatible with @opentelemetry/api Span.
+ * Only the methods used by the adapters are declared.
+ */
+export interface OTelSpan {
+    setAttribute(key: string, value: string | number | boolean): OTelSpan | void;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): OTelSpan | void;
+    recordException(exception: Error): void;
+    end(): void;
+}
+/**
+ * Minimal Tracer interface for the EVENT sink (createOTelSink): only `startSpan`
+ * is used (one instant span per discrete fact). Kept narrow so a custom,
+ * event-only tracer that does not implement `startActiveSpan` still satisfies it.
+ * The real `@opentelemetry/api` Tracer has both methods, so it satisfies this and
+ * `OTelActiveSpanTracer` below.
+ */
+export interface OTelTracer {
+    startSpan(name: string, options?: {
+        attributes?: Record<string, string | number | boolean>;
+    }): OTelSpan;
+}
+/**
+ * Minimal Tracer interface for the PHASE-SPAN adapter (createOTelTracing): only
+ * `startActiveSpan` is used (callback-bound, so the span is active for the work
+ * and child spans nest). Declared separately from `OTelTracer` so each factory
+ * requires exactly the method it calls.
+ */
+export interface OTelActiveSpanTracer {
+    startActiveSpan<T>(name: string, fn: (span: OTelSpan) => T): T;
+}
+/**
+ * Options for createOTelTracing. Alias of the shared {@link TracingToggleOptions}
+ * (`enabled` master switch + per-phase `spans` toggles); the name is public API.
+ */
+export type OTelTracingOptions = TracingToggleOptions;
+/**
+ * Create the tracing config that maps the router's phases onto OTel spans via
+ * `tracer.startActiveSpan`, which runs the work inside the span's active context
+ * (so child spans nest) and returns the work's value unchanged. The span ends
+ * when that value — or, for async work, the returned promise — settles, matching
+ * observePhase's contract. When the work throws or rejects, the exception is
+ * recorded and the span status is set to ERROR before it ends, so a failed phase
+ * stays visible in the trace (the old createOTelSink error path is preserved here
+ * now that phase spans live in this adapter). Pass the result to
+ * `createRouter({ tracing })`.
+ *
+ * @see createCloudflareTracing (`@rangojs/router/cloudflare`) for the same slot
+ *   using Cloudflare Workers native custom spans.
+ */
+export declare function createOTelTracing(tracer: OTelActiveSpanTracer, options?: OTelTracingOptions): RouterTracingConfig;
+/**
+ * Create a TelemetrySink that maps the router's discrete-fact events to instant
+ * OTel spans. One span per fact; no duration spans.
+ *
+ * Fact mapping:
+ *   - handler.error              -> "rango.handler.error" (error)
+ *   - cache.decision             -> "rango.cache.decision"
+ *   - revalidation.decision      -> "rango.revalidation.decision"
+ *   - request.timeout            -> "rango.request.timeout" (error)
+ *   - request.origin-rejected    -> "rango.request.origin-rejected" (error)
+ *
+ * Request and loader PHASE spans are intentionally NOT emitted here — they are
+ * owned by the tracing slot (createOTelTracing) so the two layers cannot produce
+ * duplicate rango.request / rango.loader spans. request.start/end and
+ * loader.start/end events are no-ops for this sink.
+ *
+ * Attributes use the `rango.*` namespace for router-specific data and
+ * `http.method` / `http.route` for HTTP semantics.
+ */
+export declare function createOTelSink(tracer: OTelTracer): TelemetrySink;

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

@@ -0,0 +1,216 @@
+/**
+ * Router Telemetry Sink
+ *
+ * Internal event model for structured lifecycle events.
+ * The sink is optional and zero-cost when not configured.
+ *
+ * Emit points:
+ *   - request.start / request.end   (match-handlers.ts)
+ *   - request.error                  (match-handlers.ts catch blocks)
+ *   - request.origin-rejected        (rsc/handler.ts origin guard)
+ *   - loader.start / loader.end / loader.error  (loader-resolution.ts)
+ *   - handler.error                  (trackHandler catch, segment-resolution/helpers.ts)
+ *   - cache.decision                 (cache-lookup middleware)
+ *   - revalidation.decision          (revalidation evaluation)
+ */
+interface BaseEvent {
+    /** Monotonic timestamp from performance.now() */
+    timestamp: number;
+    /** Request ID (from header or generated) */
+    requestId?: string;
+}
+export interface RequestStartEvent extends BaseEvent {
+    type: "request.start";
+    method: string;
+    pathname: string;
+    /** "match" for full document requests, "matchPartial" for navigation */
+    transaction: "match" | "matchPartial";
+    isPartial: boolean;
+}
+export interface RequestEndEvent extends BaseEvent {
+    type: "request.end";
+    method: string;
+    pathname: string;
+    transaction: "match" | "matchPartial";
+    durationMs: number;
+    segmentCount: number;
+    cacheHit: boolean;
+    /**
+     * HTTP status when a Response ended the transaction — a thrown-Response
+     * short-circuit (redirect / auth gate carries the Response's status, e.g. 302),
+     * or dispatch()'s final response status. Absent for a normal render completion:
+     * the Response is built after match(), so match()/matchPartial() have no status
+     * to stamp there. Lets a sink split 3xx short-circuits from 2xx completions.
+     */
+    status?: number;
+}
+export interface RequestErrorEvent extends BaseEvent {
+    type: "request.error";
+    method: string;
+    pathname: string;
+    transaction: "match" | "matchPartial";
+    error: Error;
+    phase: string;
+    durationMs: number;
+}
+export interface LoaderStartEvent extends BaseEvent {
+    type: "loader.start";
+    segmentId: string;
+    loaderName: string;
+    pathname: string;
+}
+export interface LoaderEndEvent extends BaseEvent {
+    type: "loader.end";
+    segmentId: string;
+    loaderName: string;
+    pathname: string;
+    durationMs: number;
+    ok: boolean;
+}
+export interface LoaderErrorEvent extends BaseEvent {
+    type: "loader.error";
+    segmentId: string;
+    loaderName: string;
+    pathname: string;
+    error: Error;
+    handledByBoundary: boolean;
+}
+export interface HandlerErrorEvent extends BaseEvent {
+    type: "handler.error";
+    segmentId?: string;
+    segmentType?: string;
+    error: Error;
+    handledByBoundary: boolean;
+    pathname?: string;
+    routeKey?: string;
+    params?: Record<string, string>;
+}
+/**
+ * Per-segment (or coarse route-level) cache status carried on the
+ * cache.decision telemetry event and the X-Rango-Cache debug header.
+ *
+ * v1 is COARSE: the router's pipeline tracks cache decisions at the
+ * route/entry level (cacheHit/cacheSource/shouldRevalidate), not per
+ * individual segment. The `segments` array therefore contains a single
+ * route-level entry keyed by the route key. The shape is forward-compatible
+ * with genuine per-segment status if the pipeline later exposes it.
+ */
+export type CacheSegmentStatus = "hit" | "miss" | "stale" | "prerendered" | "passthrough";
+export interface CacheSegmentSignal {
+    /** Segment id (v1: the route key, since status is route-level). */
+    id: string;
+    /** Segment type (v1: "route" for the coarse route-level entry). */
+    type: string;
+    /** Resolved cache status for this segment. */
+    cacheStatus: CacheSegmentStatus;
+    /** Whether stale-while-revalidate was triggered for this segment. */
+    shouldRevalidate?: boolean;
+}
+export interface CacheDecisionEvent extends BaseEvent {
+    type: "cache.decision";
+    pathname: string;
+    routeKey: string;
+    hit: boolean;
+    /** Whether stale-while-revalidate was triggered */
+    shouldRevalidate: boolean;
+    source?: "runtime" | "prerender";
+    /**
+     * Optional per-segment (v1: coarse route-level) cache status. Present only
+     * when telemetry or the debug cache signal is enabled. Optional so existing
+     * sinks are unaffected.
+     */
+    segments?: CacheSegmentSignal[];
+}
+export interface RevalidationDecisionEvent extends BaseEvent {
+    type: "revalidation.decision";
+    segmentId: string;
+    pathname: string;
+    routeKey: string;
+    shouldRevalidate: boolean;
+}
+export interface RequestTimeoutEvent extends BaseEvent {
+    type: "request.timeout";
+    phase: import("./timeout.js").TimeoutPhase;
+    pathname: string;
+    routeKey?: string;
+    actionId?: string;
+    durationMs: number;
+    customHandler: boolean;
+    render?: import("./timeout.js").RenderTimeoutContext;
+}
+export interface OriginCheckRejectedEvent extends BaseEvent {
+    type: "request.origin-rejected";
+    method: string;
+    pathname: string;
+    phase: import("../rsc/origin-guard.js").OriginCheckPhase;
+    origin: string | null;
+    host: string | null;
+}
+export type TelemetryEvent = RequestStartEvent | RequestEndEvent | RequestErrorEvent | LoaderStartEvent | LoaderEndEvent | LoaderErrorEvent | HandlerErrorEvent | CacheDecisionEvent | RevalidationDecisionEvent | RequestTimeoutEvent | OriginCheckRejectedEvent;
+/**
+ * Derive the coarse, route-level cache status from pipeline cache state.
+ *
+ * v1 mapping (route-level — see CacheSegmentSignal):
+ *   - prerender hit                         -> "prerendered"
+ *   - runtime hit + shouldRevalidate (SWR)  -> "stale"
+ *   - runtime hit                           -> "hit"
+ *   - no hit                                -> "miss"
+ *
+ * Note: "passthrough" is a build-time prerender concept (a route opts out of
+ * being prerendered for some params). At runtime a passthrough route renders
+ * fresh and is indistinguishable from a normal miss in the pipeline state, so
+ * v1 reports it as "miss". The "passthrough" status remains in the type union
+ * for forward compatibility.
+ */
+export declare function deriveCacheStatus(state: {
+    cacheHit: boolean;
+    cacheSource?: "runtime" | "prerender";
+    shouldRevalidate?: boolean;
+}): CacheSegmentStatus;
+/**
+ * Build the coarse route-level cache signal array (a single entry keyed by
+ * the route key). Used for both the cache.decision telemetry event and the
+ * X-Rango-Cache debug header.
+ */
+export declare function buildCacheSignalSegments(routeKey: string, state: {
+    cacheHit: boolean;
+    cacheSource?: "runtime" | "prerender";
+    shouldRevalidate?: boolean;
+}): CacheSegmentSignal[];
+/**
+ * Serialize cache signal segments into the X-Rango-Cache header value:
+ * `<segId>=<status>, <segId2>=<status2>`.
+ */
+export declare function formatCacheSignalHeader(segments: CacheSegmentSignal[]): string;
+/**
+ * Telemetry sink receives structured lifecycle events from the router.
+ * Implement this interface to integrate with any observability backend.
+ *
+ * All methods are fire-and-forget — exceptions are caught and logged.
+ */
+export interface TelemetrySink {
+    emit(event: TelemetryEvent): void;
+}
+/**
+ * Returns the configured sink, or the no-op singleton.
+ * Call sites use this so they don't need null checks.
+ */
+export declare function resolveSink(sink: TelemetrySink | undefined): TelemetrySink;
+/**
+ * Safe emit — catches any error thrown by the sink to prevent
+ * telemetry failures from affecting request handling.
+ */
+export declare function safeEmit(sink: TelemetrySink, event: TelemetryEvent): void;
+/**
+ * Get or create a request ID for telemetry correlation.
+ * Checks standard headers first (x-rsc-router-request-id, x-request-id,
+ * cf-ray), then generates an internal ID when none is present.
+ * Generated IDs use format "t-{base36}" to distinguish from header values.
+ */
+export declare function getRequestId(request: Request): string;
+/**
+ * Built-in console sink that logs events in a structured format.
+ * Designed as the default sink for development / debugging.
+ */
+export declare function createConsoleSink(): TelemetrySink;
+export {};

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

@@ -0,0 +1,107 @@
+/**
+ * Router Timeout
+ *
+ * Types, resolution logic, and helpers for request-level timeouts.
+ * Timeouts wrap action execution and render-start phases with
+ * a Promise.race mechanism, returning 504 on expiry.
+ */
+export interface RouterTimeouts {
+    /** Timeout for server action execution (ms). */
+    actionMs?: number;
+    /** Timeout for initial render/response production (ms). */
+    renderStartMs?: number;
+    /**
+     * Timeout for idle streaming after the response is handed off (ms): when no
+     * chunk flows to the client for this long, the body stream is errored with a
+     * RouterTimeoutError ("stream-idle") and the source render is canceled —
+     * bounding hangs from never-settling promises embedded in the payload.
+     * END-TO-END semantics: a stalled slow client counts as idle the same as a
+     * wedged producer, so pick generous budgets (seconds). Opt-in (unset =
+     * unbounded, and the `timeout` shorthand deliberately does not apply);
+     * onTimeout does NOT fire — no replacement Response can be served
+     * mid-stream — the trip reports via onError + the request.timeout event.
+     * Enforcement: rsc/stream-idle.ts, wired at the handler's response tail.
+     */
+    streamIdleMs?: number;
+}
+export type TimeoutPhase = "action" | "render-start" | "stream-idle";
+/**
+ * Canonical render-pipeline unions, defined here (the dependency-free timeout
+ * leaf) and shared by `import type` so the render driver
+ * (rsc/render-pipeline.ts RscRenderMode/RscRenderPhase), the foreground cursor
+ * (server/request-context.ts RenderForegroundCursor), and RenderTimeoutContext
+ * below cannot drift out of sync.
+ */
+export type RenderMode = "unknown" | "full" | "partial" | "action-revalidation" | "progressive-enhancement" | "progressive-enhancement-error";
+/** Terminal response-construction stage of the render driver. */
+export type RenderPhase = "flight" | "html" | "response";
+export interface RenderTimeoutContext {
+    mode: RenderMode;
+    phase: RenderPhase;
+    state: "paused" | "running";
+    completed: number;
+    total: number;
+    phaseDurationMs?: number;
+}
+export interface TimeoutContext<TEnv = any> {
+    phase: TimeoutPhase;
+    request: Request;
+    url: URL;
+    env: TEnv;
+    routeKey?: string;
+    actionId?: string;
+    durationMs: number;
+    /** Foreground render operation active when a render-start timeout fired. */
+    render?: RenderTimeoutContext;
+}
+export type OnTimeoutCallback<TEnv = any> = (ctx: TimeoutContext<TEnv>) => Response | Promise<Response>;
+export interface ResolvedTimeouts {
+    actionMs: number | undefined;
+    renderStartMs: number | undefined;
+    streamIdleMs: number | undefined;
+}
+/**
+ * Merge the `timeout` shorthand with the structured `timeouts` object.
+ *
+ * - `timeout` applies to `actionMs` and `renderStartMs` (NOT `streamIdleMs`).
+ * - Explicit `timeouts.*` values override the shorthand.
+ * - Returns `undefined` for any phase that has no configured value.
+ */
+export declare function resolveTimeouts(timeout?: number, timeouts?: RouterTimeouts): ResolvedTimeouts;
+export declare class RouterTimeoutError extends Error {
+    name: "RouterTimeoutError";
+    phase: TimeoutPhase;
+    durationMs: number;
+    constructor(phase: TimeoutPhase, durationMs: number);
+}
+type TimeoutResult<T> = {
+    result: T;
+    timedOut: false;
+} | {
+    timedOut: true;
+    durationMs: number;
+};
+/**
+ * A timeout phase is active only when its budget is a positive number.
+ * `undefined`/`null` (unset) and `<= 0` (explicit opt-out, e.g.
+ * `timeouts: { renderStartMs: 0 }`) both mean pass-through. withTimeout and the
+ * render-diagnostics gate (rsc/handler.ts) share this so a disabled budget can
+ * never leave one of them still doing bookkeeping the other can never read.
+ */
+export declare function isTimeoutEnabled(timeoutMs: number | undefined): boolean;
+/**
+ * Race an operation against a deadline.
+ *
+ * Returns a discriminated union so callers handle the timeout case
+ * without try/catch. Non-timeout errors from the operation re-throw.
+ *
+ * When `timeoutMs` is `undefined` or `<= 0`, the operation runs
+ * without any deadline (pass-through).
+ */
+export declare function withTimeout<T>(operation: Promise<T>, timeoutMs: number | undefined, phase: TimeoutPhase): Promise<TimeoutResult<T>>;
+/**
+ * Create the default 504 response for a timed-out request.
+ * Includes `X-Rango-Timeout-Phase` header for observability.
+ */
+export declare function createDefaultTimeoutResponse(phase: TimeoutPhase): Response;
+export {};

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

@@ -0,0 +1,139 @@
+/**
+ * Span tracing hook (platform-agnostic).
+ *
+ * The core router emits its observable phases (request, middleware, action,
+ * loaders, handler, render, ssr, response, background) as spans by calling
+ * traceSpan() at a small set of execution boundaries. When no tracing is
+ * configured the call is a direct pass-through: fn is invoked with a no-op
+ * span, with no wrapper and no allocation, so a non-traced request behaves
+ * exactly as before.
+ *
+ * A platform integration supplies a SpanRunner that wraps fn in a real span.
+ * Two runners ship: the Cloudflare one (createCloudflareTracing in
+ * src/cloudflare/tracing.ts), which bridges onto executionContext.tracing.
+ * enterSpan, and the OTel one (createOTelTracing in router/telemetry-otel.ts),
+ * which bridges onto tracer.startActiveSpan. Both wrap the actual work — not a
+ * post-hoc event — so spans nest by async context and the platform's automatic
+ * spans (KV/D1/fetch) nest under the right phase.
+ *
+ * traceSpan() below is the low-level wrap primitive. It is INTERNAL: the only
+ * caller is observePhase() (instrument.ts), the single phase-instrumentation
+ * API, which co-emits the span AND the debugPerformance perf metric from one
+ * wrap site (or just the span, for metric:false phases) so the two surfaces
+ * can't drift. Every router phase routes through observePhase via the PHASES
+ * registry; do not call traceSpan directly from new code.
+ *
+ * Phase coverage (all via observePhase): rango.request (span-only; handler:total
+ * metered directly), rango.middleware (span-only incl. intercept middleware;
+ * pre/post metered directly), rango.action (action:<id>; server-action
+ * execution, JS + no-JS/PE), rango.loader (loader:<id>; single metering site at
+ * useLoader, plus the fetchable path), rango.handler (span-only, one per segment
+ * route/layout handler execution; the handler:<id> perf metric is owned by the
+ * track() at the call site), rango.render (render:total:<route>; normal AND
+ * action-revalidation renders), rango.ssr (ssr:render-html), rango.response
+ * (span-only; final response construction + host handoff — the explicit
+ * stream-handoff marker), and rango.background (span-only; detached work, see
+ * below).
+ *
+ * Span-duration caveat (best-effort, never buffers): a span ends when its
+ * callback's value (or promise) settles. For the streaming phases (request,
+ * render, ssr) that is when the Response / HTML / RSC stream is CONSTRUCTED, not
+ * when the body finishes draining — instrumentation never wraps or buffers the
+ * response body, so it cannot regress response latency or streaming. A loader /
+ * Suspense child that resolves while the body streams therefore keeps a
+ * rango.loader span that can extend past its render parent; overlapping spans are
+ * valid (the loader really did take that long). Phase spans bound the work up to
+ * stream-handoff, which is also what the co-emitted perf metric measures.
+ * rango.response makes that handoff boundary explicit: it wraps only response
+ * finalization (redirect interception/guarding, Server-Timing mutation, final
+ * response selection) after downstream execution returns, ending immediately
+ * before the handler returns the Response to the host. It is handoff-bound,
+ * never drain-bound — it never reads, tees, or awaits response.body, and it is
+ * absent when the request throws before a response exists.
+ *
+ * rango.background wraps DETACHED work (waitUntil tasks that outlive the
+ * response): PPR shell captures and SWR background revalidations. It is the
+ * explanatory parent for spans those tasks produce after the foreground
+ * phases ended — without it, post-handoff work reads as orphan spans dangling
+ * under an ended parent. See PHASES.background (instrument.ts) for the lane
+ * kinds and per-lane inner-span policy.
+ *
+ * Both shipped runners (Cloudflare, OTel) keep the core agnostic: the
+ * platform-specific bridge lives at the edge behind the SpanRunner contract.
+ */
+/**
+ * Minimal span handle passed to traced work. Structurally compatible with both
+ * Cloudflare's `Span` and OTel's `Span` (only setAttribute is used here).
+ */
+export interface TraceSpan {
+    setAttribute(key: string, value: string | number | boolean): void;
+}
+/**
+ * Wraps a unit of work in a span. A runner MUST invoke fn exactly once, pass it
+ * a span, return fn's result unchanged, and propagate thrown errors / rejected
+ * promises unchanged. When fn returns a promise the span ends once it settles.
+ */
+export type SpanRunner = <T>(name: string, fn: (span: TraceSpan) => T) => T;
+/** The router phases that can be wrapped in a span. */
+export type TracePhase = "request" | "middleware" | "action" | "loader" | "handler" | "render" | "ssr" | "response" | "background";
+/**
+ * Per-phase span toggles. Omitted phases default to enabled. Derived from
+ * TracePhase so a new phase cannot be silently missing here — the other phase
+ * lists in this file (ALL_PHASES_ON, resolveTracing) are exhaustiveness-checked
+ * by their Record<TracePhase, boolean> annotations.
+ */
+export type TracePhaseToggles = Partial<Record<TracePhase, boolean>>;
+/**
+ * The option pair shared by every tracing factory (enabled master switch +
+ * per-phase span toggles). Extended by OTelTracingOptions,
+ * CloudflareTracingOptions, VercelTracingOptions, and RouterTracingConfig so
+ * a phase added to TracePhaseToggles propagates everywhere from one place.
+ */
+export interface TracingToggleOptions {
+    /** Master switch. Defaults to true. */
+    enabled?: boolean;
+    /** Per-phase span toggles. Omitted phases default to enabled. */
+    spans?: TracePhaseToggles;
+}
+/**
+ * Value passed to `createRouter({ tracing })`. Produced by a platform factory
+ * such as `createCloudflareTracing()`.
+ */
+export interface RouterTracingConfig extends TracingToggleOptions {
+    /** Platform span runner. */
+    runner: SpanRunner;
+}
+/**
+ * Resolved tracing state stored on the router/request context. `undefined`
+ * means tracing is fully disabled and every traceSpan() call is a pass-through.
+ */
+export interface ResolvedTracing {
+    runner: SpanRunner;
+    phases: Record<TracePhase, boolean>;
+}
+/** Shared no-op span. setAttribute is a no-op so disabled call sites stay free. */
+export declare const NOOP_TRACE_SPAN: TraceSpan;
+/**
+ * Resolve a user-supplied tracing config into the fast internal form, or
+ * `undefined` when tracing is off (no config, `enabled: false`, or no runner).
+ */
+export declare function resolveTracing(config: RouterTracingConfig | undefined): ResolvedTracing | undefined;
+/**
+ * Wrap `fn` in a span for `phase`. When tracing is off (or the phase is
+ * disabled) fn runs directly with a no-op span — identical to the untraced
+ * path. Otherwise the platform runner wraps fn so the span covers the real
+ * work and nests by async context.
+ */
+export declare function traceSpan<T>(tracing: ResolvedTracing | undefined, phase: TracePhase, name: string, fn: (span: TraceSpan) => T): T;
+/**
+ * Run `fn` once and invoke `onSettle` exactly once when it terminates — on a
+ * synchronous return, a synchronous throw, an async resolution, or an async
+ * rejection. `onSettle` receives the error (or `undefined` on success). fn's
+ * value is returned and errors propagate unchanged.
+ *
+ * Centralizes the run-once-then-settle control flow shared by the two span
+ * surfaces: observePhase records the perf metric on settle, and the OTel runner
+ * ends (or error-marks) the span on settle. The Cloudflare runner delegates
+ * settling to enterSpan, so it does not use this.
+ */
+export declare function runThenSettle<T>(fn: () => T, onSettle: (error: unknown) => void): T;

package/dist/types/router/transition-when.d.ts

@@ -0,0 +1,13 @@
+import { type EntryData } from "../server/context.js";
+import type { RequestContext } from "../server/request-context.js";
+import type { TransitionWhenContext } from "../types/segments.js";
+export type TransitionWhenErrorReporter = (error: unknown, segmentId: string) => void;
+export declare function createTransitionWhenContext<TEnv>(ctx: RequestContext<TEnv>, target?: {
+    params: Record<string, string>;
+    routeName?: string;
+}): TransitionWhenContext<Record<string, string>, TEnv>;
+/** Evaluate server-only transition gates before handlers on a PPR route. */
+export declare function evaluatePprTransitionWhen<TEnv>(entries: EntryData[], ctx: RequestContext<TEnv>, target: {
+    params: Record<string, string>;
+    routeName?: string;
+}, reportError: TransitionWhenErrorReporter): void;

package/dist/types/router/trie-matching.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Runtime Trie Matching
+ *
+ * Walks the pre-built trie by path segments in O(path_length) time.
+ * Falls back to null when no match is found (caller uses regex fallback).
+ */
+import type { TrieNode, NegotiateVariant } from "./route-trie-builder.js";
+export interface TrieMatchResult {
+    /** Route name */
+    routeKey: string;
+    /** Static prefix of the matched entry */
+    sp: string;
+    /** Matched route params */
+    params: Record<string, string>;
+    /** Redirect target if trailing slash requires it */
+    redirectTo?: string;
+    /** Route has pre-rendered data available */
+    pr?: true;
+    /** Passthrough: handler kept for live fallback on unknown params */
+    pt?: true;
+    /** Response type for non-RSC routes (json, text, image, any) */
+    responseType?: string;
+    /** Negotiate variants: response-type routes sharing this path */
+    negotiateVariants?: NegotiateVariant[];
+    /** RSC-first: RSC route was defined before response-type variants */
+    rscFirst?: true;
+}
+/**
+ * Try to match a pathname against the trie.
+ * Returns null if no match found (caller should fall back to regex).
+ */
+export declare function tryTrieMatch(trie: TrieNode | null, pathname: string): TrieMatchResult | null;