@rangojs/router 0.0.0-experimental.3 → 0.0.0-experimental.4

package/CLAUDE.md

@@ -1,3 +1,43 @@
 # @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.js

@@ -211,6 +211,36 @@ function countCreateLoaderArgs(code, startPos, endPos) {
   }
   return hasContent ? argCount + 1 : 0;
 }
+function generateClientLoaderStubs(code, filePath, isBuild) {
+  const loaderPattern = /export\s+const\s+(\w+)\s*=\s*createLoader\s*\(/g;
+  const loaders = [];
+  let match;
+  while ((match = loaderPattern.exec(code)) !== null) {
+    loaders.push(match[1]);
+  }
+  if (loaders.length === 0) {
+    return null;
+  }
+  const allExports = /export\s+(const|let|var|function|class|default)\s+(\w+)/g;
+  let exportMatch;
+  const nonLoaderExports = [];
+  while ((exportMatch = allExports.exec(code)) !== null) {
+    const name = exportMatch[2];
+    if (!loaders.includes(name)) {
+      nonLoaderExports.push(name);
+    }
+  }
+  if (nonLoaderExports.length > 0) {
+    return null;
+  }
+  const stubs = loaders.map((name) => {
+    const loaderId = isBuild ? hashLoaderId(filePath, name) : `${filePath}#${name}`;
+    return `export const ${name} = { __brand: "loader", $$id: "${loaderId}" };`;
+  });
+  return {
+    code: stubs.join("\n") + "\n"
+  };
+}
 function transformLoaderExports(code, filePath, sourceId, isBuild = false) {
   if (!code.includes("createLoader")) {
     return null;
@@ -376,6 +406,12 @@ ${lazyImports.join(",\n")}
           loaderRegistry.set(hashedId, { filePath: relativePath, exportName });
         }
       }
+      if (!isRscEnv) {
+        const stubResult = generateClientLoaderStubs(code, relativePath, isBuild);
+        if (stubResult) {
+          return stubResult;
+        }
+      }
       return transformLoaderExports(code, relativePath, id, isBuild);
     }
   };
@@ -634,7 +670,7 @@ import {
   decodeFormState,
 } from "@rangojs/router/internal/deps/rsc";
 import { router } from "${routerPath}";
-import { createRSCHandler } from "@rangojs/router/rsc";
+import { createRSCHandler } from "@rangojs/router/internal/rsc-handler";
 import { VERSION } from "@rangojs/router:version";
 
 // Import loader manifest to ensure all fetchable loaders are registered at startup
@@ -642,6 +678,9 @@ import { VERSION } from "@rangojs/router:version";
 // might not be imported before a GET request arrives
 import "virtual:rsc-router/loader-manifest";
 
