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

package/src/vercel/tracing.ts

@@ -0,0 +1,89 @@
+/**
+ * Vercel OpenTelemetry tracing integration.
+ *
+ * Bridges the router's observable phases (request, middleware, action, loaders,
+ * handler, render, ssr, response, background) onto OpenTelemetry spans so they
+ * show up in Vercel's trace waterfall next to the platform's automatic spans,
+ * with correct nesting. Vercel exposes tracing through OpenTelemetry (not a
+ * native import-free API like Cloudflare), so this is a thin convenience over
+ * `createOTelTracing`: it reads the global OTel tracer that `@vercel/otel`'s
+ * `registerOTel()` installs.
+ *
+ * Usage (vercel preset). A Rango/Vite app does NOT auto-load `instrumentation.ts`
+ * the way Next.js does, so export the tracing config from there and import it —
+ * the import is what runs `registerOTel()`. A standalone `registerOTel()` that
+ * nothing imports is a silent no-op (the tracer never registers, spans drop):
+ *
+ *   // instrumentation.ts
+ *   import { registerOTel } from "@vercel/otel";
+ *   import { createVercelTracing } from "@rangojs/router/vercel";
+ *   registerOTel({ serviceName: "my-app" });
+ *   export const tracing = createVercelTracing();
+ *
+ *   // router.tsx — importing `tracing` runs instrumentation.ts (and registerOTel)
+ *   import { createRouter } from "@rangojs/router";
+ *   import { tracing } from "./instrumentation.js";
+ *   export const router = createRouter({ tracing });
+ *
+ * Two runtime caveats inherited from the platform:
+ *   - Node.js runtime only. Vercel custom spans are unsupported on the Edge
+ *     runtime; `startActiveSpan` also needs an AsyncLocalStorage context manager
+ *     (which @vercel/otel configures on Node) for spans to nest correctly.
+ *   - `registerOTel()` must run before the first request. Reading the tracer via
+ *     `trace.getTracer` here is safe even if it runs first — the API's proxy
+ *     tracer delegates to the provider once registered — but no provider means
+ *     every span is a no-op (the request behaves exactly as if tracing were off).
+ *
+ * Whether spans are actually exported is governed by your OTel setup / Vercel
+ * tracing destination, not by this adapter.
+ */
+
+import { trace } from "@opentelemetry/api";
+import {
+  createOTelTracing,
+  type OTelActiveSpanTracer,
+} from "../router/telemetry-otel.js";
+import type {
+  RouterTracingConfig,
+  TracingToggleOptions,
+} from "../router/tracing.js";
+
+/**
+ * Options for createVercelTracing. Extends the shared
+ * {@link TracingToggleOptions} (`enabled` + per-phase `spans`) with the
+ * Vercel-specific tracer selectors.
+ */
+export interface VercelTracingOptions extends TracingToggleOptions {
+  /**
+   * OTel instrumentation-scope name passed to `trace.getTracer()`. Defaults to
+   * `"rango"`. Ignored when `tracer` is provided.
+   */
+  tracerName?: string;
+  /**
+   * Explicit tracer override. Defaults to the global OTel tracer
+   * (`trace.getTracer(tracerName)`) — the provider `@vercel/otel`'s
+   * `registerOTel()` installs. Pass this to bridge onto a tracer you own.
+   */
+  tracer?: OTelActiveSpanTracer;
+}
+
+/**
+ * Create the tracing config for a Vercel router. Pass the result to
+ * `createRouter({ tracing })`. Spans are emitted for the request, middleware,
+ * action, loaders, handler, render, ssr, response, and background phases; pass
+ * `spans` to turn individual phases off.
+ *
+ * @see createOTelTracing (`@rangojs/router`) for the underlying adapter on any
+ *   platform with an OpenTelemetry SDK.
+ * @see createCloudflareTracing (`@rangojs/router/cloudflare`) for the same slot
+ *   using Cloudflare Workers native custom spans.
+ */
+export function createVercelTracing(
+  options: VercelTracingOptions = {},
+): RouterTracingConfig {
+  const { tracerName = "rango", tracer, enabled, spans } = options;
+  return createOTelTracing(tracer ?? trace.getTracer(tracerName), {
+    enabled,
+    spans,
+  });
+}

