@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
@@ -12,7 +12,10 @@ import {
12
12
  getLocationState,
13
13
  } from "../server/request-context.js";
14
14
  import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
15
+ import { appendMetric } from "../router/metrics.js";
16
+ import { getSSRSetup, isRscRequest } from "./ssr-setup.js";
15
17
  import type { RscPayload } from "./types.js";
18
+ import type { MatchResult } from "../types.js";
16
19
  import {
17
20
  createResponseWithMergedHeaders,
18
21
  createSimpleRedirectResponse,
@@ -28,15 +31,33 @@ export async function handleRscRendering<TEnv>(
28
31
  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
29
32
  nonce: string | undefined,
30
33
  ): Promise<Response> {
31
- // Retrieve handler-level timing from variables
32
34
  const reqCtx = requireRequestContext();
33
- const handlerTimingArr: string[] = reqCtx.var.__handlerTiming || [];
34
- const handlerStart: number = reqCtx.var.__handlerStart || 0;
35
35
 
36
36
  let payload: RscPayload;
37
- let serverTiming: string | undefined;
38
37
  let hasInterceptSlots = false;
39
38
 
39
+ // Shared by the partial-fallback and full-render paths. The partial-success
40
+ // payload below is intentionally different (omits rootLayout/theme, adds slots).
41
+ const buildFullPayload = (m: MatchResult): RscPayload => ({
42
+ metadata: {
43
+ pathname: url.pathname,
44
+ routerId: ctx.router.id,
45
+ basename: ctx.router.basename,
46
+ segments: m.segments,
47
+ matched: m.matched,
48
+ diff: m.diff,
49
+ resolvedIds: m.resolvedIds,
50
+ params: m.params,
51
+ isPartial: false,
52
+ rootLayout: ctx.router.rootLayout,
53
+ handles: handleStore.stream(),
54
+ version: ctx.version,
55
+ prefetchCacheTTL: ctx.router.prefetchCacheTTL,
56
+ themeConfig: ctx.router.themeConfig,
57
+ initialTheme: reqCtx.theme,
58
+ },
59
+ });
60
+
40
61
  if (isPartial) {
41
62
  // Partial render (navigation)
42
63
  const result = await ctx.router.matchPartial(request, { env });
@@ -53,39 +74,26 @@ export async function handleRscRendering<TEnv>(
53
74
  return createSimpleRedirectResponse(match.redirect);
54
75
  }
55
76
 
56
- serverTiming = match.serverTiming;
57
-
58
- payload = {
59
- metadata: {
60
- pathname: url.pathname,
61
- segments: match.segments,
62
- matched: match.matched,
63
- diff: match.diff,
64
- params: match.params,
65
- isPartial: false,
66
- rootLayout: ctx.router.rootLayout,
67
- handles: handleStore.stream(),
68
- version: ctx.version,
69
- themeConfig: ctx.router.themeConfig,
70
- initialTheme: reqCtx.theme,
71
- },
72
- };
77
+ payload = buildFullPayload(match);
73
78
  } else {
74
79
  setRequestContextParams(result.params, result.routeName);
75
- serverTiming = result.serverTiming;
80
+
76
81
  hasInterceptSlots = !!result.slots;
77
82
 
78
83
  payload = {
79
84
  metadata: {
80
85
  pathname: url.pathname,
86
+ routerId: ctx.router.id,
81
87
  segments: result.segments,
82
88
  matched: result.matched,
83
89
  diff: result.diff,
90
+ resolvedIds: result.resolvedIds,
84
91
  params: result.params,
85
92
  isPartial: true,
86
93
  slots: result.slots,
87
94
  handles: handleStore.stream(),
88
95
  version: ctx.version,
96
+ prefetchCacheTTL: ctx.router.prefetchCacheTTL,
89
97
  },
90
98
  };
91
99
  }
@@ -132,26 +140,7 @@ export async function handleRscRendering<TEnv>(
132
140
  { headers: { "Content-Type": "application/json" } },
133
141
  );
134
142
  } else {
135
- serverTiming = match.serverTiming;
136
-
137
- payload = {
138
- // Initial SSR can reconstruct the tree from segments + rootLayout,
139
- // so we omit root to avoid sending the same structure twice.
140
-
141
- metadata: {
142
- pathname: url.pathname,
143
- segments: match.segments,
144
- matched: match.matched,
145
- diff: match.diff,
146
- params: match.params,
147
- isPartial: false,
148
- rootLayout: ctx.router.rootLayout,
149
- handles: handleStore.stream(),
150
- version: ctx.version,
151
- themeConfig: ctx.router.themeConfig,
152
- initialTheme: reqCtx.theme,
153
- },
154
- };
143
+ payload = buildFullPayload(match);
155
144
  }
156
145
  }
