@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.25dbaac3

package/src/vite/utils/banner.ts

@@ -1,4 +1,4 @@
-import packageJson from "../../../package.json" with { type: "json" };
+import packageJson from "../../../package.json";
 
 export const rangoVersion: string = packageJson.version;
 
@@ -23,11 +23,11 @@ ${dim} ╱${reset}    ${bold}╔═╗${reset}${dim}      *      ╱
 ${dim}      ${reset}${bold}║ ║${reset} ${bold}╔═╗${reset}${dim}                    *                ✧.   ╱${reset}
 ${dim}   ${reset}${bold}╔╗ ║ ║ ║ ║${reset}${dim}                          *               ╱${reset}
 ${dim}   ${reset}${bold}║║ ║ ║ ║ ║  ╦═╗╔═╗╔╗╔╔═╗╔═╗${reset}${dim}             ✧              ✦${reset}
-${dim}  ${reset}${bold}═╣║ ║ ╠═╝ ║  ╠╦╝╠═╣║║║║ ╦║ ║${reset}${dim}        *           ✧${reset}
+${dim}   ${reset}${bold}║║ ║ ╠═╝ ║  ╠╦╝╠═╣║║║║ ╦║ ║${reset}${dim}        *           ✧${reset}
 ${dim}   ${reset}${bold}║╚═╝ ╔═══╝  ╩╚═╩ ╩╝╚╝╚═╝╚═╝${reset}${dim}            ✦          .      *${reset}
 ${dim}   ${reset}${bold}╚══╗ ║${reset}${dim} *      RSC Wrangler         ✧                ✦${reset}
