@rangojs/router 0.0.0-experimental.130 → 0.0.0-experimental.132

package/src/build/route-types/per-module-writer.ts

@@ -3,7 +3,10 @@ import ts from "typescript";
 import { extractParamsFromPattern } from "./param-extraction.js";
 import { extractRoutesFromSource } from "./ast-route-extraction.js";
 import { generatePerModuleTypesSource } from "./codegen.js";
-import { buildCombinedRouteMapWithSearch } from "./include-resolution.js";
+import {
+  buildCombinedRouteMapWithSearch,
+  createScanMemo,
+} from "./include-resolution.js";
 import type { ScanFilter } from "./scan-filter.js";
 import { findTsFiles } from "./scan-filter.js";
 
@@ -78,10 +81,20 @@ export function writePerModuleRouteTypesForFile(filePath: string): void {
     if (varNames.length > 0) {
       // Follow includes recursively via the combined route map builder.
       // The visited set in buildCombinedRouteMapWithSearch prevents infinite loops.
+      // Share one per-file scan memo across all urls() variables so a shared
+      // include target is read+parsed once for this file, not once per variable.
       routes = [];
+      const memo = createScanMemo();
       for (const varName of varNames) {
         const { routes: routeMap, searchSchemas } =
-          buildCombinedRouteMapWithSearch(filePath, varName);
+          buildCombinedRouteMapWithSearch(
+            filePath,
+            varName,
+            undefined,
+            undefined,
+            undefined,
+            memo,
+          );
         for (const [name, pattern] of Object.entries(routeMap)) {
           const params = extractParamsFromPattern(pattern);
           routes.push({

package/src/cache/cache-key-utils.ts

@@ -6,24 +6,45 @@
  * document-cache, and loader-cache.
  */
 
+import { encodeKV } from "../encode-kv.js";
+
+/**
+ * Reserved URL query params that the router owns and must never key the cache
+ * on. `_rsc*` is the router's internal navigation/action/loader prefix (matched
+ * by prefix). `__no_cache` is the single `__`-prefixed param the router reads
+ * (handler.ts / testing dispatch.ts use it to bypass the store); it and the
+ * other router-internal `__`-prefixed request params are matched by an EXACT
+ * allowlist, not a blanket `__` prefix. A blanket `__` filter would silently
+ * collapse consumer params like `__variant=a` vs `__variant=b` onto one cache
+ * slot; an allowlist keeps the router's own params out of the key while leaving
+ * consumer `__` params intact.
+ */
+const RESERVED_SEARCH_PARAMS = new Set([
+  "__no_cache",
+  "__rsc",
+  "__html",
+  "__debug_manifest",
+  "__prerender_collect",
+]);
+
+function isReservedSearchParam(key: string): boolean {
+  return key.startsWith("_rsc") || RESERVED_SEARCH_PARAMS.has(key);
+}
+
 /**
  * Build a sorted, deterministic query string from URLSearchParams,
- * excluding internal _rsc* and __* params.
+ * excluding the router's reserved params (see isReservedSearchParam).
  *
  * Returns empty string when no user-facing params exist.
  */
 export function sortedSearchString(searchParams: URLSearchParams): string {
   const pairs: [string, string][] = [];
   for (const [k, v] of searchParams) {
-    if (!k.startsWith("_rsc") && !k.startsWith("__")) {
+    if (!isReservedSearchParam(k)) {
       pairs.push([k, v]);
     }
   }
-  if (pairs.length === 0) return "";
-  pairs.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-  return pairs
-    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
-    .join("&");
+  return encodeKV(pairs, { sort: true });
 }
 
 /**
@@ -35,10 +56,5 @@ export function sortedRouteParams(
   params: Record<string, string> | undefined,
 ): string {
   if (!params) return "";
-  const entries = Object.entries(params);
-  if (entries.length === 0) return "";
-  return entries
-    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
-    .join("&");
+  return encodeKV(Object.entries(params), { sort: true });
 }

package/src/cache/cf/cf-cache-store.ts

@@ -1177,6 +1177,45 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     else void write();
   }
 
+  /**
+   * Document-tier counterpart of markRevalidating for getResponse's herd guard.
+   * The segment/item tiers JSON-parse the body, so they re-put with a string
+   * body; document bodies are streamed verbatim, so we re-put with a CLONED
+   * response body (`response.clone()`) supplied by the caller -- the original
+   * body still streams to the client while the marker carries the clone. Same
+   * REVALIDATING status header, same revalidating-at stamp, same
+   * remainingCacheControl re-put math as markRevalidating, so the document tier
+   * suppresses concurrent revalidation for the identical MAX_REVALIDATION_INTERVAL
+   * window the segment tier does. Best-effort and non-blocking: a failed marker
+   * write must not affect the served stale read.
+   * @internal
+   */
+  private markResponseRevalidating(
+    cache: Cache,
+    request: Request,
+    clonedResponse: Response,
+  ): void {
+    const reputNow = Date.now();
+    const headers = new Headers(clonedResponse.headers);
+    headers.set(CACHE_STATUS_HEADER, "REVALIDATING");
+    headers.set(CACHE_REVALIDATING_AT_HEADER, String(reputNow));
+    headers.set("Cache-Control", remainingCacheControl(headers, reputNow));
+    const markerResponse = new Response(clonedResponse.body, {
+      status: clonedResponse.status,
+      statusText: clonedResponse.statusText,
+      headers,
+    });
+    const write = async (): Promise<void> => {
+      try {
+        await cache.put(request, markerResponse);
+      } catch {
+        // Best-effort: see markRevalidating.
+      }
+    };
+    if (this.waitUntil) this.waitUntil(write);
+    else void write();
+  }
+
   // ============================================================================
   // Segment Cache Methods
   // ============================================================================
@@ -1592,7 +1631,23 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
       // Check staleness
       const staleAt = Number(response.headers.get(CACHE_STALE_AT_HEADER) || 0);
-      const isStale = staleAt > 0 && Date.now() > staleAt;
+      const now = Date.now();
+      const isStale = staleAt > 0 && now > staleAt;
+
+      // Thundering-herd guard, mirroring the segment (get) and item (getItem)
+      // tiers. Without it, every concurrent stale reader returned
+      // shouldRevalidate=true and document-cache.ts scheduled a fresh render for
+      // each one. Recency comes from our own revalidating-at stamp, not CF's Age
+      // header (see CACHE_REVALIDATING_AT_HEADER); an absent/zero stamp counts as
+      // "not recent" so a dropped revalidation re-arms instead of pinning.
+      const status = response.headers.get(CACHE_STATUS_HEADER);
+      const revalidatingAt = Number(
+        response.headers.get(CACHE_REVALIDATING_AT_HEADER) ?? "0",
+      );
+      const isRevalidating =
+        status === "REVALIDATING" &&
+        revalidatingAt > 0 &&
+        now - revalidatingAt < MAX_REVALIDATION_INTERVAL * 1000;
 
       // L1 document bodies are streamed through verbatim - unlike the segment/
       // item tiers (which JSON-parse and so structurally detect corruption) and
@@ -1601,9 +1656,25 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // response atomically or fails, so a truncated body is not served back. We
       // deliberately do NOT buffer+hash the body to re-verify it: that would
       // defeat streaming the document and add a full read to every cache hit.
+
+      if (isStale && !isRevalidating) {
+        // First stale reader within the window: mark REVALIDATING (non-blocking,
+        // best-effort) so concurrent readers below see the guard and suppress,
+        // then return shouldRevalidate=true so this caller revalidates. Clone the
+        // matched response for the marker since its original body must still
+        // stream to the client.
+        this.markResponseRevalidating(cache, request, response.clone());
+        return {
+          response: this.toClientResponse(response),
+          shouldRevalidate: true,
+        };
+      }
+
+      // Fresh, or stale-but-already-REVALIDATING: serve without scheduling a
+      // (re-)revalidation. A recent marker already has a render in flight.
       return {
         response: this.toClientResponse(response),
-        shouldRevalidate: isStale,
+        shouldRevalidate: false,
       };
     } catch (error) {
       reportCacheError(error, "cache-read", "[CFCacheStore] getResponse");
@@ -1630,6 +1701,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     headers.delete(CACHE_STATUS_HEADER);
     headers.delete(CACHE_TAGS_HEADER);
     headers.delete(CACHE_TAGGED_AT_HEADER);
+    // Internal stale-path bookkeeping (hard-expiry deadline + REVALIDATING
+    // stamp). Carried on doc L1 entries for the herd guard; never serve them.
+    headers.delete(CACHE_EXPIRES_AT_HEADER);
+    headers.delete(CACHE_REVALIDATING_AT_HEADER);
     // Finding #3 (read side): strip per-client signals a pre-fix or
     // pinned-version L1 entry may carry. See the read-side note in the design doc.
     stripPerClientSignals(headers);
@@ -1683,6 +1758,11 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       }
       headers.set("Cache-Control", `public, max-age=${totalTtl}`);
       headers.set(CACHE_STALE_AT_HEADER, String(staleAt));
+      // Absolute hard-expiry deadline so a stale-path REVALIDATING re-put can
+      // recompute a shrinking max-age (remainingCacheControl) instead of
+      // restarting retention. Mirrors set()/setItem(). Stripped by
+      // toClientResponse before serving.
+      headers.set(CACHE_EXPIRES_AT_HEADER, String(staleAt + swrWindow * 1000));
       // Internal tag headers (stripped by toClientResponse before serving).
       this.setTagHeaders(headers, tags, taggedAt);
 
@@ -1710,7 +1790,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
       // L2: persist to KV (KV requires expirationTtl >= 60s)
       if (this.kv && this.waitUntil && totalTtl >= 60) {
-        const kvKey = this.toKVKey(`doc:${key}`);
+        const kvKey = this.toDocKVKey(key);
         // Finding #3: never persist a per-client signal in the KV envelope.
         const headersArray: [string, string][] = [];
         response.headers.forEach((v, k) => {
@@ -2039,6 +2119,37 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     return `${versionPath}${key}`;
   }
 
+  /**
+   * Host token for the current request, used to namespace the document KV key.
+   * Derived from the same resolveBaseUrl() that namespaces the L1 (Cache API)
+   * tier, so a doc entry's KV twin lands under the identical host bucket.
+   * Falls back to "_" if the base URL cannot be parsed (it always carries a
+   * trailing-slash origin, so parsing succeeds in practice).
+   * @internal
+   */
+  private docKVHost(): string {
+    try {
+      return new URL(this.resolveBaseUrl()).host || "_";
+    } catch {
+      return "_";
+    }
+  }
+
+  /**
+   * Convert a document key to its host-namespaced KV key. The L1 tier already
+   * namespaces document entries by host via keyToRequest/resolveBaseUrl, but the
+   * KV fallback keyed only on `doc:{key}`, so two hosts serving the same path
+   * could collide on the KV tier (one host serving another's cached document).
+   * Prefixing the host closes that cross-host collision. Deterministic per
+   * (host, key). Segment/fn/tag-marker KV keys keep toKVKey unchanged: tag
+   * markers are intentionally global (invalidation must cross hosts), and the
+   * document tier is the one with a request-host context here.
+   * @internal
+   */
+  private toDocKVKey(key: string): string {
+    return this.toKVKey(`h/${this.docKVHost()}/doc:${key}`);
+  }
+
   /**
    * Best-effort delete of a single KV key, reporting (not swallowing) a delete
    * failure as cache-delete. Used by the corrupt-entry self-heal paths.
@@ -2203,9 +2314,17 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     const rawTaggedAt = headers.get(CACHE_TAGGED_AT_HEADER);
     if (!rawTags || !rawTaggedAt) return {};
     try {
+      const taggedAt = Number(rawTaggedAt);
+      // A corrupt/non-numeric tagged-at header yields NaN. isGloballyInvalidated
+      // short-circuits on a falsy taggedAt (NaN is falsy), so returning
+      // { taggedAt: NaN } would make the entry permanently NON-invalidatable -
+      // a revalidateTag could never evict it. Treat a non-finite stamp the same
+      // as the missing-header case (untagged): drop both tags and taggedAt so the
+      // entry is re-rendered/re-tagged rather than silently un-invalidatable.
+      if (!Number.isFinite(taggedAt)) return {};
       return {
         tags: JSON.parse(decodeURIComponent(rawTags)) as string[],
-        taggedAt: Number(rawTaggedAt),
+        taggedAt,
       };
     } catch {
       return {};
@@ -2858,7 +2977,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv) return null;
 
     try {
-      const kvKey = this.toKVKey(`doc:${key}`);
+      const kvKey = this.toDocKVKey(key);
       // The document path is debug-silent (op is only get/getItem): a KV-read
       // timeout here is bounded for resilience parity (kvGetOrEvict applies the
       // budget) but emits no kv-timeout event, so its absence from the debug
@@ -2951,6 +3070,11 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           }
           headers.set("Cache-Control", `public, max-age=${remainingTtl}`);
           headers.set(CACHE_STALE_AT_HEADER, String(envelope.s));
+          // Carry the hard-expiry deadline so the document herd guard's
+          // markResponseRevalidating re-put can compute the remaining window
+          // (matches promoteSegmentToL1/promoteItemToL1); without it a stale
+          // re-put would floor to max-age=1 and churn the KV-promoted twin.
+          headers.set(CACHE_EXPIRES_AT_HEADER, String(envelope.e));
           // Re-attach the internal tag headers (envelope.hd is client-facing
           // and intentionally excludes them) so the promoted entry stays
           // invalidatable.

package/src/decode-loader-results.ts

@@ -28,7 +28,17 @@ export function decodeLoaderResults(
     if (result.fallback) {
       errorFallback = result.fallback;
     } else {
-      throw new Error(result.error.message);
+      // No boundary: rethrow preserving the ErrorInfo identity (name/stack/
+      // code/cause) instead of a stripped generic Error.
+      const info = result.error;
+      const err = new Error(
+        info.message,
+        info.cause !== undefined ? { cause: info.cause } : undefined,
+      );
+      if (info.name) err.name = info.name;
+      if (info.stack) err.stack = info.stack;
+      if (info.code !== undefined) (err as { code?: string }).code = info.code;
+      throw err;
     }
   }
 

package/src/encode-kv.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared key=value serialization core.
+ *
+ * One encode+join rule shared by every deterministic query-string serializer
+ * in the codebase (cache keys, route-param strings, search-param strings,
+ * prerender param hashes). Each call site differs only in how it pre-filters
+ * and orders the pairs it hands in, plus whether it sorts; the encoding itself
+ * (`encodeURIComponent(k)=encodeURIComponent(v)` joined by `&`) is identical.
+ *
+ * Dependency-free leaf module so any layer (build-time prerender hashing,
+ * runtime cache keys, client search-param serialization) can import it without
+ * pulling in cache/router internals.
+ */
+
+export interface EncodeKVOptions {
+  /**
+   * Sort pairs by key in codepoint (byte) order before joining. Byte order via
+   * the `<` operator, NOT localeCompare, so the result is identical across
+   * Node, Workers, and browsers regardless of runtime locale.
+   *
+   * Defaults to false (insertion order preserved).
+   */
+  sort?: boolean;
+}
+
+/**
+ * Serialize an array of [key, value] pairs to a deterministic query string
+ * (no leading `?`). Both key and value are passed through encodeURIComponent
+ * so a key/value containing `&` or `=` cannot collide with a structurally
+ * different pair set.
+ *
+ * Callers are responsible for any filtering (e.g. dropping reserved params) and
+ * any value coercion (e.g. String(v), skipping null/undefined) BEFORE calling.
+ * This function never inspects or skips values; it encodes exactly what it is
+ * given so each call site keeps its own existing output.
+ */
+export function encodeKV(
+  pairs: Iterable<readonly [string, string]>,
+  options: EncodeKVOptions = {},
+): string {
+  const list = [...pairs];
+  if (list.length === 0) return "";
+  if (options.sort) {
+    list.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  }
+  return list
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+    .join("&");
+}

package/src/handles/meta.ts

@@ -193,8 +193,12 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
           continue;
         }
 
+        // Insert the title literally. String.prototype.replace treats the
+        // replacement string specially ($&, $`, $', $$, $n), so a title like
+        // "Save $5" or one containing "$&" would be mangled. split/join inserts
+        // the raw value with no special-character interpretation.
         const finalTitle = titleTemplate
-          ? titleTemplate.replace("%s", titleValue as string)
+          ? titleTemplate.split("%s").join(titleValue as string)
           : titleValue;
         addOrReplace(
           result,

package/src/host/cookie-handler.ts

@@ -6,29 +6,10 @@ import {
   InvalidHostnameError,
   HostValidationError,
 } from "./errors.js";
+import { parseCookiesFromHeader } from "../server/cookie-parse.js";
 
 export function parseCookies(request: Request): Record<string, string> {
-  const cookieHeader = request.headers.get("cookie");
-  if (!cookieHeader) {
-    return {};
-  }
-
-  const cookies: Record<string, string> = {};
-  const pairs = cookieHeader.split(";");
-
-  for (const pair of pairs) {
-    const [name, ...rest] = pair.trim().split("=");
-    if (name && rest.length > 0) {
-      const value = rest.join("=");
-      try {
-        cookies[name] = decodeURIComponent(value);
-      } catch {
-        cookies[name] = value;
-      }
-    }
-  }
-
-  return cookies;
+  return parseCookiesFromHeader(request.headers.get("cookie"));
 }
 
 export function getCookie(request: Request, name: string): string | undefined {

package/src/prerender/param-hash.ts

@@ -4,16 +4,17 @@
  * DJB2-based; works in all JS environments without crypto imports.
  */
 
+import { encodeKV } from "../encode-kv.js";
+
 // For static routes (no params), returns "_".
 export function hashParams(params: Record<string, string>): string {
   const entries = Object.entries(params);
   if (entries.length === 0) return "_";
 
-  const sorted = entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-  const str = sorted
-    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
-    .join("&");
-  return djb2Hex(str);
+  // Byte-order sort + encodeURIComponent join (see encodeKV); output is
+  // byte-identical to the prior inline implementation, so build-time and
+  // runtime hashes stay stable.
+  return djb2Hex(encodeKV(entries, { sort: true }));
 }
 
 /**

package/src/regex-escape.ts

@@ -0,0 +1,8 @@
+/**
+ * Escape a string for literal use inside a RegExp. Single source of truth for
+ * the router runtime (matching) and the vite build (transform/scan); a pure,
+ * dependency-free leaf so both environments can share it.
+ */
+export function escapeRegExp(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/route-definition/dsl-helpers.ts

@@ -897,7 +897,11 @@ const transition = (
     "transition() must be called inside urls()",
   );
 
-  const name = `$${store.getNextIndex("transition")}`;
+  // Allocate a single index for this transition() call (used in all paths),
+  // mirroring cache() — the child form uses it for the name, the wrapper form
+  // reuses it for the namespace, so no index is burned.
+  const transitionIndex = store.getNextIndex("transition");
+  const name = `$${transitionIndex}`;
 
   if (!children) {
     // Position 1: child of path() — attach to parent entry
@@ -910,7 +914,7 @@ const transition = (
   }
 
   // Position 2: wrapper — create a transparent layout with transition config
-  const namespace = `${ctx.namespace}.${store.getNextIndex("transition")}`;
+  const namespace = `${ctx.namespace}.${transitionIndex}`;
   const entry = {
     ...emptySegmentBase(),
     id: namespace,

package/src/router/error-handling.ts

@@ -169,6 +169,37 @@ export function findNearestNotFoundBoundary(
   return defaultNotFoundBoundary || null;
 }
 
+/**
+ * Normalize an error's cause into a Flight-serializable shape.
+ * ErrorInfo.cause crosses the RSC serialization boundary (via
+ * LoaderDataResult.error + error-segment fallback props); a non-serializable
+ * cause (function, class instance, circular object) would make Flight
+ * serialization throw and mask the original loader error.
+ */
+function normalizeCause(cause: unknown): unknown {
+  if (cause == null) return undefined;
+  const t = typeof cause;
+  if (t === "string" || t === "number" || t === "boolean") return cause;
+  // The whole body is guarded: even `instanceof`/clone can run user code (a
+  // Proxy trap, a throwing getter), and this helper must never throw —
+  // throwing here would mask the original loader error it exists to protect.
+  try {
+    if (cause instanceof Error) {
+      return { name: cause.name, message: cause.message, stack: cause.stack };
+    }
+    // Prefer preserving a serializable object/array intact (Flight uses
+    // structured-clone-like semantics); fall back to a string when the value
+    // is circular, host-bound, or otherwise non-serializable.
+    return structuredClone(cause);
+  } catch {
+    try {
+      return String(cause);
+    } catch {
+      return "[unstringifiable cause]";
+    }
+  }
+}
+
 /**
  * Create ErrorInfo from an error object
  * Sanitizes error details in production
@@ -186,7 +217,7 @@ export function createErrorInfo(
       name: error.name,
       code: (error as any).code,
       stack: isDev ? error.stack : undefined,
-      cause: isDev ? error.cause : undefined,
+      cause: isDev ? normalizeCause(error.cause) : undefined,
       segmentId,
       segmentType,
     };

package/src/router/handler-context.ts

@@ -21,6 +21,11 @@ import { PRERENDER_PASSTHROUGH } from "../prerender.js";
 import { substitutePatternParams } from "./substitute-pattern-params.js";
 import { fireAndForgetWaitUntil } from "../types/request-scope.js";
 
+// Mutating Headers methods guarded so they throw inside "use cache" / cache()
+// scope. Module-level constant (read-only, .has() lookups) so it is allocated
+// once at module load instead of per createHandlerContext (per-request) call.
+const MUTATING_HEADERS_METHODS = new Set(["set", "append", "delete"]);
+
 /**
  * Strip internal _rsc* query params from a URL.
  * Returns a new URL with only user-facing params.
@@ -212,7 +217,7 @@ export function createHandlerContext<TEnv>(
   // Guard mutating Headers methods so they throw inside "use cache" or cache() scope.
   // Uses lazy `ctx` reference (assigned below) — only the specific handler ctx
   // is stamped by cache-runtime, not the shared request context.
-  const MUTATING_HEADERS_METHODS = new Set(["set", "append", "delete"]);
+  // MUTATING_HEADERS_METHODS is hoisted to module scope (constant, read-only).
   let ctx: InternalHandlerContext<any, TEnv>;
   const guardedHeaders = new Proxy(stubResponse.headers, {
     get(target, prop, receiver) {

package/src/router/instrument.ts

@@ -135,13 +135,15 @@ export const PHASES = {
   /** 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 segment id, carried
-   * as the rango.segment_id attribute to match the handler:<id> perf row. */
+   * 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. */
   handler: (id: string): PhaseSpec => ({
     metric: false,
     tracePhase: "handler",
     spanName: "rango.handler",
-    attributes: { "rango.segment_id": id },
+    attributes: { "rango.handler_id": id },
   }),
 
   /** Whole render phase: match + serialize + SSR. The metric label is resolved
@@ -231,26 +233,46 @@ export function observePhase<T>(
   // Neither surface active: direct call, zero overhead.
   if (!store && !tracing) return fn(NOOP_TRACE_SPAN);
 
-  // Attributes only land on a real span, so skip the wrapper when only the perf
-  // surface is active (traceSpan would apply them to NOOP_TRACE_SPAN for nothing).
-  // `lazyAttributes` resolve AFTER fn runs (e.g. rango.route, known post-match).
+  // Attributes only land on a real span. Build the attribute/lazy wrapper only
+  // when this phase's span is actually enabled (not toggled off via `spans`), and
+  // short-circuit inside when the runner hands back the no-op span (tracing
+  // configured but off at runtime — e.g. no executionContext.tracing). That keeps
+  // the "configured but effectively off" path free of per-call attribute loops
+  // and lazy `.then()` allocations. `lazyAttributes` resolve AFTER fn runs (e.g.
+  // rango.route, known post-match) and apply on BOTH success and failure so an
+  // errored phase span is still tagged.
   const attributes = spec.attributes;
   const lazy = spec.lazyAttributes;
+  const spanEnabled =
+    tracing !== undefined && tracing.phases[spec.tracePhase] !== false;
   const wrapped: (span: TraceSpan) => T =
-    (attributes || lazy) && tracing
+    (attributes || lazy) && spanEnabled
       ? (span) => {
+          if (span === NOOP_TRACE_SPAN) return fn(span);
           if (attributes) applyAttributes(span, attributes);
+          // A SYNCHRONOUS throw from fn skips applyLate — fine by design: the only
+          // lazyAttributes phase (render) is always async, so any internal throw
+          // surfaces as a rejection that the onReject branch below DOES tag. If a
+          // sync lazyAttributes phase is ever added, wrap this in try/catch.
           const out = fn(span);
           if (!lazy) return out;
+          const applyLate = () => {
+            const late = lazy();
+            if (late) applyAttributes(span, late);
+          };
           if (out instanceof Promise) {
-            return out.then((value) => {
-              const late = lazy();
-              if (late) applyAttributes(span, late);
-              return value;
-            }) as T;
+            return out.then(
+              (value) => {
+                applyLate();
+                return value;
+              },
+              (error) => {
+                applyLate();
+                throw error;
+              },
+            ) as T;
           }
-          const late = lazy();
-          if (late) applyAttributes(span, late);
+          applyLate();
           return out;
         }
       : fn;
@@ -269,6 +291,26 @@ export function observePhase<T>(
   return runThenSettle(runSpan, () => recordPhaseMetric(store, metric, start));
 }
 
+/**
+ * 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 function observeHandler<C, R>(
+  id: string,
+  handler: (ctx: C) => R,
+  ctx: C,
+): R {
+  const tracing = _getRequestContext()?._tracing;
+  if (!tracing || tracing.phases.handler === false) return handler(ctx);
+  return observePhase(PHASES.handler(id), () => handler(ctx));
+}
+
 /**
  * Emit one discrete telemetry event (the event-shaped counterpart to
  * observePhase). Resolves the sink from the active router context and stamps the