npm - @rangojs/router - Versions diffs - 0.0.0-experimental.32 → 0.0.0-experimental.3232cd17 - Mend

@rangojs/router 0.0.0-experimental.32 → 0.0.0-experimental.3232cd17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (376) hide show

package/AGENTS.md +4 -0
package/README.md +198 -44
package/dist/bin/rango.js +287 -105
package/dist/testing/vitest.js +82 -0
package/dist/vite/index.js +3248 -1117
package/dist/vite/plugins/cloudflare-protocol-loader-hook.mjs +76 -0
package/package.json +73 -21
package/skills/api-client/SKILL.md +211 -0
package/skills/breadcrumbs/SKILL.md +107 -1
package/skills/bundle-analysis/SKILL.md +159 -0
package/skills/cache-guide/SKILL.md +245 -21
package/skills/caching/SKILL.md +302 -6
package/skills/composability/SKILL.md +27 -2
package/skills/css/SKILL.md +76 -0
package/skills/document-cache/SKILL.md +78 -55
package/skills/handler-use/SKILL.md +364 -0
package/skills/hooks/SKILL.md +270 -30
package/skills/host-router/SKILL.md +82 -22
package/skills/i18n/SKILL.md +276 -0
package/skills/intercept/SKILL.md +49 -5
package/skills/layout/SKILL.md +35 -9
package/skills/links/SKILL.md +249 -17
package/skills/loader/SKILL.md +294 -30
package/skills/middleware/SKILL.md +52 -13
package/skills/migrate-nextjs/SKILL.md +584 -0
package/skills/migrate-react-router/SKILL.md +769 -0
package/skills/mime-routes/SKILL.md +27 -0
package/skills/observability/SKILL.md +137 -0
package/skills/parallel/SKILL.md +203 -7
package/skills/prerender/SKILL.md +123 -100
package/skills/rango/SKILL.md +250 -22
package/skills/react-compiler/SKILL.md +168 -0
package/skills/response-routes/SKILL.md +122 -47
package/skills/route/SKILL.md +97 -5
package/skills/router-setup/SKILL.md +90 -5
package/skills/server-actions/SKILL.md +775 -0
package/skills/streams-and-websockets/SKILL.md +283 -0
package/skills/tailwind/SKILL.md +27 -3
package/skills/testing/SKILL.md +129 -0
package/skills/testing/bindings.md +89 -0
package/skills/testing/cache-prerender.md +124 -0
package/skills/testing/client-components.md +122 -0
package/skills/testing/e2e-parity.md +125 -0
package/skills/testing/flight.md +92 -0
package/skills/testing/handles.md +129 -0
package/skills/testing/loader.md +128 -0
package/skills/testing/middleware.md +99 -0
package/skills/testing/render-handler.md +121 -0
package/skills/testing/response-routes.md +95 -0
package/skills/testing/reverse-and-types.md +84 -0
package/skills/testing/server-actions.md +107 -0
package/skills/testing/server-tree.md +128 -0
package/skills/testing/setup.md +120 -0
package/skills/typesafety/SKILL.md +329 -27
package/skills/use-cache/SKILL.md +36 -5
package/skills/view-transitions/SKILL.md +294 -0
package/src/__augment-tests__/augment.ts +81 -0
package/src/__augment-tests__/augmented.check.ts +116 -0
package/src/__internal.ts +67 -40
package/src/browser/action-coordinator.ts +53 -36
package/src/browser/action-fence.ts +47 -0
package/src/browser/app-shell.ts +39 -0
package/src/browser/app-version.ts +14 -0
package/src/browser/cookie-name.ts +140 -0
package/src/browser/event-controller.ts +86 -147
package/src/browser/history-state.ts +21 -0
package/src/browser/index.ts +3 -3
package/src/browser/invalidate-client-cache.ts +52 -0
package/src/browser/link-interceptor.ts +4 -0
package/src/browser/navigation-bridge.ts +148 -19
package/src/browser/navigation-client.ts +187 -67
package/src/browser/navigation-store-handle.ts +38 -0
package/src/browser/navigation-store.ts +76 -67
package/src/browser/navigation-transaction.ts +18 -66
package/src/browser/partial-update.ts +123 -94
package/src/browser/prefetch/cache.ts +214 -36
package/src/browser/prefetch/fetch.ts +260 -38
package/src/browser/prefetch/policy.ts +6 -0
package/src/browser/prefetch/queue.ts +126 -20
package/src/browser/prefetch/resource-ready.ts +77 -0
package/src/browser/rango-state.ts +158 -76
package/src/browser/react/Link.tsx +93 -11
package/src/browser/react/NavigationProvider.tsx +115 -34
package/src/browser/react/ScrollRestoration.tsx +10 -6
package/src/browser/react/context.ts +7 -2
package/src/browser/react/filter-segment-order.ts +49 -7
package/src/browser/react/index.ts +0 -48
package/src/browser/react/location-state-shared.ts +166 -8
package/src/browser/react/location-state.ts +39 -14
package/src/browser/react/use-action.ts +6 -15
package/src/browser/react/use-handle.ts +23 -69
package/src/browser/react/use-link-status.ts +0 -4
package/src/browser/react/use-navigation.ts +22 -5
package/src/browser/react/use-params.ts +20 -10
package/src/browser/react/use-reverse.ts +106 -0
package/src/browser/react/use-router.ts +46 -11
package/src/browser/react/use-search-params.ts +0 -5
package/src/browser/react/use-segments.ts +11 -21
package/src/browser/response-adapter.ts +52 -1
package/src/browser/rsc-router.tsx +215 -76
package/src/browser/scroll-restoration.ts +46 -39
package/src/browser/segment-reconciler.ts +36 -9
package/src/browser/segment-structure-assert.ts +2 -2
package/src/browser/server-action-bridge.ts +176 -50
package/src/browser/types.ts +95 -11
package/src/browser/validate-redirect-origin.ts +43 -16
package/src/build/collect-fallback-refs.ts +107 -0
package/src/build/generate-manifest.ts +65 -40
package/src/build/generate-route-types.ts +5 -0
package/src/build/index.ts +8 -2
package/src/build/prefix-tree-utils.ts +123 -0
package/src/build/route-trie.ts +137 -32
package/src/build/route-types/codegen.ts +4 -4
package/src/build/route-types/include-resolution.ts +9 -2
package/src/build/route-types/param-extraction.ts +6 -3
package/src/build/route-types/per-module-writer.ts +7 -4
package/src/build/route-types/router-processing.ts +278 -96
package/src/build/route-types/scan-filter.ts +9 -2
package/src/build/route-types/source-scan.ts +118 -0
package/src/build/runtime-discovery.ts +9 -20
package/src/cache/cache-error.ts +104 -0
package/src/cache/cache-policy.ts +68 -28
package/src/cache/cache-runtime.ts +149 -43
package/src/cache/cache-scope.ts +148 -81
package/src/cache/cache-tag.ts +98 -0
package/src/cache/cf/cf-cache-store.ts +2550 -93
package/src/cache/cf/index.ts +11 -17
package/src/cache/document-cache.ts +78 -27
package/src/cache/handle-snapshot.ts +63 -0
package/src/cache/index.ts +23 -20
package/src/cache/memory-segment-store.ts +136 -37
package/src/cache/profile-registry.ts +6 -30
package/src/cache/read-through-swr.ts +41 -11
package/src/cache/segment-codec.ts +0 -16
package/src/cache/tag-invalidation.ts +230 -0
package/src/cache/taint.ts +55 -0
package/src/cache/types.ts +33 -100
package/src/cache/vercel/index.ts +11 -0
package/src/cache/vercel/vercel-cache-store.ts +799 -0
package/src/client.rsc.tsx +6 -21
package/src/client.tsx +108 -290
package/src/component-utils.ts +19 -0
package/src/context-var.ts +84 -2
package/src/debug.ts +2 -2
package/src/decode-loader-results.ts +36 -0
package/src/defer.ts +196 -0
package/src/deps/ssr.ts +0 -1
package/src/errors.ts +30 -4
package/src/handle.ts +70 -22
package/src/handles/MetaTags.tsx +0 -14
package/src/handles/breadcrumbs.ts +16 -5
package/src/handles/meta.ts +0 -39
package/src/host/cookie-handler.ts +0 -36
package/src/host/errors.ts +0 -24
package/src/host/index.ts +8 -2
package/src/host/pattern-matcher.ts +7 -50
package/src/host/router.ts +107 -99
package/src/host/testing.ts +40 -27
package/src/host/types.ts +37 -4
package/src/host/utils.ts +1 -1
package/src/href-client.ts +137 -22
package/src/index.rsc.ts +52 -26
package/src/index.ts +100 -38
package/src/internal-debug.ts +2 -4
package/src/loader-store.ts +500 -0
package/src/loader.rsc.ts +20 -13
package/src/loader.ts +12 -11
package/src/missing-id-error.ts +68 -0
package/src/network-error-thrower.tsx +1 -6
package/src/outlet-context.ts +1 -1
package/src/outlet-provider.tsx +1 -5
package/src/prerender/param-hash.ts +10 -11
package/src/prerender/store.ts +37 -41
package/src/prerender.ts +198 -82
package/src/redirect-origin.ts +100 -0
package/src/response-utils.ts +37 -0
package/src/reverse.ts +65 -15
package/src/root-error-boundary.tsx +1 -19
package/src/route-content-wrapper.tsx +7 -72
package/src/route-definition/dsl-helpers.ts +437 -274
package/src/route-definition/helper-factories.ts +29 -139
package/src/route-definition/helpers-types.ts +113 -37
package/src/route-definition/index.ts +3 -0
package/src/route-definition/redirect.ts +52 -10
package/src/route-definition/resolve-handler-use.ts +161 -0
package/src/route-definition/use-item-types.ts +32 -0
package/src/route-map-builder.ts +7 -17
package/src/route-types.ts +37 -41
package/src/router/basename.ts +14 -0
package/src/router/content-negotiation.ts +108 -9
package/src/router/error-handling.ts +13 -17
package/src/router/find-match.ts +45 -22
package/src/router/handler-context.ts +83 -41
package/src/router/intercept-resolution.ts +25 -23
package/src/router/lazy-includes.ts +19 -53
package/src/router/loader-resolution.ts +213 -30
package/src/router/logging.ts +5 -8
package/src/router/manifest.ts +49 -45
package/src/router/match-api.ts +120 -204
package/src/router/match-context.ts +0 -22
package/src/router/match-handlers.ts +58 -58
package/src/router/match-middleware/background-revalidation.ts +27 -6
package/src/router/match-middleware/cache-lookup.ts +205 -249
package/src/router/match-middleware/cache-store.ts +45 -32
package/src/router/match-middleware/intercept-resolution.ts +8 -28
package/src/router/match-middleware/segment-resolution.ts +52 -18
package/src/router/match-pipelines.ts +1 -42
package/src/router/match-result.ts +104 -40
package/src/router/metrics.ts +5 -34
package/src/router/middleware-types.ts +13 -142
package/src/router/middleware.ts +173 -143
package/src/router/navigation-snapshot.ts +131 -0
package/src/router/params-util.ts +23 -0
package/src/router/pattern-matching.ts +109 -63
package/src/router/prerender-match.ts +190 -54
package/src/router/preview-match.ts +32 -102
package/src/router/request-classification.ts +276 -0
package/src/router/revalidation.ts +63 -55
package/src/router/route-snapshot.ts +244 -0
package/src/router/router-context.ts +6 -28
package/src/router/router-interfaces.ts +100 -35
package/src/router/router-options.ts +91 -11
package/src/router/router-registry.ts +2 -5
package/src/router/segment-resolution/fresh.ts +242 -75
package/src/router/segment-resolution/helpers.ts +63 -24
package/src/router/segment-resolution/loader-cache.ts +41 -37
package/src/router/segment-resolution/revalidation.ts +456 -372
package/src/router/segment-resolution/static-store.ts +19 -5
package/src/router/segment-resolution/streamed-handler-telemetry.ts +52 -0
package/src/router/segment-resolution/view-transition-default.ts +36 -0
package/src/router/segment-resolution.ts +4 -1
package/src/router/segment-wrappers.ts +2 -3
package/src/router/state-cookie-name.ts +33 -0
package/src/router/substitute-pattern-params.ts +56 -0
package/src/router/telemetry-otel.ts +0 -20
package/src/router/telemetry.ts +96 -19
package/src/router/timeout.ts +0 -20
package/src/router/trie-matching.ts +91 -46
package/src/router/types.ts +10 -63
package/src/router/url-params.ts +44 -0
package/src/router.ts +134 -43
package/src/rsc/handler-context.ts +3 -2
package/src/rsc/handler.ts +492 -383
package/src/rsc/helpers.ts +162 -46
package/src/rsc/index.ts +1 -1
package/src/rsc/json-route-result.ts +38 -0
package/src/rsc/loader-fetch.ts +23 -3
package/src/rsc/manifest-init.ts +33 -42
package/src/rsc/origin-guard.ts +39 -25
package/src/rsc/progressive-enhancement.ts +30 -3
package/src/rsc/redirect-guard.ts +99 -0
package/src/rsc/response-error.ts +79 -12
package/src/rsc/response-route-handler.ts +90 -63
package/src/rsc/rsc-rendering.ts +56 -54
package/src/rsc/runtime-warnings.ts +23 -10
package/src/rsc/server-action.ts +74 -67
package/src/rsc/ssr-setup.ts +18 -2
package/src/rsc/types.ts +25 -6
package/src/runtime-env.ts +18 -0
package/src/search-params.ts +4 -20
package/src/segment-content-promise.ts +67 -0
package/src/segment-loader-promise.ts +134 -0
package/src/segment-system.tsx +272 -129
package/src/serialize.ts +243 -0
package/src/server/context.ts +309 -61
package/src/server/cookie-store.ts +80 -5
package/src/server/handle-store.ts +26 -24
package/src/server/loader-registry.ts +10 -28
package/src/server/request-context.ts +338 -126
package/src/ssr/index.tsx +23 -15
package/src/static-handler.ts +27 -18
package/src/testing/cache-status.ts +162 -0
package/src/testing/collect-handle.ts +40 -0
package/src/testing/dispatch.ts +618 -0
package/src/testing/dom.entry.ts +22 -0
package/src/testing/e2e/fixture.ts +188 -0
package/src/testing/e2e/index.ts +128 -0
package/src/testing/e2e/matchers.ts +35 -0
package/src/testing/e2e/page-helpers.ts +272 -0
package/src/testing/e2e/parity.ts +387 -0
package/src/testing/e2e/server.ts +195 -0
package/src/testing/flight-matchers.ts +97 -0
package/src/testing/flight-normalize.ts +11 -0
package/src/testing/flight-runtime.d.ts +57 -0
package/src/testing/flight-tree.ts +682 -0
package/src/testing/flight.entry.ts +52 -0
package/src/testing/flight.ts +232 -0
package/src/testing/generated-routes.ts +183 -0
package/src/testing/index.ts +99 -0
package/src/testing/internal/context.ts +348 -0
package/src/testing/internal/flight-client-globals.ts +30 -0
package/src/testing/internal/seed-vars.ts +54 -0
package/src/testing/render-handler.ts +330 -0
package/src/testing/render-route.tsx +566 -0
package/src/testing/run-loader.ts +378 -0
package/src/testing/run-middleware.ts +205 -0
package/src/testing/vitest-stubs/cloudflare-email.ts +9 -0
package/src/testing/vitest-stubs/cloudflare-workers.ts +21 -0
package/src/testing/vitest-stubs/plugin-rsc.ts +16 -0
package/src/testing/vitest-stubs/version.ts +5 -0
package/src/testing/vitest.ts +305 -0
package/src/theme/ThemeProvider.tsx +0 -52
package/src/theme/ThemeScript.tsx +0 -6
package/src/theme/constants.ts +0 -12
package/src/theme/index.ts +0 -7
package/src/theme/theme-context.ts +1 -5
package/src/theme/theme-script.ts +0 -14
package/src/theme/use-theme.ts +0 -3
package/src/types/boundaries.ts +0 -35
package/src/types/cache-types.ts +17 -8
package/src/types/error-types.ts +30 -90
package/src/types/global-namespace.ts +54 -41
package/src/types/handler-context.ts +233 -81
package/src/types/index.ts +1 -10
package/src/types/loader-types.ts +44 -15
package/src/types/request-scope.ts +107 -0
package/src/types/route-config.ts +6 -50
package/src/types/route-entry.ts +19 -7
package/src/types/segments.ts +37 -14
package/src/urls/include-helper.ts +33 -70
package/src/urls/index.ts +1 -11
package/src/urls/path-helper-types.ts +58 -11
package/src/urls/path-helper.ts +57 -111
package/src/urls/pattern-types.ts +48 -19
package/src/urls/response-types.ts +25 -22
package/src/urls/type-extraction.ts +58 -139
package/src/urls/urls-function.ts +1 -18
package/src/use-loader.tsx +346 -89
package/src/vite/debug.ts +185 -0
package/src/vite/discovery/bundle-postprocess.ts +36 -38
package/src/vite/discovery/discover-routers.ts +130 -85
package/src/vite/discovery/discovery-errors.ts +194 -0
package/src/vite/discovery/gate-state.ts +171 -0
package/src/vite/discovery/prerender-collection.ts +192 -99
package/src/vite/discovery/route-types-writer.ts +40 -84
package/src/vite/discovery/self-gen-tracking.ts +27 -1
package/src/vite/discovery/state.ts +51 -6
package/src/vite/discovery/virtual-module-codegen.ts +14 -34
package/src/vite/index.ts +8 -0
package/src/vite/plugin-types.ts +187 -69
package/src/vite/plugins/cjs-to-esm.ts +8 -18
package/src/vite/plugins/client-ref-dedup.ts +16 -11
package/src/vite/plugins/client-ref-hashing.ts +28 -15
package/src/vite/plugins/cloudflare-protocol-loader-hook.d.mts +23 -0
package/src/vite/plugins/cloudflare-protocol-loader-hook.mjs +76 -0
package/src/vite/plugins/cloudflare-protocol-stub.ts +194 -0
package/src/vite/plugins/expose-action-id.ts +49 -98
package/src/vite/plugins/expose-id-utils.ts +11 -50
package/src/vite/plugins/expose-ids/export-analysis.ts +76 -34
package/src/vite/plugins/expose-ids/handler-transform.ts +10 -48
package/src/vite/plugins/expose-ids/loader-transform.ts +3 -20
package/src/vite/plugins/expose-ids/router-transform.ts +20 -16
package/src/vite/plugins/expose-internal-ids.ts +554 -317
package/src/vite/plugins/performance-tracks.ts +89 -0
package/src/vite/plugins/refresh-cmd.ts +89 -27
package/src/vite/plugins/use-cache-transform.ts +73 -83
package/src/vite/plugins/vercel-output.ts +258 -0
package/src/vite/plugins/version-injector.ts +21 -25
package/src/vite/plugins/version-plugin.ts +41 -20
package/src/vite/plugins/virtual-entries.ts +2 -17
package/src/vite/rango.ts +257 -289
package/src/vite/router-discovery.ts +930 -140
package/src/vite/utils/ast-handler-extract.ts +15 -31
package/src/vite/utils/banner.ts +4 -4
package/src/vite/utils/bundle-analysis.ts +10 -15
package/src/vite/utils/client-chunks.ts +184 -0
package/src/vite/utils/forward-user-plugins.ts +171 -0
package/src/vite/utils/manifest-utils.ts +4 -59
package/src/vite/utils/package-resolution.ts +20 -52
package/src/vite/utils/prerender-utils.ts +27 -29
package/src/vite/utils/shared-utils.ts +92 -42
package/src/browser/action-response-classifier.ts +0 -99
package/src/browser/react/use-client-cache.ts +0 -58
package/src/browser/shallow.ts +0 -40
package/src/handles/index.ts +0 -7
package/src/router/middleware-cookies.ts +0 -55