157
146
 
@@ -166,34 +155,39 @@ export async function handleRscRendering<TEnv>(
166
155
  }
167
156
  }
168
157
 
158
+ const metricsStore = reqCtx._metricsStore;
159
+ const renderStart = performance.now();
160
+
169
161
  // Serialize to RSC stream
170
162
  const rscSerializeStart = performance.now();
171
- const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
163
+ const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
164
+ onError: (error: unknown) => {
165
+ ctx.callOnError(error, "rendering", { request, url, env });
166
+ },
167
+ });
172
168
  const rscSerializeDur = performance.now() - rscSerializeStart;
173
-
174
- // Determine if this is an RSC request or HTML request.
175
- // Partial requests (_rsc_partial) are always RSC -- they come from client-side
176
- // navigation or prefetch fetch(). We cannot rely on Accept alone since some
177
- // browsers may send Accept: text/html for non-HTML requests.
178
- const isRscRequest =
179
- isPartial ||
180
- (!request.headers.get("accept")?.includes("text/html") &&
181
- !url.searchParams.has("__html")) ||
182
- url.searchParams.has("__rsc");
183
-
184
- // Build complete Server-Timing: handler phases + match/manifest + RSC serialize
185
- const timingParts: string[] = [...handlerTimingArr];
186
- if (serverTiming) {
187
- timingParts.push(serverTiming);
188
- }
189
- timingParts.push(`rsc-serialize;dur=${rscSerializeDur.toFixed(2)}`);
190
-
191
- if (isRscRequest) {
192
- const fullTiming = timingParts.join(", ");
169
+ // This measures synchronous stream creation, not end-to-end stream consumption.
170
+ appendMetric(
171
+ metricsStore,
172
+ "rsc-serialize",
173
+ rscSerializeStart,
174
+ rscSerializeDur,
175
+ );
176
+
177
+ if (isRscRequest(request, url, isPartial)) {
178
+ const renderDur = performance.now() - renderStart;
179
+ appendMetric(metricsStore, "render:total", renderStart, renderDur);
193
180
  const rscHeaders: Record<string, string> = {
194
181
  "content-type": "text/x-component;charset=utf-8",
195
182
  vary: "accept, X-Rango-State, X-RSC-Router-Client-Path",
196
183
  };
184
+ // Tell the client's prefetch cache to scope this response to its source
185
+ // URL (instead of the default source-agnostic wildcard). Intercept
186
+ // responses depend on the source page matching an intercept rule, so
187
+ // they must not be reused for navigations from other sources.
188
+ if (hasInterceptSlots) {
189
+ rscHeaders["x-rsc-prefetch-scope"] = "source";
190
+ }
197
191
  // Enable browser HTTP caching for prefetch responses only.
198
192
  // Requires X-Rango-Prefetch header (sent by Link prefetch fetch),
199
193
  // non-intercept context (intercept responses depend on source page),
@@ -205,22 +199,19 @@ export async function handleRscRendering<TEnv>(
205
199
  rscHeaders["cache-control"] = cc;
206
200
  }
207
201
  }
208
- if (fullTiming) {
209
- rscHeaders["Server-Timing"] = fullTiming;
210
- }
211
202
  return createResponseWithMergedHeaders(rscStream, {
212
203
  headers: rscHeaders,
213
204
  });
214
205
  }