package/src/vite/debug.ts

@@ -10,7 +10,7 @@
  * Returns `undefined` when no matching namespace is enabled, so call sites
  * can guard expensive diagnostics with a simple truthiness check:
  *
- *     const debug = createRangoDebugger("rango:routes");
+ *     const debug = createRangoDebugger(NS.routes);
  *     if (debug) debug("built manifest (%d routes) in %dms", n, ms);
  *
  * Back-compat: INTERNAL_RANGO_DEBUG=1 still enables all rango namespaces.
@@ -23,6 +23,21 @@
 
 import debugFactory from "debug";
 
+/**
+ * Canonical debug namespaces. Import as `NS.xxx` instead of string literals
+ * so typos become type errors and the full set lives in one place.
+ */
+export const NS = {
+  config: "rango:config",
+  discovery: "rango:discovery",
+  routes: "rango:routes",
+  prerender: "rango:prerender",
+  build: "rango:build",
+  dev: "rango:dev",
+  transform: "rango:transform",
+  chunks: "rango:chunks",
+} as const;
+
 // Back-compat: the legacy INTERNAL_RANGO_DEBUG env var enabled per-site
 // console.logs in this plugin. Map it to `rango:*` so those call sites can
 // be migrated to the `debug` pipeline without breaking existing setups.
@@ -40,8 +55,8 @@ export function createRangoDebugger(namespace: string): Debugger | undefined {
   // Shadow namespace so `vite --debug rango:*` (which expands to
   // DEBUG=vite:rango:*) and `vite --debug` (DEBUG=vite:*) both pick us up.
   const shadow = debugFactory(`vite:${namespace}`);
-  if (primary.enabled) return primary as unknown as Debugger;
-  if (shadow.enabled) return shadow as unknown as Debugger;
+  if (primary.enabled) return primary as Debugger;
+  if (shadow.enabled) return shadow as Debugger;
   return undefined;
 }
 
@@ -84,3 +99,87 @@ export function timedSync<T>(
     debug("%s (%sms)", label, (performance.now() - start).toFixed(1));
   }
 }
+
+/**
+ * Aggregate counter for high-frequency call sites (typically Vite
+ * `transform` hooks that run on many files). Per-call logging would
+ * drown real signal; this collects totals and reports once on flush.
+ *
+ *     const counter = createCounter(debug, "use-cache-transform");
+ *     // inside transform():
+ *     return counter?.time(id, () => doWork()) ?? doWork();
+ *     // or manually:
+ *     counter?.record(id, ms);
+ *     // flush on buildEnd (counter resets, so multi-env builds each get
+ *     // their own summary line):
+ *     counter?.flush();
+ *
+ * Returns `undefined` when the namespace is disabled so call sites pay
+ * nothing when off.
+ */
+export interface Counter {
+  record(file: string, ms: number): void;
+  /**
+   * Convenience: time a sync or async block and record it. Propagates
+   * throws; records regardless of outcome. Returns the function's result.
+   */
+  time<T>(file: string, fn: () => T): T;
+  time<T>(file: string, fn: () => Promise<T>): Promise<T>;
+  flush(): void;
+}
+
+export function createCounter(
+  debug: Debugger | undefined,
+  label: string,
+): Counter | undefined {
+  if (!debug) return undefined;
+  let n = 0;
+  let totalMs = 0;
+  let slowestMs = 0;
+  let slowestFile = "";
+  const record = (file: string, ms: number): void => {
+    n++;
+    totalMs += ms;
+    if (ms > slowestMs) {
+      slowestMs = ms;
+      slowestFile = file;
+    }
+  };
+  return {
+    record,
+    time<T>(file: string, fn: () => T | Promise<T>): T | Promise<T> {
+      const start = performance.now();
+      let out: T | Promise<T>;
+      try {
+        out = fn();
+      } catch (err) {
+        record(file, performance.now() - start);
+        throw err;
+      }
+      if (out && typeof (out as any).then === "function") {
+        return (out as Promise<T>).finally(() =>
+          record(file, performance.now() - start),
+        );
+      }
+      record(file, performance.now() - start);
+      return out;
+    },
+    flush(): void {
+      if (n === 0) return;
+      debug(
+        "%s: %d files, %sms total, slowest %sms %s",
+        label,
+        n,
+        totalMs.toFixed(1),
+        slowestMs.toFixed(1),
+        slowestFile,
+      );
+      // Reset so buildEnd firing once per environment (Vite 6+ multi-env)
+      // gives one log line per env rather than silently dropping later data.
+      n = 0;
+      totalMs = 0;
+      slowestMs = 0;
+      slowestFile = "";
+    },
+  };
+}