+// Route manifest is now loaded at runtime on first request via getRouteManifestData()
+// This eliminates the need for build-time manifest generation
+
 export default createRSCHandler({
   router,
   version: VERSION,
@@ -675,7 +714,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.3",
+  version: "0.0.0-experimental.4",
   type: "module",
   description: "Django-inspired RSC router with composable URL patterns",
   author: "Ivo Todorov",
@@ -760,6 +799,11 @@ var package_default = {
       types: "./src/deps/html-stream-server.ts",
       default: "./src/deps/html-stream-server.ts"
     },
+    "./internal/rsc-handler": {
+      "react-server": "./src/rsc/handler.ts",
+      types: "./src/rsc/handler.ts",
+      default: "./src/rsc/handler.ts"
+    },
     "./cache": {
       "react-server": "./src/cache/index.ts",
       types: "./src/cache/index.ts",
@@ -768,6 +812,10 @@ var package_default = {
     "./theme": {
       types: "./src/theme/index.ts",
       default: "./src/theme/index.ts"
+    },
+    "./build": {
+      types: "./src/build/index.ts",
+      import: "./src/build/index.ts"
     }
   },
   files: [
@@ -814,12 +862,13 @@ var package_default = {
     "@types/node": "^24.10.1",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
+    esbuild: "^0.27.0",
+    jiti: "^2.6.1",
     react: "catalog:",
     "react-dom": "catalog:",
-    esbuild: "^0.27.0",
     tinyexec: "^0.3.2",
     typescript: "^5.3.0",
-    vitest: "^2.1.8"
+    vitest: "^4.0.0"
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.3",
+  "version": "0.0.0-experimental.4",
   "type": "module",
   "description": "Django-inspired RSC router with composable URL patterns",
   "author": "Ivo Todorov",
@@ -85,6 +85,11 @@
       "types": "./src/deps/html-stream-server.ts",
       "default": "./src/deps/html-stream-server.ts"
     },
+    "./internal/rsc-handler": {
+      "react-server": "./src/rsc/handler.ts",
+      "types": "./src/rsc/handler.ts",
+      "default": "./src/rsc/handler.ts"
+    },
     "./cache": {
       "react-server": "./src/cache/index.ts",
       "types": "./src/cache/index.ts",
@@ -93,6 +98,10 @@
     "./theme": {
       "types": "./src/theme/index.ts",
       "default": "./src/theme/index.ts"
+    },
+    "./build": {
+      "types": "./src/build/index.ts",
+      "import": "./src/build/index.ts"
     }
   },
   "files": [
@@ -130,12 +139,13 @@
     "@types/node": "^24.10.1",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
+    "esbuild": "^0.27.0",
+    "jiti": "^2.6.1",
     "react": "^19.2.1",
     "react-dom": "^19.2.1",
-    "esbuild": "^0.27.0",
     "tinyexec": "^0.3.2",
     "typescript": "^5.3.0",
-    "vitest": "^2.1.8"
+    "vitest": "^4.0.0"
   },
   "scripts": {
     "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external",

package/skills/caching/SKILL.md

@@ -13,7 +13,7 @@ argument-hint: [setup]
 Use the `cache()` DSL function to cache routes:
 
 ```typescript
-import { urls } from "@rangojs/router/server";
+import { urls } from "@rangojs/router";
 
 export const urlpatterns = urls(({ path, cache }) => [
   // Cache these routes for 60 seconds, SWR for 5 minutes
@@ -59,14 +59,14 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 Configure a cache store in the router:
 
 ```typescript
-import { createRSCRouter } from "@rangojs/router/server";
+import { createRouter } from "@rangojs/router";
 import { MemorySegmentCacheStore } from "@rangojs/router/rsc";
 
 const store = new MemorySegmentCacheStore({
   defaults: { ttl: 60, swr: 300 },
 });
 
-const router = createRSCRouter({
+const router = createRouter({
   document: Document,
   urls: urlpatterns,
   cache: {
@@ -98,7 +98,7 @@ For distributed caching on Cloudflare Workers:
 ```typescript
 import { CFCacheStore } from "@rangojs/router/cache/cf";
 
-const router = createRSCRouter({
+const router = createRouter({
   document: Document,
   urls: urlpatterns,
   cache: (env) => ({
@@ -145,7 +145,7 @@ cache({ store: checkoutCache }, () => [
 ## Complete Example
 
 ```typescript
-import { urls } from "@rangojs/router/server";
+import { urls } from "@rangojs/router";
 import { MemorySegmentCacheStore } from "@rangojs/router/rsc";
 
 // Custom store for checkout (short TTL)

package/skills/document-cache/SKILL.md

@@ -13,11 +13,11 @@ Caches complete HTTP responses (HTML/RSC) at the edge based on Cache-Control hea
 Configure document cache in router:
 
 ```typescript
-import { createRSCRouter } from "@rangojs/router/server";
+import { createRouter } from "@rangojs/router";
 import { CFCacheStore } from "@rangojs/router/cache/cf";
 import { urlpatterns } from "./urls";
 
-const router = createRSCRouter<AppEnv>({
+const router = createRouter<AppEnv>({
   document: Document,
   urls: urlpatterns,
   documentCache: (env) => ({
@@ -35,7 +35,7 @@ export default router;
 Routes opt-in to document caching using the `cache()` DSL with `documentCache` option:
 
 ```typescript
-import { urls } from "@rangojs/router/server";
+import { urls } from "@rangojs/router";
 
 export const urlpatterns = urls(({ path, cache }) => [
   // Cache full page for 5 min, serve stale for 1 hour
@@ -56,7 +56,7 @@ export const urlpatterns = urls(({ path, cache }) => [
 ## Document Cache Options
 
 ```typescript
-createRSCRouter({
+createRouter({
   // ...
   documentCache: (env) => ({
     // Cache store (required)
@@ -131,11 +131,11 @@ Segment hash ensures different cached responses for navigations from different s
 
 ```typescript
 // router.tsx
-import { createRSCRouter } from "@rangojs/router/server";
+import { createRouter } from "@rangojs/router";
 import { CFCacheStore } from "@rangojs/router/cache/cf";
 import { urlpatterns } from "./urls";
 
-const router = createRSCRouter<AppEnv>({
+const router = createRouter<AppEnv>({
   document: Document,
   urls: urlpatterns,
   documentCache: (env) => ({
@@ -148,7 +148,7 @@ const router = createRSCRouter<AppEnv>({
 export default router;
 
 // urls.tsx
-import { urls } from "@rangojs/router/server";
+import { urls } from "@rangojs/router";
 
 export const urlpatterns = urls(({ path, layout, cache, loader }) => [
   // Blog with document caching

package/skills/hooks/SKILL.md

@@ -108,6 +108,20 @@ function ProductPrice() {
 
 **Precondition**: Loader must be registered on route via `loader()` helper.
 
+Loaders can also be passed as props from server to client components:
+
+```tsx
+"use client";
+import { useLoader } from "@rangojs/router/client";
+import type { ProductLoader } from "../loaders";
+
+// typeof infers the full data type from the loader definition
+function ProductCard({ loader }: { loader: typeof ProductLoader }) {
+  const { data } = useLoader(loader);
+  return <h2>{data.product.name}</h2>;
+}
+```
+
 ### useFetchLoader()
 
 Access loader with on-demand fetching (flexible):
@@ -194,6 +208,31 @@ function BreadcrumbNav() {
 const lastCrumb = useHandle(Breadcrumbs, data => data.at(-1));
 ```
 
+Handles can be passed as props from server to client components:
+
+```tsx
+// Server component
+path("/dashboard", (ctx) => {
+  const push = ctx.use(Breadcrumbs);
+  push({ label: "Dashboard", href: "/dashboard" });
+  return <DashboardNav handle={Breadcrumbs} />;
+})
+
+// Client component — typeof infers the full Handle<T> type
+"use client";
+import { useHandle } from "@rangojs/router/client";
+import type { Breadcrumbs } from "../handles";
+
+function DashboardNav({ handle }: { handle: typeof Breadcrumbs }) {
+  const crumbs = useHandle(handle);
+  return <nav>{crumbs.map(c => <a href={c.href}>{c.label}</a>)}</nav>;
+}
+```
+
+RSC serialization strips the `collect` function via `toJSON()`. On the client,
+`useHandle()` recovers it from the module-level registry (populated when
+`createHandle()` runs during module initialization).
+
 ## Action Hooks
 
 ### useAction()
@@ -343,10 +382,54 @@ function ConditionalLayout() {
 }
 ```
 
+## URL Hooks
+
+### useHref()
+
+Mount-aware href for client components inside `include()` scopes:
+
+```tsx
+"use client";
+import { useHref, href, Link } from "@rangojs/router/client";
+
+// Inside include("/shop", shopPatterns)
+function ShopNav() {
+  const href = useHref();
+
+  return (
+    <>
+      {/* Local paths - auto-prefixed with /shop */}
+      <Link to={href("/cart")}>Cart</Link>
+      <Link to={href("/product/widget")}>Widget</Link>
+    </>
+  );
+}
+```
+
+Use `useHref()` for local navigation. Use the bare `href()` function for absolute paths.
+
+### useMount()
+
+Returns the current `include()` mount path:
+
+```tsx
+"use client";
+import { useMount } from "@rangojs/router/client";
+
+function MountInfo() {
+  const mount = useMount(); // "/shop" inside include("/shop", ...)
+  return <span>Mounted at: {mount}</span>;
+}
+```
+
+See `/links` for full URL generation guide including server-side `ctx.href`.
+
 ## Hook Summary
 
 | Hook | Purpose | Returns |
 |------|---------|---------|
+| `useHref()` | Mount-aware href | `(path) => string` |
+| `useMount()` | Current include() mount path | `string` |
 | `useNavigation()` | Navigation state & control | state, navigate, refresh |
 | `useSegments()` | URL path & segment IDs | path, segmentIds, location |
 | `useLinkStatus()` | Link pending state | { pending } |

package/skills/intercept/SKILL.md

@@ -11,7 +11,7 @@ Intercept routes render a different component during soft navigation (client-sid
 ## Basic Intercept
 
 ```typescript
-import { urls } from "@rangojs/router/server";
+import { urls } from "@rangojs/router";
 import { Outlet, ParallelOutlet } from "@rangojs/router/client";
 
 function ShopLayout() {
@@ -149,7 +149,7 @@ function ModalWrapper({ children }) {
 }
 
 // urls/shop.tsx
-import { urls } from "@rangojs/router/server";
+import { urls } from "@rangojs/router";
 
 export const shopPatterns = urls(({
   path,

package/skills/layout/SKILL.md

@@ -11,7 +11,7 @@ Layouts wrap child routes and persist during navigation within their scope.
 ## Basic Layout
 
 ```typescript
-import { urls } from "@rangojs/router/server";
+import { urls } from "@rangojs/router";
 import { Outlet } from "@rangojs/router/client";
 
 function ShopLayout() {
@@ -164,7 +164,7 @@ layout(<CartLayout />, () => [
 ## Complete Example
 
 ```typescript
-import { urls } from "@rangojs/router/server";
+import { urls } from "@rangojs/router";
 import { Outlet, ParallelOutlet } from "@rangojs/router/client";
 
 function ShopLayout() {

package/skills/links/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: links
+description: URL generation with ctx.href (server), href (client), useHref (mounted), useMount, and scopedHref
+argument-hint: [href|useHref|useMount|scopedHref]
+---
+
+# Links & URL Generation
+
+@rangojs/router provides different href APIs for server and client contexts.
+
+## Server: ctx.href()
+
+Available in route handlers via HandlerContext. Resolves named routes using the full route map.
+
+```typescript
+import { urls, scopedHref } from "@rangojs/router";
+
+export const shopPatterns = urls(({ path, layout }) => [
+  layout(<ShopLayout />, () => [
+    path("/", ShopIndex, { name: "index" }),
+    path("/cart", CartPage, { name: "cart" }),
+    path("/product/:slug", ProductPage, { name: "product" }),
+  ]),
+]);
+```
+
+### Resolution priority
+
+1. **Path-based** (`/...`) - returned as-is
+2. **Absolute name** (contains dot: `blog.post`) - global lookup
+3. **Local name** (`cart`) - resolved relative to current route's namespace
+
+```typescript
+// Inside a handler within shopPatterns (mounted at /shop)
+path("/product/:slug", (ctx) => {
+  ctx.href("cart");                        // "/shop/cart" (local)
+  ctx.href("product", { slug: "widget" }); // "/shop/product/widget" (local + params)
+  ctx.href("blog.post", { slug: "hi" });   // "/blog/hi" (absolute)
+  ctx.href("/about");                      // "/about" (path-based)
+
+  return <ProductPage slug={ctx.params.slug} />;
+}, { name: "product" })
+```
+
+### scopedHref() - type-safe ctx.href
+
+Wraps `ctx.href` with local route type information for autocomplete and validation:
+
+```typescript
+import { scopedHref } from "@rangojs/router";
+
+path("/product/:slug", (ctx) => {
+  const href = scopedHref<typeof shopPatterns>(ctx.href);
+
+  href("cart");                        // Type-safe local name
+  href("product", { slug: "widget" }); // Type-safe with params
+  href("blog.post");                   // Absolute names (dot notation) always allowed
+  href("/about");                      // Path-based always allowed
+
+  return <ProductPage slug={ctx.params.slug} />;
+}, { name: "product" })
+```
+
+## Client: href()
+
+Plain function for absolute path-based URLs. No hook needed - works anywhere.
+
+```typescript
+"use client";
+import { href, Link } from "@rangojs/router/client";
+
+function GlobalNav() {
+  return (
+    <nav>
+      <Link to={href("/")}>Home</Link>
+      <Link to={href("/about")}>About</Link>
+      <Link to={href("/blog/hello")}>Post</Link>
+    </nav>
+  );
+}
+```
+
+`href()` is an identity function at runtime but provides compile-time validation via `ValidPaths` type. Paths are validated against registered route patterns using `PatternToPath`.
+
+## Client: useHref()
+
+Hook that returns a mount-aware href function. Automatically prepends the `include()` mount prefix.
+
+```typescript
+"use client";
+import { useHref, href, Link } from "@rangojs/router/client";
+
+// Inside include("/shop", shopPatterns)
+function ShopNav() {
+  const href = useHref();
+
+  return (
+    <nav>
+      <Link to={href("/")}>Shop Home</Link>        {/* "/shop/" */}
+      <Link to={href("/cart")}>Cart</Link>          {/* "/shop/cart" */}
+      <Link to={href("/product/widget")}>W</Link>   {/* "/shop/product/widget" */}
+    </nav>
+  );
+}
+```
+
+Use `useHref()` for local navigation within a mounted module. Use the bare `href()` function for absolute paths outside the current mount.
+
+## Client: useMount()
+
+Returns the current `include()` mount path. Useful for building custom logic based on mount location.
+
+```typescript
+"use client";
+import { useMount } from "@rangojs/router/client";
+
+function MountInfo() {
+  const mount = useMount(); // "/shop" inside include("/shop", ...)
+                            // "/" at root level
+
+  return <span>Mounted at: {mount}</span>;
+}
+```
+
+`useMount()` reads from `MountContext`, which is automatically set by `include()` in the segment tree.
+
+## When to use what
+
+| Context | API | Resolves | Use for |
+|---------|-----|----------|---------|
+| Server handler | `ctx.href("name")` | Named routes (local + absolute) | Server-side URL generation |
+| Server handler | `scopedHref<T>(ctx.href)` | Same, with type safety | Type-safe server URLs |
+| Client component | `href("/path")` | Absolute paths | Global navigation |
+| Client component | `useHref()` | Mount-prefixed paths | Local navigation inside `include()` |
+| Client component | `useMount()` | Raw mount path | Custom mount-aware logic |
+
+## Complete example: mounted module
+
+```typescript
+// urls/shop.tsx (server)
+import { urls, scopedHref } from "@rangojs/router";
+
+export const shopPatterns = urls(({ path, layout }) => [
+  layout((ctx) => {
+    const href = scopedHref<typeof shopPatterns>(ctx.href);
+    return <ShopLayout cartUrl={href("cart")} />;
+  }, () => [
+    path("/", ShopIndex, { name: "index" }),
+    path("/cart", CartPage, { name: "cart" }),
+    path("/product/:slug", ProductPage, { name: "product" }),
+  ]),
+]);
+
+// urls.tsx (server)
+export const urlpatterns = urls(({ path, include }) => [
+  path("/", HomePage, { name: "home" }),
+  include("/shop", shopPatterns),
+]);
+```
+
+```tsx
+// components/ShopNav.tsx (client)
+"use client";
+import { useHref, href, Link } from "@rangojs/router/client";
+
+export function ShopNav() {
+  const localHref = useHref();
+
+  return (
+    <nav>
+      {/* Local paths - auto-prefixed with /shop */}
+      <Link to={localHref("/cart")}>Cart</Link>
+      <Link to={localHref("/product/widget")}>Widget</Link>
+
+      {/* Absolute path - no prefix */}
+      <Link to={href("/")}>Home</Link>
+    </nav>
+  );
+}
+```