215
206
 
216
- // Delegate to SSR for HTML response
217
- const ssrSetupStart = performance.now();
218
- const [ssrModule, streamMode] = await Promise.all([
219
- ctx.loadSSRModule(),
220
- ctx.resolveStreamMode(request, env, url),
221
- ]);
222
- const ssrSetupDur = performance.now() - ssrSetupStart;
223
- timingParts.push(`ssr-setup;dur=${ssrSetupDur.toFixed(2)}`);
207
+ // Delegate to SSR for HTML response (reuse early setup if available)
208
+ const [ssrModule, streamMode] = await getSSRSetup(
209
+ ctx,
210
+ request,
211
+ env,
212
+ url,
213
+ metricsStore,
214
+ );
224
215
 
225
216
  const ssrRenderStart = performance.now();
226
217
  const htmlStream = await ssrModule.renderHTML(rscStream, {
@@ -228,23 +219,12 @@ export async function handleRscRendering<TEnv>(
228
219
  streamMode,
229
220
  });
230
221
  const ssrRenderDur = performance.now() - ssrRenderStart;
231
- timingParts.push(`ssr-render-html;dur=${ssrRenderDur.toFixed(2)}`);
232
-
233
- // Add total handler duration
234
- if (handlerStart) {
235
- const totalHandler = performance.now() - handlerStart;
236
- timingParts.push(`handler-total;dur=${totalHandler.toFixed(2)}`);
237
- }
222
+ appendMetric(metricsStore, "ssr-render-html", ssrRenderStart, ssrRenderDur);
238
223
 
239
- const fullTiming = timingParts.join(", ");
240
- const htmlHeaders: Record<string, string> = {
241
- "content-type": "text/html;charset=utf-8",
242
- };
243
- if (fullTiming) {
244
- htmlHeaders["Server-Timing"] = fullTiming;
245
- }
224
+ const renderDur = performance.now() - renderStart;
225
+ appendMetric(metricsStore, "render:total", renderStart, renderDur);
246
226
 
247
227
  return createResponseWithMergedHeaders(htmlStream, {
248
- headers: htmlHeaders,
228
+ headers: { "content-type": "text/html;charset=utf-8" },
249
229
  });
250
230
  }
@@ -8,6 +8,7 @@ import {
8
8
  createResponseWithMergedHeaders,
9
9
  carryOverRedirectHeaders,
10
10
  } from "./helpers.js";
11
+ import { isRedirectResponse } from "../response-utils.js";
11
12
 
12
13
  // W3 -----------------------------------------------------------------------
13
14
 