package/src/vite/discovery/bundle-postprocess.ts

@@ -9,6 +9,7 @@ import { resolve } from "node:path";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { evictHandlerCode } from "../utils/bundle-analysis.js";
 import { copyStagedBuildAssets } from "../utils/prerender-utils.js";
+import { jsonParseExpression } from "../utils/manifest-utils.js";
 import type { DiscoveryState } from "./state.js";
 
 /**
@@ -71,12 +72,12 @@ export function postprocessBundle(state: DiscoveryState): void {
           writeFileSync(chunkPath, result.code);
           const savedKB = (result.savedBytes / 1024).toFixed(1);
           console.log(
-            `[rsc-router] Evicted ${target.label} (${savedKB} KB saved): ${info.fileName}`,
+            `[rango] Evicted ${target.label} (${savedKB} KB saved): ${info.fileName}`,
           );
         }
       } catch (replaceErr: any) {
         console.warn(
-          `[rsc-router] Failed to evict ${target.label}: ${replaceErr.message}`,
+          `[rango] Failed to evict ${target.label}: ${replaceErr.message}`,
         );
       }
     }
@@ -104,7 +105,7 @@ export function postprocessBundle(state: DiscoveryState): void {
         }
 
         const manifestCode = [
-          `const m=JSON.parse('${JSON.stringify(manifestMap).replace(/'/g, "\\'")}');`,
+          `const m=${jsonParseExpression(manifestMap)};`,
           `export function loadPrerenderAsset(s){return import(s)}`,
           `export default m;`,
           "",
@@ -121,18 +122,18 @@ export function postprocessBundle(state: DiscoveryState): void {
 
         const totalKB = (totalBytes / 1024).toFixed(1);
         console.log(
-          `[rsc-router] Wrote prerender assets (${totalKB} KB total, ${Object.keys(state.prerenderManifestEntries!).length} entries)`,
+          `[rango] Wrote prerender assets (${totalKB} KB total, ${Object.keys(state.prerenderManifestEntries!).length} entries)`,
         );
       } catch (err: any) {
         throw new Error(
-          `[rsc-router] Failed to write prerender assets: ${err.message}`,
+          `[rango] Failed to write prerender assets: ${err.message}`,
         );
       }
     }
   }
 
   // 3. Write static handler data as separate importable asset modules
-  // and inject a __STATIC_MANIFEST import into the RSC entry.
+  // and inject a lazy loader thunk into the RSC entry.
   if (hasStaticData && existsSync(rscEntryPath)) {
     const rscCode = readFileSync(rscEntryPath, "utf-8");
     if (!rscCode.includes("__static-manifest.js")) {
@@ -151,9 +152,10 @@ export function postprocessBundle(state: DiscoveryState): void {
           );
         }
 
-        // Set the global inside the manifest module so it is assigned
-        // during module evaluation (before dependent modules like
-        // segment-resolution.ts run their top-level initializers).
+        // The module assigns the global on evaluation; evaluation itself is
+        // DEFERRED behind the loader thunk below (mirroring the prerender and
+        // shell manifests), so the thunk table stays off the worker's eager
+        // cold-start path (issue #760) — it grows O(#Static handlers).
         const manifestCode = `const m={${manifestEntries.join(",")}};globalThis.__STATIC_MANIFEST=m;export default m;\n`;
         const manifestPath = resolve(
           state.projectRoot,
@@ -162,18 +164,20 @@ export function postprocessBundle(state: DiscoveryState): void {
         writeFileSync(manifestPath, manifestCode);
         totalBytes += Buffer.byteLength(manifestCode);
 
-        // The import ensures the manifest module is evaluated early.
-        // The global is already set inside the module itself.
-        const injection = `import "./__static-manifest.js";\n`;
+        // Lazy thunk, NOT an eager import: static-store.ts resolves it on the
+        // first Static() lookup (a first-call latch — the entry body assigning
+        // this global runs after hoisted imports, so an eval-time read in
+        // static-store.ts could never see it).
+        const injection = `globalThis.__loadStaticManifestModule = () => import("./__static-manifest.js");\n`;
         writeFileSync(rscEntryPath, injection + rscCode);
 
         const totalKB = (totalBytes / 1024).toFixed(1);
         console.log(
-          `[rsc-router] Wrote static assets (${totalKB} KB total, ${Object.keys(state.staticManifestEntries!).length} entries)`,
+          `[rango] Wrote static assets (${totalKB} KB total, ${Object.keys(state.staticManifestEntries!).length} entries)`,
         );
       } catch (err: any) {
         throw new Error(
-          `[rsc-router] Failed to write static assets: ${err.message}`,
+          `[rango] Failed to write static assets: ${err.message}`,
         );
       }
     }

package/src/vite/discovery/client-urls-projection.ts

@@ -0,0 +1,322 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { normalizePath, parseAst } from "vite";
+import {
+  serializeClientUrlPatterns,
+  type ClientUrlProjection,
+} from "../../client-urls/server-projection.js";
+import type { ClientUrlPatterns } from "../../client-urls/types.js";
+import {
+  computeProductionHash,
+  hashRefKey,
+} from "../plugins/client-ref-hashing.js";
+import { hasUseClientDirective } from "../utils/directive-prologue.js";
+import { createRangoDebugger, NS } from "../debug.js";
+import { findTsFiles } from "../../build/route-types/scan-filter.js";
+import type { DiscoveryState } from "./state.js";
+
+const debug = createRangoDebugger(NS.discovery);
+
+interface ClientUrlSsrEnvironment {
+  readonly runner?: {
+    import(id: string): Promise<Record<string, unknown>>;
+  };
+}
+
+interface ClientUrlProjectionServerModule {
+  clearClientUrlProjections(): void;
+  setClientUrlProjection(
+    referenceId: string,
+    projection: ClientUrlProjection,
+  ): void;
+}
+
+function hasDefaultExport(code: string): boolean {
+  let program: { body?: any[] };
+  try {
+    program = parseAst(code, { lang: "tsx" }) as { body?: any[] };
+  } catch {
+    return false;
+  }
+
+  for (const node of program.body ?? []) {
+    if (node?.type === "ExportDefaultDeclaration") return true;
+    if (node?.type !== "ExportNamedDeclaration") continue;
+    for (const specifier of node.specifiers ?? []) {
+      const exportedName =
+        specifier?.exported?.name ?? specifier?.exported?.value;
+      if (exportedName === "default") return true;
+    }
+  }
+  return false;
+}
+
+function normalizeSource(state: DiscoveryState, id: string): string {
+  const cleanId = id.split("?", 1)[0];
+  const absoluteId = isAbsolute(cleanId)
+    ? cleanId
+    : resolve(state.projectRoot, cleanId);
+  return normalizePath(absoluteId);
+}
+
+function referenceId(referenceKey: string): string {
+  return `${referenceKey}#default`;
+}
+
+function withoutReferenceQuery(reference: string): string {
+  const exportIndex = reference.lastIndexOf("#");
+  const moduleId =
+    exportIndex === -1 ? reference : reference.slice(0, exportIndex);
+  const exportName = exportIndex === -1 ? "" : reference.slice(exportIndex);
+  const queryIndex = moduleId.indexOf("?");
+  return `${queryIndex === -1 ? moduleId : moduleId.slice(0, queryIndex)}${exportName}`;
+}
+
+export function recordClientUrlsModule(
+  state: DiscoveryState,
+  code: string,
+  id: string,
+): void {
+  if (
+    !code.includes("clientUrls(") ||
+    !hasUseClientDirective(code) ||
+    !hasDefaultExport(code)
+  ) {
+    return;
+  }
+
+  const source = normalizeSource(state, id);
+  const projectRoot = normalizePath(resolve(state.projectRoot));
+  const relativeId = normalizePath(relative(projectRoot, source));
+  const outsideProject =
+    relativeId === ".." ||
+    relativeId.startsWith("../") ||
+    isAbsolute(relativeId);
+  const devReferenceKey = outsideProject ? `/@fs${source}` : `/${relativeId}`;
+
+  const sourceByReferenceId = (state.clientUrlSourceByReferenceId ??=
+    new Map());
+  sourceByReferenceId.set(referenceId(devReferenceKey), source);
+
+  const productionReferenceKeys = new Set([
+    hashRefKey(relativeId),
+    computeProductionHash(projectRoot, devReferenceKey),
+  ]);
+  for (const productionReferenceKey of productionReferenceKeys) {
+    sourceByReferenceId.set(referenceId(productionReferenceKey), source);
+  }
+}
+
+export function resolveClientUrlsSource(
+  state: DiscoveryState,
+  referenceId: string,
+): string | undefined {
+  return state.clientUrlSourceByReferenceId?.get(
+    withoutReferenceQuery(referenceId),
+  );
+}
+
+/**
+ * Deterministic filesystem discovery of clientUrls modules. Transform-based
+ * recording only sees modules that some environment actually loads — a
+ * clientUrls module not yet reachable from any transformed graph at discovery
+ * time (cold ordering, a mount added before its first import is served) would
+ * never be recorded and its include would fail with empty projections. Walking
+ * the project source (the same walk static route-type generation performs)
+ * makes recording independent of module-graph timing. The transform hooks
+ * still record too — they refresh dev HMR edits between scans.
+ */
+export function scanForClientUrlModules(state: DiscoveryState): void {
+  if (!state.projectRoot) return;
+  for (const filePath of findTsFiles(state.projectRoot, state.scanFilter)) {
+    let code: string;
+    try {
+      code = readFileSync(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+    recordClientUrlsModule(state, code, filePath);
+  }
+}
+
+function projectionError(
+  referenceId: string,
+  source: string | undefined,
+  message: string,
+  cause?: unknown,
+): Error {
+  const sourceDescription = source ? ` from source "${source}"` : "";
+  const errorMessage = `Cannot discover client URL projection for reference "${referenceId}"${sourceDescription}: ${message}`;
+  return cause === undefined
+    ? new Error(errorMessage)
+    : new Error(errorMessage, { cause });
+}
+
+/**
+ * Lenient pre-entry projection refresh. Re-serializes every RECORDED clientUrls
+ * module before the discovery pass imports the entry, so routers re-created by
+ * that import materialize against the CURRENT module contents.
+ *
+ * Scar: node-preset HMR served stale client-urls routes after a route-shape
+ * edit — the clientUrls module is an HMR-accepted client boundary in the rsc
+ * graph, and the strict registry-driven pass below only runs AFTER the entry
+ * import, so `.routes(reference)` materialized the previous pass's projection.
+ *
+ * Errors are deliberately swallowed per source (a module mid-edit keeps its
+ * last-known projection); the strict discoverClientUrlProjections() pass still
+ * surfaces real failures afterwards. No-ops on cold start (nothing recorded
+ * yet) and when the SSR runner is unavailable.
+ */
+export async function refreshRecordedClientUrlProjections(
+  state: DiscoveryState,
+  ssrEnv: ClientUrlSsrEnvironment | undefined,
+  serverMod: ClientUrlProjectionServerModule,
+): Promise<void> {
+  const sourceByReferenceId = state.clientUrlSourceByReferenceId;
+  if (
+    !sourceByReferenceId?.size ||
+    typeof ssrEnv?.runner?.import !== "function"
+  ) {
+    return;
+  }
+
+  const referenceIdsBySource = new Map<string, string[]>();
+  for (const [refId, source] of sourceByReferenceId) {
+    const ids = referenceIdsBySource.get(source);
+    if (ids) {
+      ids.push(refId);
+    } else {
+      referenceIdsBySource.set(source, [refId]);
+    }
+  }
+
+  for (const [source, referenceIds] of referenceIdsBySource) {
+    let definition: unknown;
+    try {
+      definition = (await ssrEnv.runner.import(source)).default;
+    } catch {
+      continue;
+    }
+    if (
+      (typeof definition !== "object" && typeof definition !== "function") ||
+      definition === null ||
+      (definition as { __brand?: unknown }).__brand !== "client-urls"
+    ) {
+      continue;
+    }
+    const projection = serializeClientUrlPatterns(
+      definition as ClientUrlPatterns,
+    );
+    debug?.(
+      "pre-entry refresh %s -> [%s]",
+      source,
+      projection.routes.map((route) => route.pattern).join(", "),
+    );
+    for (const referenceId of referenceIds) {
+      serverMod.setClientUrlProjection(referenceId, projection);
+      // The eager routes-manifest virtual module REPLAYS this state map
+      // (clearClientUrlProjections + set) whenever it re-evaluates — and the
+      // watcher's gen-file write invalidates it right before the entry import,
+      // so a stale map here would clobber the registry install above before
+      // the router materializes its mount. Keep both in sync.
+      state.clientUrlProjectionMap?.set(referenceId, projection);
+    }
+  }
+}
+
+/**
+ * Strict projection discovery over every RECORDED clientUrls module. Recorded
+ * modules — not router references — are the source of truth: include() mounts
+ * materialize lazily from the projection registry, so there is no router-level
+ * reference list to consult. Serializes every source before atomically
+ * installing the new projections (a failure preserves last-known state).
+ *
+ * A recorded source whose file no longer exists is dropped silently
+ * (recordClientUrlsModule never un-records, so deletions must self-heal here).
+ * A present-but-broken module is a hard error: it is part of the app graph.
+ */
+export async function discoverClientUrlProjections(
+  state: DiscoveryState,
+  ssrEnv: ClientUrlSsrEnvironment | undefined,
+  serverMod: ClientUrlProjectionServerModule,
+): Promise<void> {
+  scanForClientUrlModules(state);
+  const sourceByReferenceId = state.clientUrlSourceByReferenceId;
+  if (!sourceByReferenceId?.size) {
+    serverMod.clearClientUrlProjections();
+    state.clientUrlProjectionMap = new Map();
+    return;
+  }
+
+  const referenceIdsBySource = new Map<string, string[]>();
+  for (const [referenceId, source] of sourceByReferenceId) {
+    const ids = referenceIdsBySource.get(source);
+    if (ids) {
+      ids.push(referenceId);
+    } else {
+      referenceIdsBySource.set(source, [referenceId]);
+    }
+  }
+
+  if (typeof ssrEnv?.runner?.import !== "function") {
+    const [source, ids] = referenceIdsBySource.entries().next().value as [
+      string,
+      string[],
+    ];
+    throw projectionError(
+      ids[0],
+      source,
+      "the SSR module runner is unavailable",
+    );
+  }
+
+  const nextProjections = new Map<string, ClientUrlProjection>();
+  const removedSources: string[] = [];
+  for (const [source, referenceIds] of referenceIdsBySource) {
+    let module: Record<string, unknown>;
+    try {
+      module = await ssrEnv.runner.import(source);
+    } catch (cause) {
+      if (!existsSync(source)) {
+        removedSources.push(source);
+        continue;
+      }
+      throw projectionError(
+        referenceIds[0],
+        source,
+        "failed to import the source module",
+        cause,
+      );
+    }
+    const definition = module.default;
+    if (
+      (typeof definition !== "object" && typeof definition !== "function") ||
+      definition === null ||
+      (definition as { __brand?: unknown }).__brand !== "client-urls"
+    ) {
+      throw projectionError(
+        referenceIds[0],
+        source,
+        'the module default export must be created by clientUrls() and have __brand === "client-urls"',
+      );
+    }
+    const projection = serializeClientUrlPatterns(
+      definition as ClientUrlPatterns,
+    );
+    for (const referenceId of referenceIds) {
+      nextProjections.set(referenceId, projection);
+    }
+  }
+
+  for (const source of removedSources) {
+    for (const [referenceId, recorded] of sourceByReferenceId) {
+      if (recorded === source) sourceByReferenceId.delete(referenceId);
+    }
+  }
+
+  serverMod.clearClientUrlProjections();
+  for (const [id, projection] of nextProjections) {
+    serverMod.setClientUrlProjection(id, projection);
+  }
+  state.clientUrlProjectionMap = nextProjections;
+}