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

package/src/vite/rango.ts

@@ -66,18 +66,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
   const resolvedOptions: RangoOptions = options ?? { preset: "node" };
   const preset = resolvedOptions.preset ?? "node";
   const showBanner = resolvedOptions.banner ?? true;
-  // Client-chunking strategy (per-route/per-feature splitting of the browser
-  // bundle). Defaults to the built-in directory strategy (`true`) pre-1.0; pass
-  // `clientChunks: false` to opt out. Resolved once and forwarded to
-  // @vitejs/plugin-rsc in both presets. The built-in strategy only splits where it
-  // recognizes a route structure, so this default is a no-op for flat / host-split
-  // apps and never duplicates the shared runtime.
   const clientChunksOption = resolvedOptions.clientChunks ?? true;
-  // Shared context the built-in strategy reads at build time: the production
-  // hashes of registered error/notFound fallback modules (-> app-fallback).
-  // Populated by the discovery plugin in buildStart, before the client build
-  // invokes the strategy. Only wired when the built-in strategy is active; a
-  // custom function owns its own grouping.
   const useBuiltInClientChunks = clientChunksOption === true;
   const clientChunkCtx: ClientChunkContext | undefined = useBuiltInClientChunks
     ? { fallbackRefs: new Set<string>() }
@@ -124,14 +113,8 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
   const prerenderEnabled = true;
 
   if (preset === "cloudflare") {
-    // Cloudflare preset: configure entries for cloudflare worker setup
-    // Router is not needed here - worker.rsc.tsx imports it directly
-
-    // Dynamically import @vitejs/plugin-rsc
     const { default: rsc } = await import("@vitejs/plugin-rsc");
 
-    // Only client and ssr entries - rsc entry is handled by cloudflare plugin
-    // Always use virtual modules for cloudflare preset
     const finalEntries: { client: string; ssr: string } = {
       client: VIRTUAL_IDS.browser,
       ssr: VIRTUAL_IDS.ssr,
@@ -142,10 +125,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
       enforce: "pre",
 
       config() {
-        // Configure environments for cloudflare deployment
         return {
-          // Exclude rsc-router modules from optimization to prevent module duplication
-          // This ensures the same Context instance is used by both browser entry and RSC proxy modules
           optimizeDeps: {
             exclude: excludeDeps,
             rolldownOptions: sharedRolldownOptions,
@@ -168,21 +148,12 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
             client: {
               build: {
                 rollupOptions: {
-                  // FILE_NAME_CONFLICT (and any other client-build warning) is
-                  // emitted by the CLIENT environment build, which consults THIS
-                  // env's onwarn -- Vite 8's environment builds do NOT propagate
-                  // the top-level build.rollupOptions.onwarn into the client env.
-                  // Wire it here so the suppression runs where the conflicts
-                  // originate (the top-level handler is invoked 0x for these; the
-                  // client-env handler is invoked for all of them).
                   onwarn,
                   output: {
                     manualChunks: getManualChunks,
                   },
                 },
               },
-              // Pre-bundle rsc-html-stream to prevent discovery during first request
-              // Exclude rsc-router modules to ensure same Context instance
               optimizeDeps: {
                 include: [nested("rsc-html-stream/client")],
                 exclude: excludeDeps,
@@ -190,12 +161,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
               },
             },
             ssr: {
-              // Build SSR inside RSC directory so wrangler can deploy self-contained dist/rsc
               build: {
                 outDir: "./dist/rsc/ssr",
               },
-              // Pre-bundle SSR entry and React for proper module linking with childEnvironments
-              // All deps must be listed to avoid late discovery triggering ERR_OUTDATED_OPTIMIZED_DEP
               optimizeDeps: {
                 entries: [finalEntries.ssr],
                 include: [
@@ -215,10 +183,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
               },
             },
             rsc: {
-              // RSC environment needs exclude list and esbuild options
-              // Exclude rsc-router modules to prevent createContext in RSC environment
               optimizeDeps: {
-                // Pre-bundle all RSC deps to prevent late discovery triggering ERR_OUTDATED_OPTIMIZED_DEP
                 include: [
                   "react",
                   "react/jsx-runtime",
@@ -249,13 +214,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     });
 
     plugins.push(createVirtualEntriesPlugin(finalEntries));
-
-    // Dev-only: RSDW client patch for React Performance Tracks
     plugins.push(performanceTracksPlugin());
-
-    // Add RSC plugin with cloudflare-specific options
-    // Note: loadModuleDevProxy should NOT be used with childEnvironments
-    // since SSR runs in workerd alongside RSC
     plugins.push(
       rsc({
         entries: finalEntries,
@@ -263,13 +222,8 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
         clientChunks,
       }) as PluginOption,
     );
-
-    // Deduplicate client references from third-party packages in dev mode.
-    // Prevents module duplication when server components import "use client"
-    // packages that are also imported directly by client components.
     plugins.push(clientRefDedup());
   } else {
-    // Auto-discover router using Vite's resolved root (not process.cwd())
     plugins.push({
       name: "@rangojs/router:auto-discover",
       config(userConfig) {
@@ -292,18 +246,15 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
             .join("\n");
           throw new Error(`[rango] Multiple routers found:\n${list}`);
         }
-        // 0 found: routerRef.path stays undefined, warn at startup via discovery plugin
       },
     });
 
-    // Always use virtual entries for client, ssr, and rsc
     const finalEntries = {
       client: VIRTUAL_IDS.browser,
       ssr: VIRTUAL_IDS.ssr,
       rsc: VIRTUAL_IDS.rsc,
     };
 
-    // Dynamically import @vitejs/plugin-rsc
     const { default: rsc } = await import("@vitejs/plugin-rsc");
 
     let hasWarnedDuplicate = false;
@@ -336,13 +287,6 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
             client: {
               build: {
                 rollupOptions: {
-                  // FILE_NAME_CONFLICT (and any other client-build warning) is
-                  // emitted by the CLIENT environment build, which consults THIS
-                  // env's onwarn -- Vite 8's environment builds do NOT propagate
-                  // the top-level build.rollupOptions.onwarn into the client env.
-                  // Wire it here so the suppression runs where the conflicts
-                  // originate (the top-level handler is invoked 0x for these; the
-                  // client-env handler is invoked for all of them).
                   onwarn,
                   output: {
                     manualChunks: getManualChunks,
@@ -423,36 +367,17 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
       },
     });
 
-    // Add virtual entries plugin (RSC entry generated lazily from routerRef)
     plugins.push(createVirtualEntriesPlugin(finalEntries, routerRef));
-
-    // Dev-only: RSDW client patch for React Performance Tracks
     plugins.push(performanceTracksPlugin());
-
     plugins.push(
       rsc({
         entries: finalEntries,
         clientChunks,
       }) as PluginOption,
     );
-
-    // Deduplicate client references from third-party packages in dev mode.
-    // Prevents module duplication when server components import "use client"
-    // packages that are also imported directly by client components.
     plugins.push(clientRefDedup());
   }
 
-  // Fix HMR for "use client" components.
-  //
-  // @vitejs/plugin-rsc's hotUpdate returns undefined for "use client" files
-  // in the RSC environment. Vite then tries to propagate through the RSC
-  // module graph, but the proxy module has no import.meta.hot.accept()
-  // boundary, causing a full page reload. The client env would handle it
-  // fine via React Refresh, but the RSC env's full-reload arrives first.
-  //
-  // Fix: in the RSC env, return [] for "use client" files to signal
-  // "handled, nothing to propagate". The client env is left alone so
-  // React Refresh processes the update normally.
   plugins.push({
     name: "@rangojs/router:client-component-hmr",
     hotUpdate(ctx) {
@@ -476,59 +401,27 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
           trimmed.startsWith('"use client"') ||
           trimmed.startsWith("'use client'")
         ) {
-          // Consume the update in RSC/SSR envs. The proxy module was already
-          // re-transformed by the RSC plugin's hotUpdate. Without this, Vite
-          // tries to propagate through the RSC/SSR module graph where the proxy
-          // has no import.meta.hot.accept() boundary, triggering a full reload.
-          // The actual component update is handled by React Refresh in the
-          // client environment.
           return [];
         }
-      } catch {
-        // File deleted/moved during HMR, let default handling proceed
-      }
+      } catch {}
     },
   });
 
   plugins.push(exposeActionId());
-
-  // "use cache" directive transform (enforce: "post"):
-  // Wraps exports with registerCachedFunction() for function-level caching.
   plugins.push(useCacheTransform());
-
-  // Consolidated plugin for create* ID injection (enforce: "post"):
-  // loaders, handles, location state, and prerender handlers.
   plugins.push(exposeInternalIds());
-
-  // Router ID injection runs at normal priority (no enforce) to avoid
-  // changing Vite's dep optimization timing.
   plugins.push(exposeRouterId());
-
-  // Add version virtual module plugin for cache invalidation
   plugins.push(createVersionPlugin());
 
-  // Entry path for discovery: user-specified value (if any) or undefined.
-  // Auto-discovered path is passed separately via routerRef.
-  // Cloudflare preset: deferred to configResolved (read from resolved Vite env config).
   const discoveryEntryPath =
     preset !== "cloudflare" ? routerRef.path : undefined;
-  // Ref for deferred auto-discovery (node preset only, undefined for cloudflare)
   const discoveryRouterRef = preset !== "cloudflare" ? routerRef : undefined;
 
-  // Version injector: auto-injects VERSION and routes-manifest into the RSC entry.
-  // For cloudflare preset, the entry is resolved lazily in configResolved.
-  // For node preset, the virtual entry already includes these imports.
   if (preset === "cloudflare") {
     plugins.push(createVersionInjectorPlugin(undefined));
   }
 
-  // Transform CJS vendor files to ESM for browser compatibility
-  // optimizeDeps.include doesn't work because the file is loaded after initial optimization
   plugins.push(createCjsToEsmPlugin());
-
-  // Router discovery plugin for build-time manifest generation.
-  // For cloudflare, the entry is resolved lazily in configResolved from the RSC environment.
-  // For node, discoveryRouterRef provides the auto-discovered path when not user-specified.
   plugins.push(
     createRouterDiscoveryPlugin(discoveryEntryPath, {
       routerPathRef: discoveryRouterRef,

package/src/vite/router-discovery.ts

@@ -424,7 +424,8 @@ export function createRouterDiscoveryPlugin(
         releaseBuildEnv(s).catch(() => {});
       });
 
-      // Mirror the build-path contract (router-discovery.ts ~line 878):
+      // Mirror the build-path contract (the buildStart hook below, which sets
+      // __rscRouterDiscoveryActive before running user modules):
       // set __rscRouterDiscoveryActive before running user modules so any
       // module-level router.reverse() calls return a placeholder instead
       // of throwing. The temp Vite server's module runner has its own

package/src/vite/utils/ast-handler-extract.ts

@@ -1,10 +1,6 @@
 import type MagicString from "magic-string";
 import { hashInlineId, buildExportMap } from "../plugins/expose-id-utils.js";
 
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
 /** Minimal ESTree Program node — avoids importing from `rollup` (not a direct dep). */
 interface ProgramNode {
   type: "Program";
@@ -70,10 +66,6 @@ function findImportInsertionPos(
   return insertionPos;
 }
 
-// ---------------------------------------------------------------------------
-// AST walking helper
-// ---------------------------------------------------------------------------
-
 /**
  * Recursively walk an ESTree AST node, calling `enter` on each node.
  * Parent is passed for context.
@@ -111,10 +103,6 @@ function walkNode(
   ancestors.pop();
 }
 
-// ---------------------------------------------------------------------------
-// AST analysis
-// ---------------------------------------------------------------------------
-
 /**
  * Parse the file with Vite's parseAst and find all calls to `fnName`.
  * Distinguishes between `export const X = fnName(...)` (exportInfo set)
@@ -426,10 +414,6 @@ export function extractModuleLevelDeclarations(
   return declarations;
 }
 
-// ---------------------------------------------------------------------------
-// Transform
-// ---------------------------------------------------------------------------
-
 /**
  * Transform inline handler calls by extracting them into virtual modules.
  * Only processes inline calls (exportInfo === null); export const calls are

package/src/vite/utils/bundle-analysis.ts

@@ -5,9 +5,7 @@ import {
 
 /**
  * Find matching close paren in bundled code using depth counting.
- * Uses skipStringOrComment from expose-id-utils to correctly handle
- * template literal ${...} expressions, comments, and nested strings.
- * Returns the position after the closing paren, or -1 if unmatched.
+ * Uses skipStringOrComment to correctly handle template literals, comments, and nested strings.
  * @internal Exported for testing only.
  */
 export function findMatchingParenInBundle(
@@ -30,9 +28,8 @@ export function findMatchingParenInBundle(
 }
 
 /**
- * Scan a bundled chunk for handler exports of a given type and extract
- * their names + $$id values. Optionally detects passthrough flag.
- * @internal Exported for testing only.
+ * Scan a bundled chunk for handler exports and extract their names + $$id values.
+ * Optionally detects passthrough flag. @internal Exported for testing only.
  */
 export function extractHandlerExportsFromChunk(
   chunkCode: string,
@@ -67,7 +64,7 @@ export function extractHandlerExportsFromChunk(
           const closePos = findMatchingParenInBundle(chunkCode, afterOpen);
           if (closePos !== -1) {
             const callBody = chunkCode.slice(callStart.index, closePos);
-            isPassthrough = /passthrough\s*:\s*(!0|true)/.test(callBody);
+            isPassthrough = /passthrough\s*:\s*(!0|true)/.test(callBody); // !0 is minified true
           }
         }
       }
@@ -79,9 +76,8 @@ export function extractHandlerExportsFromChunk(
 }
 
 /**
- * Evict handler code from a bundled chunk, replacing full handler call
- * expressions with lightweight stub objects. Returns the modified code
- * and bytes saved, or null if no changes were made.
+ * Evict handler code from a bundled chunk, replacing full call expressions with stubs.
+ * Returns the modified code and bytes saved, or null if no changes were made.
  * @internal Exported for testing only.
  */
 export function evictHandlerCode(
@@ -110,13 +106,11 @@ export function evictHandlerCode(
     const closePos = findMatchingParenInBundle(modified, afterOpen);
     if (closePos === -1) continue;
 
-    // Skip trailing whitespace and optional semicolon
     let rangeEnd = closePos;
     while (rangeEnd < modified.length && /\s/.test(modified[rangeEnd]))
       rangeEnd++;
     if (modified[rangeEnd] === ";") rangeEnd++;
 
-    // Validate: matched range must contain the expected handlerId
     const matched = modified.slice(startMatch.index, rangeEnd);
     if (!matched.includes(handlerId)) continue;
 
@@ -124,7 +118,6 @@ export function evictHandlerCode(
     modified =
       modified.slice(0, startMatch.index) + stub + modified.slice(rangeEnd);
 
-    // Remove the now-redundant $$id assignment line.
     modified = modified.replace(
       new RegExp(`\\n${eName}\\.\\$\\$id\\s*=\\s*"[^"]+";`),
       "",

package/src/vite/utils/client-chunks.ts

@@ -1,9 +1,3 @@
-// Resolution of the public `clientChunks` option into the callback shape that
-// @vitejs/plugin-rsc expects. See plugin-types.ts (ClientChunks) and
-// docs/client-chunking.md for the contract. The mechanism: a distinct returned
-// name yields a distinct, dynamically-imported client chunk, independent of how
-// the RSC/server build chunked the importing modules.
-
 import type { ClientChunkMeta, ClientChunks } from "../plugin-types.js";
 import { createRangoDebugger, NS } from "../debug.js";
 import { hashRefKey } from "../plugins/client-ref-hashing.js";

package/src/vite/utils/forward-user-plugins.ts

@@ -1,25 +1,3 @@
-/**
- * Discovery Runner Config Parity
- *
- * The discovery temp server (createTempRscServer) runs the user's handler
- * graph through a throwaway Node Vite server built with `configFile: false`.
- * Without help, that server only sees a fixed Rango-owned plugin set, so any
- * user resolution is absent during discovery, prerender, and static handler
- * rendering — even though it applies at request time. Two flavors of user
- * resolution must be carried across:
- *
- * - Third-party resolveId plugins (e.g. vite-tsconfig-paths) — forwarded as
- *   plugin instances, see selectForwardableResolvePlugins.
- * - Native config-driven resolution, including Vite 8's built-in
- *   `resolve.tsconfigPaths` (which supersedes vite-tsconfig-paths) — forwarded
- *   as the data slice, see pickForwardedRunnerConfig.
- *
- * These helpers extract the resolution-relevant slice of the user's resolved
- * config (resolve.*, define, oxc) and forward the user's resolution plugins
- * into the temp server so discovery resolves modules the same way the real
- * environment does.
- */
-
 import type { Plugin, ResolvedConfig, UserConfig } from "vite";
 
 /**

package/src/vite/utils/manifest-utils.ts

@@ -1,7 +1,3 @@
-// Pure prefix-tree walks live in the build layer so runtime code can consume
-// them without importing from vite/. Re-exported here for the vite-side
-// callers (discover-routers, virtual-module-codegen) that already import them
-// from this module.
 export {
   flattenLeafEntries,
   buildRouteToStaticPrefix,

package/src/vite/utils/package-resolution.ts

@@ -1,10 +1,3 @@
-/**
- * Package Resolution Utilities
- *
- * Handles detection of workspace vs npm install context and generates
- * appropriate aliases and exclude lists for Vite configuration.
- */
-
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { resolve } from "node:path";
@@ -17,44 +10,20 @@ const require = createRequire(import.meta.url);
  */
 const VIRTUAL_PACKAGE_NAME = "@rangojs/router";
 
-/**
- * Get the published package name (e.g., "@rangojs/router")
- */
 export function getPublishedPackageName(): string {
   return packageJson.name;
 }
 
-/**
- * Check if the package is installed from npm (scoped) vs workspace (unscoped)
- *
- * In workspace development:
- * - Package is installed as "@rangojs/router" via pnpm workspace alias
- * - The scoped name (@rangojs/router) doesn't exist in node_modules
- *
- * When installed from npm:
- * - Package is installed as "@rangojs/router"
- * - We need aliases to map "@rangojs/router/*" to "@rangojs/router/*"
- */
 export function isInstalledFromNpm(): boolean {
   const packageName = getPublishedPackageName();
   // Check if the scoped package exists in node_modules
   return existsSync(resolve(process.cwd(), "node_modules", packageName));
 }
 
-/**
- * Check if we're in a monorepo/workspace development context
- */
 export function isWorkspaceDevelopment(): boolean {
   return !isInstalledFromNpm();
 }
 
-/**
- * Subpaths derived from package.json exports that use TypeScript source.
- * These must be excluded from Vite's dependency optimization (they ship
- * as .ts/.tsx, not compiled JS) and aliased when installed from npm.
- *
- * Derived automatically from the exports field to prevent drift.
- */
 const SOURCE_EXPORT_SUBPATHS = Object.keys(packageJson.exports)
   .filter((key) => {
     const entry = (
@@ -70,12 +39,6 @@ const SOURCE_EXPORT_SUBPATHS = Object.keys(packageJson.exports)
   })
   .map((key) => key.replace(/^\./, ""));
 
-/**
- * Generate the list of modules to exclude from Vite's dependency optimization.
- *
- * We include both the published name and the virtual name because
- * Vite's optimizer runs before alias resolution.
- */
 export function getExcludeDeps(): string[] {
   const packageName = getPublishedPackageName();
   const excludes: string[] = [];
@@ -92,24 +55,10 @@ export function getExcludeDeps(): string[] {
   return excludes;
 }
 
-/**
- * Subpaths that need aliasing — same as SOURCE_EXPORT_SUBPATHS.
- * When installed from npm, virtual entries may use a different package name
- * than the published one; aliases bridge them.
- */
 const ALIAS_SUBPATHS = SOURCE_EXPORT_SUBPATHS;
 
-/**
- * Generate aliases to map virtual package paths to the actual published package.
- *
- * Only needed when installed from npm, where the package is under @rangojs/router
- * but virtual entries import from rsc-router/*.
- *
- * Returns empty object in workspace development where rsc-router resolves directly.
- */
 export function getPackageAliases(): Record<string, string> {
   if (isWorkspaceDevelopment()) {
-    // No aliases needed - rsc-router resolves directly
     return {};
   }
 
@@ -123,28 +72,7 @@ export function getPackageAliases(): Record<string, string> {
   return aliases;
 }
 
-/**
- * Plugin-rsc pushes bare specs like
- * `@vitejs/plugin-rsc/vendor/react-server-dom/client.edge` into
- * `optimizeDeps.include` for the ssr and rsc environments. In strict pnpm
- * consumer apps, `@vitejs/plugin-rsc` is only reachable from @rangojs/router's
- * node_modules, so Vite's optimizer — which resolves from the project root —
- * can't find them and emits "Failed to resolve dependency" warnings.
- *
- * We resolve those specs from this plugin's location (where plugin-rsc is
- * guaranteed to be installed as our dep) and expose them as `resolve.alias`
- * entries. The optimizer's resolver honors aliases, so the bare specs map to
- * absolute paths and resolve cleanly.
- */
 export function getVendorAliases(): Record<string, string> {
-  // client.browser is intentionally NOT aliased. plugin-rsc injects it into
-  // the client env's optimizeDeps.include; Vite's manual-include path resolves
-  // and pre-bundles regardless of optimizeDeps.exclude, so aliasing would
-  // trigger esbuild pre-bundling of the CJS vendor file and bypass the
-  // cjs-to-esm transform that patches `require('react'|'react-dom')` into
-  // real ESM imports. The consumer may still see a single "Failed to resolve"
-  // warning for client.browser; runtime resolution from plugin-rsc's own
-  // importer works because Vite resolves relative to the importer (not root).
   const specs = [
     "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
     "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
@@ -154,7 +82,7 @@ export function getVendorAliases(): Record<string, string> {
     try {
       aliases[spec] = require.resolve(spec);
     } catch {
-      // Spec unresolvable (unexpected but non-fatal — Vite will warn as before).
+      // Non-fatal; Vite will warn if it cannot resolve the spec
     }
   }
   return aliases;

package/src/vite/utils/prerender-utils.ts

@@ -9,18 +9,10 @@ import {
 } from "node:fs";
 import { resolve } from "node:path";
 
-/**
- * Escape special RegExp characters in a string for safe interpolation
- * into new RegExp() patterns.
- */
 export function escapeRegExp(str: string): string {
   return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-/**
- * Encode route param values for path interpolation while preserving path
- * separators for wildcard params (splat-style values can include `/`).
- */
 export function encodePathParam(value: unknown): string {
   return String(value)
     .split("/")
@@ -28,11 +20,6 @@ export function encodePathParam(value: unknown): string {
     .join("/");
 }
 
-/**
- * Substitute route params into a pattern, stripping constraint and optional
- * syntax (:param(a|b)? -> value). Also handles wildcard params (*key).
- * Optional params not present in `params` are removed from the output.
- */
 export function substituteRouteParams(
   pattern: string,
   params: Record<string, string>,
@@ -41,17 +28,9 @@ export function substituteRouteParams(
   let result = pattern;
   let hadOmittedOptional = false;
 
-  // First pass: substitute provided params.
-  // Empty string on an optional placeholder is treated as omitted —
-  // caller-supplied params or `getParams()` shapes may pass `""` for an
-  // absent optional, so letting the second pass strip them keeps slash
-  // cleanup consistent. Empty string on required `:key` or wildcard
-  // `*key` still substitutes, matching prior behaviour.
   for (const [key, value] of Object.entries(params)) {
     const escaped = escapeRegExp(key);
     if (value === "") {
-      // Only replace required placeholders (negative lookahead for `?`);
-      // leave `:key?` for the second pass.
       result = result.replace(
         new RegExp(`:${escaped}(\\([^)]*\\))?(?!\\?)`),
         "",
@@ -66,13 +45,11 @@ export function substituteRouteParams(
     }
   }
 
-  // Second pass: strip remaining optional param placeholders not in params
   result = result.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?\?/g, () => {
     hadOmittedOptional = true;
     return "";
   });
 
-  // Clean up slashes from omitted optional segments
   if (hadOmittedOptional) {
     const hadTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
     result = result.replace(/\/\/+/g, "/").replace(/\/+$/, "") || "/";
@@ -82,10 +59,6 @@ export function substituteRouteParams(
   return result;
 }
 
-/**
- * Run an async function over items with bounded concurrency.
- * Errors propagate immediately and abort remaining work.
- */
 export async function runWithConcurrency<T>(
   items: T[],
   concurrency: number,
@@ -106,10 +79,6 @@ export async function runWithConcurrency<T>(
   await Promise.all(Array.from({ length: limit }, () => worker()));
 }
 
-/**
- * Group prerender entries by their concurrency setting so each group
- * can be rendered with the appropriate parallelism.
- */
 export function groupByConcurrency<T extends { concurrency: number }>(
   entries: T[],
 ): { concurrency: number; entries: T[] }[] {
@@ -129,10 +98,6 @@ export function groupByConcurrency<T extends { concurrency: number }>(
   }));
 }
 
-/**
- * Notify all routers' onError callbacks about a build-time error.
- * Uses a synthetic request since there is no real request during build.
- */
 export function notifyOnError(
   registry: Map<string, any>,
   error: unknown,