@@ -18,16 +19,14 @@ import {
18
19
  */
19
20
  export function extractRedirectResponse(value: unknown): Response | null {
20
21
  if (!(value instanceof Response)) return null;
21
- const location = value.headers.get("Location");
22
- if (value.status >= 300 && value.status < 400 && location) {
23
- const redirect = createResponseWithMergedHeaders(null, {
24
- status: value.status,
25
- headers: { Location: location },
26
- });
27
- carryOverRedirectHeaders(value, redirect);
28
- return redirect;
29
- }
30
- return null;
22
+ if (!isRedirectResponse(value)) return null;
23
+ const location = value.headers.get("Location")!;
24
+ const redirect = createResponseWithMergedHeaders(null, {
25
+ status: value.status,
26
+ headers: { Location: location },
27
+ });
28
+ carryOverRedirectHeaders(value, redirect);
29
+ return redirect;
31
30
  }
32
31
 
33
32
  /**
@@ -21,12 +21,13 @@ import {
21
21
  getLocationState,
22
22
  } from "../server/request-context.js";
23
23
  import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
24
+ import { appendMetric } from "../router/metrics.js";
24
25
  import type { RscPayload } from "./types.js";
25
26
  import {
26
27
  hasBodyContent,
27
28
  createResponseWithMergedHeaders,
28
29
  createSimpleRedirectResponse,
29
- carryOverRedirectHeaders,
30
+ interceptRedirectForPartial,
30
31
  } from "./helpers.js";
31
32
  import type { HandlerContext } from "./handler-context.js";
32
33
 
@@ -110,49 +111,25 @@ export async function executeServerAction<TEnv>(
110
111
  loadedAction = await ctx.loadServerAction(actionId);
111
112
  const data = await loadedAction!.apply(null, args);
112
113
 
113
- // Intercept redirect responses from actions. Without this, the redirect
114
- // Response would be serialized as the action returnValue (which fails)
115
- // and the revalidation step would run unnecessarily.
114
+ // Intercept redirect Responses: serializing one as the action returnValue
115
+ // would fail, and revalidation would run needlessly.
116
116
  if (data instanceof Response) {
117
- const redirectUrl = data.headers.get("Location");
118
- const isRedirect = data.status >= 300 && data.status < 400 && redirectUrl;
119
- if (isRedirect) {
120
- const locationState = getLocationState();
121
- let redirect: Response;
122
- if (locationState) {
123
- redirect = ctx.createRedirectFlightResponse(
124
- redirectUrl,
125
- resolveLocationStateEntries(locationState),
126
- );
127
- } else {
128
- redirect = createSimpleRedirectResponse(redirectUrl);
129
- }
130
- carryOverRedirectHeaders(data, redirect);
131
- return redirect;
132
- }
117
+ const intercepted = interceptRedirectForPartial(
118
+ data,
119
+ ctx.createRedirectFlightResponse,
120
+ );
121
+ if (intercepted) return intercepted;
133
122
  }
134
123
 
135
124
  returnValue = { ok: true, data };
136
125
  } catch (error) {
137
126
  // Handle thrown redirect (e.g., throw redirect('/path'))
138
127
  if (error instanceof Response) {
139
- const redirectUrl = error.headers.get("Location");
140
- const isRedirect =
141
- error.status >= 300 && error.status < 400 && redirectUrl;
142
- if (isRedirect) {
143
- const locationState = getLocationState();
144
- let redirect: Response;
145
- if (locationState) {
146
- redirect = ctx.createRedirectFlightResponse(
147
- redirectUrl,
148
- resolveLocationStateEntries(locationState),
149
- );
150
- } else {
151
- redirect = createSimpleRedirectResponse(redirectUrl);
152
- }
153
- carryOverRedirectHeaders(error, redirect);
154
- return redirect;
155
- }
128
+ const intercepted = interceptRedirectForPartial(
129
+ error,
130
+ ctx.createRedirectFlightResponse,
131
+ );
132
+ if (intercepted) return intercepted;
156
133
 
157
134
  // Non-redirect Response thrown from action — this will be treated
158
135
  // as a regular error and routed to the error boundary. Warn in dev
@@ -207,10 +184,13 @@ export async function executeServerAction<TEnv>(
207
184
  const payload: RscPayload = {
208
185
  metadata: {
209
186
  pathname: url.pathname,
187
+ routerId: ctx.router.id,
210
188
  segments: errorResult.segments,
211
189
  isPartial: true,
212
190
  matched: errorResult.matched,
213
191
  diff: errorResult.diff,
192
+ resolvedIds: errorResult.resolvedIds,
193
+ params: errorResult.params,
214
194
  isError: true,
215
195
  handles: handleStore.stream(),
216
196
  version: ctx.version,
@@ -224,6 +204,9 @@ export async function executeServerAction<TEnv>(
224
204
 
225
205
  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
226
206
  temporaryReferences,
207
+ onError: (error: unknown) => {
208
+ ctx.callOnError(error, "rendering", { request, url, env });
209
+ },
227
210
  });
228
211
 
229
212
  return createResponseWithMergedHeaders(rscStream, {
@@ -274,6 +257,8 @@ export async function revalidateAfterAction<TEnv>(
274
257
  ): Promise<Response> {
275
258
  const { returnValue, actionStatus, temporaryReferences, actionContext } =
276
259
  continuation;
260
+ const reqCtx = requireRequestContext();
261
+ const metricsStore = reqCtx._metricsStore;
277
262
 
278
263
  const matchResult = await ctx.router.matchPartial(
279
264
  request,
@@ -308,15 +293,16 @@ export async function revalidateAfterAction<TEnv>(
308
293
  // Return updated segments
309
294
  setRequestContextParams(matchResult.params, matchResult.routeName);
310
295
 
311
- const serverTiming = matchResult.serverTiming;
312
-
313
296
  const payload: RscPayload = {
314
297
  metadata: {
315
298
  pathname: url.pathname,
299
+ routerId: ctx.router.id,
316
300
  segments: matchResult.segments,
317
301
  isPartial: true,
318
302
  matched: matchResult.matched,
319
303
  diff: matchResult.diff,
304
+ resolvedIds: matchResult.resolvedIds,
305
+ params: matchResult.params,
320
306
  slots: matchResult.slots,
321
307
  handles: handleStore.stream(),
322
308
  version: ctx.version,
@@ -326,19 +312,25 @@ export async function revalidateAfterAction<TEnv>(
326
312
 
327
313
  attachLocationState(payload);
328
314
 
315
+ const renderStart = performance.now();
329
316
  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
330
317
  temporaryReferences,
318
+ onError: (error: unknown) => {
319
+ ctx.callOnError(error, "rendering", { request, url, env });
320
+ },
331
321
  });
332
-
333
- const actionHeaders: Record<string, string> = {
334
- "content-type": "text/x-component;charset=utf-8",
335
- };
336
- if (serverTiming) {
337
- actionHeaders["Server-Timing"] = serverTiming;
338
- }
322
+ const rscSerializeDur = performance.now() - renderStart;
323
+ // This measures synchronous stream creation, not end-to-end stream consumption.
324
+ appendMetric(metricsStore, "rsc-serialize", renderStart, rscSerializeDur);
325
+ appendMetric(
326
+ metricsStore,
327
+ "render:total",
328
+ renderStart,
329
+ performance.now() - renderStart,
330
+ );
339
331
 
340
332
  return createResponseWithMergedHeaders(rscStream, {
341
333
  status: actionStatus,
342
- headers: actionHeaders,
334
+ headers: { "content-type": "text/x-component;charset=utf-8" },
343
335
  });
344
336
  }
@@ -0,0 +1,144 @@
1
+ /**
2
+ * SSR Setup Utilities
3
+ *
4
+ * Manages early kickoff and retrieval of SSR module loading and stream mode
5
+ * resolution. Both operations are request-scoped but independent of route
6
+ * matching, so they can run in parallel with segment resolution.
7
+ */
8
+
9
+ import type { HandlerContext } from "./handler-context.js";
10
+ import type { SSRModule } from "./types.js";
11
+ import type { SSRStreamMode } from "../router/router-options.js";
12
+ import type { MetricsStore } from "../server/context.js";
13
+ import { appendMetric } from "../router/metrics.js";
14
+ import { _getRequestContext } from "../server/request-context.js";
15
+
16
+ export type SSRSetup = readonly [SSRModule, SSRStreamMode];
17
+
18
+ /**
19
+ * Key used to stash the early SSR setup promise on request variables.
20
+ * Read back via `getSSRSetup`.
21
+ */
22
+ export const SSR_SETUP_VAR = "__ssrSetup";
23
+
24
+ /**
25
+ * Start loading the SSR module and resolving the stream mode in parallel.
26
+ * When a `getMetricsStore` getter is provided, records individual
27
+ * `ssr:module-load` and `ssr:stream-mode` metrics (the getter is called
28
+ * lazily so stores created after kickoff are still captured). Without a
29
+ * getter the promises run bare — no `.then()` microtasks, no
30
+ * `performance.now()` calls — keeping the non-debug hot path lean.
31
+ */
32
+ export function startSSRSetup<TEnv>(
33
+ ctx: HandlerContext<TEnv>,
34
+ request: Request,
35
+ env: TEnv,
36
+ url: URL,
37
+ getMetricsStore?: () => MetricsStore | undefined,
38
+ ): Promise<SSRSetup> {
39
+ if (!getMetricsStore) {
40
+ return Promise.all([
41
+ ctx.loadSSRModule(),
42
+ ctx.resolveStreamMode(request, env, url),
43
+ ]);
44
+ }
45
+ const start = performance.now();
46
+ return Promise.all([
47
+ ctx.loadSSRModule().then((mod) => {
48
+ appendMetric(
49
+ getMetricsStore(),
50
+ "ssr:module-load",
51
+ start,
52
+ performance.now() - start,
53
+ );
54
+ return mod;
55
+ }),
56
+ ctx.resolveStreamMode(request, env, url).then((mode) => {
57
+ appendMetric(
58
+ getMetricsStore(),
59
+ "ssr:stream-mode",
60
+ start,
61
+ performance.now() - start,
62
+ );
63
+ return mode;
64
+ }),
65
+ ]);
66
+ }
67
+
68
+ /**
69
+ * Retrieve the SSR setup result. Returns the early-kicked-off promise
70
+ * when available (stashed on request variables), otherwise starts a
71
+ * fresh setup.
72
+ */
73
+ export function getSSRSetup<TEnv>(
74
+ ctx: HandlerContext<TEnv>,
75
+ request: Request,
76
+ env: TEnv,
77
+ url: URL,
78
+ metricsStore: MetricsStore | undefined,
79
+ ): Promise<SSRSetup> {
80
+ const early = _getRequestContext()?._variables?.[SSR_SETUP_VAR] as
81
+ | Promise<SSRSetup>
82
+ | undefined;
83
+ if (early) return early;
84
+ return startSSRSetup(
85
+ ctx,
86
+ request,
87
+ env,
88
+ url,
89
+ metricsStore ? () => metricsStore : undefined,
90
+ );
91
+ }
92
+
93
+ /**
94
+ * Classify whether a request may require SSR (HTML rendering).
95
+ *
96
+ * Returns false for requests that are definitively RSC-only, loader fetches,
97
+ * prerender collection, or Accept-based RSC (no text/html). This mirrors
98
+ * the isRscRequest decision in rsc-rendering.ts.
99
+ *
100
+ * Note: response/mime routes are excluded by the caller — this function
101
+ * runs after classifyRequest() determines the request mode.
102
+ */
103
+ export function mayNeedSSR(request: Request, url: URL): boolean {
104
+ if (
105
+ url.searchParams.has("_rsc_partial") ||
106
+ url.searchParams.has("_rsc_action") ||
107
+ request.headers.has("rsc-action") ||
108
+ url.searchParams.has("_rsc_loader") ||
109
+ url.searchParams.has("__rsc") ||
110
+ url.searchParams.has("__prerender_collect")
111
+ ) {
112
+ return false;
113
+ }
114
+
115
+ // Mirror the Accept-based RSC decision from rsc-rendering.ts:
116
+ // if Accept is present and does not include text/html (and no __html override),
117
+ // the response will be RSC, not HTML.
118
+ const accept = request.headers.get("accept");
119
+ if (
120
+ accept &&
121
+ !accept.includes("text/html") &&
122
+ !url.searchParams.has("__html")
123
+ ) {
124
+ return false;
125
+ }
126
+
127
+ return true;
128
+ }
129
+
130
+ // Final render-time decision: is the response an RSC stream (vs HTML)? Distinct
131
+ // from mayNeedSSR, which is a conservative pre-classifier (it treats a missing
132
+ // Accept header as needing SSR; this treats it as RSC).
133
+ export function isRscRequest(
134
+ request: Request,
135
+ url: URL,
136
+ isPartial: boolean,
137
+ ): boolean {
138
+ return (
139
+ isPartial ||
140
+ (!request.headers.get("accept")?.includes("text/html") &&
141
+ !url.searchParams.has("__html")) ||
142
+ url.searchParams.has("__rsc")
143
+ );
144
+ }
package/src/rsc/types.ts CHANGED
@@ -7,7 +7,7 @@
7
7
 
8
8
  import type { ResolvedSegment, SlotState } from "../types.js";
9
9
  import type { HandleData } from "../server/handle-store.js";
10
- import type { RSCRouterInternal } from "../router/router-interfaces.js";
10
+ import type { RangoInternal } from "../router/router-interfaces.js";
11
11
  import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
12
12
 
13
13
  /**
@@ -19,10 +19,19 @@ export interface RscPayload {
19
19
  metadata?: {
20
20
  pathname: string;
21
21
  segments: ResolvedSegment[];
22
+ /** Router instance ID. When this changes between navigations, the client
23
+ * discards cached segments and does a full tree replacement (app switch). */
24
+ routerId?: string;
22
25
  isPartial?: boolean;
23
26
  isError?: boolean;
24
27
  matched?: string[];
25
28
  diff?: string[];
29
+ /**
30
+ * All segment ids re-resolved on the server, including null-component
31
+ * ones excluded from `segments`/`diff`. Drives client-side handle-bucket
32
+ * cleanup. Superset of `diff`. See MatchResult.resolvedIds.
33
+ */
34
+ resolvedIds?: string[];
26
35
  /** Merged route params from the matched route */
27
36
  params?: Record<string, string>;
28
37
  slots?: Record<string, SlotState>;
@@ -32,10 +41,14 @@ export interface RscPayload {
32
41
  handles?: AsyncGenerator<HandleData, void, unknown>;
33
42
  /** RSC version string for cache invalidation */
34
43
  version?: string;
44
+ /** TTL in milliseconds for the client-side in-memory prefetch cache */
45
+ prefetchCacheTTL?: number;
35
46
  /** Theme configuration for FOUC prevention */
36
47
  themeConfig?: ResolvedThemeConfig | null;
37
48
  /** Initial theme from cookie (for SSR hydration) */
38
49
  initialTheme?: Theme;
50
+ /** URL prefix for all routes (from createRouter({ basename })). */
51
+ basename?: string;
39
52
  /** Whether connection warmup is enabled */
40
53
  warmupEnabled?: boolean;
41
54
  /** Server-side redirect with optional state (for partial requests) */
@@ -61,7 +74,10 @@ export interface RSCDependencies {
61
74
  */
62
75
  renderToReadableStream: <T>(
63
76
  payload: T,
64
- options?: { temporaryReferences?: unknown },
77
+ options?: {
78
+ temporaryReferences?: unknown;
79
+ onError?: (error: unknown) => string | void;
80
+ },
65
81
  ) => ReadableStream<Uint8Array>;
66
82
 
67
83
  /**
@@ -169,7 +185,7 @@ export interface CreateRSCHandlerOptions<
169
185
  /**
170
186
  * The RSC router instance
171
187
  */
172
- router: RSCRouterInternal<TEnv, TRoutes>;
188
+ router: RangoInternal<TEnv, TRoutes>;
173
189
 
174
190
  /**
175
191
  * RSC dependencies from @vitejs/plugin-rsc/rsc.