@rangojs/router 0.0.0-experimental.20 → 0.0.0-experimental.204030a9

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 (293) hide show
  1. package/AGENTS.md +4 -0
  2. package/README.md +242 -55
  3. package/dist/bin/rango.js +277 -99
  4. package/dist/vite/index.js +2929 -1132
  5. package/dist/vite/index.js.bak +5448 -0
  6. package/dist/vite/plugins/cloudflare-protocol-loader-hook.mjs +76 -0
  7. package/package.json +68 -21
  8. package/skills/breadcrumbs/SKILL.md +252 -0
  9. package/skills/bundle-analysis/SKILL.md +159 -0
  10. package/skills/cache-guide/SKILL.md +243 -21
  11. package/skills/caching/SKILL.md +159 -10
  12. package/skills/composability/SKILL.md +27 -2
  13. package/skills/document-cache/SKILL.md +78 -55
  14. package/skills/handler-use/SKILL.md +364 -0
  15. package/skills/hooks/SKILL.md +262 -51
  16. package/skills/host-router/SKILL.md +243 -0
  17. package/skills/i18n/SKILL.md +276 -0
  18. package/skills/intercept/SKILL.md +46 -4
  19. package/skills/layout/SKILL.md +28 -7
  20. package/skills/links/SKILL.md +249 -17
  21. package/skills/loader/SKILL.md +291 -31
  22. package/skills/middleware/SKILL.md +49 -12
  23. package/skills/migrate-nextjs/SKILL.md +562 -0
  24. package/skills/migrate-react-router/SKILL.md +769 -0
  25. package/skills/mime-routes/SKILL.md +27 -0
  26. package/skills/observability/SKILL.md +137 -0
  27. package/skills/parallel/SKILL.md +197 -6
  28. package/skills/prerender/SKILL.md +125 -102
  29. package/skills/rango/SKILL.md +242 -23
  30. package/skills/react-compiler/SKILL.md +168 -0
  31. package/skills/response-routes/SKILL.md +66 -9
  32. package/skills/route/SKILL.md +91 -8
  33. package/skills/router-setup/SKILL.md +98 -8
  34. package/skills/server-actions/SKILL.md +751 -0
  35. package/skills/streams-and-websockets/SKILL.md +283 -0
  36. package/skills/testing/SKILL.md +511 -188
  37. package/skills/typesafety/SKILL.md +354 -50
  38. package/skills/use-cache/SKILL.md +34 -5
  39. package/skills/view-transitions/SKILL.md +294 -0
  40. package/src/__augment-tests__/augment.ts +81 -0
  41. package/src/__augment-tests__/augmented.check.ts +117 -0
  42. package/src/__internal.ts +92 -0
  43. package/src/browser/action-coordinator.ts +53 -36
  44. package/src/browser/app-shell.ts +52 -0
  45. package/src/browser/app-version.ts +14 -0
  46. package/src/browser/event-controller.ts +91 -70
  47. package/src/browser/history-state.ts +21 -0
  48. package/src/browser/index.ts +3 -3
  49. package/src/browser/link-interceptor.ts +4 -0
  50. package/src/browser/navigation-bridge.ts +183 -18
  51. package/src/browser/navigation-client.ts +187 -57
  52. package/src/browser/navigation-store.ts +75 -17
  53. package/src/browser/navigation-transaction.ts +21 -37
  54. package/src/browser/partial-update.ts +143 -40
  55. package/src/browser/prefetch/cache.ts +275 -28
  56. package/src/browser/prefetch/fetch.ts +191 -46
  57. package/src/browser/prefetch/policy.ts +6 -0
  58. package/src/browser/prefetch/queue.ts +123 -20
  59. package/src/browser/prefetch/resource-ready.ts +77 -0
  60. package/src/browser/rango-state.ts +53 -13
  61. package/src/browser/react/Link.tsx +98 -14
  62. package/src/browser/react/NavigationProvider.tsx +110 -33
  63. package/src/browser/react/context.ts +7 -2
  64. package/src/browser/react/filter-segment-order.ts +51 -7
  65. package/src/browser/react/index.ts +3 -0
  66. package/src/browser/react/location-state-shared.ts +175 -4
  67. package/src/browser/react/location-state.ts +39 -13
  68. package/src/browser/react/use-handle.ts +23 -64
  69. package/src/browser/react/use-navigation.ts +22 -2
  70. package/src/browser/react/use-params.ts +20 -8
  71. package/src/browser/react/use-reverse.ts +106 -0
  72. package/src/browser/react/use-router.ts +43 -10
  73. package/src/browser/react/use-segments.ts +11 -8
  74. package/src/browser/response-adapter.ts +25 -0
  75. package/src/browser/rsc-router.tsx +200 -75
  76. package/src/browser/scroll-restoration.ts +46 -39
  77. package/src/browser/segment-reconciler.ts +36 -9
  78. package/src/browser/segment-structure-assert.ts +2 -2
  79. package/src/browser/server-action-bridge.ts +31 -36
  80. package/src/browser/types.ts +81 -5
  81. package/src/build/collect-fallback-refs.ts +107 -0
  82. package/src/build/generate-manifest.ts +65 -40
  83. package/src/build/generate-route-types.ts +5 -0
  84. package/src/build/index.ts +2 -0
  85. package/src/build/route-trie.ts +69 -26
  86. package/src/build/route-types/codegen.ts +4 -4
  87. package/src/build/route-types/include-resolution.ts +9 -2
  88. package/src/build/route-types/per-module-writer.ts +7 -4
  89. package/src/build/route-types/router-processing.ts +278 -88
  90. package/src/build/route-types/scan-filter.ts +9 -2
  91. package/src/build/route-types/source-scan.ts +118 -0
  92. package/src/build/runtime-discovery.ts +9 -20
  93. package/src/cache/cache-runtime.ts +15 -11
  94. package/src/cache/cache-scope.ts +76 -49
  95. package/src/cache/cf/cf-cache-store.ts +501 -18
  96. package/src/cache/cf/index.ts +5 -1
  97. package/src/cache/document-cache.ts +17 -7
  98. package/src/cache/index.ts +1 -0
  99. package/src/cache/taint.ts +55 -0
  100. package/src/client.rsc.tsx +5 -1
  101. package/src/client.tsx +95 -284
  102. package/src/context-var.ts +72 -2
  103. package/src/debug.ts +2 -2
  104. package/src/decode-loader-results.ts +36 -0
  105. package/src/errors.ts +30 -1
  106. package/src/handle.ts +65 -12
  107. package/src/handles/breadcrumbs.ts +66 -0
  108. package/src/handles/index.ts +1 -0
  109. package/src/host/index.ts +2 -5
  110. package/src/host/router.ts +129 -57
  111. package/src/host/types.ts +31 -2
  112. package/src/host/utils.ts +1 -1
  113. package/src/href-client.ts +140 -20
  114. package/src/index.rsc.ts +15 -40
  115. package/src/index.ts +92 -76
  116. package/src/loader-store.ts +500 -0
  117. package/src/loader.rsc.ts +2 -5
  118. package/src/loader.ts +3 -10
  119. package/src/missing-id-error.ts +68 -0
  120. package/src/outlet-context.ts +1 -1
  121. package/src/prerender/store.ts +57 -15
  122. package/src/prerender.ts +141 -80
  123. package/src/response-utils.ts +37 -0
  124. package/src/reverse.ts +65 -15
  125. package/src/route-content-wrapper.tsx +6 -28
  126. package/src/route-definition/dsl-helpers.ts +435 -260
  127. package/src/route-definition/helper-factories.ts +29 -139
  128. package/src/route-definition/helpers-types.ts +110 -34
  129. package/src/route-definition/index.ts +3 -3
  130. package/src/route-definition/redirect.ts +11 -3
  131. package/src/route-definition/resolve-handler-use.ts +155 -0
  132. package/src/route-definition/use-item-types.ts +32 -0
  133. package/src/route-map-builder.ts +7 -1
  134. package/src/route-types.ts +37 -41
  135. package/src/router/basename.ts +14 -0
  136. package/src/router/content-negotiation.ts +113 -1
  137. package/src/router/error-handling.ts +1 -1
  138. package/src/router/find-match.ts +4 -2
  139. package/src/router/handler-context.ts +105 -39
  140. package/src/router/intercept-resolution.ts +15 -22
  141. package/src/router/lazy-includes.ts +12 -9
  142. package/src/router/loader-resolution.ts +175 -23
  143. package/src/router/logging.ts +5 -2
  144. package/src/router/manifest.ts +31 -16
  145. package/src/router/match-api.ts +129 -193
  146. package/src/router/match-handlers.ts +63 -20
  147. package/src/router/match-middleware/background-revalidation.ts +30 -2
  148. package/src/router/match-middleware/cache-lookup.ts +136 -106
  149. package/src/router/match-middleware/cache-store.ts +54 -10
  150. package/src/router/match-middleware/intercept-resolution.ts +9 -7
  151. package/src/router/match-middleware/segment-resolution.ts +61 -5
  152. package/src/router/match-result.ts +124 -18
  153. package/src/router/metrics.ts +239 -14
  154. package/src/router/middleware-types.ts +61 -31
  155. package/src/router/middleware.ts +226 -124
  156. package/src/router/navigation-snapshot.ts +182 -0
  157. package/src/router/pattern-matching.ts +118 -19
  158. package/src/router/prerender-match.ts +114 -10
  159. package/src/router/preview-match.ts +32 -102
  160. package/src/router/request-classification.ts +286 -0
  161. package/src/router/revalidation.ts +85 -9
  162. package/src/router/route-snapshot.ts +245 -0
  163. package/src/router/router-context.ts +6 -1
  164. package/src/router/router-interfaces.ts +91 -29
  165. package/src/router/router-options.ts +89 -19
  166. package/src/router/router-registry.ts +2 -5
  167. package/src/router/segment-resolution/fresh.ts +240 -23
  168. package/src/router/segment-resolution/helpers.ts +30 -25
  169. package/src/router/segment-resolution/loader-cache.ts +1 -0
  170. package/src/router/segment-resolution/revalidation.ts +483 -289
  171. package/src/router/segment-resolution/view-transition-default.ts +36 -0
  172. package/src/router/segment-wrappers.ts +2 -0
  173. package/src/router/substitute-pattern-params.ts +56 -0
  174. package/src/router/telemetry.ts +99 -0
  175. package/src/router/trie-matching.ts +38 -15
  176. package/src/router/types.ts +9 -0
  177. package/src/router/url-params.ts +49 -0
  178. package/src/router.ts +120 -32
  179. package/src/rsc/handler-context.ts +2 -2
  180. package/src/rsc/handler.ts +524 -370
  181. package/src/rsc/helpers.ts +91 -43
  182. package/src/rsc/index.ts +1 -21
  183. package/src/rsc/loader-fetch.ts +23 -3
  184. package/src/rsc/manifest-init.ts +5 -1
  185. package/src/rsc/origin-guard.ts +28 -10
  186. package/src/rsc/progressive-enhancement.ts +39 -10
  187. package/src/rsc/response-route-handler.ts +46 -53
  188. package/src/rsc/rsc-rendering.ts +69 -89
  189. package/src/rsc/runtime-warnings.ts +9 -10
  190. package/src/rsc/server-action.ts +39 -47
  191. package/src/rsc/ssr-setup.ts +144 -0
  192. package/src/rsc/types.ts +19 -3
  193. package/src/search-params.ts +20 -17
  194. package/src/segment-content-promise.ts +67 -0
  195. package/src/segment-loader-promise.ts +122 -0
  196. package/src/segment-system.tsx +219 -67
  197. package/src/serialize.ts +243 -0
  198. package/src/server/context.ts +285 -63
  199. package/src/server/cookie-store.ts +28 -4
  200. package/src/server/handle-store.ts +19 -0
  201. package/src/server/loader-registry.ts +9 -8
  202. package/src/server/request-context.ts +228 -65
  203. package/src/server.ts +6 -0
  204. package/src/ssr/index.tsx +9 -1
  205. package/src/static-handler.ts +19 -7
  206. package/src/testing/cache-status.ts +166 -0
  207. package/src/testing/collect-handle.ts +63 -0
  208. package/src/testing/dispatch.ts +440 -0
  209. package/src/testing/dom.entry.ts +22 -0
  210. package/src/testing/e2e/fixture.ts +154 -0
  211. package/src/testing/e2e/index.ts +149 -0
  212. package/src/testing/e2e/matchers.ts +51 -0
  213. package/src/testing/e2e/page-helpers.ts +272 -0
  214. package/src/testing/e2e/parity.ts +306 -0
  215. package/src/testing/e2e/server.ts +183 -0
  216. package/src/testing/flight-matchers.ts +104 -0
  217. package/src/testing/flight-runtime.d.ts +21 -0
  218. package/src/testing/flight.entry.ts +22 -0
  219. package/src/testing/flight.ts +182 -0
  220. package/src/testing/generated-routes.ts +223 -0
  221. package/src/testing/index.ts +98 -0
  222. package/src/testing/internal/context.ts +151 -0
  223. package/src/testing/render-route.tsx +536 -0
  224. package/src/testing/run-loader.ts +296 -0
  225. package/src/testing/run-middleware.ts +170 -0
  226. package/src/testing/vitest-stubs/cloudflare-email.ts +9 -0
  227. package/src/testing/vitest-stubs/cloudflare-workers.ts +21 -0
  228. package/src/testing/vitest-stubs/plugin-rsc.ts +16 -0
  229. package/src/testing/vitest-stubs/version.ts +5 -0
  230. package/src/testing/vitest.ts +112 -0
  231. package/src/theme/index.ts +4 -13
  232. package/src/types/cache-types.ts +4 -4
  233. package/src/types/global-namespace.ts +39 -26
  234. package/src/types/handler-context.ts +197 -79
  235. package/src/types/index.ts +1 -0
  236. package/src/types/loader-types.ts +41 -15
  237. package/src/types/request-scope.ts +126 -0
  238. package/src/types/route-config.ts +17 -8
  239. package/src/types/route-entry.ts +19 -1
  240. package/src/types/segments.ts +37 -6
  241. package/src/urls/include-helper.ts +34 -67
  242. package/src/urls/index.ts +0 -3
  243. package/src/urls/path-helper-types.ts +50 -9
  244. package/src/urls/path-helper.ts +63 -63
  245. package/src/urls/pattern-types.ts +48 -19
  246. package/src/urls/response-types.ts +25 -22
  247. package/src/urls/type-extraction.ts +26 -116
  248. package/src/urls/urls-function.ts +1 -5
  249. package/src/use-loader.tsx +487 -44
  250. package/src/vite/debug.ts +185 -0
  251. package/src/vite/discovery/bundle-postprocess.ts +63 -91
  252. package/src/vite/discovery/discover-routers.ts +106 -53
  253. package/src/vite/discovery/discovery-errors.ts +194 -0
  254. package/src/vite/discovery/gate-state.ts +171 -0
  255. package/src/vite/discovery/prerender-collection.ts +222 -107
  256. package/src/vite/discovery/route-types-writer.ts +40 -84
  257. package/src/vite/discovery/self-gen-tracking.ts +27 -1
  258. package/src/vite/discovery/state.ts +50 -13
  259. package/src/vite/discovery/virtual-module-codegen.ts +13 -23
  260. package/src/vite/index.ts +10 -3
  261. package/src/vite/plugin-types.ts +111 -72
  262. package/src/vite/plugins/cjs-to-esm.ts +8 -7
  263. package/src/vite/plugins/client-ref-dedup.ts +16 -0
  264. package/src/vite/plugins/client-ref-hashing.ts +28 -5
  265. package/src/vite/plugins/cloudflare-protocol-loader-hook.d.mts +23 -0
  266. package/src/vite/plugins/cloudflare-protocol-loader-hook.mjs +76 -0
  267. package/src/vite/plugins/cloudflare-protocol-stub.ts +214 -0
  268. package/src/vite/plugins/expose-action-id.ts +55 -33
  269. package/src/vite/plugins/expose-id-utils.ts +24 -8
  270. package/src/vite/plugins/expose-ids/export-analysis.ts +100 -20
  271. package/src/vite/plugins/expose-ids/handler-transform.ts +12 -35
  272. package/src/vite/plugins/expose-ids/loader-transform.ts +3 -5
  273. package/src/vite/plugins/expose-ids/router-transform.ts +20 -3
  274. package/src/vite/plugins/expose-internal-ids.ts +544 -317
  275. package/src/vite/plugins/performance-tracks.ts +92 -0
  276. package/src/vite/plugins/refresh-cmd.ts +127 -0
  277. package/src/vite/plugins/use-cache-transform.ts +65 -50
  278. package/src/vite/plugins/version-injector.ts +39 -23
  279. package/src/vite/plugins/version-plugin.ts +72 -3
  280. package/src/vite/plugins/virtual-entries.ts +2 -2
  281. package/src/vite/rango.ts +265 -226
  282. package/src/vite/router-discovery.ts +924 -137
  283. package/src/vite/utils/ast-handler-extract.ts +15 -15
  284. package/src/vite/utils/banner.ts +4 -4
  285. package/src/vite/utils/bundle-analysis.ts +4 -2
  286. package/src/vite/utils/client-chunks.ts +190 -0
  287. package/src/vite/utils/forward-user-plugins.ts +193 -0
  288. package/src/vite/utils/manifest-utils.ts +21 -5
  289. package/src/vite/utils/package-resolution.ts +41 -1
  290. package/src/vite/utils/prerender-utils.ts +98 -5
  291. package/src/vite/utils/shared-utils.ts +109 -27
  292. package/src/browser/action-response-classifier.ts +0 -99
  293. package/src/route-definition/route-function.ts +0 -119
