@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.13221847

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

@@ -0,0 +1,189 @@
+import { createHash } from "node:crypto";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} 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("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
+/**
+ * Substitute route params into a pattern, stripping constraint and optional
+ * syntax (:param(a|b)? -> value). Also handles wildcard params (*key).
+ */
+export function substituteRouteParams(
+  pattern: string,
+  params: Record<string, string>,
+  encode: (value: string) => string = encodeURIComponent,
+): string {
+  let result = pattern;
+  for (const [key, value] of Object.entries(params)) {
+    const escaped = escapeRegExp(key);
+    result = result.replace(
+      new RegExp(`:${escaped}(\\([^)]*\\))?\\??`),
+      encode(value),
+    );
+    result = result.replace(`*${key}`, encode(value));
+  }
+  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,
+  fn: (item: T) => Promise<void>,
+): Promise<void> {
+  const limit = Math.max(1, Math.min(concurrency, items.length));
+  if (limit <= 1) {
+    for (const item of items) await fn(item);
+    return;
+  }
+  let nextIndex = 0;
+  async function worker() {
+    while (nextIndex < items.length) {
+      const idx = nextIndex++;
+      await fn(items[idx]);
+    }
+  }
+  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[] }[] {
+  const map = new Map<number, T[]>();
+  for (const entry of entries) {
+    const key = entry.concurrency;
+    let group = map.get(key);
+    if (!group) {
+      group = [];
+      map.set(key, group);
+    }
+    group.push(entry);
+  }
+  return Array.from(map.entries(), ([concurrency, items]) => ({
+    concurrency,
+    entries: items,
+  }));
+}
+
+/**
+ * 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,
+  phase: "prerender" | "static",
+  routeKey?: string,
+  pathname?: string,
+  skipped?: boolean,
+): void {
+  for (const [, routerInstance] of registry) {
+    const onError = routerInstance.onError;
+    if (!onError) continue;
+
+    const errorObj = error instanceof Error ? error : new Error(String(error));
+    const syntheticUrl = new URL("http://prerender" + (pathname || "/"));
+    const context = {
+      error: errorObj,
+      phase,
+      request: new Request(syntheticUrl),
+      url: syntheticUrl,
+      pathname: syntheticUrl.pathname,
+      method: "GET",
+      routeKey,
+      metadata: skipped ? { skipped: true } : undefined,
+    };
+
+    try {
+      const result = onError(context);
+      if (result instanceof Promise) {
+        result.catch((cbErr: unknown) => {
+          console.error(`[Build.onError] Callback error:`, cbErr);
+        });
+      }
+    } catch (cbErr) {
+      console.error(`[Build.onError] Callback error:`, cbErr);
+    }
+    break; // Only notify the first router with onError
+  }
+}
+
+function getStagedAssetDir(projectRoot: string): string {
+  return resolve(projectRoot, "node_modules/.rangojs-router-build/rsc-assets");
+}
+
+export function resetStagedBuildAssets(projectRoot: string): void {
+  rmSync(getStagedAssetDir(projectRoot), { recursive: true, force: true });
+}
+
+export function stageBuildAssetModule(
+  projectRoot: string,
+  prefix: "__pr" | "__st",
+  exportValue: string,
+): string {
+  const stagedDir = getStagedAssetDir(projectRoot);
+  mkdirSync(stagedDir, { recursive: true });
+
+  const contentHash = createHash("sha256")
+    .update(exportValue)
+    .digest("hex")
+    .slice(0, 8);
+  const fileName = `${prefix}-${contentHash}.js`;
+  const filePath = resolve(stagedDir, fileName);
+
+  if (!existsSync(filePath)) {
+    writeFileSync(filePath, `export default ${exportValue};\n`);
+  }
+
+  return fileName;
+}
+
+export function copyStagedBuildAssets(
+  projectRoot: string,
+  fileNames: Iterable<string>,
+): number {
+  const stagedDir = getStagedAssetDir(projectRoot);
+  const distAssetsDir = resolve(projectRoot, "dist/rsc/assets");
+  mkdirSync(distAssetsDir, { recursive: true });
+
+  let totalBytes = 0;
+  for (const fileName of new Set(fileNames)) {
+    const stagedPath = resolve(stagedDir, fileName);
+    const distPath = resolve(distAssetsDir, fileName);
+    copyFileSync(stagedPath, distPath);
+    totalBytes += statSync(stagedPath).size;
+  }
+
+  return totalBytes;
+}

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

@@ -0,0 +1,169 @@
+import type { Plugin } from "vite";
+import * as Vite from "vite";
+import { getPublishedPackageName } from "./package-resolution.js";
+import {
+  VIRTUAL_ENTRY_BROWSER,
+  VIRTUAL_ENTRY_SSR,
+  getVirtualEntryRSC,
+  VIRTUAL_IDS,
+} from "../plugins/virtual-entries.js";
+
+/**
+ * esbuild plugin to provide rsc-router:version virtual module during optimization.
+ * This is needed because esbuild runs during Vite's dependency optimization phase,
+ * before Vite's plugin system can handle virtual modules.
+ */
+const versionEsbuildPlugin = {
+  name: "@rangojs/router-version",
+  setup(build: any): void {
+    build.onResolve({ filter: /^rsc-router:version$/ }, (args: any) => ({
+      path: args.path,
+      namespace: "@rangojs/router-virtual",
+    }));
+    build.onLoad(
+      { filter: /.*/, namespace: "@rangojs/router-virtual" },
+      () => ({
+        contents: `export const VERSION = "dev";`,
+        loader: "js",
+      }),
+    );
+  },
+};
+
+/**
+ * Shared esbuild options for dependency optimization.
+ * Includes the version stub plugin for all environments.
+ */
+export const sharedEsbuildOptions: {
+  plugins: (typeof versionEsbuildPlugin)[];
+} = {
+  plugins: [versionEsbuildPlugin],
+};
+
+/**
+ * Create a virtual modules plugin for default entry files.
+ * Provides virtual module content when entries use VIRTUAL_IDS (no custom entry configured).
+ */
+export function createVirtualEntriesPlugin(
+  entries: { client: string; ssr: string; rsc?: string },
+  routerPathRef?: { path?: string },
+): Plugin {
+  // Build virtual modules map based on which entries use virtual IDs
+  const virtualModules: Record<string, string> = {};
+
+  if (entries.client === VIRTUAL_IDS.browser) {
+    virtualModules[VIRTUAL_IDS.browser] = VIRTUAL_ENTRY_BROWSER;
+  }
+  if (entries.ssr === VIRTUAL_IDS.ssr) {
+    virtualModules[VIRTUAL_IDS.ssr] = VIRTUAL_ENTRY_SSR;
+  }
+
+  // RSC entry is resolved lazily in load() because routerPath may be
+  // set after plugin creation (e.g. by the auto-discover config() hook).
+  // Track all known virtual IDs for resolveId (content is separate).
+  const knownIds = new Set(Object.keys(virtualModules));
+  if (entries.rsc === VIRTUAL_IDS.rsc) {
+    knownIds.add(VIRTUAL_IDS.rsc);
+  }
+
+  return {
+    name: "@rangojs/router:virtual-entries",
+    enforce: "pre",
+
+    resolveId(id) {
+      if (knownIds.has(id)) {
+        return "\0" + id;
+      }
+      // Handle if the id already has the null prefix (RSC plugin wrapper imports)
+      if (id.startsWith("\0") && knownIds.has(id.slice(1))) {
+        return id;
+      }
+      return null;
+    },
+
+    load(id) {
+      if (id.startsWith("\0virtual:rsc-router/")) {
+        const virtualId = id.slice(1);
+        if (virtualId in virtualModules) {
+          return virtualModules[virtualId];
+        }
+        // Lazy RSC entry: routerPath may have been set by a config() hook
+        if (virtualId === VIRTUAL_IDS.rsc && routerPathRef?.path) {
+          const raw = routerPathRef.path.startsWith(".")
+            ? "/" + routerPathRef.path.slice(2) // ./src/router.tsx -> /src/router.tsx
+            : routerPathRef.path;
+          // Normalize backslashes for Windows (path.join/slice preserve native separators)
+          const absoluteRouterPath = raw.replaceAll("\\", "/");
+          return getVirtualEntryRSC(absoluteRouterPath);
+        }
+      }
+      return null;
+    },
+  };
+}
+
+/**
+ * Rollup onwarn handler that suppresses known harmless warnings:
+ * - "use client" directives: handled by the RSC plugin, not relevant to Rollup
+ * - sourcemap errors: caused by "use client" directive at line 1:0 confusing sourcemap resolution
+ * - sourcemap incomplete: plugins that transform without generating sourcemaps (router + RSC plugin)
+ * - dynamic/static mixed imports: expected for router internals (e.g. request-context, cache-scope)
+ * - empty bundle: @vitejs/plugin-rsc scan build (step 1/5) produces an empty "index" chunk
+ *   because the RSC entry is fully externalized during client-reference analysis
+ */
+export function onwarn(
+  warning: Vite.Rollup.RollupLog,
+  defaultHandler: (warning: Vite.Rollup.RollupLog) => void,
+): void {
+  if (
+    warning.code === "MODULE_LEVEL_DIRECTIVE" ||
+    warning.code === "SOURCEMAP_ERROR" ||
+    warning.code === "EMPTY_BUNDLE"
+  ) {
+    return;
+  }
+  // @vitejs/plugin-rsc@0.5.14: rsc:virtual:vite-rsc/assets-manifest renderChunk
+  // returns { code } without map, causing Rollup to warn about incorrect sourcemaps.
+  // This is harmless (simple string replacement). Remove this suppression if a
+  // future version of @vitejs/plugin-rsc fixes the missing sourcemap.
+  if (warning.message?.includes("Sourcemap is likely to be incorrect")) {
+    return;
+  }
+  if (
+    warning.plugin === "vite:reporter" &&
+    warning.message?.includes(
+      "dynamic import will not move module into another chunk",
+    )
+  ) {
+    return;
+  }
+  defaultHandler(warning);
+}
+
+/**
+ * Manual chunks configuration for client build.
+ * Splits React and router packages into separate chunks for better caching.
+ */
+export function getManualChunks(id: string): string | undefined {
+  const normalized = Vite.normalizePath(id);
+
+  if (
+    normalized.includes("node_modules/react/") ||
+    normalized.includes("node_modules/react-dom/") ||
+    normalized.includes("node_modules/react-server-dom-webpack/") ||
+    normalized.includes("node_modules/@vitejs/plugin-rsc/")
+  ) {
+    return "react";
+  }
+  // Use dynamic package name from package.json
+  // Check both npm install path and workspace symlink resolved path
+  const packageName = getPublishedPackageName();
+  if (
+    normalized.includes(`node_modules/${packageName}/`) ||
+    normalized.includes("packages/rsc-router/") ||
+    normalized.includes("packages/rangojs-router/")
+  ) {
+    return "router";
+  }
+  return undefined;
+}

package/CLAUDE.md

@@ -1,43 +0,0 @@
-# @rangojs/router
-
-Run `/rango` first to understand the API. Skills are in `node_modules/@rangojs/router/skills/`.
-
-## Tree-Structure-Critical Files (DO NOT MODIFY without understanding)
-
-The following files control the React tree structure. Changing the tree structure
-(element types, nesting depth, or keys at any position) between SSR, navigation,
-and action renders will cause React to remount components, destroying client state
-like `useActionState`, refs, and local state. This is extremely hard to debug.
-
-**Protected files:**
-
-- `src/segment-system.tsx` - `renderSegments()` builds the React tree from segments.
-  The `loading` property determines tree structure:
-  - `undefined` / `null` -> OutletProvider directly (no boundary)
-  - `false` -> LoaderBoundary + OutletProvider (boundary, no RouteContentWrapper)
-  - truthy (ReactNode) -> LoaderBoundary + OutletProvider + RouteContentWrapper
-
-- `src/route-content-wrapper.tsx` - `LoaderBoundary` and `RouteContentWrapper`.
-  These add structural depth (Suspense boundaries) to the React tree.
-
-- `src/browser/server-action-bridge.ts` - Merges server action segments with
-  cached segments. Must preserve cached `loading` values to prevent tree drift.
-
-- `src/browser/partial-update.ts` - Merges navigation segments with cached segments.
-
-**Rules:**
-
-1. Never change the conditional logic in `renderSegments()` that decides between
-   LoaderBoundary/RouteContentWrapper/OutletProvider without verifying all three
-   render paths (SSR, navigation, action) produce identical tree structures.
-
-2. Never add or remove wrapper elements (Suspense, div, Fragment) around segment
-   content without checking that the same wrappers exist in ALL render paths.
-
-3. When merging segments (action bridge, partial update), always preserve the
-   cached `loading` value if it differs from the server value. The server may
-   return different `loading` values based on `isSSR` context.
-
-4. Run `pnpm --filter @rangojs/router exec playwright test loader-behavior` after
-   any changes to these files. The skipSSR action tests specifically catch tree
-   structure regressions.

package/dist/vite/index.named-routes.gen.ts

@@ -1,103 +0,0 @@
-// Auto-generated by @rangojs/router - do not edit
-export {};
-
-declare global {
-  namespace RSCRouter {
-    interface GeneratedRouteMap {
-      "apiShop.cart": "/api/shop/cart";
-      "apiShop.cartItem": "/api/shop/cart/:itemId";
-      "apiShop.catalog": "/api/shop/catalog";
-      "apiShop.health": "/api/shop/health";
-      "apiShop.product": "/api/shop/catalog/:productId";
-      "blog.index": "/blog";
-      "blog.post": "/blog/:postId";
-      "cacheStatus.notFound": "/cache-status/not-found";
-      "cacheStatus.redirect": "/cache-status/redirect";
-      "cacheStatus.redirectTarget": "/cache-status/redirect-target";
-      "cacheStatus.serverError": "/cache-status/server-error";
-      "cacheStatus.success": "/cache-status/success";
-      "cacheTest.cachedLoader": "/cache-test/cached-loader";
-      "cacheTest.interceptDetail": "/cache-test/intercept/:itemId";
-      "cacheTest.interceptIndex": "/cache-test/intercept";
-      "cacheTest.nonCachedLoader": "/cache-test/non-cached-loader";
-      "cacheTest.useLoaderDetail": "/cache-test/useloader/:itemId";
-      "cacheTest.useLoaderIndex": "/cache-test/useloader";
-      "changelog": "/changelog";
-      "docs": "/docs";
-      "docs.article": "/docs/:slug";
-      "errors.clientError": "/errors/client-error";
-      "errors.index": "/errors";
-      "errors.serverError": "/errors/server-error";
-      "errors.streamingError": "/errors/streaming-error";
-      "fetchLoader": "/fetch-loader";
-      "handlePassthrough": "/handle-passthrough";
-      "handlePassthroughAsync": "/handle-passthrough-async";
-      "hookTests.formAction": "/hook-tests/form-action";
-      "hookTests.index": "/hook-tests";
-      "hookTests.noLoader": "/hook-tests/no-loader";
-      "hookTests.routeA": "/hook-tests/route-a";
-      "hookTests.routeB": "/hook-tests/route-b";
-      "href.detail": "/href/:id";
-      "href.index": "/href";
-      "href.nested.index": "/href/nested";
-      "hydrationTest": "/hydration-test";
-      "index": "/";
-      "inlineAction": "/inline-action";
-      "loaderComposition": "/loader-composition";
-      "metaMerge.child": "/meta-merge/child";
-      "metaMerge.deep": "/meta-merge/deep/nested";
-      "metaMerge.index": "/meta-merge";
-      "metaTemplate.absolute": "/meta-template/absolute";
-      "metaTemplate.child": "/meta-template/child";
-      "metaTemplate.index": "/meta-template";
-      "metaTemplate.nested": "/meta-template/nested";
-      "metaTemplate.nestedChild": "/meta-template/nested/child";
-      "metaUnset.child": "/meta-unset/child";
-      "metaUnset.index": "/meta-unset";
-      "metaUnset.unsetThenSet": "/meta-unset/unset-then-set";
-      "middlewareTest.cookies": "/middleware-test/cookies";
-      "middlewareTest.errorHandler": "/middleware-test/error-handler/trigger";
-      "middlewareTest.index": "/middleware-test";
-      "middlewareTest.params": "/middleware-test/params/:paramId";
-      "middlewareTest.protected": "/middleware-test/protected";
-      "middlewareTest.protectedDashboard": "/middleware-test/protected/dashboard";
-      "middlewareTest.routeLevel": "/middleware-test/route-level";
-      "middlewareTest.routeLevelWithParams": "/middleware-test/route-level/:routeId";
-      "middlewareTest.sharedVars": "/middleware-test/shared-vars";
-      "negotiateJsonFirst": "/negotiate-test-json-first";
-      "negotiateJsonFirstRsc": "/negotiate-test-json-first";
-      "negotiateTest": "/negotiate-test";
-      "negotiateTestJson": "/negotiate-test";
-      "negotiateTestMd": "/negotiate-test";
-      "proactiveCache.index": "/proactive-cache";
-      "proactiveCache.itemA": "/proactive-cache/item-a";
-      "proactiveCache.itemB": "/proactive-cache/item-b";
-      "product.detail": "/product/:productId";
-      "progressiveEnhancement": "/progressive-enhancement";
-      "refTest.bothProps": "/ref-test/both-props";
-      "refTest.handleProp": "/ref-test/handle-prop";
-      "refTest.loaderProp": "/ref-test/loader-prop";
-      "responseInLayout": "/response-in-layout";
-      "responseInLayoutMd": "/response-in-layout-md";
-      "responseMwMd": "/response-mw/md-with-mw";
-      "responseMwNested": "/response-mw/nested";
-      "responseWrapAuto": "/response-wrap/auto";
-      "responseWrapCustom": "/response-wrap/custom-response";
-      "responseWrapHtml": "/response-wrap/html";
-      "responseWrapJsonHeaders": "/response-wrap/json-headers";
-      "responseWrapText": "/response-wrap/text";
-      "responseWrapWithHeaders": "/response-wrap/with-headers";
-      "responseWrapXml": "/response-wrap/xml";
-      "shopPlayground": "/shop-playground";
-      "slow": "/slow";
-      "slowProduct.detail": "/slow-product/:productId";
-      "slowStreaming": "/slow-streaming";
-      "slowStreamingSkipSsr": "/slow-streaming-skip-ssr";
-      "theme.index": "/theme";
-      "theme.toggle": "/theme/toggle";
-      "trailingSlash.always": "/ts-always";
-      "trailingSlash.ignore": "/ts-ignore";
-      "trailingSlash.never": "/ts-never";
-    }
-  }
-}

package/src/browser/lru-cache.ts

@@ -1,69 +0,0 @@
-/**
- * Simple LRU (Least Recently Used) cache implementation
- * Used for caching navigation segments to enable instant back/forward
- */
-export class LRUCache<K, V> {
-  private cache = new Map<K, V>();
-  private maxSize: number;
-
-  constructor(maxSize: number) {
-    this.maxSize = maxSize;
-  }
-
-  get(key: K): V | undefined {
-    if (!this.cache.has(key)) {
-      return undefined;
-    }
-
-    // Move to end (most recently used)
-    const value = this.cache.get(key)!;
-    this.cache.delete(key);
-    this.cache.set(key, value);
-    return value;
-  }
-
-  set(key: K, value: V): void {
-    // If key exists, delete it first to update position
-    if (this.cache.has(key)) {
-      this.cache.delete(key);
-    }
-
-    this.cache.set(key, value);
-
-    // Evict oldest entries if over capacity
-    while (this.cache.size > this.maxSize) {
-      const oldestKey = this.cache.keys().next().value;
-      if (oldestKey !== undefined) {
-        this.cache.delete(oldestKey);
-      }
-    }
-  }
-
-  has(key: K): boolean {
-    if (!this.cache.has(key)) {
-      return false;
-    }
-
-    // Move to end (most recently used) - same as get()
-    const value = this.cache.get(key)!;
-    this.cache.delete(key);
-    this.cache.set(key, value);
-    return true;
-  }
-
-  delete(key: K): boolean {
-    return this.cache.delete(key);
-  }
-
-  clear(): void {
-    this.cache.clear();
-  }
-
-  keys(): IterableIterator<K> {
-    return this.cache.keys();
-  }
-
-  get size(): number {
-    return this.cache.size;
-  }
-}