@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
package/src/router.ts CHANGED
@@ -19,11 +19,12 @@ import {
19
19
  import MapRootLayout from "./server/root-layout.js";
20
20
  import type { AllUseItems } from "./route-types.js";
21
21
  import type { UrlPatterns } from "./urls.js";
22
+ import type { UrlBuilder } from "./urls/pattern-types.js";
23
+ import { urls } from "./urls.js";
22
24
  import {
23
- EntryData,
24
- InterceptSelectorContext,
25
+ type EntryData,
25
26
  getContext,
26
- RSCRouterContext,
27
+ RangoContext,
27
28
  type MetricsStore,
28
29
  } from "./server/context";
29
30
  import { createHandleStore, type HandleStore } from "./server/handle-store.js";
@@ -55,6 +56,7 @@ import { buildDebugManifest } from "./router/debug-manifest.js";
55
56
 
56
57
  import type { SegmentResolutionDeps, MatchApiDeps } from "./router/types.js";
57
58
  import { createHandlerContext } from "./router/handler-context.js";
59
+ import { normalizeBasename } from "./router/basename.js";
58
60
  import {
59
61
  setupLoaderAccess,
60
62
  setupLoaderAccessSilent,
@@ -89,13 +91,10 @@ import {
89
91
  RouterRegistry,
90
92
  nextRouterAutoId,
91
93
  } from "./router/router-registry.js";
94
+ import type { RangoOptions, RootLayoutProps } from "./router/router-options.js";
92
95
  import type {
93
- RSCRouterOptions,
94
- RootLayoutProps,
95
- } from "./router/router-options.js";
96
- import type {
97
- RSCRouter,
98
- RSCRouterInternal,
96
+ Rango,
97
+ RangoInternal,
99
98
  RouterRequestInput,
100
99
  } from "./router/router-interfaces.js";
101
100
 
@@ -114,25 +113,26 @@ import {
114
113
  // Re-export public types and values from extracted modules
115
114
  export { RSC_ROUTER_BRAND, RouterRegistry } from "./router/router-registry.js";
116
115
  export type {
117
- RSCRouterOptions,
116
+ RangoOptions,
118
117
  RootLayoutProps,
119
118
  SSRStreamMode,
120
119
  SSROptions,
121
120
  ResolveStreamingContext,
122
121
  } from "./router/router-options.js";
123
122
  export type {
124
- RSCRouter,
125
- RSCRouterInternal,
123
+ Rango,
124
+ RangoInternal,
126
125
  RouterRequestInput,
127
126
  } from "./router/router-interfaces.js";
128
127
  export { toInternal } from "./router/router-interfaces.js";
129
128
 
130
129
  export function createRouter<TEnv = any>(
131
- options: RSCRouterOptions<TEnv> = {},
132
- ): RSCRouter<TEnv, {}> {
130
+ options: RangoOptions<TEnv> = {},
131
+ ): Rango<TEnv, {}> {
133
132
  const {
134
133
  id: userProvidedId,
135
134
  $$id: injectedId,
135
+ basename: basenameOption,
136
136
  debugPerformance = false,
137
137
  document: documentOption,
138
138
  defaultErrorBoundary,
@@ -147,7 +147,7 @@ export function createRouter<TEnv = any>(
147
147
  $$sourceFile: injectedSourceFile,
148
148
  nonce,
149
149
  version,
150
- prefetchCacheControl: prefetchCacheControlOption,
150
+ prefetchCacheTTL: prefetchCacheTTLOption,
151
151
  warmup: warmupOption,
152
152
  allowDebugManifest: allowDebugManifestOption = false,
153
153
  telemetry: telemetrySink,
@@ -156,8 +156,24 @@ export function createRouter<TEnv = any>(
156
156
  timeouts: timeoutsOption,
157
157
  onTimeout,
158
158
  originCheck: originCheckOption,
159
+ viewTransition: viewTransitionOption = "auto",
160
+ debugCacheSignal: debugCacheSignalOption = false,
159
161
  } = options;
160
162
 
163
+ // Debug cache signal gate (DEVELOPMENT/TEST ONLY). Enabled by the
164
+ // debugCacheSignal option OR the RANGO_TEST_SIGNALS=1 env flag. When off,
165
+ // no X-Rango-Cache header is emitted and output is byte-identical.
166
+ const cacheSignalEnabled =
167
+ debugCacheSignalOption ||
168
+ (typeof process !== "undefined" &&
169
+ (process as { env?: Record<string, string | undefined> }).env
170
+ ?.RANGO_TEST_SIGNALS === "1");
171
+
172
+ // Normalize basename: ensure leading slash, strip trailing slash.
173
+ // A bare "/" is equivalent to no basename. Shared with the testing
174
+ // primitives via normalizeBasename so they can never drift.
175
+ const basename = normalizeBasename(basenameOption);
176
+
161
177
  // Resolve telemetry sink (no-op when not configured)
162
178
  const telemetry = resolveSink(telemetrySink);
163
179
 
@@ -200,11 +216,17 @@ export function createRouter<TEnv = any>(
200
216
  const routerId =
201
217
  userProvidedId ?? injectedId ?? `router_${nextRouterAutoId()}`;
202
218
 
203
- // Resolve prefetch cache control (default: 'private, max-age=300')
204
- const prefetchCacheControl =
205
- prefetchCacheControlOption !== undefined
206
- ? prefetchCacheControlOption
207
- : "private, max-age=300";
219
+ // Resolve prefetch cache TTL (default: 300 seconds / 5 minutes)
220
+ // Clamp to a non-negative integer for valid Cache-Control max-age.
221
+ const rawTTL =
222
+ prefetchCacheTTLOption !== undefined ? prefetchCacheTTLOption : 300;
223
+ const prefetchCacheTTLSeconds =
224
+ rawTTL === false ? 0 : Math.max(0, Math.floor(rawTTL));
225
+ const prefetchCacheTTL = prefetchCacheTTLSeconds * 1000;
226
+ const prefetchCacheControl: string | false =
227
+ prefetchCacheTTLSeconds === 0
228
+ ? false
229
+ : `private, max-age=${prefetchCacheTTLSeconds}`;
208
230
 
209
231
  // Resolve warmup enabled flag (default: true)
210
232
  const warmupEnabled = warmupOption !== false;
@@ -357,8 +379,18 @@ export function createRouter<TEnv = any>(
357
379
  return precomputedByPrefix;
358
380
  }
359
381
 
360
- // Wrapper to pass debugPerformance to external createMetricsStore
361
- const getMetricsStore = () => createMetricsStore(debugPerformance);
382
+ // Wrapper to pass debugPerformance to external createMetricsStore.
383
+ // Also checks per-request flag set by ctx.debugPerformance() in middleware.
384
+ const getMetricsStore = () => {
385
+ const reqCtx = _getRequestContext();
386
+ const enabled = debugPerformance || !!reqCtx?._debugPerformance;
387
+ if (!enabled) return undefined;
388
+ if (!reqCtx) {
389
+ return createMetricsStore(true);
390
+ }
391
+ reqCtx._metricsStore ??= createMetricsStore(true);
392
+ return reqCtx._metricsStore;
393
+ };
362
394
 
363
395
  // Wrapper to pass defaults to error/notFound boundary finders
364
396
  const findNearestErrorBoundary = (entry: EntryData | null) =>
@@ -510,7 +542,9 @@ export function createRouter<TEnv = any>(
510
542
  trackHandler,
511
543
  findNearestErrorBoundary,
512
544
  findNearestNotFoundBoundary,
545
+ notFoundComponent: notFound,
513
546
  callOnError,
547
+ viewTransitionDefault: viewTransitionOption,
514
548
  };
515
549
 
516
550
  // Match API dependencies
@@ -544,6 +578,7 @@ export function createRouter<TEnv = any>(
544
578
  mergedRouteMap,
545
579
  nextMountIndex: () => mountIndex++,
546
580
  getPrecomputedByPrefix,
581
+ routerId,
547
582
  };
548
583
 
549
584
  function evaluateLazyEntry(entry: RouteEntry<TEnv>): void {
@@ -597,6 +632,8 @@ export function createRouter<TEnv = any>(
597
632
  params: Record<string, string>,
598
633
  buildVars?: Record<string, any>,
599
634
  isPassthroughRoute?: boolean,
635
+ buildEnv?: TEnv,
636
+ devMode?: boolean,
600
637
  ) {
601
638
  return _matchForPrerender(
602
639
  pathname,
@@ -604,6 +641,8 @@ export function createRouter<TEnv = any>(
604
641
  prerenderDeps,
605
642
  buildVars,
606
643
  isPassthroughRoute,
644
+ buildEnv,
645
+ devMode,
607
646
  );
608
647
  }
609
648
 
@@ -611,12 +650,16 @@ export function createRouter<TEnv = any>(
611
650
  handler: Function,
612
651
  handlerId: string,
613
652
  routeName?: string,
653
+ buildEnv?: TEnv,
654
+ devMode?: boolean,
614
655
  ) {
615
656
  return _renderStaticSegment<TEnv>(
616
657
  handler,
617
658
  handlerId,
618
659
  mergedRouteMap,
619
660
  routeName,
661
+ buildEnv,
662
+ devMode,
620
663
  );
621
664
  }
622
665
 
@@ -629,6 +672,7 @@ export function createRouter<TEnv = any>(
629
672
  findMatch,
630
673
  findInterceptForRoute,
631
674
  telemetry: telemetrySink,
675
+ cacheSignalEnabled,
632
676
  });
633
677
 
634
678
  const { match, matchPartial, matchError, previewMatch } = matchHandlers;
@@ -638,11 +682,18 @@ export function createRouter<TEnv = any>(
638
682
  * The type system tracks accumulated routes through the builder chain
639
683
  * Initial TRoutes is {} (empty) to avoid poisoning accumulated types with Record<string, string>
640
684
  */
641
- const router: RSCRouterInternal<TEnv, {}> = {
685
+ const router: RangoInternal<TEnv, {}> = {
642
686
  __brand: RSC_ROUTER_BRAND,
643
687
  id: routerId,
688
+ basename,
689
+
690
+ routes(patternsOrBuilder: UrlPatterns<TEnv> | UrlBuilder<TEnv>): any {
691
+ // Wrap builder functions in urls() automatically
692
+ const urlPatterns: UrlPatterns<TEnv> =
693
+ typeof patternsOrBuilder === "function"
694
+ ? (urls(patternsOrBuilder) as UrlPatterns<TEnv>)
695
+ : patternsOrBuilder;
644
696
 
645
- routes(urlPatterns: UrlPatterns<TEnv>): any {
646
697
  // Store reference for runtime manifest generation
647
698
  storedUrlPatterns = urlPatterns;
648
699
  const currentMountIndex = mountIndex++;
@@ -673,13 +724,13 @@ export function createRouter<TEnv = any>(
673
724
  errorBoundary: [],
674
725
  notFoundBoundary: [],
675
726
  layout: [],
676
- parallel: [],
727
+ parallel: {},
677
728
  intercept: [],
678
729
  loader: [],
679
730
  };
680
731
 
681
732
  let handlerResult: AllUseItems[] = [];
682
- RSCRouterContext.run(
733
+ RangoContext.run(
683
734
  {
684
735
  manifest,
685
736
  patterns: routePatterns,
@@ -690,6 +741,10 @@ export function createRouter<TEnv = any>(
690
741
  counters: {},
691
742
  mountIndex: currentMountIndex,
692
743
  cacheProfiles: resolvedCacheProfiles,
744
+ // basename sets the initial URL prefix so all path() patterns
745
+ // are registered with the prefix (e.g. "/admin" + "/users" = "/admin/users").
746
+ // No namePrefix — route names stay unprefixed.
747
+ ...(basename ? { urlPrefix: basename } : {}),
693
748
  },
694
749
  () => {
695
750
  handlerResult = urlPatterns.handler() as AllUseItems[];
@@ -709,7 +764,7 @@ export function createRouter<TEnv = any>(
709
764
  if (entry.type === "route" && entry.isPrerender) {
710
765
  if (!prerenderRouteKeys) prerenderRouteKeys = new Set();
711
766
  prerenderRouteKeys.add(name);
712
- if (entry.prerenderDef?.options?.passthrough === true) {
767
+ if (entry.isPassthrough === true) {
713
768
  if (!passthroughRouteKeys) passthroughRouteKeys = new Set();
714
769
  passthroughRouteKeys.add(name);
715
770
  }
@@ -735,6 +790,7 @@ export function createRouter<TEnv = any>(
735
790
  trailingSlash: trailingSlashConfig,
736
791
  handler: urlPatterns.handler,
737
792
  mountIndex: currentMountIndex,
793
+ routerId,
738
794
  cacheProfiles: resolvedCacheProfiles,
739
795
  ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
740
796
  ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
@@ -754,6 +810,7 @@ export function createRouter<TEnv = any>(
754
810
  trailingSlash: trailingSlashConfig,
755
811
  handler: urlPatterns.handler,
756
812
  mountIndex: currentMountIndex,
813
+ routerId,
757
814
  cacheProfiles: resolvedCacheProfiles,
758
815
  ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
759
816
  ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
@@ -797,6 +854,7 @@ export function createRouter<TEnv = any>(
797
854
  trailingSlash: trailingSlashConfig,
798
855
  handler: urlPatterns.handler,
799
856
  mountIndex: mountIndex++,
857
+ routerId,
800
858
  // Lazy evaluation fields
801
859
  lazy: true,
802
860
  lazyPatterns: lazyInclude.patterns,
@@ -835,8 +893,18 @@ export function createRouter<TEnv = any>(
835
893
  patternOrMiddleware: string | MiddlewareFn<TEnv>,
836
894
  middleware?: MiddlewareFn<TEnv>,
837
895
  ): any {
838
- // Global middleware - no mount prefix
839
- addMiddleware(patternOrMiddleware, middleware, null);
896
+ // Auto-prefix pattern with basename so router-level middleware
897
+ // patterns are router-relative (e.g. "/users/*" matches "/app/users/*").
898
+ if (basename && typeof patternOrMiddleware === "string") {
899
+ const pattern = patternOrMiddleware;
900
+ const prefixed =
901
+ pattern === "/*" || pattern === "*"
902
+ ? `${basename}/*`
903
+ : `${basename}${pattern}`;
904
+ addMiddleware(prefixed, middleware, null);
905
+ } else {
906
+ addMiddleware(patternOrMiddleware, middleware, null);
907
+ }
840
908
  return router;
841
909
  },
842
910
 
@@ -869,12 +937,16 @@ export function createRouter<TEnv = any>(
869
937
  // Expose resolved cache profiles for per-request resolution
870
938
  cacheProfiles: resolvedCacheProfiles,
871
939
 
872
- // Expose prefetch cache control for RSC handler
940
+ // Expose prefetch cache settings
873
941
  prefetchCacheControl,
942
+ prefetchCacheTTL,
874
943
 
875
944
  // Expose warmup enabled flag for handler and client
876
945
  warmupEnabled,
877
946
 
947
+ // Expose router-wide performance debugging for request-level metrics setup
948
+ debugPerformance,
949
+
878
950
  // Expose debug manifest flag for handler
879
951
  allowDebugManifest: allowDebugManifestOption,
880
952
 
@@ -933,6 +1005,16 @@ export function createRouter<TEnv = any>(
933
1005
  // Expose source file for per-router type generation
934
1006
  __sourceFile,
935
1007
 
1008
+ // Expose basename for runtime manifest generation
1009
+ __basename: basename,
1010
+
1011
+ // Expose router-level boundary defaults for build-time clientChunks
1012
+ // discovery (so a "use client" default boundary lands in app-fallback).
1013
+ // These are createRouter options, never pushed onto EntryData.
1014
+ __defaultErrorBoundary: defaultErrorBoundary,
1015
+ __defaultNotFoundBoundary: defaultNotFoundBoundary,
1016
+ __notFound: notFound,
1017
+
936
1018
  // RSC request handler (lazily created on first call)
937
1019
  fetch: (() => {
938
1020
  // Handler is created on first call and reused
@@ -966,6 +1048,10 @@ export function createRouter<TEnv = any>(
966
1048
  };
967
1049
  })(),
968
1050
 
1051
+ // Low-level route matching for request classification
1052
+ findMatch: (pathname: string, metricsStore?: any) =>
1053
+ findMatch(pathname, metricsStore),
1054
+
969
1055
  // Debug utility for manifest inspection
970
1056
  debugManifest: () => buildDebugManifest<TEnv>(routesEntries),
971
1057
  };
@@ -974,8 +1060,10 @@ export function createRouter<TEnv = any>(
974
1060
  RouterRegistry.set(routerId, router);
975
1061
 
976
1062
  // If urls option was provided, auto-register them
977
- if (urlsOption) {
978
- return router.routes(urlsOption) as RSCRouter<TEnv, {}>;
1063
+ if (typeof urlsOption === "function") {
1064
+ return router.routes(urlsOption) as Rango<TEnv, {}>;
1065
+ } else if (urlsOption) {
1066
+ return router.routes(urlsOption) as Rango<TEnv, {}>;
979
1067
  }
980
1068
 
981
1069
  return router;
@@ -6,14 +6,14 @@
6
6
  * RSC rendering) so they can be standalone modules without closure coupling.
7
7
  */
8
8
 
9
- import type { RSCRouterInternal } from "../router/router-interfaces.js";
9
+ import type { RangoInternal } from "../router/router-interfaces.js";
10
10
  import type { ErrorPhase } from "../types.js";
11
11
  import type { InvokeOnErrorContext } from "../router/error-handling.js";
12
12
  import type { RSCDependencies, LoadSSRModule } from "./types.js";
13
13
  import type { SSRStreamMode } from "../router/router-options.js";
14
14
 
15
15
  export interface HandlerContext<TEnv = unknown> {
16
- router: RSCRouterInternal<TEnv, any>;
16
+ router: RangoInternal<TEnv, any>;
17
17
  version: string;
18
18
  renderToReadableStream: RSCDependencies["renderToReadableStream"];
19
19
  decodeReply: RSCDependencies["decodeReply"];