@rangojs/router 0.0.0-experimental.139 → 0.0.0-experimental.140

package/dist/bin/rango.js

@@ -1437,9 +1437,14 @@ initializeApp().catch(console.error);
 `.trim();
     VIRTUAL_ENTRY_SSR = `
 import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
-import { renderToReadableStream } from "react-dom/server.edge";
+import { renderToReadableStream, resume } from "react-dom/server.edge";
+import { prerender } from "react-dom/static.edge";
 import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
-import { createSSRHandler } from "@rangojs/router/ssr";
+import {
+  createSSRHandler,
+  createShellCaptureHandler,
+  createShellResumeHandler,
+} from "@rangojs/router/ssr";
 
 export const renderHTML = createSSRHandler({
   createFromReadableStream,
@@ -1448,6 +1453,26 @@ export const renderHTML = createSSRHandler({
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
+
+export const captureShellHTML = createShellCaptureHandler({
+  createFromReadableStream,
+  renderToReadableStream,
+  injectRSCPayload,
+  prerender,
+  resume,
+  loadBootstrapScriptContent: () =>
+    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+});
+
+export const resumeShellHTML = createShellResumeHandler({
+  createFromReadableStream,
+  renderToReadableStream,
+  injectRSCPayload,
+  prerender,
+  resume,
+  loadBootstrapScriptContent: () =>
+    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+});
 `.trim();
     VIRTUAL_IDS = {
       browser: "virtual:rsc-router/entry.browser.js",

package/dist/vite/index.js

@@ -2212,9 +2212,14 @@ initializeApp().catch(console.error);
 `.trim();
 var VIRTUAL_ENTRY_SSR = `
 import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
-import { renderToReadableStream } from "react-dom/server.edge";
+import { renderToReadableStream, resume } from "react-dom/server.edge";
+import { prerender } from "react-dom/static.edge";
 import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
-import { createSSRHandler } from "@rangojs/router/ssr";
+import {
+  createSSRHandler,
+  createShellCaptureHandler,
+  createShellResumeHandler,
+} from "@rangojs/router/ssr";
 
 export const renderHTML = createSSRHandler({
   createFromReadableStream,
@@ -2223,6 +2228,26 @@ export const renderHTML = createSSRHandler({
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
+
+export const captureShellHTML = createShellCaptureHandler({
+  createFromReadableStream,
+  renderToReadableStream,
+  injectRSCPayload,
+  prerender,
+  resume,
+  loadBootstrapScriptContent: () =>
+    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+});
+
+export const resumeShellHTML = createShellResumeHandler({
+  createFromReadableStream,
+  renderToReadableStream,
+  injectRSCPayload,
+  prerender,
+  resume,
+  loadBootstrapScriptContent: () =>
+    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+});
 `.trim();
 var RSC_ENTRY_BOOTSTRAP_IMPORTS = [
   "virtual:rsc-router/routes-manifest",
@@ -4874,10 +4899,31 @@ var INTERNAL_RANGO_DEBUG = typeof process !== "undefined" && Boolean(process.env
 // src/router/logging.ts
 var routerLogContext = new AsyncLocalStorage();
 
-// src/router/pattern-matching.ts
+// src/router/url-params.ts
+var PATH_SAFE_ESCAPES = {
+  "%3A": ":",
+  "%40": "@",
+  "%24": "$",
+  "%26": "&",
+  "%2B": "+",
+  "%2C": ",",
+  "%3B": ";",
+  "%3D": "="
+};
+function encodePathSegment(value) {
+  return encodeURIComponent(value).replace(
+    /%(?:3A|40|24|26|2B|2C|3B|3D)/gi,
+    (match) => PATH_SAFE_ESCAPES[match.toUpperCase()] ?? match
+  );
+}
+function encodePathRemainder(value, encode = encodePathSegment) {
+  return value.split("/").map(encode).join("/");
+}
+
+// src/router/parse-pattern.ts
 function parsePattern(pattern) {
   const segments = [];
-  const segmentRegex = /\/(:([a-zA-Z_][a-zA-Z0-9_]*)(\(([^)]+)\))?(\?)?([^/]*)|(\*)|([^/]+))/g;
+  const segmentRegex = /\/(:([a-zA-Z_][a-zA-Z0-9_]*)(\(([^)]+)\))?(\?)?([+*])?([^/]*)|(\*)|([^/]+))/g;
   let match;
   while ((match = segmentRegex.exec(pattern)) !== null) {
     const [
@@ -4887,6 +4933,7 @@ function parsePattern(pattern) {
       ,
       constraint,
       optional,
+      repeat,
       suffix,
       wildcard,
       staticText
@@ -4894,17 +4941,38 @@ function parsePattern(pattern) {
     if (wildcard) {
       segments.push({ type: "wildcard", value: "*", optional: false });
     } else if (paramName) {
-      segments.push({
-        type: "param",
-        value: paramName,
-        optional: optional === "?",
-        constraint: constraint ? constraint.split("|") : void 0,
-        suffix: suffix || void 0
-      });
+      if (repeat && !suffix && optional !== "?" && !constraint) {
+        segments.push({
+          type: "wildcard",
+          value: paramName,
+          optional: false,
+          oneOrMore: repeat === "+"
+        });
+      } else {
+        segments.push({
+          type: "param",
+          value: paramName,
+          optional: optional === "?",
+          constraint: constraint ? constraint.split("|") : void 0,
+          // Fold a non-modifier `+`/`*` back into the literal suffix.
+          suffix: (repeat ?? "") + (suffix ?? "") || void 0
+        });
+      }
     } else if (staticText) {
       segments.push({ type: "static", value: staticText, optional: false });
     }
   }
+  for (let i = 0; i < segments.length - 1; i++) {
+    const s = segments[i];
+    if (s.type === "wildcard" && s.value !== "*") {
+      segments[i] = {
+        type: "param",
+        value: s.value,
+        optional: false,
+        suffix: s.oneOrMore ? "+" : "*"
+      };
+    }
+  }
   return segments;
 }
 
@@ -5107,11 +5175,18 @@ function insertSegments(node, segments, index, leafBase, paramNames) {
   } else if (segment.type === "wildcard") {
     const wildLeaf = {
       ...buildLeaf(leafBase, paramNames),
-      pn: "*"
+      pn: segment.value,
+      ...segment.oneOrMore ? { w1: true } : {}
     };
-    const existing = node.w ? { ...node.w } : void 0;
-    const merged = mergeLeaves(existing, wildLeaf);
-    node.w = merged;
+    const existing = node.w;
+    const canMerge = existing === void 0 || Boolean(existing.rt) || Boolean(wildLeaf.rt) || existing.pn === wildLeaf.pn && Boolean(existing.w1) === Boolean(wildLeaf.w1);
+    if (canMerge) {
+      const merged = mergeLeaves(
+        existing ? { ...existing } : void 0,
+        wildLeaf
+      );
+      node.w = merged;
+    }
   }
 }
 
@@ -5213,13 +5288,23 @@ import {
 } from "node:fs";
 import { resolve as resolve7 } from "node:path";
 function encodePathParam(value) {
-  return String(value).split("/").map((segment) => encodeURIComponent(segment)).join("/");
+  return encodePathRemainder(String(value), encodeURIComponent);
 }
 function substituteRouteParams(pattern, params, encode = encodeURIComponent) {
   let result = pattern;
   let hadOmittedOptional = false;
   for (const [key, value] of Object.entries(params)) {
     const escaped = escapeRegExp(key);
+    const catchAllRe = new RegExp(`:${escaped}[+*]`);
+    if (catchAllRe.test(result)) {
+      if (value === "") {
+        result = result.replace(catchAllRe, "");
+        hadOmittedOptional = true;
+      } else {
+        result = result.replace(catchAllRe, encodePathRemainder(value, encode));
+      }
+      continue;
+    }
     if (value === "") {
       result = result.replace(
         new RegExp(`:${escaped}(\\([^)]*\\))?(?!\\?)`),
@@ -5799,6 +5884,28 @@ var DiscoveryError = class _DiscoveryError extends Error {
     Object.setPrototypeOf(this, _DiscoveryError.prototype);
   }
 };
+function describeDiscoveryFailure(err, opts = {}) {
+  if (err instanceof DiscoveryError && err.caught.length === 0) {
+    const entry = err.entryPath ?? "the router entry";
+    if (opts.reoptimizeObserved) {
+      return {
+        level: "warn",
+        message: `[rango] No routers found while Vite was re-optimizing dependencies on dev boot. This is transient: routes are served per-request and discovery re-runs automatically, so it clears on the next boot. If routes still 404, confirm ${entry} calls createRouter().`
+      };
+    }
+    return {
+      level: "error",
+      message: `${err.message}
+  Ensure ${entry} calls createRouter() at module top level and that the configured router entry path is correct.`
+    };
+  }
+  const e = err;
+  const detail = e?.stack ?? e?.message ?? String(err);
+  return {
+    level: "error",
+    message: `[rango] Router discovery failed: ${detail}`
+  };
+}
 
 // src/vite/discovery/discover-routers.ts
 var debug10 = createRangoDebugger(NS.discovery);
@@ -6861,6 +6968,15 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
         await importEntryAndRegistry(tempRscEnv);
         return tempRscEnv;
       }
+      const emitDiscoveryFailure = (err, hashBefore, hashAfter) => {
+        const reoptimizeObserved = hashBefore !== void 0 && hashAfter !== void 0 && hashBefore !== hashAfter;
+        const report = describeDiscoveryFailure(err, { reoptimizeObserved });
+        if (report.level === "warn") {
+          console.warn(report.message);
+        } else {
+          console.error(report.message);
+        }
+      };
       const discover = async () => {
         const discoverStart = performance.now();
         const rscEnv = server.environments?.rsc;
@@ -6870,18 +6986,21 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
             globalThis.__rscRouterDiscoveryActive ?? false
           );
           s.devServerOrigin = getDevServerOrigin();
+          let tempRscEnv;
+          let optimizerHashBefore2;
           try {
             await timed(
               debugDiscovery,
               "acquireBuildEnv",
               () => acquireBuildEnv(s, viteCommand, viteMode)
             );
-            const tempRscEnv = await timed(
+            tempRscEnv = await timed(
               debugDiscovery,
               "getOrCreateTempServer",
               () => getOrCreateTempServer()
             );
             if (tempRscEnv) {
+              optimizerHashBefore2 = tempRscEnv.depsOptimizer?.metadata?.browserHash;
               await timed(
                 debugDiscovery,
                 "discoverRouters (cloudflare)",
@@ -6894,9 +7013,10 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
               );
             }
           } catch (err) {
-            console.warn(
-              `[rango] Cloudflare dev discovery failed: ${err.message}
-${err.stack}`
+            emitDiscoveryFailure(
+              err,
+              optimizerHashBefore2,
+              tempRscEnv?.depsOptimizer?.metadata?.browserHash
             );
           }
           debugDiscovery?.(
@@ -6906,6 +7026,7 @@ ${err.stack}`
           resolveDiscovery();
           return;
         }
+        const optimizerHashBefore = rscEnv.depsOptimizer?.metadata?.browserHash;
         try {
           debugDiscovery?.("dev: node path start");
           await timed(
@@ -6915,17 +7036,12 @@ ${err.stack}`
           );
           const serverMod = await timed(
             debugDiscovery,
-            "import @rangojs/router/server",
-            () => rscEnv.runner.import("@rangojs/router/server")
+            "discoverRouters",
+            () => discoverRouters(s, rscEnv)
           );
           if (serverMod?.setManifestReadyPromise) {
             serverMod.setManifestReadyPromise(discoveryPromise);
           }
-          await timed(
-            debugDiscovery,
-            "discoverRouters",
-            () => discoverRouters(s, rscEnv)
-          );
           s.devServerOrigin = getDevServerOrigin();
           timedSync(
             debugDiscovery,
@@ -6938,9 +7054,10 @@ ${err.stack}`
             () => propagateDiscoveryState(rscEnv)
           );
         } catch (err) {
-          console.warn(
-            `[rango] Router discovery failed: ${err.message}
-${err.stack}`
+          emitDiscoveryFailure(
+            err,
+            optimizerHashBefore,
+            rscEnv.depsOptimizer?.metadata?.browserHash
           );
         } finally {
           debugDiscovery?.(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.139",
+  "version": "0.0.0-experimental.140",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/breadcrumbs/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: breadcrumbs
 description: Built-in Breadcrumbs handle for accumulating breadcrumb navigation across route segments
-argument-hint: [setup]
+argument-hint: "[setup]"
 ---
 
 # Breadcrumbs

package/skills/cache-guide/SKILL.md

@@ -484,3 +484,4 @@ overrides — see `/loader` for the full reference.
 - `/caching` — cache() DSL setup, stores, nested boundaries
 - `/use-cache` — "use cache" directive details, profiles, transforms, guards
 - `/document-cache` — Edge caching with Cache-Control headers (different layer)
+- `/ppr` — PPR shell caching: cached HTML shell + live loader holes (different layer)

package/skills/caching/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: caching
 description: Configure segment caching with memory or Cloudflare KV stores in @rangojs/router
-argument-hint: [setup]
+argument-hint: "[setup]"
 ---
 
 # Caching

package/skills/migrate-nextjs/SKILL.md

@@ -88,6 +88,21 @@ The Document component replaces `app/layout.tsx`'s `<html>` wrapper. See `/route
 | `app/shop/[...path]/page.tsx`   | `path("/shop/:path+", CatchAll, { name: "shopCatchAll" })` |
 | `app/docs/[[...slug]]/page.tsx` | `path("/docs/:slug*", Docs, { name: "docs" })`             |
 
+The catch-all remainder is a single string at `ctx.params.<name>` with the `/`
+separators preserved — split it to recover the array Next gives you:
+
+```typescript
+// app/docs/[[...slug]]/page.tsx  ->  params.slug is string[] | undefined in Next
+path("/docs/:slug*", (ctx) => {
+  // "" for /docs, "a/b/c" for /docs/a/b/c
+  const slug = ctx.params.slug === "" ? [] : ctx.params.slug.split("/");
+  return <Docs slug={slug} />;
+}, { name: "docs" });
+```
+
+`[...path]` (required, ≥1 segment) maps to `:path+`; `[[...slug]]` (optional,
+matches the bare parent too) maps to `:slug*` — which binds `""` at `/docs`.
+
 ### Layouts
 
 ```typescript

package/skills/migrate-react-router/SKILL.md

@@ -199,7 +199,7 @@ Key shift: the route module's scattered exports consolidate into the handler
 | `app/routes/_index.tsx`                  | `path("/", HomePage, { name: "home" })`                       |
 | `app/routes/about.tsx`                   | `path("/about", AboutPage, { name: "about" })`                |
 | `app/routes/blog.$slug.tsx`              | `path("/blog/:slug", BlogPost, { name: "blogPost" })`         |
-| `app/routes/files.$.tsx` (splat)         | `path("/files/:path+", FileBrowser, { name: "files" })`       |
+| `app/routes/files.$.tsx` (splat)         | `path("/files/:path*", FileBrowser, { name: "files" })`       |
 | `app/routes/dashboard.tsx` (layout)      | `layout(<DashboardLayout />, () => [...])`                    |
 | `app/routes/dashboard._index.tsx`        | `path("/dashboard", DashboardIndex, { name: "dashboard" })`   |
 | `app/routes/dashboard.settings.tsx`      | `path("/dashboard/settings", Settings, { name: "settings" })` |
@@ -213,9 +213,22 @@ Key shift: the route module's scattered exports consolidate into the handler
 | `path: "/"`                            | `path("/", HomePage, { name: "home" })`                 |
 | `path: "about"`                        | `path("/about", AboutPage, { name: "about" })`          |
 | `path: "blog/:slug"`                   | `path("/blog/:slug", BlogPost, { name: "blogPost" })`   |
-| `path: "files/*"` (splat)              | `path("/files/:path+", FileBrowser, { name: "files" })` |
+| `path: "files/*"` (splat)              | `path("/files/:path*", FileBrowser, { name: "files" })` |
 | `path: "docs/:lang?"` (optional param) | `path("/docs/:lang?", Docs, { name: "docs" })`          |
 
+The RR splat (`$` / `*`) matches the bare parent too (`/files` binds `""`), so
+it maps to `:path*` (zero-or-more). Use `:path+` only when you require at least
+one trailing segment. RR reads the splat at `params["*"]`; Rango exposes it as a
+named string at `ctx.params.path` with the `/` separators preserved (split to
+recover RR's array):
+
+```typescript
+path("/files/:path*", (ctx) => {
+  const parts = ctx.params.path === "" ? [] : ctx.params.path.split("/");
+  return <FileBrowser path={parts} />;
+}, { name: "files" });
+```
+
 ### Layouts
 
 React Router layouts use `<Outlet />` — same concept in Rango: