@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
@@ -25,10 +25,12 @@ import { validateRedirectOrigin } from "./validate-redirect-origin.js";
25
25
  import {
26
26
  extractRscHeaderUrl,
27
27
  emptyResponse,
28
+ handleReloadHeader,
28
29
  teeWithCompletion,
29
30
  } from "./response-adapter.js";
30
31
  import { mergeLocationState } from "./history-state.js";
31
32
  import { classifyActionOutcome } from "./action-coordinator.js";
33
+ import { getAppVersion } from "./app-version.js";
32
34
 
33
35
  // Polyfill Symbol.dispose/asyncDispose for Safari and older browsers
34
36
  if (typeof Symbol.dispose === "undefined") {
@@ -43,8 +45,6 @@ if (typeof Symbol.asyncDispose === "undefined") {
43
45
  */
44
46
  export interface ServerActionBridgeConfigWithController extends ServerActionBridgeConfig {
45
47
  eventController: EventController;
46
- /** RSC version from initial payload metadata */
47
- version?: string;
48
48
  /** Callback to trigger SPA navigation (for action redirects) */
49
49
  onNavigate?: (
50
50
  url: string,
@@ -75,10 +75,23 @@ export function createServerActionBridge(
75
75
  deps,
76
76
  onUpdate,
77
77
  renderSegments,
78
- version,
79
78
  onNavigate,
80
79
  } = config;
81
80
 
81
+ // SPA-navigate when onNavigate is set, else hard-reload. state is omitted (not
82
+ // passed as undefined) to match the header path's prior call shape.
83
+ async function dispatchRedirect(url: string, state?: unknown): Promise<void> {
84
+ if (onNavigate) {
85
+ await onNavigate(url, {
86
+ ...(state !== undefined ? { state } : {}),
87
+ replace: true,
88
+ _skipCache: true,
89
+ });
90
+ } else {
91
+ window.location.href = url;
92
+ }
93
+ }
94
+
82
95
  let isRegistered = false;
83
96
 
84
97
  const fetchPartialUpdate = createPartialUpdater({
@@ -86,7 +99,7 @@ export function createServerActionBridge(
86
99
  client,
87
100
  onUpdate,
88
101
  renderSegments,
89
- version,
102
+ getVersion: getAppVersion,
90
103
  });
91
104
 
92
105
  /**
@@ -165,9 +178,15 @@ export function createServerActionBridge(
165
178
  segmentState.currentSegmentIds.join(","),
166
179
  );
167
180
  // Add version param for version mismatch detection
181
+ const version = getAppVersion();
168
182
  if (version) {
169
183
  url.searchParams.set("_rsc_v", version);
170
184
  }
185
+ // Add router ID for app switch detection
186
+ const rid = store.getRouterId?.();
187
+ if (rid) {
188
+ url.searchParams.set("_rsc_rid", rid);
189
+ }
171
190
 
172
191
  // Encode arguments
173
192
  const encodedBody = await deps.encodeReply(args, { temporaryReferences });
@@ -206,7 +225,6 @@ export function createServerActionBridge(
206
225
  "rsc-action": id,
207
226
  "X-RSC-Router-Client-Path": segmentState.currentUrl,
208
227
  ...(tx && { "X-RSC-Router-Request-Id": tx.requestId }),
209
- // Send intercept source URL so server can maintain intercept context
210
228
  ...(interceptSourceUrl && {
211
229
  "X-RSC-Router-Intercept-Source": interceptSourceUrl,
212
230
  }),
@@ -219,18 +237,12 @@ export function createServerActionBridge(
219
237
  handle.signal.removeEventListener("abort", onHandleAbort);
220
238
 
221
239
  // Check for version mismatch - server wants us to reload
222
- const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
223
- if (reload === "blocked") {
224
- resolveStreamComplete();
225
- return emptyResponse();
226
- }
227
- if (reload) {
228
- log("version mismatch on action, reloading", {
229
- reloadUrl: reload.url,
230
- });
231
- window.location.href = reload.url;
232
- return new Promise<Response>(() => {});
233
- }
240
+ const reloadResult = handleReloadHeader(response, {
241
+ onBlocked: resolveStreamComplete,
242
+ onReload: (url) =>
243
+ log("version mismatch on action, reloading", { reloadUrl: url }),
244
+ });
245
+ if (reloadResult) return reloadResult;
234
246
 
235
247
  // Simple redirect from action (no state, no RSC payload).
236
248
  // Short-circuits before createFromFetch — no Flight deserialization needed.
@@ -240,14 +252,7 @@ export function createServerActionBridge(
240
252
  if (redirect && redirect !== "blocked" && !handle.signal.aborted) {
241
253
  log("action simple redirect", { url: redirect.url });
242
254
  handle.complete(undefined);
243
- if (onNavigate) {
244
- await onNavigate(redirect.url, {
245
- replace: true,
246
- _skipCache: true,
247
- });
248
- } else {
249
- window.location.href = redirect.url;
250
- }
255
+ await dispatchRedirect(redirect.url);
251
256
  return new Promise<Response>(() => {});
252
257
  }
253
258
  if (redirect === "blocked") {
@@ -309,7 +314,6 @@ export function createServerActionBridge(
309
314
  matchedCount: payload.metadata?.matched?.length ?? 0,
310
315
  diffCount: payload.metadata?.diff?.length ?? 0,
311
316
  });
312
-
313
317
  // Guard: if the action was aborted while streaming (e.g., user navigated
314
318
  // away or abortAllActions fired), bail out before any reconcile/render/cache
315
319
  // writes to avoid overwriting the current UI with stale action results.
@@ -337,18 +341,9 @@ export function createServerActionBridge(
337
341
  handle.complete(returnValue?.data);
338
342
  return returnValue?.data;
339
343
  }
340
- const redirectState = metadata.locationState;
341
344
  log("action redirect", { url: redirectUrl });
342
345
  handle.complete(returnValue?.data);
343
- if (onNavigate) {
344
- await onNavigate(redirectUrl, {
345
- state: redirectState,
346
- replace: true,
347
- _skipCache: true,
348
- });
349
- } else {
350
- window.location.href = redirectUrl;
351
- }
346
+ await dispatchRedirect(redirectUrl, metadata.locationState);
352
347
  return returnValue?.data;
353
348
  }
354
349
 
@@ -32,10 +32,19 @@ export type HandleData = Record<string, Record<string, unknown[]>>;
32
32
  export interface RscMetadata {
33
33
  pathname: string;
34
34
  segments: ResolvedSegment[];
35
+ /** Router instance ID. When this changes between navigations, the client
36
+ * forces a full tree replacement (app switch via host router). */
37
+ routerId?: string;
35
38
  isPartial?: boolean;
36
39
  isError?: boolean;
37
40
  matched?: string[];
38
41
  diff?: string[];
42
+ /**
43
+ * All segment ids re-resolved on the server, including null-component
44
+ * ones excluded from `segments`/`diff`. Drives client-side handle-bucket
45
+ * cleanup. Superset of `diff`. See MatchResult.resolvedIds.
46
+ */
47
+ resolvedIds?: string[];
39
48
  /** Merged route params from the matched route */
40
49
  params?: Record<string, string>;
41
50
  /**
@@ -55,6 +64,11 @@ export interface RscMetadata {
55
64
  * Used to detect version mismatches after HMR/deployment.
56
65
  */
57
66
  version?: string;
67
+ /**
68
+ * TTL in milliseconds for the client-side in-memory prefetch cache.
69
+ * Sent on initial render so the browser can configure its cache duration.
70
+ */
71
+ prefetchCacheTTL?: number;
58
72
  /**
59
73
  * Theme configuration from router.
60
74
  * Included when theme is enabled in router config.
@@ -65,6 +79,8 @@ export interface RscMetadata {
65
79
  * Included when theme is enabled in router config.
66
80
  */
67
81
  initialTheme?: Theme;
82
+ /** URL prefix for all routes (from createRouter({ basename })). */
83
+ basename?: string;
68
84
  /** Whether connection warmup is enabled */
69
85
  warmupEnabled?: boolean;
70
86
  /** Server-side redirect with optional state (for partial requests) */
@@ -210,6 +226,15 @@ export interface SegmentState {
210
226
  export interface NavigationUpdate {
211
227
  root: ReactNode | Promise<ReactNode>;
212
228
  metadata: RscMetadata;
229
+ /** Scroll behavior to apply after React commits this update */
230
+ scroll?: {
231
+ /** For back/forward: restore saved position */
232
+ restore?: boolean;
233
+ /** Set to false to disable scrolling entirely */
234
+ enabled?: boolean;
235
+ /** Function to check if streaming is in progress */
236
+ isStreaming?: () => boolean;
237
+ };
213
238
  }
214
239
 
215
240
  /**
@@ -227,6 +252,25 @@ export type HistoryState =
227
252
  export interface NavigateOptions {
228
253
  replace?: boolean;
229
254
  scroll?: boolean;
255
+ /**
256
+ * Whether to revalidate server data on navigation.
257
+ * Set to `false` to skip the RSC server fetch and only update the URL.
258
+ *
259
+ * Only takes effect when the pathname stays the same (search param / hash changes).
260
+ * If the pathname changes, this option is ignored and a full navigation occurs.
261
+ *
262
+ * All location-aware hooks (`useSearchParams`, `useNavigation`, etc.) still update.
263
+ * Server components do not re-render.
264
+ *
265
+ * @default true
266
+ *
267
+ * @example
268
+ * ```tsx
269
+ * router.push("/products?color=blue", { revalidate: false });
270
+ * router.replace("/products?page=3", { revalidate: false });
271
+ * ```
272
+ */
273
+ revalidate?: boolean;
230
274
  /**
231
275
  * State to pass to history.pushState/replaceState
232
276
  * Accessible via useLocationState() hook.
@@ -308,7 +352,13 @@ export type ReadonlyURLSearchParams = Omit<
308
352
  export interface RscBrowserDependencies {
309
353
  createFromFetch: <T>(
310
354
  response: Promise<Response>,
311
- options?: { temporaryReferences?: any },
355
+ options?: {
356
+ temporaryReferences?: any;
357
+ findSourceMapURL?: (
358
+ filename: string,
359
+ environmentName: string,
360
+ ) => string | null;
361
+ },
312
362
  ) => Promise<T>;
313
363
  createFromReadableStream: <T>(stream: ReadableStream) => Promise<T>;
314
364
  encodeReply: (
@@ -370,16 +420,25 @@ export interface NavigationStore {
370
420
  segments: ResolvedSegment[],
371
421
  handleData?: HandleData,
372
422
  ): void;
373
- getCachedSegments(
374
- historyKey: string,
375
- ):
376
- | { segments: ResolvedSegment[]; stale: boolean; handleData?: HandleData }
423
+ getCachedSegments(historyKey: string):
424
+ | {
425
+ segments: ResolvedSegment[];
426
+ stale: boolean;
427
+ handleData?: HandleData;
428
+ routerId?: string;
429
+ }
377
430
  | undefined;
378
431
  hasHistoryCache(historyKey: string): boolean;
379
432
  updateCacheHandleData(historyKey: string, handleData: HandleData): void;
380
433
  markCacheAsStale(): void;
381
434
  markCacheAsStaleAndBroadcast(): void;
382
435
  clearHistoryCache(): void;
436
+ /**
437
+ * Clear this tab's nav + prefetch caches without broadcasting or rotating
438
+ * shared state. Intended for app-switch transitions that affect only this
439
+ * tab's session.
440
+ */
441
+ clearHistoryCacheLocal(): void;
383
442
  broadcastCacheInvalidation(): void;
384
443
 
385
444
  // Cross-tab refresh callback (set by navigation bridge)
@@ -389,6 +448,10 @@ export interface NavigationStore {
389
448
  getInterceptSourceUrl(): string | null;
390
449
  setInterceptSourceUrl(url: string | null): void;
391
450
 
451
+ // Router identity tracking (for cross-app navigation detection)
452
+ getRouterId?(): string | undefined;
453
+ setRouterId?(id: string): void;
454
+
392
455
  // UI update notifications
393
456
  onUpdate(callback: UpdateSubscriber): () => void;
394
457
  emitUpdate(update: NavigationUpdate): void;
@@ -419,6 +482,8 @@ export interface FetchPartialOptions {
419
482
  interceptSourceUrl?: string;
420
483
  /** RSC version for cache invalidation detection */
421
484
  version?: string;
485
+ /** Current router ID — server detects app switch and returns full response */
486
+ routerId?: string;
422
487
  /** If true, this is an HMR refetch - server should invalidate manifest cache */
423
488
  hmr?: boolean;
424
489
  }
@@ -487,6 +552,17 @@ export interface NavigationBridge {
487
552
  refresh(): Promise<void>;
488
553
  handlePopstate(): Promise<void>;
489
554
  registerLinkInterception(): () => void;
555
+ /** Current RSC version (live, reflects the latest updateVersion). */
556
+ getVersion(): string | undefined;
557
+ /** Update the RSC version (e.g. after HMR). Clears prefetch cache. */
558
+ updateVersion(newVersion: string): void;
559
+ /**
560
+ * Replace the active app-shell snapshot (rootLayout, basename, version)
561
+ * atomically. Used on cross-app navigations when the response's routerId
562
+ * indicates the user entered a different app. Theme, warmup, and prefetch
563
+ * TTL are document-lifetime and not part of the shell.
564
+ */
565
+ updateAppShell(next: import("./app-shell.js").AppShell): void;
490
566
  }
491
567
 
492
568
  /**
@@ -0,0 +1,107 @@
1
+ // Collect the `"use client"` client-reference keys reachable from an error /
2
+ // notFound boundary registration, for routing them into the dedicated
3
+ // `app-fallback` chunk (see vite/utils/client-chunks.ts).
4
+ //
5
+ // A boundary registration is not always a bare client element. The common,
6
+ // load-bearing pattern wraps the client boundary in providers a thrown handler
7
+ // needs (the layout that would normally supply them did not mount):
8
+ //
9
+ // defaultErrorBoundary: ({ error }) => (
10
+ // <FallbackIntl locales={...}>
11
+ // <ThemedError error={error} /> // <- the real "use client" boundary
12
+ // </FallbackIntl>
13
+ // )
14
+ //
15
+ // So the value may be (a) a handler FUNCTION returning a tree, or (b) an element
16
+ // tree with the client boundary nested below server wrappers. We:
17
+ // 1. If it's a function, CALL it with synthetic props to get the returned tree.
18
+ // This only constructs JSX — the inner components are element `type`s, never
19
+ // invoked — so no hooks run. Guarded: a boundary that needs a real render
20
+ // context (request globals, etc.) throws and is skipped (graceful: it simply
21
+ // stays on the default grouping, as before).
22
+ // 2. Walk the resulting tree and report every element whose `.type` is a
23
+ // plugin-rsc client reference.
24
+ //
25
+ // Limit: a boundary that *conditionally* renders different client components based
26
+ // on the runtime error cannot be resolved statically — only the branch taken with
27
+ // the synthetic error is seen. Such cases fall back to the default chunk; the
28
+ // custom `clientChunks` function is the escape hatch.
29
+
30
+ const CLIENT_REF = Symbol.for("react.client.reference");
31
+ const MAX_DEPTH = 40;
32
+
33
+ // Synthetic props covering the error-boundary (`{ error, reset }`) and notFound
34
+ // (`{ pathname }`) handler shapes. The handler destructures what it needs.
35
+ const SYNTHETIC_PROPS = {
36
+ error: new Error("rango: build-time fallback-chunk discovery"),
37
+ reset: () => {},
38
+ pathname: "/",
39
+ info: { componentStack: "" },
40
+ };
41
+
42
+ interface MaybeElement {
43
+ type?: { $$typeof?: symbol; $$id?: string };
44
+ props?: Record<string, unknown>;
45
+ }
46
+
47
+ function isReactNodeLike(v: unknown): boolean {
48
+ return (
49
+ Array.isArray(v) ||
50
+ (typeof v === "object" && v !== null && "$$typeof" in (v as object))
51
+ );
52
+ }
53
+
54
+ function walkElementTree(
55
+ node: unknown,
56
+ report: (refKey: string) => void,
57
+ depth: number,
58
+ ): void {
59
+ if (node == null || depth > MAX_DEPTH) return;
60
+ if (Array.isArray(node)) {
61
+ for (const child of node) walkElementTree(child, report, depth + 1);
62
+ return;
63
+ }
64
+ if (typeof node !== "object") return;
65
+
66
+ const el = node as MaybeElement;
67
+ const type = el.type;
68
+ if (type?.$$typeof === CLIENT_REF && typeof type.$$id === "string") {
69
+ // $$id is `<referenceKey>#<exportName>` in build mode — keep the referenceKey.
70
+ report(type.$$id.split("#")[0]);
71
+ }
72
+
73
+ const props = el.props;
74
+ if (props && typeof props === "object") {
75
+ // Children are always nodes; other props are followed only when they look
76
+ // like React nodes (slots/icons), never arbitrary data objects.
77
+ walkElementTree(props.children, report, depth + 1);
78
+ for (const key in props) {
79
+ if (key === "children") continue;
80
+ const value = props[key];
81
+ if (isReactNodeLike(value)) walkElementTree(value, report, depth + 1);
82
+ }
83
+ }
84
+ }
85
+
86
+ /**
87
+ * Report every `"use client"` client-reference key reachable from a single
88
+ * error/notFound boundary registration (handler function or element tree).
89
+ */
90
+ export function collectFallbackClientRefs(
91
+ boundary: unknown,
92
+ report: (refKey: string) => void,
93
+ ): void {
94
+ try {
95
+ let node = boundary;
96
+ if (typeof node === "function") {
97
+ node = (node as (props: unknown) => unknown)(SYNTHETIC_PROPS);
98
+ }
99
+ walkElementTree(node, report, 0);
100
+ } catch {
101
+ // The boundary needs a real render context (request globals, hooks at the
102
+ // top level) or its tree has hostile getters. Its client refs can't be
103
+ // resolved statically — skip. It stays on the default grouping (no
104
+ // regression vs. not collecting), and the custom clientChunks fn is the
105
+ // escape hatch for such cases.
106
+ }
107
+ }
@@ -11,11 +11,12 @@
11
11
  import type { UrlPatterns } from "../urls.js";
12
12
  import type { AllUseItems } from "../route-types.js";
13
13
  import { extractStaticPrefix } from "../router/pattern-matching.js";
14
- import { RSCRouterContext, runWithPrefixes } from "../server/context.js";
14
+ import { RangoContext, runWithPrefixes } from "../server/context.js";
15
15
  import type { EntryData, TrackedInclude } from "../server/context.js";
16
16
  import type { TrailingSlashMode } from "../types.js";
17
17
  import { createRouteHelpers } from "../route-definition.js";
18
18
  import MapRootLayout from "../server/root-layout.js";
19
+ import { collectFallbackClientRefs } from "./collect-fallback-refs.js";
19
20
 
20
21
  /**
21
22
  * Node in the prefix tree
@@ -45,7 +46,7 @@ export interface GeneratedManifest {
45
46
  routeTrailingSlash?: Record<string, string>;
46
47
  /** Route names using Prerender (for dev-mode Node.js delegation) */
47
48
  prerenderRoutes?: string[];
48
- /** Route names with passthrough: true (handler kept in bundle for live fallback) */
49
+ /** Route names wrapped with Passthrough() (live handler for runtime fallback) */
49
50
  passthroughRoutes?: string[];
50
51
  /** Route name → response type for non-RSC routes */
51
52
  responseTypeRoutes?: Record<string, string>;
@@ -57,6 +58,26 @@ export interface GeneratedManifest {
57
58
  * Build prefix tree node by running the patterns with proper context.
58
59
  * Uses a visited set to detect circular includes and prevent infinite recursion.
59
60
  */
61
+ // Merge tracked nested includes into `target`. Multiple includes can share a
62
+ // fullPrefix (e.g. include("/", a), include("/", b)) — concat their routes and
63
+ // Object.assign children rather than overwrite.
64
+ function mergeIncludeNodes(
65
+ target: Record<string, PrefixTreeNode>,
66
+ includes: TrackedInclude[],
67
+ buildChild: (include: TrackedInclude) => PrefixTreeNode,
68
+ ): void {
69
+ for (const include of includes) {
70
+ const node = buildChild(include);
71
+ const existing = target[include.fullPrefix];
72
+ if (existing) {
73
+ existing.routes.push(...node.routes);
74
+ Object.assign(existing.children, node.children);
75
+ } else {
76
+ target[include.fullPrefix] = node;
77
+ }
78
+ }
79
+ }
80
+
60
81
  function buildPrefixTreeNode(
61
82
  urlPrefix: string,
62
83
  namePrefix: string | undefined,
@@ -93,7 +114,7 @@ function buildPrefixTreeNode(
93
114
  const searchSchemasMap = new Map<string, Record<string, string>>();
94
115
  const trackedIncludes: TrackedInclude[] = [];
95
116
 
96
- RSCRouterContext.run(
117
+ RangoContext.run(
97
118
  {
98
119
  manifest,
99
120
  patterns: patternsMap,
@@ -150,10 +171,7 @@ function buildPrefixTreeNode(
150
171
  if (prerenderDefs && entry.prerenderDef) {
151
172
  prerenderDefs[name] = entry.prerenderDef;
152
173
  }
153
- if (
154
- passthroughRoutes &&
155
- entry.prerenderDef?.options?.passthrough === true
156
- ) {
174
+ if (passthroughRoutes && entry.isPassthrough === true) {
157
175
  passthroughRoutes.push(name);
158
176
  }
159
177
  }
@@ -169,13 +187,9 @@ function buildPrefixTreeNode(
169
187
  }
170
188
  }
171
189
 
172
- // Build children from tracked nested includes.
173
- // Multiple includes can share the same fullPrefix (e.g., include("/", patternsA),
174
- // include("/", patternsB)). Merge their routes instead of overwriting.
175
190
  const children: Record<string, PrefixTreeNode> = {};
176
-
177
- for (const include of trackedIncludes) {
178
- const childNode = buildPrefixTreeNode(
191
+ mergeIncludeNodes(children, trackedIncludes, (include) =>
192
+ buildPrefixTreeNode(
179
193
  include.fullPrefix,
180
194
  include.namePrefix,
181
195
  include.patterns as UrlPatterns<any>,
@@ -189,16 +203,8 @@ function buildPrefixTreeNode(
189
203
  passthroughRoutes,
190
204
  responseTypeRoutes,
191
205
  routeSearchSchemas,
192
- );
193
-
194
- const existing = children[include.fullPrefix];
195
- if (existing) {
196
- existing.routes.push(...childNode.routes);
197
- Object.assign(existing.children, childNode.children);
198
- } else {
199
- children[include.fullPrefix] = childNode;
200
- }
201
- }
206
+ ),
207
+ );
202
208
 
203
209
  // Remove from visited so sibling branches can reuse the same patterns
204
210
  // without false circular-include detection. Only ancestors in the current
@@ -285,6 +291,17 @@ export function generateManifest<TEnv>(
285
291
  export function generateManifestFull<TEnv>(
286
292
  urlpatterns: UrlPatterns<TEnv, any>,
287
293
  mountIndex: number = 0,
294
+ options?: {
295
+ urlPrefix?: string;
296
+ /**
297
+ * Called once per `"use client"` component registered as an
298
+ * errorBoundary/notFoundBoundary fallback, with its client-reference key
299
+ * (`$$id`). Lets the build collect fallback module ids for dedicated
300
+ * chunking without exposing the otherwise-discarded EntryData tree. The
301
+ * EntryData map built below is local; this is the only seam that surfaces it.
302
+ */
303
+ collectClientFallbackRef?: (refKey: string) => void;
304
+ },
288
305
  ): FullManifest {
289
306
  const routeManifest: Record<string, string> = {};
290
307
  const routeAncestry: Record<string, string[]> = {};
@@ -298,7 +315,7 @@ export function generateManifestFull<TEnv>(
298
315
  const searchSchemasMap = new Map<string, Record<string, string>>();
299
316
  const trackedIncludes: TrackedInclude[] = [];
300
317
 
301
- RSCRouterContext.run(
318
+ RangoContext.run(
302
319
  {
303
320
  manifest,
304
321
  patterns: patternsMap,
@@ -310,6 +327,8 @@ export function generateManifestFull<TEnv>(
310
327
  counters: {},
311
328
  mountIndex,
312
329
  trackedIncludes, // Enable include tracking
330
+ // basename sets the initial URL prefix for all path() registrations
331
+ ...(options?.urlPrefix ? { urlPrefix: options.urlPrefix } : {}),
313
332
  },
314
333
  () => {
315
334
  const helpers = createRouteHelpers();
@@ -320,6 +339,22 @@ export function generateManifestFull<TEnv>(
320
339
  },
321
340
  );
322
341
 
342
+ // Surface the "use client" components registered as error/notFound fallbacks
343
+ // (route-tree errorBoundary()/notFoundBoundary() helpers, stored on EntryData).
344
+ // The boundary may be a handler function and/or wrap the client boundary in
345
+ // server providers, so walk the whole tree (see collectFallbackClientRefs).
346
+ if (options?.collectClientFallbackRef) {
347
+ const report = options.collectClientFallbackRef;
348
+ const collect = (boundary: unknown[] | undefined) => {
349
+ for (const item of boundary ?? [])
350
+ collectFallbackClientRefs(item, report);
351
+ };
352
+ for (const entry of manifest.values()) {
353
+ collect(entry.errorBoundary);
354
+ collect(entry.notFoundBoundary);
355
+ }
356
+ }
357
+
323
358
  // Collect root-level routes and trailing slash config
324
359
  const routeTrailingSlash: Record<string, string> = {};
325
360
  for (const [name, pattern] of patternsMap.entries()) {
@@ -347,7 +382,7 @@ export function generateManifestFull<TEnv>(
347
382
  if (entry.prerenderDef) {
348
383
  prerenderDefs[name] = entry.prerenderDef;
349
384
  }
350
- if (entry.prerenderDef?.options?.passthrough === true) {
385
+ if (entry.isPassthrough === true) {
351
386
  passthroughRoutes.push(name);
352
387
  }
353
388
  }
@@ -356,12 +391,10 @@ export function generateManifestFull<TEnv>(
356
391
  }
357
392
  }
358
393
 
359
- // Build prefix tree from tracked includes (shared visited set for cycle detection).
360
- // Multiple includes can share the same fullPrefix (e.g., include("/", patternsA),
361
- // include("/", patternsB)). Merge their routes instead of overwriting.
394
+ // Shared visited set for cycle detection across all root-level includes.
362
395
  const visited = new Set<unknown>();
363
- for (const include of trackedIncludes) {
364
- const node = buildPrefixTreeNode(
396
+ mergeIncludeNodes(prefixTree, trackedIncludes, (include) =>
397
+ buildPrefixTreeNode(
365
398
  include.fullPrefix,
366
399
  include.namePrefix,
367
400
  include.patterns as UrlPatterns<any>,
@@ -375,16 +408,8 @@ export function generateManifestFull<TEnv>(
375
408
  passthroughRoutes,
376
409
  responseTypeRoutes,
377
410
  routeSearchSchemas,
378
- );
379
-
380
- const existing = prefixTree[include.fullPrefix];
381
- if (existing) {
382
- existing.routes.push(...node.routes);
383
- Object.assign(existing.children, node.children);
384
- } else {
385
- prefixTree[include.fullPrefix] = node;
386
- }
387
- }
411
+ ),
412
+ );
388
413
 
389
414
  return {
390
415
  prefixTree,
@@ -25,6 +25,9 @@ export {
25
25
  } from "./route-types/include-resolution.js";
26
26
  export {
27
27
  extractUrlsVariableFromRouter,
28
+ extractUrlsFromRouter,
29
+ extractBasenameFromRouter,
30
+ type UrlsExtractionResult,
28
31
  buildCombinedRouteMapForRouterFile,
29
32
  detectUnresolvableIncludes,
30
33
  detectUnresolvableIncludesForUrlsFile,
@@ -32,5 +35,7 @@ export {
32
35
  formatNestedRouterConflictError,
33
36
  findRouterFiles,
34
37
  writeCombinedRouteTypes,
38
+ genFileTsPath,
39
+ resolveSearchSchemas,
35
40
  } from "./route-types/router-processing.js";
36
41
  export { findUrlsVariableNames } from "./route-types/per-module-writer.js";
@@ -24,6 +24,8 @@ export {
24
24
 
25
25
  export { buildRouteTrie, type TrieNode, type TrieLeaf } from "./route-trie.js";
26
26
 
27
+ export { collectFallbackClientRefs } from "./collect-fallback-refs.js";
28
+
27
29
  export {
28
30
  writePerModuleRouteTypes,
29
31
  extractRoutesFromSource,