@@ -6,7 +6,10 @@ argument-hint: [loader]
6
6
 
7
7
  # Data Loaders with loader()
8
8
 
9
- Loaders fetch data on the server and stream it to the client.
9
+ Loaders fetch data on the server and stream it to the client. For mutations
10
+ (writes triggered by forms or buttons), use server actions instead — see
11
+ `/server-actions`. Loaders re-resolve after an action runs, so the typical
12
+ flow is _action mutates → loader re-reads → UI updates_.
10
13
 
11
14
  ## Creating a Loader
12
15
 
@@ -65,19 +68,10 @@ export const urlpatterns = urls(({ path, loader }) => [
65
68
 
66
69
  ## Consuming Loader Data
67
70
 
68
- ### In Server Components
69
-
70
- ```typescript
71
- import { useLoader } from "@rangojs/router";
72
- import { ProductLoader } from "./loaders/product";
73
-
74
- async function ProductPage() {
75
- const { product } = await useLoader(ProductLoader);
76
- return <h1>{product.name}</h1>;
77
- }
78
- ```
79
-
80
- ### In Client Components
71
+ Register loaders with `loader()` in the DSL and consume them in client
72
+ components with `useLoader()`. This is the recommended pattern — it keeps
73
+ data fetching on the server and consumption on the client, with a clean
74
+ separation that works correctly with `cache()`.
81
75
 
82
76
  ```typescript
83
77
  "use client";
@@ -90,9 +84,101 @@ function ProductDetails() {
90
84
  }
91
85
  ```
92
86
 
87
+ ```typescript
88
+ // Route definition — loader() registration required
89
+ path("/product/:slug", ProductPage, { name: "product" }, () => [
90
+ loader(ProductLoader),
91
+ ]);
92
+ ```
93
+
94
+ > **Client refresh `key` vs. server `cache({ key })` vs. `revalidate()`.** Three
95
+ > different "what refreshes" knobs that are easy to confuse:
96
+ >
97
+ > - `useLoader(Loader, { key })` / `useFetchLoader(Loader, { key })` — a
98
+ > **client** refresh identity. It groups which mounted reads of one loader
99
+ > refresh together when one calls `load()`. It never touches the server
100
+ > request. For refreshing **different** loaders together, tag them with
101
+ > `{ refreshGroup }` (one name or several) and call `useRefreshLoaders()(name)`
102
+ > (plain GET only). See the hooks skill ("Scoping refetch with a `key`" and
103
+ > "Refreshing multiple loaders together").
104
+ > - `cache({ key })` — a **server** cache identity (storage hit/miss/ttl/swr).
105
+ > - `revalidate()` — which **server** segments/loaders recompute during
106
+ > navigation and action refreshes.
107
+
108
+ DSL loaders are the **live data layer** — they resolve fresh on every
109
+ request, even when the route is inside a `cache()` boundary. The router
110
+ excludes them from the segment cache at storage time and re-resolves them
111
+ on retrieval. This means `cache()` gives you cached UI + fresh data by
112
+ default.
113
+
114
+ ### Cache safety
115
+
116
+ DSL loaders can safely read `createVar({ cache: false })` variables
117
+ because they are always resolved fresh. The read guard is bypassed for
118
+ loader functions — they never produce stale data.
119
+
120
+ ### ctx.use(Loader) — escape hatch
121
+
122
+ For cases where you need loader data in the server handler itself (e.g.,
123
+ to set ctx variables or make routing decisions), use `ctx.use(Loader)`:
124
+
125
+ ```typescript
126
+ path("/product/:slug", async (ctx) => {
127
+ const { product } = await ctx.use(ProductLoader);
128
+ ctx.set(Product, product); // make available to children
129
+ return <ProductPage />;
130
+ }, { name: "product" }, () => [
131
+ loader(ProductLoader), // still register for client consumption
132
+ ])
133
+ ```
134
+
135
+ When you register with `loader()` in the DSL, `ctx.use()` returns the
136
+ same memoized result — loaders never run twice per request.
137
+
138
+ **Limitations of ctx.use(Loader):**
139
+
140
+ - The handler output depends on the loader data. If the route is inside
141
+ `cache()`, the handler is cached with the loader result baked in —
142
+ defeating the live data guarantee.
143
+ - Non-cacheable variable reads (`createVar({ cache: false })`) inside the
144
+ handler still throw, even if the data came from a loader.
145
+ - Prefer DSL `loader()` + client `useLoader()` for data that depends on
146
+ non-cacheable context variables.
147
+
148
+ **Never use `useLoader()` in server components** — it is a client-only API.
149
+
150
+ ### Summary
151
+
152
+ | Pattern | API | Cache-safe | Recommended |
153
+ | ---------------------- | ------------------- | ---------- | ----------- |
154
+ | DSL + client component | `useLoader(Loader)` | Yes | Yes |
155
+ | Handler escape hatch | `ctx.use(Loader)` | No | When needed |
156
+
93
157
  ## Loader Context
94
158
 
95
- Loaders receive the same context as route handlers:
159
+ Loaders receive the same context shape as route handlers.
160
+
161
+ ### Full field surface
162
+
163
+ | Field | Type | Notes |
164
+ | -------------- | ------------------------------ | --------------------------------------------------------------------------------------------------- |
165
+ | `params` | `TParams` | Merged route + explicit loader params; overridable by fetchable `load({ params })`. |
166
+ | `routeParams` | `Record<string, string>` | Server-trusted route params from URL pattern matching; cannot be overridden. |
167
+ | `request` | `Request` | The incoming `Request` (headers, method, body, `signal` for abort). |
168
+ | `url` | `URL` | Parsed request URL. |
169
+ | `pathname` | `string` | URL pathname (shortcut for `ctx.url.pathname`). |
170
+ | `searchParams` | `URLSearchParams` | Shortcut for `ctx.url.searchParams`. |
171
+ | `search` | `ResolveSearchSchema<TSearch>` | Typed query params when a search schema is declared on the route; `{}` otherwise. |
172
+ | `env` | `TEnv` | Plain bindings from `createRouter<TEnv>()` (DB, KV, secrets, etc.). |
173
+ | `get` | `(key \| ContextVar) => value` | Reads variables/context-vars set by middleware. |
174
+ | `use` | `(loader \| handle) => T` | Access another loader's data (Promise) or a handle's collected data (after `await ctx.rendered()`). |
175
+ | `rendered` | `() => Promise<void>` | **Experimental.** DSL loaders only — waits for non-loader segments before reading handle data. |
176
+ | `method` | `string` | HTTP method. `"GET"` for SSR loader runs; reflects real method for fetchable loaders. |
177
+ | `body` | `TBody \| undefined` | Parsed request body for fetchable POST/PUT/PATCH/DELETE calls. |
178
+ | `formData` | `FormData \| undefined` | Present when a fetchable loader is invoked via form submission. |
179
+ | `reverse` | `ScopedReverseFunction` | Generate type-checked URLs from route names (same scoped semantics as route handlers). |
180
+
181
+ ### Example
96
182
 
97
183
  ```typescript
98
184
  export const ProductLoader = createLoader(async (ctx) => {
@@ -113,13 +199,24 @@ export const ProductLoader = createLoader(async (ctx) => {
113
199
  // Request headers
114
200
  const auth = ctx.request.headers.get("Authorization");
115
201
 
116
- // Variables set by middleware (from RSCRouter.Vars augmentation)
202
+ // Variables set by middleware (from Rango.Vars augmentation)
117
203
  const user = ctx.get("user");
118
204
 
119
- return { product: await fetchProduct(slug) };
205
+ // Type-checked URLs for payloads. `.name` resolves within the current
206
+ // include() scope; a bare `name` resolves globally. See /route and
207
+ // /typesafety for scope rules and route-name autocomplete.
208
+ const detailUrl = ctx.reverse(".detail", { slug });
209
+
210
+ return {
211
+ product: await fetchProduct(slug),
212
+ links: { self: detailUrl },
213
+ };
120
214
  });
121
215
  ```
122
216
 
217
+ See `/route` for the full handler-context contract (shared with loaders) and
218
+ `/typesafety` for route-name typing that powers `ctx.reverse` autocomplete.
219
+
123
220
  ### params vs routeParams
124
221
 
125
222
  - `ctx.params` — merged route params + explicit loader params. For fetchable
@@ -161,13 +258,104 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
161
258
  revalidate(() => false), // Never revalidate
162
259
  ]),