package/skills/migrate-nextjs/SKILL.md ADDED Viewed

@@ -0,0 +1,584 @@
+---
+name: migrate-nextjs
+description: Migrate a Next.js App Router project to @rangojs/router. Use when the user asks to "migrate from Next.js", "convert Next.js to Rango", "replace Next.js", or has a Next.js app they want to port.
+argument-hint: [path-to-nextjs-app]
+---
+# Migrate from Next.js App Router to @rangojs/router
+## Why Rango
+Common reasons to migrate:
+- **Server components by default** — keep data fetching on the server without
+  framework-specific file conventions.
+  See: `/router-setup`, `/route`
+- **Django-style route definition** — `urls()`, `path()`, and `layout()` make
+  the route tree explicit instead of spreading routing across many special files.
+  See: `/route`, `/layout`
+- **Named routes** — reverse URLs by route name instead of hard-coding path
+  strings throughout the app.
+  See: `/links`, `/typesafety`
+- **Clear execution model** — request scope, render scope, segment boundaries,
+  and shared `ctx` behavior are explicit in the routing model.
+  See: `/middleware`, `/loader`
+- **Live data layer** — `createLoader()` and `loader()` keep data fresh
+  independently of cached UI. A route can serve cached segments while loaders
+  still resolve live on every request.
+  See: `/loader`, `/caching`, `/cache-guide`
+- **Explicit caching model** — `cache()` DSL, `revalidate()`, `use cache`, and
+  custom cache stores make caching and revalidation behavior visible in code.
+  See: `/caching`, `/cache-guide`, `/use-cache`
+- **Build-time rendering** — `Static()` and `Prerender()` provide explicit
+  build-time rendering instead of mixing rendering and caching behind conventions.
+  See: `/prerender`
+- **Composable route tree** — layouts, includes, middleware, parallels, and
+  intercepts compose directly in the route definition.
+  See: `/composability`, `/parallel`, `/intercept`
+- **Multi-router flexibility** — support multiple routers, domain routing, and
+  worker/edge-style deployment patterns.
+  See: `/host-router`
+## Migration Strategy
+Work route-by-route, bottom-up. Start with leaf pages, then layouts, then middleware. Verify each route works before moving to the next.
+## 1. Project Setup
+Replace Next.js tooling with Vite + Rango:
+```bash
+npm remove next @next/env
+npm install @rangojs/router @vitejs/plugin-react
+npm install -D vite
+```
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import { rango } from "@rangojs/router/vite";
+export default defineConfig({
+  plugins: [rango()],
+});
+```
+```typescript
+// src/router.tsx
+import { createRouter } from "@rangojs/router";
+import { Document } from "./document";
+import { urlpatterns } from "./urls";
+export default createRouter({
+  document: Document,
+}).routes(urlpatterns);
+```
+The Document component replaces `app/layout.tsx`'s `<html>` wrapper. See `/router-setup` for full config options.
+## 2. Route Mapping
+### File-based → URL pattern DSL
+| Next.js file path               | Rango equivalent                                           |
+| ------------------------------- | ---------------------------------------------------------- |
+| `app/page.tsx`                  | `path("/", HomePage, { name: "home" })`                    |
+| `app/about/page.tsx`            | `path("/about", AboutPage, { name: "about" })`             |
+| `app/blog/[slug]/page.tsx`      | `path("/blog/:slug", BlogPost, { name: "blogPost" })`      |
+| `app/shop/[...path]/page.tsx`   | `path("/shop/:path+", CatchAll, { name: "shopCatchAll" })` |
+| `app/docs/[[...slug]]/page.tsx` | `path("/docs/:slug*", Docs, { name: "docs" })`             |
+### Layouts
+```typescript
+// Next.js: app/dashboard/layout.tsx
+export default function DashboardLayout({ children }) {
+  return <div className="dashboard">{children}</div>;
+}
+// Rango:
+import { Outlet } from "@rangojs/router/client";
+function DashboardLayout() {
+  return (
+    <div className="dashboard">
+      <Outlet />
+    </div>
+  );
+}
+// In urls.tsx:
+layout(<DashboardLayout />, () => [
+  path("/dashboard", DashboardIndex, { name: "dashboard" }),
+  path("/dashboard/settings", Settings, { name: "settings" }),
+])
+```
+Key difference: Rango layouts use `<Outlet />` instead of `{children}`. Layouts are server components by default.
+### Dynamic layouts (with data)
+```typescript
+// Next.js: app/dashboard/layout.tsx
+export default async function DashboardLayout({ children }) {
+  const user = await getUser();
+  return <Shell user={user}>{children}</Shell>;
+}
+// Rango: handler function layout
+layout(async (ctx) => {
+  const user = ctx.get("user");
+  return (
+    <Shell user={user}>
+      <Outlet />
+    </Shell>
+  );
+}, () => [
+  path("/dashboard", DashboardIndex, { name: "dashboard" }),
+])
+```
+### Route groups
+Next.js `app/(marketing)/page.tsx` route groups have no URL segment. In Rango, just organize with `include()`:
+```typescript
+// src/urls/marketing.tsx
+export const marketingPatterns = urls(({ path }) => [
+  path("/", LandingPage, { name: "landing" }),
+  path("/pricing", PricingPage, { name: "pricing" }),
+]);
+// src/urls.tsx
+include("/", marketingPatterns, { name: "marketing" }),
+```
+### Parallel routes
+In Next.js, `@sidebar` and `@main` are both named slots. In Rango, the main content
+renders through `<Outlet />` (the path handler), and only extra slots use `parallel()` +
+`<ParallelOutlet />`:
+```typescript
+// Next.js: app/layout.tsx renders {sidebar} and {children}
+//          app/@sidebar/page.tsx provides the sidebar slot
+//          app/page.tsx provides the main content
+// Rango: main content is the path handler, sidebar is a parallel slot
+layout(
+  () => (
+    <div className="dashboard">
+      <ParallelOutlet name="@sidebar" />
+      <Outlet />
+    </div>
+  ),
+  () => [
+    parallel({
+      "@sidebar": <Sidebar />,
+    }),
+    path("/dashboard", DashboardPage, { name: "dashboard" }),
+  ],
+)
+```
+Only add `parallel()` slots for content that renders alongside the main route.
+The main content always goes through `<Outlet />` via the `path()` handler.
+### Intercepting routes
+```typescript
+// Next.js: app/(.)product/[id]/page.tsx
+// (convention: (.) means same level, (..) parent level)
+// Rango: explicit intercept in layout
+layout(<ShopLayout />, () => [
+  path("/product/:id", ProductPage, { name: "product" }),
+  intercept("@modal", ".product", <ProductModal />, () => [
+    when(({ from }) => from.pathname.startsWith("/shop")),
+  ]),
+])
+```
+## 3. Data Fetching
+### Server component data fetching
+Inline `fetch()` or direct DB calls in server components work as-is — no migration needed:
+```typescript
+// Next.js:
+async function ProductPage({ params }) {
+  const product = await fetch(`/api/products/${params.slug}`).then(r => r.json());
+  return <div>{product.name}</div>;
+}
+// Rango: same pattern, params come from ctx
+const ProductPage: Handler<"product"> = async (ctx) => {
+  const product = await fetch(`/api/products/${ctx.params.slug}`).then(r => r.json());
+  return <div>{product.name}</div>;
+};
+```
+### When to use createLoader
+Loaders are Rango's live data layer. Use them when you need:
+- **Client-side data refresh** — `useLoader()` in client components for reactive data
+- **Per-loader caching** — opt in with `loader(MyLoader, () => [cache({ ttl: 60 })])`; loaders stay live by default
+- **Revalidation control** — `revalidate()` targets specific segments and loaders after actions
+- **Loading skeletons** — `loading()` shows a Suspense fallback while loaders resolve
+```typescript
+import { createLoader } from "@rangojs/router";
+export const ProductLoader = createLoader(async (ctx) => {
+  return await db.getProduct(ctx.params.slug);
+});
+// In urls:
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  loader(ProductLoader),
+  loading(<ProductSkeleton />),
+])
+```
+If the existing fetch pattern works and you don't need these features, leave it as-is. See `/loader` for full API.
+### generateStaticParams → Prerender + Passthrough
+Plain `Prerender` only serves the listed params — unlisted params get no live
+fallback in production (the handler is evicted). If the Next.js route serves
+params outside the generated set at runtime, wrap with `Passthrough()`:
+```typescript
+// Next.js:
+export async function generateStaticParams() {
+  return [{ slug: "a" }, { slug: "b" }];
+}
+// Rango (build-only, no live fallback for unlisted params):
+import { Prerender } from "@rangojs/router";
+export const ProductDef = Prerender<{ slug: string }>(
+  async () => [{ slug: "a" }, { slug: "b" }],
+  async (ctx) => {
+    const product = await getProduct(ctx.params.slug);
+    return <ProductPage product={product} />;
+  },
+);
+// Rango (with live fallback — matches Next.js dynamicParams behavior):
+import { Prerender, Passthrough } from "@rangojs/router";
+const ProductDef = Prerender<{ slug: string }>(
+  async () => [{ slug: "a" }, { slug: "b" }],
+  async (ctx) => {
+    const product = await getProduct(ctx.params.slug);
+    if (!product) return ctx.passthrough();
+    return <ProductPage product={product} />;
+  },
+);
+export const Product = Passthrough(ProductDef, async (ctx) => {
+  const product = await getProduct(ctx.params.slug);
+  return <ProductPage product={product} />;
+});
+```
+Use `Passthrough()` whenever the Next.js route has `dynamicParams: true` (the
+default) or serves an open-ended param space. See `/prerender` for full API.
+### Revalidation: two distinct axes
+Next.js conflates two things under "revalidation." Rango separates them — and
+tag-based cache invalidation now maps directly.
+**1. Cache invalidation (bust cached values) — direct equivalent.** Tag entries
+with `cache({ tags })` or, inside a `"use cache"` function, runtime
+`cacheTag(...tags)`. Then invalidate by tag:
+```typescript
+// Next.js                    Rango
+// revalidateTag("products")  →  await updateTag("products")  // in a server action: awaitable,
+//                                                            // read-your-own-writes (next render is fresh)
+//                            or  revalidateTag("products")    // in a route handler / webhook:
+//                                                            // background, non-blocking (hard-purge)
+```
+`updateTag` is awaitable and immediate; `revalidateTag` is fire-and-forget. Both
+hard-purge (the next read re-renders fresh); the only difference is awaitability —
+despite the Next.js name, `revalidateTag` here is NOT stale-while-revalidate.
+Built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`) index by tag. Next's
+`revalidatePath` has no path-based equivalent — tag the relevant entries instead.
+**2. Partial-render selection (which segments re-run after an action).** This is
+NOT cache invalidation — it is `revalidate()`, controlling which segments
+(layouts, paths, loaders, parallels) recompute during partial action
+re-rendering:
+```typescript
+import { updateBlog } from "./actions/blog";
+// Re-run this layout when a blog action fires
+layout(BlogLayout, () => [
+  revalidate((ctx) => ctx.isAction(updateBlog) || undefined),
+  path("/blog/:slug", BlogPost, { name: "blogPost" }),
+]);
+// Re-run sidebar parallel when params change
+parallel({ "@sidebar": BlogSidebar }, () => [
+  revalidate(
+    ({ currentParams, nextParams }) => currentParams.slug !== nextParams.slug,
+  ),
+]);
+```
+**Server-side caching** — `cache()` DSL, loader-level `cache()`, and `"use cache"`
+control what gets cached and for how long. This is separate from `revalidate()`:
+```typescript
+cache({ ttl: 60, swr: 300 }, () => [
+  path("/blog/:slug", BlogPost, { name: "blogPost" }),
+]);
+```
+The two axes compose: `updateTag()` / `revalidateTag()` bust cached values;
+`revalidate()` selects which segments re-render and stream to the client after an
+action.
+When migrating:
+- `revalidateTag(tag)` → `await updateTag(tag)` (in a server action) or
+  `revalidateTag(tag)` (in a route handler / webhook). Effectively 1:1.
+- `revalidatePath(path)` → no path-based equivalent; tag the entries on that
+  route (`cache({ tags })` / `cacheTag(...)`) and invalidate by tag.
+- To also force specific segments to re-render after the action (independent of
+  cache busting), attach a `revalidate()` rule at those segment boundaries.
+## 4. Middleware
+Next.js `middleware.ts` wraps the entire request — including server actions.
+The direct equivalent is `router.use()`, not the DSL `middleware()`:
+```typescript
+// Next.js: middleware.ts (file-convention, wraps all requests)
+import { NextResponse } from "next/server";
+export function middleware(request) {
+  if (!request.cookies.get("session")) {
+    return NextResponse.redirect(new URL("/login", request.url));
+  }
+}
+export const config = { matcher: ["/dashboard/:path*"] };
+// Rango: split into initialisation (global) + guard (scoped)
+import { redirect, cookies } from "@rangojs/router";
+import type { Middleware } from "@rangojs/router";
+// Runs on every request — resolves the session for all routes
+const authInit: Middleware = async (ctx, next) => {
+  const session = cookies().get("session")?.value;
+  if (session) {
+    const user = await verifySession(session);
+    ctx.set("user", user);
+  }
+  await next();
+};
+// Scoped guard — redirects unauthenticated users
+const requireAuth: Middleware = async (ctx, next) => {
+  if (!ctx.get("user")) {
+    return redirect("/login");
+  }
+  await next();
+};
+const router = createRouter({})
+  .use(authInit) // all routes — sets ctx user
+  .use("/dashboard/*", requireAuth) // dashboard only — redirects
+  .routes(urlpatterns);
+```
+**Rango has two middleware levels with different scopes:**
+|                    | `router.use()`                       | `middleware()` in DSL           |
+| ------------------ | ------------------------------------ | ------------------------------- |
+| Wraps              | Entire request (actions + rendering) | Rendering only                  |
+| Use for            | Auth guards, logging, CORS           | Context shaping, render headers |
+| Next.js equivalent | `middleware.ts`                      | No direct equivalent            |
+Use `router.use()` for auth guards — it wraps the full request including actions.
+DSL `middleware()` can also guard rendering (e.g. redirect unauthenticated users
+away from a page), but it does not protect actions on that route. For full auth
+coverage, prefer `router.use()`. See `/middleware`.
+## 5. Loading & Error States
+```typescript
+// Next.js: app/dashboard/loading.tsx
+export default function Loading() { return <Skeleton />; }
+// Rango:
+path("/dashboard", DashboardPage, { name: "dashboard" }, () => [
+  loading(<Skeleton />),
+])
+```
+```typescript
+// Next.js: app/dashboard/error.tsx wraps all routes under /dashboard
+"use client";
+export default function Error({ error, reset }) { ... }
+// Rango: errorBoundary wrapping a group of routes
+layout(<DashboardLayout />, () => [
+  errorBoundary(({ error, reset }) => (
+    <div>
+      <h2>Something went wrong</h2>
+      <button onClick={reset}>Try again</button>
+    </div>
+  )),
+  path("/dashboard", DashboardIndex, { name: "dashboard" }),
+  path("/dashboard/settings", Settings, { name: "settings" }),
+])
+```
+```typescript
+// Next.js: app/not-found.tsx
+export default function NotFound() { ... }
+// Rango (app-level — no route match, or notFound() without a boundary):
+createRouter({
+  notFound: ({ pathname }) => <NotFoundPage pathname={pathname} />,
+})
+// Rango (route-level — notFoundBoundary wrapping a group of routes):
+layout(<ShopLayout />, () => [
+  notFoundBoundary(({ notFound: info }) => (
+    <div>
+      <h2>Not Found</h2>
+      <p>{info.message}</p>
+    </div>
+  )),
+  path("/product/:slug", ProductPage, { name: "product" }),
+  path("/product/:slug/reviews", ReviewsPage, { name: "reviews" }),
+])
+```
+Both `errorBoundary()` and `notFoundBoundary()` catch errors from all
+children in their scope — handlers, loaders, and nested segments.
+## 6. Navigation
+| Next.js                         | Rango                                             |
+| ------------------------------- | ------------------------------------------------- |
+| `import Link from "next/link"`  | `import { Link } from "@rangojs/router/client"`   |
+| `<Link href="/about">`          | `<Link to="/about">`                              |
+| `useRouter().push("/about")`    | `useRouter().push("/about")`                      |
+| `useRouter().replace("/about")` | `useRouter().replace("/about")`                   |
+| `usePathname()`                 | `usePathname()` from `@rangojs/router/client`     |
+| `useSearchParams()`             | `useSearchParams()` from `@rangojs/router/client` |
+| `redirect("/login")` (server)   | `redirect("/login")` from `@rangojs/router`       |
+## 7. Server Actions
+Server actions work the same way — `"use server"` directive, `useActionState`, form actions. No migration needed for action logic.
+Key difference: in Rango, route middleware does NOT wrap action execution. Actions only see global middleware context. Use `getRequestContext()` in actions to access `ctx.set()`/`ctx.get()`.
+Next.js's `revalidateTag()` maps directly: tag entries via `cache({ tags })` / `cacheTag(...)`, then invalidate. **In a server action use `await updateTag(tag)`** — it is read-your-own-writes, so the action's own re-render sees fresh data; `revalidateTag(tag)` is a background (non-blocking) hard-purge and is NOT read-your-own-writes, so reserve it for route handlers / webhooks (calling it from an action can leave that action's re-render stale). `revalidatePath()` has no path-based equivalent — tag the route's entries instead. Separately, to force specific matched segments (path/layout/parallel/intercept) and their loaders to re-render after an action, attach a `revalidate(({ actionId }) => ...)` rule to that segment or loader registration. See `/server-actions` for the full pattern (validation, error handling, file uploads), `/caching` for tag invalidation, and `/loader` for revalidation rule semantics.
+## 8. Metadata / Head
+Rango uses the `Meta` handle + `<MetaTags />` client component:
+```typescript
+// Next.js: export const metadata = { title: "Home" }
+// Next.js: export function generateMetadata({ params }) { ... }
+// Rango: Meta handle in handlers (server), MetaTags in document <head> (client)
+import { Meta } from "@rangojs/router";
+const HomePage: Handler<"home"> = (ctx) => {
+  const meta = ctx.use(Meta);
+  meta({ title: "Home" });
+  meta({ name: "description", content: "Welcome to the site" });
+  return <div>Home page</div>;
+};
+```
+Add `<MetaTags />` in the Document component's `<head>`:
+```typescript
+import { MetaTags } from "@rangojs/router/client";
+function Document({ children }: { children: ReactNode }) {
+  return (
+    <html>
+      <head>
+        <MetaTags />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+Later routes override earlier ones for the same meta key (deduplication).
+## 9. API Routes
+```typescript
+// Next.js: app/api/users/route.ts
+export async function GET(request) { ... }
+// Rango: response routes
+path.json("/api/users", async (ctx) => {
+  const users = await db.getUsers();
+  return users;
+}, { name: "apiUsers" })
+path.text("/api/health", () => "ok", { name: "apiHealth" })
+```
+See `/response-routes` for full API.
+## 10. Theme / Dark Mode
+If the Next.js app uses `next-themes` or a custom theme provider, replace it
+with Rango's built-in theme system (FOUC prevention included):
+```typescript
+const router = createRouter({
+  theme: true, // or { defaultTheme: "system", attribute: "class" }
+});
+```
+Client components use `useTheme()` to read and toggle:
+```typescript
+"use client";
+import { useTheme } from "@rangojs/router/theme";
+function ThemeToggle() {
+  const { theme, setTheme } = useTheme();
+  return <button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>{theme}</button>;
+}
+```
+See `/theme` for full API including system detection and cookie persistence.
+## Migration Checklist
+1. [ ] Set up Vite config with `rango()` plugin
+2. [ ] Create Document component (replaces root `<html>` layout)
+3. [ ] Create `router.tsx` with `createRouter()`
+4. [ ] Convert file-based routes to `urls()` DSL in `urls.tsx`
+5. [ ] Migrate layouts to `layout()` with `<Outlet />`
+6. [ ] Convert data fetching to `createLoader()` + `ctx.use()`
+7. [ ] Migrate `middleware.ts` to `router.use()` (auth, guards, logging)
+8. [ ] Replace `next/link` with `Link` from `@rangojs/router/client`
+9. [ ] Convert loading/error files to `loading()` / `errorBoundary()`
+10. [ ] Migrate API routes to `path.json()` / `path.text()`
+11. [ ] Update metadata to use `Meta` handle + `<MetaTags />` in document head
+12. [ ] Replace `next-themes` with `theme: true` in createRouter (see `/theme`)
+13. [ ] Run `npx rango generate src/` to generate route types