-${dim}  *   ${reset}${bold}║ ╠═${reset}${dim}                         *            ✧.    ╱${reset}
-${bold}══════╝ ╚═════════╩═══${reset}${dim}                  ✦            *${reset}
+${dim}  *   ${reset}${bold}║ ║${reset}${dim}                          *            ✧.    ╱${reset}
+${dim}   ${reset}${bold}═══╝ ╚════${reset}${dim}                           ✦            *${reset}
 
    v${version} · ${preset} · ${mode}
 `;

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

@@ -6,8 +6,11 @@
  */
 
 import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
 import { resolve } from "node:path";
-import packageJson from "../../../package.json" with { type: "json" };
+import packageJson from "../../../package.json";
+
+const require = createRequire(import.meta.url);
 
 /**
  * The canonical name used in virtual entries (without scope)
@@ -119,3 +122,40 @@ 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",
+  ];
+  const aliases: Record<string, string> = {};
+  for (const spec of specs) {
+    try {
+      aliases[spec] = require.resolve(spec);
+    } catch {
+      // Spec unresolvable (unexpected but non-fatal — Vite will warn as before).
+    }
+  }
+  return aliases;
+}

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

@@ -1,3 +1,14 @@
+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.
@@ -17,6 +28,59 @@ 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>,
+  encode: (value: string) => string = encodeURIComponent,
+): string {
+  let result = pattern;
+  let hadOmittedOptional = false;
+
+  // First pass: substitute provided params.
+  // Empty string on an optional placeholder is treated as omitted (the trie
+  // matcher fills unmatched optionals with "" — 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}(\\([^)]*\\))?(?!\\?)`),
+        "",
+      );
+      result = result.replace(`*${key}`, "");
+    } else {
+      result = result.replace(
+        new RegExp(`:${escaped}(\\([^)]*\\))?\\??`),
+        encode(value),
+      );
+      result = result.replace(`*${key}`, encode(value));
+    }
+  }
+
+  // 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(/\/+$/, "") || "/";
+    if (hadTrailingSlash && !result.endsWith("/")) result += "/";
+  }
+
+  return result;
+}
+
 /**
  * Run an async function over items with bounded concurrency.
  * Errors propagate immediately and abort remaining work.
@@ -106,3 +170,52 @@ export function notifyOnError(
     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

@@ -1,6 +1,7 @@
 import type { Plugin } from "vite";
 import * as Vite from "vite";
 import { getPublishedPackageName } from "./package-resolution.js";
+import { performanceTracksOptimizeDepsPlugin } from "../plugins/performance-tracks.js";
 import {
   VIRTUAL_ENTRY_BROWSER,
   VIRTUAL_ENTRY_SSR,
@@ -35,9 +36,9 @@ const versionEsbuildPlugin = {
  * Includes the version stub plugin for all environments.
  */
 export const sharedEsbuildOptions: {
-  plugins: (typeof versionEsbuildPlugin)[];
+  plugins: any[];
 } = {
-  plugins: [versionEsbuildPlugin],
+  plugins: [versionEsbuildPlugin, performanceTracksOptimizeDepsPlugin()],
 };
 
 /**
@@ -46,7 +47,7 @@ export const sharedEsbuildOptions: {
  */
 export function createVirtualEntriesPlugin(
   entries: { client: string; ssr: string; rsc?: string },
-  routerPath?: string,
+  routerPathRef?: { path?: string },
 ): Plugin {
   // Build virtual modules map based on which entries use virtual IDs
   const virtualModules: Record<string, string> = {};
@@ -57,12 +58,13 @@ export function createVirtualEntriesPlugin(
   if (entries.ssr === VIRTUAL_IDS.ssr) {
     virtualModules[VIRTUAL_IDS.ssr] = VIRTUAL_ENTRY_SSR;
   }
-  if (entries.rsc === VIRTUAL_IDS.rsc && routerPath) {
-    // Convert relative path to absolute for virtual module imports
-    const absoluteRouterPath = routerPath.startsWith(".")
-      ? "/" + routerPath.slice(2) // ./src/router.tsx -> /src/router.tsx
-      : routerPath;
-    virtualModules[VIRTUAL_IDS.rsc] = getVirtualEntryRSC(absoluteRouterPath);
+
+  // 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 {
@@ -70,11 +72,11 @@ export function createVirtualEntriesPlugin(
     enforce: "pre",
 
     resolveId(id) {
-      if (id in virtualModules) {
+      if (knownIds.has(id)) {
         return "\0" + id;
       }
       // Handle if the id already has the null prefix (RSC plugin wrapper imports)
-      if (id.startsWith("\0") && id.slice(1) in virtualModules) {
+      if (id.startsWith("\0") && knownIds.has(id.slice(1))) {
         return id;
       }
       return null;
@@ -86,6 +88,15 @@ export function createVirtualEntriesPlugin(
         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;
     },

package/skills/testing/SKILL.md

@@ -1,226 +0,0 @@
----
-name: testing
-description: Unit test route trees with buildRouteTree()
-argument-hint:
----
-
-# Route Tree Unit Testing
-
-Unit test route definitions by inspecting the route tree, segment IDs, middleware, intercepts, loaders, and pattern matching without running a dev server.
-
-## Setup
-
-The `buildRouteTree` helper lives in `src/__tests__/helpers/route-tree.ts` (not shipped with npm). Import it in your test files:
-
-```typescript
-import { buildRouteTree } from "./helpers/route-tree.js";
-```
-
-## buildRouteTree(urlPatterns)
-
-Takes a `urls()` result and returns a `RouteTree` with inspection methods:
-
-```typescript
-import { urls } from "@rangojs/router";
-import { buildRouteTree } from "./helpers/route-tree.js";
-
-const tree = buildRouteTree(
-  urls(({ path, layout, middleware, loader, intercept, when }) => [
-    layout(RootLayout, () => [
-      middleware(authMiddleware),
-      path("/", HomePage, { name: "home" }),
-      path("/blog/:slug", BlogPost, { name: "blog.post" }, () => [
-        loader(PostLoader),
-      ]),
-    ]),
-  ]),
-);
-```
-
-## RouteTree API
-
-### Route Patterns
-
-```typescript
-tree.routes(); // { home: "/", "blog.post": "/blog/:slug" }
-tree.routeNames(); // ["home", "blog.post"]
-```
-
-### URL Matching
-
-```typescript
-const m = tree.match("/blog/hello");
-m.routeKey; // "blog.post"
-m.params; // { slug: "hello" }
-
-tree.match("/nonexistent"); // null
-```
-
-### Segment IDs
-
-```typescript
-tree.segmentId("home"); // "M0L0L0R0"
-tree.segmentIds(); // { home: "M0L0L0R0", "blog.post": "M0L0L0R1" }
-tree.segmentPath("blog.post");
-// [
-//   { id: "M0L0",     type: "layout" },  // synthetic root
-//   { id: "M0L0L0",   type: "layout" },  // RootLayout
-//   { id: "M0L0L0R1", type: "route", pattern: "/blog/:slug" },
-// ]
-```
-
-### Entry Access
-
-```typescript
-tree.entry("blog.post"); // EntryData
-tree.entry("blog.post")!.parent!.type; // "layout"
-tree.entryByPattern("/blog/:slug"); // EntryData (lookup by URL pattern)
-```
-
-### Middleware
-
-```typescript
-tree.hasMiddleware("home"); // true (inherited from layout)
-tree.middleware("home"); // [authMiddleware] (direct only)
-tree.middlewareChain("home");
-// [{ segmentId: "M0L0L0", count: 1 }]   // all middleware root-to-route
-```
-
-### Loaders
-
-```typescript
-tree.hasLoaders("blog.post"); // true
-tree.loaders("blog.post"); // [LoaderEntry { loader, revalidate, cache? }]
-```
-
-### Intercepts
-
-```typescript
-tree.intercepts("home");
-// [{ slotName: "@modal", routeName: "card", hasWhen: true, whenCount: 1, hasLoader: false, hasMiddleware: false }]
-tree.interceptEntries("home"); // raw InterceptEntry[]
-```
-
-### Parallel Slots
-
-```typescript
-tree.parallelSlots("home"); // EntryData[] of type="parallel"
-tree.parallelSlotNames("home"); // ["@sidebar", "@main"]
-```
-
-### Boundaries
-
-```typescript
-tree.hasErrorBoundary("home"); // boolean
-tree.hasNotFoundBoundary("home"); // boolean
-```
-
-### Cache & Loading
-
-```typescript
-tree.hasCache("home"); // boolean
-tree.hasLoading("home"); // boolean
-```
-
-### Debug
-
-```typescript
-console.log(tree.debug());
-// Route Tree:
-//   home: / [M0L0L0R0] (M0L0 > M0L0L0 > M0L0L0R0) {mw:1}
-//   blog.post: /blog/:slug [M0L0L0R1] (M0L0 > M0L0L0 > M0L0L0R1) {mw:1, ld:1}
-```
-
-## Segment ID Format
-
-| Prefix | Meaning                       |
-| ------ | ----------------------------- |
-| `M0`   | Mount index (router instance) |
-| `L`    | Layout                        |
-| `R`    | Route                         |
-| `P`    | Parallel slot                 |
-| `D`    | Loader (data)                 |
-| `C`    | Cache boundary                |
-
-Example: `M0L0L0R1` = mount 0, synthetic root layout, user layout, second route.
-
-## Examples
-
-### include() with prefix
-
-```typescript
-const blogPatterns = urls(({ path }) => [
-  path("/", BlogIndex, { name: "index" }),
-  path("/:slug", BlogPost, { name: "post" }),
-]);
-
-const tree = buildRouteTree(
-  urls(({ path, include }) => [
-    path("/", HomePage, { name: "home" }),
-    include("/blog", blogPatterns, { name: "blog" }),
-  ]),
-);
-
-expect(tree.routes()).toEqual({
-  home: "/",
-  "blog.index": "/blog",
-  "blog.post": "/blog/:slug",
-});
-```
-
-### Middleware chain
-
-```typescript
-const authMw = async (ctx, next) => next();
-const logMw = async (ctx, next) => next();
-
-const tree = buildRouteTree(
-  urls(({ path, layout, middleware }) => [
-    layout(RootLayout, () => [
-      middleware(logMw),
-      layout(AuthLayout, () => [
-        middleware(authMw),
-        path("/dashboard", Dashboard, { name: "dashboard" }),
-      ]),
-    ]),
-  ]),
-);
-
-expect(tree.middlewareChain("dashboard")).toEqual([
-  { segmentId: "M0L0L0", count: 1 }, // logMw on RootLayout
-  { segmentId: "M0L0L0L0", count: 1 }, // authMw on AuthLayout
-]);
-```
-
-### Intercepts with when()
-
-```typescript
-const tree = buildRouteTree(
-  urls(({ path, layout, intercept, when }) => [
-    layout(ShopLayout, () => [
-      path("/products", ProductList, { name: "products" }),
-      path("/products/:id", ProductDetail, { name: "product.detail" }),
-      intercept("@modal", "product.detail", ProductModal, () => [
-        when((ctx) => ctx.from.pathname.startsWith("/products")),
-      ]),
-    ]),
-  ]),
-);
-
-const intercepts = tree.intercepts("products");
-// Note: intercepts are on the parent where intercept() is called
-```
-
-### Constrained parameters
-
-```typescript
-const tree = buildRouteTree(
-  urls(({ path }) => [
-    path("/:locale(en|fr)?/about", AboutPage, { name: "about" }),
-  ]),
-);
-
-expect(tree.match("/about")).not.toBeNull();
-expect(tree.match("/fr/about")!.params).toEqual({ locale: "fr" });
-expect(tree.match("/de/about")).toBeNull();
-```

package/src/browser/lru-cache.ts

@@ -1,61 +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 {
-    return this.cache.has(key);
-  }
-
-  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;
-  }
-}

package/src/browser/react/prefetch.ts

@@ -1,27 +0,0 @@
-"use client";
-
-// Track prefetched URLs to avoid duplicate <link> elements
-const prefetchedUrls = new Set<string>();
-
-/**
- * Inject a <link rel="prefetch"> element into the document head
- * for the given URL with RSC partial request parameters.
- */
-export function prefetchUrl(url: string, segmentIds: string[]): void {
-  if (prefetchedUrls.has(url)) return;
-  prefetchedUrls.add(url);
-
-  // Build RSC partial URL with segment IDs
-  const targetUrl = new URL(url, window.location.origin);
-  targetUrl.searchParams.set("_rsc_partial", "true");
-  if (segmentIds.length > 0) {
-    targetUrl.searchParams.set("_rsc_segments", segmentIds.join(","));
-  }
-
-  // Inject <link rel="prefetch"> into head
-  const link = document.createElement("link");
-  link.rel = "prefetch";
-  link.href = targetUrl.toString();
-  link.as = "fetch";
-  document.head.appendChild(link);
-}