163
260
 
164
- // Loader that revalidates after cart actions
261
+ // Loader that revalidates after cart actions (defer otherwise — keeps the
262
+ // permissive loader defaults for navigation and other actions intact)
165
263
  loader(CartLoader, () => [
166
- revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
264
+ revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
167
265
  ]),
168
266
  ]);
169
267
  ```
170
268
 
269
+ ### `revalidate()` return shapes
270
+
271
+ > **Scope: `revalidate()` is a partial-render concern, not a cache concern.**
272
+ > It decides whether a segment (here, a loader) re-runs and streams to the
273
+ > client on a navigation or action — never whether a cached value is stale. The
274
+ > cache decides hit/miss/ttl/swr independently and never reads `revalidate()`.
275
+ > Caching a loader is a separate, opt-in step (`loader(Fn, () => [cache({...})])`).
276
+ > See `/cache-guide` → "Two axes" and `/rango` → "The shape of rango".
277
+
278
+ A `revalidate(fn)` callback can return one of four shapes. The chain
279
+ processes revalidators in order; each call's return controls how the
280
+ chain continues:
281
+
282
+ ```typescript
283
+ // 1) Hard decision — short-circuits the chain, used as the final answer.
284
+ revalidate(() => true);
285
+ revalidate(({ actionId }) => actionId?.includes("Cart") ?? false);
286
+
287
+ // 2) Soft decision — updates the running suggestion for downstream
288
+ // revalidators on the same segment, chain continues.
289
+ revalidate(({ defaultShouldRevalidate }) => ({
290
+ defaultShouldRevalidate: !defaultShouldRevalidate,
291
+ }));
292
+
293
+ // 3) Defer (no opinion) — leaves the running suggestion unchanged and
294
+ // continues to the next revalidator. Implicit return / null /
295
+ // undefined are all equivalent and consumer-friendly.
296
+ revalidate(({ actionId }) => {
297
+ if (actionId?.includes("Cart")) return true; // hard for this branch only
298
+ // implicit return — let downstream revalidators or the segment default decide
299
+ });
300
+ revalidate(() => undefined); // explicit defer
301
+ revalidate(() => null); // explicit defer
302
+ ```
303
+
304
+ If every revalidator on a segment defers, the segment-type default
305
+ (e.g. params-changed for routes, `false` for parallels) is used.
306
+
307
+ #### `|| undefined` (defer) vs `?? false` (hard) — pick deliberately
308
+
309
+ A boolean return — including `false` — is a **hard** decision: it short-circuits
310
+ the chain and overrides the segment default. `undefined` **defers** to the
311
+ running suggestion / segment default. They are not interchangeable:
312
+
313
+ ```typescript
314
+ // Defer: "revalidate on match, otherwise let the default/downstream decide."
315
+ revalidate(({ actionId }) => actionId?.includes("Cart") || undefined);
316
+
317
+ // Hard: "revalidate ONLY on match, suppress everything else."
318
+ revalidate(({ actionId }) => actionId?.includes("Cart") ?? false);
319
+ ```
320
+
321
+ This matters most for loaders, whose defaults are permissive: a loader defaults
322
+ to revalidating on **any** action (`POST`) and on **param/search changes**
323
+ during navigation. So `?? false` on a loader silently suppresses both — the
324
+ loader will not refetch when you navigate to a different `:id`. Use
325
+ `|| undefined` when you want to _add_ a revalidation signal on top of the
326
+ sensible defaults, and reserve `?? false` for the rare case where you genuinely
327
+ want the loader to refetch on nothing but your matched action.
328
+
329
+ When **composing multiple revalidators** on one segment (see below), defer is
330
+ mandatory: the first hard `?? false` ends the chain and the later contracts
331
+ never run.
332
+
333
+ #### Matching actions: `ctx.isAction()`
334
+
335
+ To revalidate after specific server actions, match them by **reference** with
336
+ `ctx.isAction()` rather than hand-written `actionId` substrings. A rename or
337
+ moved file then becomes a type error instead of silently failing to match:
338
+
339
+ ```typescript
340
+ import { addToCart, removeFromCart } from "../actions/cart";
341
+ import * as CartActions from "../actions/cart";
342
+
343
+ loader(CartLoader, () => [
344
+ revalidate((ctx) => ctx.isAction(addToCart) || undefined), // one action
345
+ ]);
346
+ revalidate((ctx) => ctx.isAction(addToCart, removeFromCart) || undefined); // several
347
+ revalidate((ctx) => ctx.isAction(CartActions) || undefined); // any action in the module
348
+ ```
349
+
350
+ `isAction()` is a method on the revalidate predicate's **context argument** —
351
+ there is no standalone `isAction` import; you always reach it through the callback
352
+ parameter (`revalidate((ctx) => ctx.isAction(...))`). It returns a raw boolean, so
353
+ pair it with `|| undefined` for the usual "revalidate on match, else defer"
354
+ intent. It returns `false` on plain navigation and on non-matches, and resolves
355
+ the reference the same way the router derives `actionId` (`$id` in production,
356
+ `$$id` in dev), so it matches in both modes. The raw `actionId` string stays
357
+ available on the same context as an escape hatch.
358
+
171
359
  ### Revalidation Contracts for Loader Dependencies
172
360
 
173
361
  If a loader reads `ctx.get()` data produced by an outer handler/layout, share
@@ -175,8 +363,12 @@ the same named revalidation contract across producer and consumer segments.
175
363
 
176
364
  ```typescript
