@rangojs/router 0.0.0-experimental.122 → 0.0.0-experimental.125

package/src/router/router-context.ts

@@ -54,10 +54,8 @@ export interface InterceptResult {
  * Instead of passing 20+ parameters, middleware calls getRouterContext() to access them.
  */
 export interface RouterContext<TEnv = any> {
-  // Route matching
   findMatch: (pathname: string) => RouteMatchResult | null;
 
-  // Manifest loading
   loadManifest: (
     entry: any,
     routeKey: string,
@@ -66,10 +64,8 @@ export interface RouterContext<TEnv = any> {
     isSSR?: boolean,
   ) => Promise<EntryData>;
 
-  // Entry traversal
   traverseBack: (entry: EntryData) => Generator<EntryData>;
 
-  // Handler context creation
   createHandlerContext: (
     params: Record<string, string>,
     request: Request,
@@ -83,7 +79,6 @@ export interface RouterContext<TEnv = any> {
     isPassthroughRoute?: boolean,
   ) => HandlerContext<any, TEnv>;
 
-  // Loader setup
   setupLoaderAccess: (
     ctx: HandlerContext<any, TEnv>,
     loaderPromises: Map<string, Promise<any>>,
@@ -94,7 +89,6 @@ export interface RouterContext<TEnv = any> {
     loaderPromises: Map<string, Promise<any>>,
   ) => void;
 
-  // Context access
   getContext: () => {
     getOrCreateStore: (key: string) => any;
     runWithStore: <T>(
@@ -105,16 +99,13 @@ export interface RouterContext<TEnv = any> {
     ) => T;
   };
 
-  // Metrics
   getMetricsStore: () => MetricsStore | undefined;
 
-  // Cache
   createCacheScope: (
     cacheConfig: any,
     parent: CacheScope | null,
   ) => CacheScope | null;
 
-  // Intercept detection
   findInterceptForRoute: (
     routeKey: string,
     parentEntry: EntryData | null,
@@ -122,7 +113,6 @@ export interface RouterContext<TEnv = any> {
     isAction: boolean,
   ) => InterceptResult | null;
 
-  // Segment resolution (with revalidation)
   resolveAllSegmentsWithRevalidation: (
     entries: EntryData[],
     routeKey: string,
@@ -166,12 +156,10 @@ export interface RouterContext<TEnv = any> {
     revalidationContext?: RevalidationContext,
   ) => Promise<ResolvedSegment[]>;
 
-  // Collect with markers
   collectWithMarkers?: <T>(
     gen: AsyncGenerator<T | { __type: "id"; id: string }>,
   ) => Promise<{ items: T[]; matchedIds: string[] }>;
 
-  // Revalidation evaluation
   evaluateRevalidation: (params: {
     segment: ResolvedSegment;
     prevParams: Record<string, string>;
@@ -195,7 +183,6 @@ export interface RouterContext<TEnv = any> {
       | "intercept-loader";
   }) => Promise<boolean>;
 
-  // Request context
   getRequestContext: () =>
     | {
         waitUntil: (fn: () => Promise<void>) => void;
@@ -203,7 +190,6 @@ export interface RouterContext<TEnv = any> {
       }
     | undefined;
 
-  // Simple segment resolution (without revalidation - for full match)
   resolveAllSegments: (
     entries: EntryData[],
     routeKey: string,
@@ -213,7 +199,6 @@ export interface RouterContext<TEnv = any> {
     options?: { skipLoaders?: boolean },
   ) => Promise<ResolvedSegment[]>;
 
-  // Generator-based simple resolution
   resolveAllSegmentsGenerator?: (
     entries: EntryData[],
     routeKey: string,
@@ -222,21 +207,17 @@ export interface RouterContext<TEnv = any> {
     loaderPromises: Map<string, Promise<any>>,
   ) => AsyncGenerator<ResolvedSegment | { __type: "id"; id: string }>;
 
-  // Collect segments from generator
   collectSegmentsFromGenerator?: <T>(
     gen: AsyncGenerator<T | { __type: "id"; id: string }>,
   ) => Promise<T[]>;
 
-  // Handle store
   createHandleStore: () => any;
 
-  // Loaders-only resolution (for full match cache hit - no revalidation)
   resolveLoadersOnly?: (
     entries: EntryData[],
     handlerContext: HandlerContext<any, TEnv>,
   ) => Promise<ResolvedSegment[]>;
 
-  // Loaders-only resolution (for cache hit scenarios)
   resolveLoadersOnlyWithRevalidation?: (
     entries: EntryData[],
     handlerContext: HandlerContext<any, TEnv>,
@@ -258,10 +239,8 @@ export interface RouterContext<TEnv = any> {
   // Telemetry sink (optional, no-op when undefined)
   telemetry?: TelemetrySink;
 
-  // Request ID for telemetry span correlation (set per-request in match handlers)
   requestId?: string;
 
-  // Intercept loaders only (for cache hit + intercept scenarios)
   resolveInterceptLoadersOnly?: (
     intercept: InterceptEntry,
     entry: EntryData,
@@ -284,7 +263,6 @@ export interface RouterContext<TEnv = any> {
   } | null>;
 }
 
-// AsyncLocalStorage instance for router context
 const routerContext = new AsyncLocalStorage<RouterContext<any>>();
 
 /**
@@ -308,10 +286,6 @@ export function getRouterContext<TEnv = any>(): RouterContext<TEnv> {
  *
  * All async code within fn() can call getRouterContext() to access router closures.
  * This works across async boundaries thanks to AsyncLocalStorage.
- *
- * @param deps Router dependencies to make available
- * @param fn Function to run with dependencies available
- * @returns Result of fn()
  */
 export function runWithRouterContext<T, TEnv = any>(
   deps: RouterContext<TEnv>,

package/src/router/router-interfaces.ts

@@ -290,6 +290,13 @@ export interface RangoInternal<
    */
   readonly prefetchCacheTTL: number;
 
+  /**
+   * Resolved rango state cookie name (`{prefix}_{routerId}`), composed once at
+   * router init and shipped to the client in payload metadata. The server-side
+   * cookie writer reads it from here; the client reads it from metadata.
+   */
+  readonly resolvedStateCookieName: string;
+
   /**
    * Whether connection warmup is enabled.
    * When true, the client sends HEAD /?_rsc_warmup after idle periods

package/src/router/router-options.ts

@@ -132,6 +132,21 @@ export interface RangoOptions<TEnv = any> {
    */
   allowDebugManifest?: boolean;
 
+  /**
+   * DEVELOPMENT/TEST ONLY. Emit an `X-Rango-Cache` response header describing
+   * the cache status of the matched route, for use by testing primitives such
+   * as `assertCacheStatus`.
+   *
+   * Defaults to `false`. When neither this option nor the
+   * `RANGO_TEST_SIGNALS=1` environment flag is set, NO header is emitted and
+   * router output is byte-identical to the default.
+   *
+   * The header encodes per-segment (v1: coarse route-level) status keyed by the
+   * route NAME, e.g. `X-Rango-Cache: product.detail=hit`. Do NOT enable in
+   * production — it exposes internal cache decisions.
+   */
+  debugCacheSignal?: boolean;
+
   /**
    * Document component that wraps the entire application.
    *
@@ -481,6 +496,21 @@ export interface RangoOptions<TEnv = any> {
    */
   prefetchCacheTTL?: number | false;
 
+  /**
+   * Prefix for the rango state cookie name. The resolved name is
+   * `{prefix}_{routerId}`; the prefix is sanitized to cookie-name-safe
+   * characters (`[A-Za-z0-9-]`) and an empty result falls back to the default.
+   *
+   * The rango state cookie keys the client's prefetch / HTTP caches. Overriding
+   * the prefix lets you align it with cookie-naming policies or consent-manager
+   * classification lists, or avoid colliding with an existing `rango-state`
+   * cookie. It is not a full-name override: the `_{routerId}` suffix is what
+   * keeps sibling apps on one origin from clobbering each other's state.
+   *
+   * @default "rango-state"
+   */
+  stateCookiePrefix?: string;
+
   /**
    * Enable connection warmup to keep TCP+TLS alive after idle periods.
    *

package/src/router/segment-resolution/fresh.ts

@@ -27,59 +27,17 @@ import {
   tryStaticSlot,
   resolveLayoutComponent,
   resolveWithErrorBoundary,
+  warnOnStreamedResponse,
 } from "./helpers.js";
 import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
-import { resolveSink, safeEmit } from "../telemetry.js";
+import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
 import {
   track,
   RangoContext,
   runInsideLoaderScope,
 } from "../../server/context.js";
 
-// ---------------------------------------------------------------------------
-// Streamed handler telemetry
-// ---------------------------------------------------------------------------
-
-/**
- * Attach a fire-and-forget rejection observer to a streamed handler promise.
- * React catches the actual error via its error boundary; this only emits
- * the handler.error telemetry event.
- */
-function observeStreamedHandler(
-  promise: Promise<ReactNode>,
-  segmentId: string,
-  segmentType: string,
-  pathname?: string,
-  routeKey?: string,
-  params?: Record<string, string>,
-): void {
-  let routerCtx;
-  try {
-    routerCtx = getRouterContext();
-  } catch {
-    return;
-  }
-  if (!routerCtx?.telemetry) return;
-  const sink = resolveSink(routerCtx.telemetry);
-  const reqId = routerCtx.requestId;
-  promise.catch((err: unknown) => {
-    const errorObj = err instanceof Error ? err : new Error(String(err));
-    safeEmit(sink, {
-      type: "handler.error",
-      timestamp: performance.now(),
-      requestId: reqId,
-      segmentId,
-      segmentType,
-      error: errorObj,
-      handledByBoundary: true,
-      pathname,
-      routeKey,
-      params,
-    });
-  });
-}
-
 // ---------------------------------------------------------------------------
 // Fresh path (full match, no revalidation)
 // ---------------------------------------------------------------------------
@@ -133,18 +91,32 @@ export async function resolveLoaders<TEnv>(
 
   // Loading disabled: still start all loaders in parallel, but only emit
   // settled promises so handlers don't stream loading placeholders.
-  const pendingLoaderData = loaderEntries.map((loaderEntry) => {
+  //
+  // Wrap each loader promise with wrapLoaderPromise BEFORE awaiting. The wrapped
+  // promise resolves to a LoaderDataResult and never rejects, routing a failed
+  // loader to its own per-loader error boundary. Awaiting the RAW promises here
+  // instead would (1) propagate a rejection to the segment-level boundary,
+  // collapsing the whole entry and discarding successful sibling data, and
+  // (2) leave the other in-flight raw promises without a .catch, producing
+  // unhandled rejections. Mirrors the loading path and intercept-resolution.
+  const pendingLoaderData = loaderEntries.map((loaderEntry, i) => {
+    const { loader } = loaderEntry;
+    const segmentId = `${shortCode}D${i}.${loader.$$id}`;
     const start = performance.now();
-    const promise = runInsideLoaderScope(() =>
-      resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+    const wrapped = deps.wrapLoaderPromise(
+      runInsideLoaderScope(() =>
+        resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+      ),
+      entry,
+      segmentId,
+      ctx.pathname,
     );
-    return { promise, start, loaderId: loaderEntry.loader.$$id };
+    return { wrapped, start, segmentId, loaderId: loader.$$id };
   });
-  await Promise.all(pendingLoaderData.map((p) => p.promise));
+  await Promise.all(pendingLoaderData.map((p) => p.wrapped));
 
   return loaderEntries.map((loaderEntry, i) => {
     const { loader } = loaderEntry;
-    const segmentId = `${shortCode}D${i}.${loader.$$id}`;
     const pending = pendingLoaderData[i]!;
     if (ms && !ms.metrics.some((m) => m.label === `loader:${loader.$$id}`)) {
       // All loaders ran in parallel via Promise.all — each span covers
@@ -160,19 +132,14 @@ export async function resolveLoaders<TEnv>(
       );
     }
     return {
-      id: segmentId,
+      id: pending.segmentId,
       namespace: entry.id,
       type: "loader" as const,
       index: i,
       component: null,
       params: ctx.params,
       loaderId: loader.$$id,
-      loaderData: deps.wrapLoaderPromise(
-        pending.promise,
-        entry,
-        segmentId,
-        ctx.pathname,
-      ),
+      loaderData: pending.wrapped,
       belongsToRoute,
     };
   });
@@ -297,6 +264,7 @@ export async function resolveSegment<TEnv>(
       if (entry.loading) {
         const result = handleHandlerResult(handler(context));
         if (result instanceof Promise) {
+          warnOnStreamedResponse(result, entry.id);
           result.finally(doneRouteHandler).catch(() => {});
           const tracked = deps.trackHandler(result, {
             segmentId: entry.shortCode,

package/src/router/segment-resolution/helpers.ts

@@ -52,6 +52,40 @@ export function handleHandlerResult(
   return result;
 }
 
+/**
+ * Dev-only: warn when a handler on a route that declares loading() resolves or
+ * rejects with a Response (e.g. redirect()).
+ *
+ * On a non-loading route a returned/thrown Response short-circuits to an HTTP
+ * redirect. But when the route declares loading(), the handler result is
+ * streamed (not awaited at the resolution boundary), so the Response surfaces
+ * only during RSC serialization and is rendered into the stream instead of
+ * becoming a 302/308 — a silent failure mode. Issue redirects from middleware,
+ * a loader, or a synchronous handler return instead. Compiled out in production.
+ */
+export function warnOnStreamedResponse(
+  result: Promise<unknown>,
+  entryId: string,
+): void {
+  if (process.env.NODE_ENV === "production") return;
+  // A Response can surface either as a rejection (handleHandlerResult rethrows a
+  // resolved Response) or as a resolved value (the raw parallel-slot handler is
+  // not run through handleHandlerResult). Check both so every streamed path is
+  // covered. Each handler is an independent observer; it does not consume the
+  // rejection for the trackHandler/observeStreamedHandler chains.
+  const check = (value: unknown) => {
+    if (value instanceof Response) {
+      console.warn(
+        `[rango] Handler for "${entryId}" returned a Response (e.g. ` +
+          `redirect()), but it declares loading(): the Response is rendered ` +
+          `into the RSC stream, NOT sent as an HTTP redirect. Issue redirects ` +
+          `from middleware, a loader, or a synchronous handler return.`,
+      );
+    }
+  };
+  result.then(check, check);
+}
+
 // ---------------------------------------------------------------------------
 // Static handler interception
 // ---------------------------------------------------------------------------

package/src/router/segment-resolution/loader-cache.ts

@@ -8,7 +8,7 @@
  * Cache key resolution (3-tier, matching CacheScope.resolveKey):
  *   1. options.key(requestCtx) — full override
  *   2. store.keyGenerator(requestCtx, defaultKey) — store-level modification
- *   3. loader:{loaderId}:{pathname}:{sortedParams} — default
+ *   3. loader:{loaderId}:{host}{pathname}:{sortedParams} — default
  *
  * Values are serialized via RSC Flight (serializeResult/deserializeResult),
  * supporting ReactNode, Promises, null, and all RSC-serializable types.
@@ -57,12 +57,13 @@ function debugLoaderCacheLog(message: string): void {
 
 function getDefaultLoaderCacheKey(
   loaderId: string,
+  host: string,
   pathname: string,
   params: Record<string, string>,
 ): string {
   const paramStr = sortedRouteParams(params);
   const base = paramStr ? `${pathname}:${paramStr}` : pathname;
-  return `loader:${loaderId}:${base}`;
+  return `loader:${loaderId}:${host}${base}`;
 }
 
 /**
@@ -76,7 +77,13 @@ async function resolveLoaderKey(
   params: Record<string, string>,
 ): Promise<string> {
   const options = loaderEntry.cache!.options;
-  const defaultKey = getDefaultLoaderCacheKey(loaderId, pathname, params);
+  // The host is part of the loader cache identity, matching the route-level
+  // cache (cache-scope getCacheKeyBase: `${host}${pathname}`) and "use cache"
+  // (cache-runtime pushes ctx.url.host). Without it, a multi-tenant host router
+  // serving the same pathname for different hosts would leak one host's cached
+  // loader data to another.
+  const host = getRequestContext()?.url?.host ?? "localhost";
+  const defaultKey = getDefaultLoaderCacheKey(loaderId, host, pathname, params);
   if (options === false) return defaultKey;
   return resolveCacheKey(options.key, store, defaultKey, "LoaderCache");
 }
@@ -139,14 +146,8 @@ export function resolveLoaderData<TEnv>(
   const swrWindow = resolveSwrWindow(options.swr, store.defaults);
   const swr = swrWindow || undefined;
   const tags = resolveTags(loaderEntry);
-  // Loader tags are config-derived, so they are the complete set whether this is
-  // a cache hit or miss; record them every time so a document built from this
-  // loader is tagged for invalidation.
   recordRequestTags(tags);
 
-  // Wrap ctx.use() so cache HIT primes the handler's memoization map.
-  // ctx.use() closes over the match context's loaderPromises (not request context's).
-  // By intercepting ctx.use(), we inject cached data into the correct map.
   const originalUse = ctx.use;
   const dataPromise = (async () => {
     const codec = await getCodec();
@@ -174,10 +175,6 @@ export function resolveLoaderData<TEnv>(
     });
   })();
 
-  // Temporarily replace ctx.use() so the handler's call returns cached data.
-  // This is needed because ctx.use() closes over the match context's loaderPromises
-  // map which is separate from the request context. By wrapping use(), we intercept
-  // the handler's call and return the shared dataPromise.
   const wrappedUse = ((item: any) => {
     if (item === loaderEntry.loader || item?.$$id === loaderId) {
       return dataPromise;

package/src/router/segment-resolution/revalidation.ts

@@ -34,6 +34,7 @@ import {
 import { resolveLoaderData } from "./loader-cache.js";
 import {
   handleHandlerResult,
+  warnOnStreamedResponse,
   tryStaticHandler,
   tryStaticSlot,
   resolveLayoutComponent,
@@ -42,54 +43,13 @@ import {
 import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
 import { resolveSink, safeEmit } from "../telemetry.js";
+import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
 import {
   track,
   RangoContext,
   runInsideLoaderScope,
 } from "../../server/context.js";
 
-// ---------------------------------------------------------------------------
-// Telemetry helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Attach a fire-and-forget rejection observer to a streamed handler promise.
- * Silently no-ops when called outside RouterContext (e.g. in unit tests).
- */
-function observeStreamedHandler(
-  promise: Promise<ReactNode>,
-  segmentId: string,
-  segmentType: string,
-  pathname?: string,
-  routeKey?: string,
-  params?: Record<string, string>,
-): void {
-  let routerCtx;
-  try {
-    routerCtx = getRouterContext();
-  } catch {
-    return;
-  }
-  if (!routerCtx?.telemetry) return;
-  const sink = resolveSink(routerCtx.telemetry);
-  const reqId = routerCtx.requestId;
-  promise.catch((err: unknown) => {
-    const errorObj = err instanceof Error ? err : new Error(String(err));
-    safeEmit(sink, {
-      type: "handler.error",
-      timestamp: performance.now(),
-      requestId: reqId,
-      segmentId,
-      segmentType,
-      error: errorObj,
-      handledByBoundary: true,
-      pathname,
-      routeKey,
-      params,
-    });
-  });
-}
-
 /**
  * Trace a parallel slot that's being force-rendered on a full refetch (client
  * has no cached state). User revalidate fns are bypassed in this case — see
@@ -564,6 +524,7 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
           const result =
             typeof handler === "function" ? handler(context) : handler;
           if (result instanceof Promise) {
+            warnOnStreamedResponse(result, parallelId);
             const tracked = deps.trackHandler(result, {
               segmentId: parallelId,
               segmentType: "parallel",
@@ -762,6 +723,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
       if (!actionContext) {
         const result = handleHandlerResult(handler(context));
         if (result instanceof Promise) {
+          warnOnStreamedResponse(result, routeEntry.id);
           result.finally(doneHandler).catch(() => {});
           const tracked = deps.trackHandler(result, {
             segmentId: entry.shortCode,
@@ -1274,6 +1236,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
           const result =
             typeof handler === "function" ? handler(context) : handler;
           if (result instanceof Promise) {
+            warnOnStreamedResponse(result, parallelId);
             const tracked = deps.trackHandler(result, {
               segmentId: parallelId,
               segmentType: "parallel",

package/src/router/segment-resolution/streamed-handler-telemetry.ts

@@ -0,0 +1,52 @@
+/**
+ * Streamed Handler Telemetry
+ *
+ * Shared fire-and-forget rejection observer for streamed handler promises,
+ * used by both the fresh and revalidation segment-resolution paths. Lives in
+ * its own module (never mocked) so the resolution unit tests that mock
+ * helpers.js / telemetry.js with explicit export lists do not resolve it to
+ * undefined.
+ */
+
+import type { ReactNode } from "react";
+import { getRouterContext } from "../router-context.js";
+import { resolveSink, safeEmit } from "../telemetry.js";
+
+/**
+ * Attach a fire-and-forget rejection observer to a streamed handler promise.
+ * React catches the actual error via its error boundary; this only emits
+ * the handler.error telemetry event.
+ */
+export function observeStreamedHandler(
+  promise: Promise<ReactNode>,
+  segmentId: string,
+  segmentType: string,
+  pathname?: string,
+  routeKey?: string,
+  params?: Record<string, string>,
+): void {
+  let routerCtx;
+  try {
+    routerCtx = getRouterContext();
+  } catch {
+    return;
+  }
+  if (!routerCtx?.telemetry) return;
+  const sink = resolveSink(routerCtx.telemetry);
+  const reqId = routerCtx.requestId;
+  promise.catch((err: unknown) => {
+    const errorObj = err instanceof Error ? err : new Error(String(err));
+    safeEmit(sink, {
+      type: "handler.error",
+      timestamp: performance.now(),
+      requestId: reqId,
+      segmentId,
+      segmentType,
+      error: errorObj,
+      handledByBoundary: true,
+      pathname,
+      routeKey,
+      params,
+    });
+  });
+}

package/src/router/segment-resolution.ts

@@ -1,5 +1,8 @@
 // Barrel re-export -- see segment-resolution/ for implementations.
-export { handleHandlerResult } from "./segment-resolution/helpers.js";
+export {
+  handleHandlerResult,
+  warnOnStreamedResponse,
+} from "./segment-resolution/helpers.js";
 export {
   resolveLoaders,
   type ResolveSegmentOptions,

package/src/router/state-cookie-name.ts

@@ -0,0 +1,33 @@
+import { DEFAULT_STATE_COOKIE_PREFIX } from "../browser/cookie-name.js";
+
+/**
+ * Resolve the rango state cookie name once, server-side, at router init. The
+ * resolved string is shipped in payload metadata and the client reads it
+ * verbatim, so composition happens in exactly one place.
+ *
+ * Shape: `{sanitizedPrefix}_{sanitizedRouterId}`. The prefix charset excludes
+ * `_` so the FIRST `_` is always the prefix/routerId boundary; that keeps the
+ * name injective even though a routerId may legitimately contain `_` (the
+ * counter fallback is `router_{n}`). Without that exclusion, prefix
+ * `rango-state` + id `router_0` and prefix `rango-state_router` + id `0` would
+ * both resolve to `rango-state_router_0` and silently share a cache key.
+ */
+
+// Prefix excludes `_` so it can never collide with the separator.
+function sanitizePrefix(prefix: string): string {
+  return prefix.replace(/[^A-Za-z0-9-]/g, "");
+}
+
+// routerId keeps `_` (so `router_0` survives); other illegal chars are dropped.
+function sanitizeRouterId(routerId: string): string {
+  return routerId.replace(/[^A-Za-z0-9_-]/g, "");
+}
+
+export function resolveStateCookieName(
+  prefix: string | undefined,
+  routerId: string,
+): string {
+  const sanitized = sanitizePrefix(prefix ?? DEFAULT_STATE_COOKIE_PREFIX);
+  const finalPrefix = sanitized || DEFAULT_STATE_COOKIE_PREFIX;
+  return `${finalPrefix}_${sanitizeRouterId(routerId)}`;
+}

package/src/router/telemetry-otel.ts

@@ -125,10 +125,6 @@ export function createOTelSink(tracer: OTelTracer): TelemetrySink {
   return {
     emit(event: TelemetryEvent): void {
       switch (event.type) {
-        // -----------------------------------------------------------------
-        // Request lifecycle
-        // -----------------------------------------------------------------
-
         case "request.start": {
           const span = tracer.startSpan("rango.request", {
             attributes: {
@@ -169,10 +165,6 @@ export function createOTelSink(tracer: OTelTracer): TelemetrySink {
           break;
         }
 
-        // -----------------------------------------------------------------
-        // Loader lifecycle
-        // -----------------------------------------------------------------
-
         case "loader.start": {
           const span = tracer.startSpan("rango.loader", {
             attributes: {
@@ -231,10 +223,6 @@ export function createOTelSink(tracer: OTelTracer): TelemetrySink {
           break;
         }
 
-        // -----------------------------------------------------------------
-        // Handler errors (instant span)
-        // -----------------------------------------------------------------
-
         case "handler.error": {
           const attrs: Record<string, string | number | boolean> = {
             "rango.handled_by_boundary": event.handledByBoundary,
@@ -257,10 +245,6 @@ export function createOTelSink(tracer: OTelTracer): TelemetrySink {
           break;
         }
 
-        // -----------------------------------------------------------------
-        // Cache decision (instant span)
-        // -----------------------------------------------------------------
-
         case "cache.decision": {
           const attrs: Record<string, string | number | boolean> = {
             "http.route": event.pathname,
@@ -277,10 +261,6 @@ export function createOTelSink(tracer: OTelTracer): TelemetrySink {
           break;
         }
 
-        // -----------------------------------------------------------------
-        // Revalidation decision (instant span)
-        // -----------------------------------------------------------------
-
         case "revalidation.decision": {
           const span = tracer.startSpan("rango.revalidation.decision", {
             attributes: {