177
365
  // revalidation-contracts.ts
178
- export const revalidateAccountScope = ({ actionId }) =>
179
- actionId?.includes("src/actions/account.ts#") ?? false;
366
+ import * as AccountActions from "./actions/account";
367
+
368
+ // Match by reference with ctx.isAction() (rename-safe), and defer (|| undefined)
369
+ // so these contracts compose — a hard `false` would short-circuit the rest.
370
+ export const revalidateAccountScope = (ctx) =>
371
+ ctx.isAction(AccountActions) || undefined;
180
372
 
181
373
  layout(AccountLayout, () => [
182
374
  revalidate(revalidateAccountScope), // producer reruns
@@ -219,6 +411,64 @@ follows the same rule: at build time, loaders are skipped entirely (there is no
219
411
  real request context), and at runtime the worker resolves them fresh against
220
412
  the live database.
221
413
 
414
+ ### Parallel and streaming — latency overlaps first paint
415
+
416
+ Loaders do not block the page. As the render pass begins — the pass that route
417
+ middleware wraps, so loaders run right after middleware, not in a later
418
+ phase — every matched loader is kicked off **concurrently** (their promises start in the
419
+ same tick), and each result is **streamed** to the client as its own RSC Flight
420
+ chunk rather than awaited up front. Pair a loader with `loading()` (or a
421
+ client `<Suspense>`) and the shell paints immediately while the data streams in.
422
+
423
+ This is why **"cached UI still pays full data latency" is the wrong intuition**:
424
+ on a `cache()` hit the UI segments stream instantly from cache while the live
425
+ loaders resolve fresh **in parallel** — data latency _overlaps_ first paint
426
+ instead of being added on top of it. (Without a `loading()` / `<Suspense>`
427
+ boundary a parallel loader blocks its parent, so add one to keep the overlap.)
428
+
429
+ If you come from a framework where the loader is a blocking step that runs
430
+ before the response is built, this is the shift to internalize: here the
431
+ response starts streaming first and loader data fills in.
432
+
433
+ ### See it: `debugPerformance`
434
+
435
+ Turn on the per-request performance timeline early — it is the fastest way to
436
+ confirm loaders overlap rather than serialize, and to find the real bottleneck
437
+ locally instead of guessing:
438
+
439
+ ```typescript
440
+ const router = createRouter({ document: Document, debugPerformance: true });
441
+ ```
442
+
443
+ Or enable it per-request from middleware (e.g. only when `?debug` is present) by
444
+ calling `ctx.debugPerformance()` **before** `await next()`. Each HTML request
445
+ then prints a shared-axis waterfall (and emits a `Server-Timing` header):
446
+
447
+ ```
448
+ [RSC Perf] GET /product/widget (24.53ms)
449
+ start dur span timeline
450
+ 0.08ms 3.20ms route-matching |#####...................................|
451
+ 3.40ms 8.70ms ssr-render-html |.....##############.....................|
452
+ 3.42ms 11.90ms loader:…#ProductLoader |.....###################................|
453
+ 3.45ms 11.40ms loader:…#ReviewsLoader |.....##################.................|
454
+ 0.00ms 24.53ms handler:total |########################################|
455
+ ```
456
+
457
+ How to read it:
458
+
459
+ - **Humans:** scan the `#` bars on the shared axis. Bars that start at the same
460
+ offset and run side by side are executing **in parallel** — loaders should
461
+ overlap `ssr-render-html` / `render:total`, not sit alone to the right of
462
+ everything. A lone `loader:*` bar past the render bar is serialized latency to
463
+ chase. `handler:total` is the whole request; `render:total` is the render pass.
464
+ - **LLMs / programmatic:** read each row as `{ start, dur, label }`. A loader
465
+ overlaps paint when its `[start, start+dur]` interval intersects
466
+ `render:total` / `ssr-render-html`. Flag a regression when a `loader:*`
467
+ interval is **disjoint from and starts after** `render:total`, or when its
468
+ `dur` approaches `handler:total` — that loader is on the critical path instead
469
+ of overlapping it. Two `loader:*` rows with near-equal `start` confirm
470
+ parallel execution.
471
+
222
472
  ### Opting a Loader into Caching
223
473
 
224
474
  To cache a specific loader's data, attach a `cache()` child:
@@ -492,6 +742,13 @@ export const FileUploadLoader = createLoader(async (ctx) => {
492
742
 
493
743
  Client usage — see `/hooks useFetchLoader` for the full client-side pattern.
494
744
 
745
+ > **Refetch sharing**: when the loader is registered on the route via
746
+ > `loader()`, a plain `load()` call (no `params`, no `body`) broadcasts
747
+ > the new value to every component reading the same loader id —
748
+ > `useLoader` reads in layouts, pages, and parallel slots all converge.
749
+ > Calls with `params` or a non-GET method stay local to the call site.
750
+ > See `/hooks` → "Shared refetch behavior" for the full contract.
751
+
495
752
  ## Complete Example
496
753
 
497
754
  ```typescript
@@ -507,7 +764,7 @@ export const ProductLoader = createLoader(async (ctx) => {
507
764
  .first();
508
765
 
509
766
  if (!product) {
510
- throw new Response("Product not found", { status: 404 });
767
+ notFound("Product not found");
511
768
  }
512
769
 
513
770
  return { product };
@@ -523,12 +780,11 @@ export const CartLoader = createLoader(async (ctx) => {
523
780
  return { cart };
524
781
  });
525
782
 
526
- // urls.tsx
783
+ // urls.tsx — register loaders in the DSL
527
784
  export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalidate }) => [
528
785
  layout(<ShopLayout />, () => [
529
- // Shared cart loader for all shop routes
530
786
  loader(CartLoader, () => [
531
- revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
787
+ revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
532
788
  ]),
533
789
 
534
790
  path("/shop/product/:slug", ProductPage, { name: "product" }, () => [
@@ -538,18 +794,22 @@ export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalid
538
794
  ]),
539
795
  ]);
540
796
 
541
- // pages/product.tsx
542
- import { useLoader } from "@rangojs/router";
797
+ // components/ProductDetails.tsx — consume in client component
798
+ "use client";
799
+ import { useLoader } from "@rangojs/router/client";
543
800
  import { ProductLoader, CartLoader } from "./loaders/shop";
544
801
 
545
- async function ProductPage() {
546
- const { product } = await useLoader(ProductLoader);
547
- const { cart } = await useLoader(CartLoader);
802
+ function ProductDetails() {
803
+ const { data: { product } } = useLoader(ProductLoader);
804
+ const { data: { cart } } = useLoader(CartLoader);
548
805
 
549
806
  return (
550
807
  <div>
551
808
  <h1>{product.name}</h1>
552
- <AddToCartButton productId={product.id} inCart={cart?.items.includes(product.id)} />
809
+ <AddToCartButton
810
+ productId={product.id}
811
+ inCart={cart?.items.includes(product.id)}
812
+ />
553
813
  </div>
554
814
  );
555
815
  }
@@ -10,9 +10,6 @@ Middleware runs before/after route handlers using the onion model.
10
10
 
11
11
  ## Execution Model
12
12
 
13
- Canonical semantics reference:
14
- [docs/execution-model.md](../../docs/internal/execution-model.md)
15
-
16
13
  There are two levels of middleware with different execution scopes:
17
14
 
18
15
  ### Global middleware (`router.use()`)
@@ -26,21 +23,32 @@ const router = createRouter<AppEnv>({})
26
23
  .routes(urlpatterns);
27
24
  ```
28
25
 
26
+ When the router has a `basename`, pattern-scoped `.use()` patterns are automatically prefixed. For example, with `basename: "/app"`, `.use("/admin/*", mw)` matches `/app/admin/*`.
27
+
29
28
  ### Route middleware (`middleware()` in `urls()`)
30
29
 
31
30
  Registered inside `urls()` callback. Wraps **rendering only** -- it does NOT wrap server action execution. Actions run before route middleware, so when route middleware executes during post-action revalidation, it can observe state that the action set (cookies, context variables, headers).
32
31
 
32
+ > **Implication for auth:** route middleware cannot guard server actions. Use `router.use("/admin/*", requireAuth)` (global, scoped) for action protection, or check inside the action body. See `/server-actions` for action-side auth patterns.
33
+
33
34
  ```
34
35
  Request flow (with action):
35
- global mw -> action executes -> route mw -> layout -> handler -> loaders
36
+ global mw -> action executes -> route mw -> render pass
36
37
 
37
38
  Request flow (no action):
38
- global mw -> route mw -> layout -> handler -> loaders
39
+ global mw -> route mw -> render pass
39
40
 
40
41
  Progressive enhancement (no-JS form POST):
41
42
  global mw -> action executes -> route mw -> full page re-render
42
43
  ```
43
44
 
45
+ The **render pass** resolves handler, layouts, parallels, and loaders together —
46
+ it is not a handler-then-loaders sequence. Handler-first ordering is guaranteed
47
+ only between a route handler and its child/orphan layouts and parallels (so
48
+ `ctx.set` is visible); loaders run **concurrently** and stream their results, so
49
+ their latency overlaps rendering rather than blocking it. See `/loader` →
50
+ "Parallel and streaming".
51
+
44
52
  The contract is: **route middleware wraps rendering regardless of transport** (JS-enabled RSC stream or no-JS HTML). During PE re-render, route middleware observes action-set state (cookies, context variables) the same way it does during JS-enabled post-action revalidation.
45
53
 
46
54
  Revalidation is still partial. Route middleware wraps the render pass that
@@ -60,7 +68,7 @@ and consumer segments, even when middleware is present in the chain.
60
68
 
61
69
  ```typescript
62
70
  export const revalidateCartData = ({ actionId }) =>
63
- actionId?.includes("src/actions/cart.ts#") ?? false;
71
+ actionId?.includes("src/actions/cart.ts#") || undefined;
64
72
 
65
73
  layout(CartLayout, () => [
66
74
  middleware(cartRenderMiddleware),
@@ -135,17 +143,46 @@ export const urlpatterns = urls(({ path, layout, middleware }) => [
135
143
  ## Middleware with Multiple Handlers
136
144
 
137
145
  ```typescript
138
- // Spread multiple middleware from a single export
146
+ // Group multiple middleware in an array
139
147
  export const shopMiddleware = [loggerMiddleware, mockAuthMiddleware];
140
148
 
141
- // In routes
149
+ // In routes — pass the array directly
142
150
  layout(<ShopLayout />, () => [
143
- middleware(...shopMiddleware),
151
+ middleware(shopMiddleware),
144
152
 
145
153
  path("/shop", ShopIndex, { name: "shop" }),
146
154
  ])
147
155
  ```
148
156
 
157
+ ## Wrapping Middleware (Scoped to Children)
158
+
159
+ Use the wrapping form to scope middleware to a subset of routes without
160
+ introducing a visible layout:
161
+
162
+ ```typescript
163
+ urls(({ path, middleware }) => [
164
+ // authMw only applies to /admin and /admin/settings
165
+ middleware(authMw, () => [
166
+ path("/admin", AdminPage, { name: "admin" }),
167
+ path("/admin/settings", SettingsPage, { name: "settings" }),
168
+ ]),
169
+
170
+ // Public route — no authMw
171
+ path("/", HomePage, { name: "home" }),
172
+ ]);
173
+ ```
174
+
175
+ Multiple middleware with wrapping:
176
+
177
+ ```typescript
178
+ middleware([authMw, loggingMw], () => [
179
+ path("/admin", AdminPage, { name: "admin" }),
180
+ ]);
181
+ ```
182
+
183
+ This creates a transparent layout (`<Outlet />`) that carries the middleware.
184
+ The middleware does not affect sibling routes outside the callback.
185
+
149
186
  ## Middleware Context
150
187
 
151
188
  ```typescript
@@ -159,7 +196,7 @@ export const myMiddleware: Middleware = async (ctx, next) => {
159
196
  ctx.env.DB; // D1Database
160
197
  ctx.env.KV; // KVNamespace
161
198
 
162
- // Set variables for downstream handlers (typed via RSCRouter.Vars)
199
+ // Set variables for downstream handlers (typed via Rango.Vars)
163
200
  ctx.set("user", { id: "123", name: "John" });
164
201
 
165
202
  // Continue to next middleware/handler
@@ -200,8 +237,8 @@ const Dashboard: Handler<"dashboard"> = (ctx) => {
200
237
  ```
201
238
 
202
239
  This works alongside `ctx.get("key")` / `ctx.set("key", value)` (global typing
203
- via RSCRouter.Vars augmentation). Use `createVar` for route-local or feature-scoped
204
- data; use RSCRouter.Vars for app-wide middleware state.
240
+ via Rango.Vars augmentation). Use `createVar` for route-local or feature-scoped
241
+ data; use Rango.Vars for app-wide middleware state.
205
242
 
206
243
  ## Redirect with State in Middleware
207
244