@rangojs/router 0.0.0-experimental.a769fbe7 → 0.0.0-experimental.ac99d918

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 (374) hide show
  1. package/README.md +211 -43
  2. package/dist/bin/rango.js +279 -102
  3. package/dist/testing/vitest.js +82 -0
  4. package/dist/vite/index.js +3313 -1160
  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 +62 -11
  8. package/skills/api-client/SKILL.md +211 -0
  9. package/skills/breadcrumbs/SKILL.md +63 -1
  10. package/skills/bundle-analysis/SKILL.md +159 -0
  11. package/skills/cache-guide/SKILL.md +222 -30
  12. package/skills/caching/SKILL.md +263 -8
  13. package/skills/composability/SKILL.md +27 -2
  14. package/skills/css/SKILL.md +76 -0
  15. package/skills/document-cache/SKILL.md +78 -55
  16. package/skills/handler-use/SKILL.md +364 -0
  17. package/skills/hooks/SKILL.md +250 -30
  18. package/skills/host-router/SKILL.md +124 -22
  19. package/skills/i18n/SKILL.md +276 -0
  20. package/skills/intercept/SKILL.md +49 -5
  21. package/skills/layout/SKILL.md +35 -9
  22. package/skills/links/SKILL.md +249 -17
  23. package/skills/loader/SKILL.md +223 -9
  24. package/skills/middleware/SKILL.md +52 -13
  25. package/skills/migrate-nextjs/SKILL.md +584 -0
  26. package/skills/migrate-react-router/SKILL.md +769 -0
  27. package/skills/mime-routes/SKILL.md +27 -0
  28. package/skills/observability/SKILL.md +137 -0
  29. package/skills/parallel/SKILL.md +77 -7
  30. package/skills/prerender/SKILL.md +123 -100
  31. package/skills/rango/SKILL.md +250 -22
  32. package/skills/react-compiler/SKILL.md +168 -0
  33. package/skills/response-routes/SKILL.md +122 -47
  34. package/skills/route/SKILL.md +66 -5
  35. package/skills/router-setup/SKILL.md +38 -3
  36. package/skills/server-actions/SKILL.md +775 -0
  37. package/skills/streams-and-websockets/SKILL.md +283 -0
  38. package/skills/tailwind/SKILL.md +27 -3
  39. package/skills/testing/SKILL.md +129 -0
  40. package/skills/testing/bindings.md +89 -0
  41. package/skills/testing/cache-prerender.md +124 -0
  42. package/skills/testing/client-components.md +122 -0
  43. package/skills/testing/e2e-parity.md +125 -0
  44. package/skills/testing/flight.md +92 -0
  45. package/skills/testing/handles.md +129 -0
  46. package/skills/testing/loader.md +128 -0
  47. package/skills/testing/middleware.md +99 -0
  48. package/skills/testing/render-handler.md +121 -0
  49. package/skills/testing/response-routes.md +95 -0
  50. package/skills/testing/reverse-and-types.md +84 -0
  51. package/skills/testing/server-actions.md +107 -0
  52. package/skills/testing/server-tree.md +128 -0
  53. package/skills/testing/setup.md +120 -0
  54. package/skills/typesafety/SKILL.md +319 -27
  55. package/skills/use-cache/SKILL.md +36 -5
  56. package/skills/vercel/SKILL.md +107 -0
  57. package/skills/view-transitions/SKILL.md +294 -0
  58. package/src/__augment-tests__/augment.ts +81 -0
  59. package/src/__augment-tests__/augmented.check.ts +116 -0
  60. package/src/__internal.ts +1 -66
  61. package/src/browser/action-coordinator.ts +53 -36
  62. package/src/browser/action-fence.ts +47 -0
  63. package/src/browser/app-shell.ts +39 -0
  64. package/src/browser/app-version.ts +14 -0
  65. package/src/browser/cookie-name.ts +140 -0
  66. package/src/browser/event-controller.ts +81 -147
  67. package/src/browser/history-state.ts +21 -0
  68. package/src/browser/index.ts +3 -3
  69. package/src/browser/invalidate-client-cache.ts +52 -0
  70. package/src/browser/navigation-bridge.ts +66 -14
  71. package/src/browser/navigation-client.ts +172 -109
  72. package/src/browser/navigation-store-handle.ts +38 -0
  73. package/src/browser/navigation-store.ts +76 -67
  74. package/src/browser/navigation-transaction.ts +9 -59
  75. package/src/browser/partial-update.ts +79 -93
  76. package/src/browser/prefetch/cache.ts +180 -62
  77. package/src/browser/prefetch/fetch.ts +252 -39
  78. package/src/browser/prefetch/queue.ts +42 -8
  79. package/src/browser/rango-state.ts +158 -76
  80. package/src/browser/react/Link.tsx +72 -10
  81. package/src/browser/react/NavigationProvider.tsx +83 -31
  82. package/src/browser/react/ScrollRestoration.tsx +10 -6
  83. package/src/browser/react/context.ts +7 -2
  84. package/src/browser/react/filter-segment-order.ts +49 -7
  85. package/src/browser/react/index.ts +0 -48
  86. package/src/browser/react/location-state-shared.ts +166 -8
  87. package/src/browser/react/location-state.ts +39 -14
  88. package/src/browser/react/use-action.ts +6 -15
  89. package/src/browser/react/use-handle.ts +23 -69
  90. package/src/browser/react/use-link-status.ts +0 -4
  91. package/src/browser/react/use-navigation.ts +22 -5
  92. package/src/browser/react/use-params.ts +20 -10
  93. package/src/browser/react/use-reverse.ts +106 -0
  94. package/src/browser/react/use-router.ts +46 -11
  95. package/src/browser/react/use-search-params.ts +0 -5
  96. package/src/browser/react/use-segments.ts +11 -21
  97. package/src/browser/response-adapter.ts +52 -1
  98. package/src/browser/rsc-router.tsx +111 -24
  99. package/src/browser/scroll-restoration.ts +29 -19
  100. package/src/browser/segment-reconciler.ts +36 -14
  101. package/src/browser/segment-structure-assert.ts +2 -2
  102. package/src/browser/server-action-bridge.ts +176 -62
  103. package/src/browser/types.ts +60 -11
  104. package/src/browser/validate-redirect-origin.ts +43 -16
  105. package/src/build/collect-fallback-refs.ts +107 -0
  106. package/src/build/generate-manifest.ts +65 -40
  107. package/src/build/generate-route-types.ts +6 -0
  108. package/src/build/index.ts +8 -2
  109. package/src/build/prefix-tree-utils.ts +123 -0
  110. package/src/build/route-trie.ts +137 -32
  111. package/src/build/route-types/codegen.ts +4 -4
  112. package/src/build/route-types/include-resolution.ts +9 -2
  113. package/src/build/route-types/param-extraction.ts +6 -3
  114. package/src/build/route-types/per-module-writer.ts +7 -4
  115. package/src/build/route-types/router-processing.ts +333 -94
  116. package/src/build/route-types/scan-filter.ts +9 -2
  117. package/src/build/route-types/source-scan.ts +118 -0
  118. package/src/build/runtime-discovery.ts +9 -20
  119. package/src/cache/cache-error.ts +104 -0
  120. package/src/cache/cache-policy.ts +68 -28
  121. package/src/cache/cache-runtime.ts +134 -32
  122. package/src/cache/cache-scope.ts +100 -74
  123. package/src/cache/cache-tag.ts +98 -0
  124. package/src/cache/cf/cf-cache-store.ts +2256 -241
  125. package/src/cache/cf/index.ts +6 -16
  126. package/src/cache/document-cache.ts +61 -20
  127. package/src/cache/handle-snapshot.ts +63 -0
  128. package/src/cache/index.ts +22 -20
  129. package/src/cache/memory-segment-store.ts +136 -37
  130. package/src/cache/profile-registry.ts +6 -30
  131. package/src/cache/read-through-swr.ts +41 -11
  132. package/src/cache/segment-codec.ts +0 -16
  133. package/src/cache/tag-invalidation.ts +230 -0
  134. package/src/cache/types.ts +33 -100
  135. package/src/cache/vercel/index.ts +11 -0
  136. package/src/cache/vercel/vercel-cache-store.ts +799 -0
  137. package/src/client.rsc.tsx +6 -21
  138. package/src/client.tsx +108 -290
  139. package/src/component-utils.ts +19 -0
  140. package/src/context-var.ts +17 -5
  141. package/src/decode-loader-results.ts +36 -0
  142. package/src/defer.ts +196 -0
  143. package/src/deps/browser.ts +0 -1
  144. package/src/deps/ssr.ts +0 -1
  145. package/src/errors.ts +30 -4
  146. package/src/handle.ts +70 -22
  147. package/src/handles/MetaTags.tsx +0 -14
  148. package/src/handles/breadcrumbs.ts +16 -5
  149. package/src/handles/meta.ts +0 -39
  150. package/src/host/cookie-handler.ts +0 -36
  151. package/src/host/errors.ts +0 -24
  152. package/src/host/index.ts +8 -2
  153. package/src/host/pattern-matcher.ts +7 -50
  154. package/src/host/router.ts +107 -99
  155. package/src/host/testing.ts +40 -27
  156. package/src/host/types.ts +37 -4
  157. package/src/host/utils.ts +1 -1
  158. package/src/href-client.ts +137 -22
  159. package/src/index.rsc.ts +69 -10
  160. package/src/index.ts +112 -14
  161. package/src/internal-debug.ts +2 -4
  162. package/src/loader-store.ts +500 -0
  163. package/src/loader.rsc.ts +20 -13
  164. package/src/loader.ts +12 -11
  165. package/src/missing-id-error.ts +68 -0
  166. package/src/network-error-thrower.tsx +1 -6
  167. package/src/outlet-context.ts +1 -1
  168. package/src/outlet-provider.tsx +1 -5
  169. package/src/prerender/param-hash.ts +10 -11
  170. package/src/prerender/store.ts +37 -41
  171. package/src/prerender.ts +198 -82
  172. package/src/redirect-origin.ts +100 -0
  173. package/src/response-utils.ts +37 -0
  174. package/src/reverse.ts +65 -15
  175. package/src/root-error-boundary.tsx +1 -19
  176. package/src/route-content-wrapper.tsx +7 -72
  177. package/src/route-definition/dsl-helpers.ts +413 -275
  178. package/src/route-definition/helper-factories.ts +29 -139
  179. package/src/route-definition/helpers-types.ts +107 -32
  180. package/src/route-definition/index.ts +3 -0
  181. package/src/route-definition/redirect.ts +50 -8
  182. package/src/route-definition/resolve-handler-use.ts +161 -0
  183. package/src/route-definition/use-item-types.ts +32 -0
  184. package/src/route-map-builder.ts +0 -16
  185. package/src/route-types.ts +37 -41
  186. package/src/router/basename.ts +14 -0
  187. package/src/router/content-negotiation.ts +108 -9
  188. package/src/router/error-handling.ts +13 -17
  189. package/src/router/find-match.ts +44 -23
  190. package/src/router/handler-context.ts +46 -30
  191. package/src/router/intercept-resolution.ts +23 -23
  192. package/src/router/lazy-includes.ts +15 -52
  193. package/src/router/loader-resolution.ts +207 -30
  194. package/src/router/logging.ts +0 -6
  195. package/src/router/manifest.ts +40 -42
  196. package/src/router/match-api.ts +120 -204
  197. package/src/router/match-context.ts +0 -22
  198. package/src/router/match-handlers.ts +58 -58
  199. package/src/router/match-middleware/background-revalidation.ts +0 -7
  200. package/src/router/match-middleware/cache-lookup.ts +161 -262
  201. package/src/router/match-middleware/cache-store.ts +3 -33
  202. package/src/router/match-middleware/intercept-resolution.ts +0 -22
  203. package/src/router/match-middleware/segment-resolution.ts +45 -14
  204. package/src/router/match-pipelines.ts +1 -42
  205. package/src/router/match-result.ts +87 -39
  206. package/src/router/metrics.ts +0 -34
  207. package/src/router/middleware-types.ts +7 -140
  208. package/src/router/middleware.ts +169 -140
  209. package/src/router/navigation-snapshot.ts +131 -0
  210. package/src/router/params-util.ts +23 -0
  211. package/src/router/pattern-matching.ts +109 -63
  212. package/src/router/prerender-match.ts +190 -54
  213. package/src/router/preview-match.ts +32 -102
  214. package/src/router/request-classification.ts +276 -0
  215. package/src/router/revalidation.ts +63 -55
  216. package/src/router/route-snapshot.ts +244 -0
  217. package/src/router/router-context.ts +0 -27
  218. package/src/router/router-interfaces.ts +100 -35
  219. package/src/router/router-options.ts +91 -11
  220. package/src/router/router-registry.ts +2 -5
  221. package/src/router/segment-resolution/fresh.ts +119 -65
  222. package/src/router/segment-resolution/helpers.ts +34 -0
  223. package/src/router/segment-resolution/loader-cache.ts +40 -37
  224. package/src/router/segment-resolution/revalidation.ts +329 -305
  225. package/src/router/segment-resolution/static-store.ts +19 -5
  226. package/src/router/segment-resolution/streamed-handler-telemetry.ts +52 -0
  227. package/src/router/segment-resolution/view-transition-default.ts +36 -0
  228. package/src/router/segment-resolution.ts +4 -1
  229. package/src/router/segment-wrappers.ts +0 -3
  230. package/src/router/state-cookie-name.ts +33 -0
  231. package/src/router/substitute-pattern-params.ts +56 -0
  232. package/src/router/telemetry-otel.ts +0 -20
  233. package/src/router/telemetry.ts +96 -19
  234. package/src/router/timeout.ts +0 -20
  235. package/src/router/trie-matching.ts +91 -46
  236. package/src/router/types.ts +9 -63
  237. package/src/router/url-params.ts +44 -0
  238. package/src/router.ts +128 -42
  239. package/src/rsc/handler-context.ts +3 -2
  240. package/src/rsc/handler.ts +492 -409
  241. package/src/rsc/helpers.ts +162 -46
  242. package/src/rsc/index.ts +1 -1
  243. package/src/rsc/json-route-result.ts +38 -0
  244. package/src/rsc/loader-fetch.ts +18 -3
  245. package/src/rsc/manifest-init.ts +33 -42
  246. package/src/rsc/origin-guard.ts +39 -25
  247. package/src/rsc/progressive-enhancement.ts +28 -4
  248. package/src/rsc/redirect-guard.ts +99 -0
  249. package/src/rsc/response-error.ts +79 -12
  250. package/src/rsc/response-route-handler.ts +90 -63
  251. package/src/rsc/rsc-rendering.ts +53 -56
  252. package/src/rsc/runtime-warnings.ts +23 -10
  253. package/src/rsc/server-action.ts +74 -69
  254. package/src/rsc/ssr-setup.ts +18 -2
  255. package/src/rsc/types.ts +22 -9
  256. package/src/runtime-env.ts +18 -0
  257. package/src/search-params.ts +4 -20
  258. package/src/segment-content-promise.ts +67 -0
  259. package/src/segment-loader-promise.ts +134 -0
  260. package/src/segment-system.tsx +208 -201
  261. package/src/serialize.ts +243 -0
  262. package/src/server/context.ts +211 -52
  263. package/src/server/cookie-store.ts +80 -5
  264. package/src/server/handle-store.ts +26 -24
  265. package/src/server/loader-registry.ts +10 -28
  266. package/src/server/request-context.ts +289 -124
  267. package/src/ssr/index.tsx +22 -15
  268. package/src/static-handler.ts +27 -18
  269. package/src/testing/cache-status.ts +162 -0
  270. package/src/testing/collect-handle.ts +40 -0
  271. package/src/testing/dispatch.ts +618 -0
  272. package/src/testing/dom.entry.ts +22 -0
  273. package/src/testing/e2e/fixture.ts +188 -0
  274. package/src/testing/e2e/index.ts +128 -0
  275. package/src/testing/e2e/matchers.ts +35 -0
  276. package/src/testing/e2e/page-helpers.ts +272 -0
  277. package/src/testing/e2e/parity.ts +387 -0
  278. package/src/testing/e2e/server.ts +195 -0
  279. package/src/testing/flight-matchers.ts +97 -0
  280. package/src/testing/flight-normalize.ts +11 -0
  281. package/src/testing/flight-runtime.d.ts +57 -0
  282. package/src/testing/flight-tree.ts +682 -0
  283. package/src/testing/flight.entry.ts +52 -0
  284. package/src/testing/flight.ts +232 -0
  285. package/src/testing/generated-routes.ts +183 -0
  286. package/src/testing/index.ts +99 -0
  287. package/src/testing/internal/context.ts +348 -0
  288. package/src/testing/internal/flight-client-globals.ts +30 -0
  289. package/src/testing/internal/seed-vars.ts +54 -0
  290. package/src/testing/render-handler.ts +330 -0
  291. package/src/testing/render-route.tsx +566 -0
  292. package/src/testing/run-loader.ts +378 -0
  293. package/src/testing/run-middleware.ts +205 -0
  294. package/src/testing/vitest-stubs/cloudflare-email.ts +9 -0
  295. package/src/testing/vitest-stubs/cloudflare-workers.ts +21 -0
  296. package/src/testing/vitest-stubs/plugin-rsc.ts +16 -0
  297. package/src/testing/vitest-stubs/version.ts +5 -0
  298. package/src/testing/vitest.ts +305 -0
  299. package/src/theme/ThemeProvider.tsx +0 -52
  300. package/src/theme/ThemeScript.tsx +0 -6
  301. package/src/theme/constants.ts +0 -12
  302. package/src/theme/index.ts +0 -7
  303. package/src/theme/theme-context.ts +1 -5
  304. package/src/theme/theme-script.ts +0 -14
  305. package/src/theme/use-theme.ts +0 -3
  306. package/src/types/boundaries.ts +0 -35
  307. package/src/types/cache-types.ts +17 -8
  308. package/src/types/error-types.ts +30 -90
  309. package/src/types/global-namespace.ts +54 -41
  310. package/src/types/handler-context.ts +124 -70
  311. package/src/types/index.ts +1 -10
  312. package/src/types/loader-types.ts +40 -11
  313. package/src/types/request-scope.ts +107 -0
  314. package/src/types/route-config.ts +6 -50
  315. package/src/types/route-entry.ts +12 -7
  316. package/src/types/segments.ts +36 -15
  317. package/src/urls/include-helper.ts +33 -70
  318. package/src/urls/index.ts +1 -11
  319. package/src/urls/path-helper-types.ts +58 -11
  320. package/src/urls/path-helper.ts +57 -111
  321. package/src/urls/pattern-types.ts +48 -19
  322. package/src/urls/response-types.ts +25 -22
  323. package/src/urls/type-extraction.ts +58 -139
  324. package/src/urls/urls-function.ts +1 -18
  325. package/src/use-loader.tsx +346 -89
  326. package/src/vite/debug.ts +185 -0
  327. package/src/vite/discovery/bundle-postprocess.ts +36 -38
  328. package/src/vite/discovery/discover-routers.ts +130 -85
  329. package/src/vite/discovery/discovery-errors.ts +194 -0
  330. package/src/vite/discovery/gate-state.ts +171 -0
  331. package/src/vite/discovery/prerender-collection.ts +192 -99
  332. package/src/vite/discovery/route-types-writer.ts +40 -84
  333. package/src/vite/discovery/self-gen-tracking.ts +27 -1
  334. package/src/vite/discovery/state.ts +51 -4
  335. package/src/vite/discovery/virtual-module-codegen.ts +14 -34
  336. package/src/vite/index.ts +8 -0
  337. package/src/vite/plugin-types.ts +236 -6
  338. package/src/vite/plugins/cjs-to-esm.ts +8 -18
  339. package/src/vite/plugins/client-ref-dedup.ts +16 -11
  340. package/src/vite/plugins/client-ref-hashing.ts +28 -15
  341. package/src/vite/plugins/cloudflare-protocol-loader-hook.d.mts +23 -0
  342. package/src/vite/plugins/cloudflare-protocol-loader-hook.mjs +76 -0
  343. package/src/vite/plugins/cloudflare-protocol-stub.ts +194 -0
  344. package/src/vite/plugins/expose-action-id.ts +48 -95
  345. package/src/vite/plugins/expose-id-utils.ts +11 -50
  346. package/src/vite/plugins/expose-ids/export-analysis.ts +76 -34
  347. package/src/vite/plugins/expose-ids/handler-transform.ts +10 -48
  348. package/src/vite/plugins/expose-ids/loader-transform.ts +3 -20
  349. package/src/vite/plugins/expose-ids/router-transform.ts +20 -16
  350. package/src/vite/plugins/expose-internal-ids.ts +554 -317
  351. package/src/vite/plugins/performance-tracks.ts +65 -207
  352. package/src/vite/plugins/refresh-cmd.ts +89 -27
  353. package/src/vite/plugins/use-cache-transform.ts +73 -83
  354. package/src/vite/plugins/vercel-output.ts +258 -0
  355. package/src/vite/plugins/version-injector.ts +21 -25
  356. package/src/vite/plugins/version-plugin.ts +32 -23
  357. package/src/vite/plugins/virtual-entries.ts +46 -17
  358. package/src/vite/rango.ts +207 -125
  359. package/src/vite/router-discovery.ts +931 -133
  360. package/src/vite/utils/ast-handler-extract.ts +15 -31
  361. package/src/vite/utils/banner.ts +1 -1
  362. package/src/vite/utils/bundle-analysis.ts +10 -15
  363. package/src/vite/utils/client-chunks.ts +184 -0
  364. package/src/vite/utils/forward-user-plugins.ts +171 -0
  365. package/src/vite/utils/manifest-utils.ts +4 -59
  366. package/src/vite/utils/package-resolution.ts +20 -52
  367. package/src/vite/utils/prerender-utils.ts +27 -29
  368. package/src/vite/utils/shared-utils.ts +97 -44
  369. package/src/browser/action-response-classifier.ts +0 -99
  370. package/src/browser/debug-channel.ts +0 -93
  371. package/src/browser/react/use-client-cache.ts +0 -58
  372. package/src/browser/shallow.ts +0 -40
  373. package/src/handles/index.ts +0 -7
  374. package/src/router/middleware-cookies.ts +0 -55
@@ -8,6 +8,7 @@ import type {
8
8
  import type { NonceProvider } from "../rsc/types.js";
9
9
  import type { ExecutionContext } from "../server/request-context.js";
10
10
  import type { UrlPatterns } from "../urls.js";
11
+ import type { UrlBuilder } from "../urls/pattern-types.js";
11
12
  import type { NamedRouteEntry } from "./content-negotiation.js";
12
13
  import type { TelemetrySink } from "./telemetry.js";
13
14
  import type { RouterTimeouts, OnTimeoutCallback } from "./timeout.js";
@@ -72,7 +73,7 @@ export interface RootLayoutProps {
72
73
  /**
73
74
  * Router configuration options
74
75
  */
75
- export interface RSCRouterOptions<TEnv = any> {
76
+ export interface RangoOptions<TEnv = any> {
76
77
  /**
77
78
  * Unique identifier for this router instance.
78
79
  * Used to namespace static output files and route maps.
@@ -95,6 +96,28 @@ export interface RSCRouterOptions<TEnv = any> {
95
96
  */
96
97
  $$sourceFile?: string;
97
98
 
99
+ /**
100
+ * URL prefix applied to all routes registered with this router.
101
+ *
102
+ * Useful when the app is served under a sub-path (e.g. `/admin` or `/v2`).
103
+ * All `path()` patterns are automatically prefixed and `reverse()` returns
104
+ * full paths including the basename. Route names are NOT prefixed.
105
+ *
106
+ * @example
107
+ * ```typescript
108
+ * const router = createRouter({
109
+ * basename: "/admin",
110
+ * }).routes(({ path }) => [
111
+ * path("/", Dashboard, { name: "home" }), // matches /admin
112
+ * path("/users", Users, { name: "users" }), // matches /admin/users
113
+ * ]);
114
+ *
115
+ * router.reverse("home"); // "/admin"
116
+ * router.reverse("users"); // "/admin/users"
117
+ * ```
118
+ */
119
+ basename?: string;
120
+
98
121
  /**
99
122
  * Enable performance metrics collection
100
123
  * When enabled, metrics are output to console and available via Server-Timing header
@@ -109,6 +132,21 @@ export interface RSCRouterOptions<TEnv = any> {
109
132
  */
110
133
  allowDebugManifest?: boolean;
111
134
 
135
+ /**
136
+ * DEVELOPMENT/TEST ONLY. Emit an `X-Rango-Cache` response header describing
137
+ * the cache status of the matched route, for use by testing primitives such
138
+ * as `assertCacheStatus`.
139
+ *
140
+ * Defaults to `false`. When neither this option nor the
141
+ * `RANGO_TEST_SIGNALS=1` environment flag is set, NO header is emitted and
142
+ * router output is byte-identical to the default.
143
+ *
144
+ * The header encodes per-segment (v1: coarse route-level) status keyed by the
145
+ * route NAME, e.g. `X-Rango-Cache: product.detail=hit`. Do NOT enable in
146
+ * production — it exposes internal cache decisions.
147
+ */
148
+ debugCacheSignal?: boolean;
149
+
112
150
  /**
113
151
  * Document component that wraps the entire application.
114
152
  *
@@ -335,27 +373,54 @@ export interface RSCRouterOptions<TEnv = any> {
335
373
  theme?: import("../theme/types.js").ThemeConfig | true;
336
374
 
337
375
  /**
338
- * URL patterns to register with the router.
376
+ * Default for whether the router wraps `transition()` segments in its own
377
+ * React `<ViewTransition>` boundary (experimental React only).
378
+ *
379
+ * - "auto" (default): every route/layout that opts in via `transition()`
380
+ * gets a router-owned cross-fade.
381
+ * - false: the router never places its own boundary. Routes that use
382
+ * `transition()` still drive navigation through startTransition (so loaders
383
+ * hold instead of flashing a skeleton) and still let consumer-placed
384
+ * `<ViewTransition>` elements animate — the router just contributes no
385
+ * cross-fade of its own. This is the "router triggers, you place the
386
+ * transitions" model.
339
387
  *
340
- * Alternative to calling `.routes()` method - allows passing patterns
341
- * directly in the config for a more concise setup.
388
+ * A per-segment `transition({ viewTransition })` overrides this default.
342
389
  *
343
390
  * @example
344
391
  * ```typescript
345
- * import { urls } from "@rangojs/router/server";
392
+ * // App-wide: drive + hold, but never auto-wrap. Place <ViewTransition>
393
+ * // yourself in components where you want a morph.
394
+ * const router = createRouter<AppEnv>({ viewTransition: false });
395
+ * ```
396
+ */
397
+ viewTransition?: "auto" | false;
398
+
399
+ /**
400
+ * URL patterns to register with the router.
346
401
  *
347
- * const urlpatterns = urls(({ path, layout }) => [
348
- * path("/", HomePage, { name: "home" }),
349
- * path("/about", AboutPage, { name: "about" }),
350
- * ]);
402
+ * Accepts either a `UrlPatterns` object from `urls()` or a builder function
403
+ * directly (urls() is called implicitly).
351
404
  *
352
- * const router = createRouter<AppEnv>({
405
+ * @example
406
+ * ```typescript
407
+ * // With urls()
408
+ * createRouter<AppEnv>({
353
409
  * document: Document,
354
410
  * urls: urlpatterns,
355
411
  * });
412
+ *
413
+ * // With builder function
414
+ * createRouter<AppEnv>({
415
+ * document: Document,
416
+ * urls: ({ path }) => [
417
+ * path("/", HomePage, { name: "home" }),
418
+ * path("/about", AboutPage, { name: "about" }),
419
+ * ],
420
+ * });
356
421
  * ```
357
422
  */
358
- urls?: UrlPatterns<TEnv, any>;
423
+ urls?: UrlPatterns<TEnv, any> | UrlBuilder<TEnv>;
359
424
 
360
425
  /**
361
426
  * Injected by the Vite transform at compile time.
@@ -431,6 +496,21 @@ export interface RSCRouterOptions<TEnv = any> {
431
496
  */
432
497
  prefetchCacheTTL?: number | false;
433
498
 
499
+ /**
500
+ * Prefix for the rango state cookie name. The resolved name is
501
+ * `{prefix}_{routerId}`; the prefix is sanitized to cookie-name-safe
502
+ * characters (`[A-Za-z0-9-]`) and an empty result falls back to the default.
503
+ *
504
+ * The rango state cookie keys the client's prefetch / HTTP caches. Overriding
505
+ * the prefix lets you align it with cookie-naming policies or consent-manager
506
+ * classification lists, or avoid colliding with an existing `rango-state`
507
+ * cookie. It is not a full-name override: the `_{routerId}` suffix is what
508
+ * keeps sibling apps on one origin from clobbering each other's state.
509
+ *
510
+ * @default "rango-state"
511
+ */
512
+ stateCookiePrefix?: string;
513
+
434
514
  /**
435
515
  * Enable connection warmup to keep TCP+TLS alive after idle periods.
436
516
  *
@@ -1,4 +1,4 @@
1
- import type { RSCRouterInternal } from "./router-interfaces.js";
1
+ import type { RangoInternal } from "./router-interfaces.js";
2
2
 
3
3
  /**
4
4
  * Brand marker for identifying router instances at build time.
@@ -12,10 +12,7 @@ export const RSC_ROUTER_BRAND = "__rsc_router__" as const;
12
12
  * Used by the Vite plugin at build time to discover routers and extract
13
13
  * manifests, prefix trees, and pre-render candidates.
14
14
  */
15
- export const RouterRegistry: Map<
16
- string,
17
- RSCRouterInternal<any, any>
18
- > = new Map();
15
+ export const RouterRegistry: Map<string, RangoInternal<any, any>> = new Map();
19
16
 
20
17
  export let routerAutoId = 0;
21
18
 
@@ -27,53 +27,16 @@ import {
27
27
  tryStaticSlot,
28
28
  resolveLayoutComponent,
29
29
  resolveWithErrorBoundary,
30
+ warnOnStreamedResponse,
30
31
  } from "./helpers.js";
32
+ import { applyViewTransitionDefault } from "./view-transition-default.js";
31
33
  import { getRouterContext } from "../router-context.js";
32
- import { resolveSink, safeEmit } from "../telemetry.js";
33
- import { track, RSCRouterContext } from "../../server/context.js";
34
-
35
- // ---------------------------------------------------------------------------
36
- // Streamed handler telemetry
37
- // ---------------------------------------------------------------------------
38
-
39
- /**
40
- * Attach a fire-and-forget rejection observer to a streamed handler promise.
41
- * React catches the actual error via its error boundary; this only emits
42
- * the handler.error telemetry event.
43
- */
44
- function observeStreamedHandler(
45
- promise: Promise<ReactNode>,
46
- segmentId: string,
47
- segmentType: string,
48
- pathname?: string,
49
- routeKey?: string,
50
- params?: Record<string, string>,
51
- ): void {
52
- let routerCtx;
53
- try {
54
- routerCtx = getRouterContext();
55
- } catch {
56
- return;
57
- }
58
- if (!routerCtx?.telemetry) return;
59
- const sink = resolveSink(routerCtx.telemetry);
60
- const reqId = routerCtx.requestId;
61
- promise.catch((err: unknown) => {
62
- const errorObj = err instanceof Error ? err : new Error(String(err));
63
- safeEmit(sink, {
64
- type: "handler.error",
65
- timestamp: performance.now(),
66
- requestId: reqId,
67
- segmentId,
68
- segmentType,
69
- error: errorObj,
70
- handledByBoundary: true,
71
- pathname,
72
- routeKey,
73
- params,
74
- });
75
- });
76
- }
34
+ import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
35
+ import {
36
+ track,
37
+ RangoContext,
38
+ runInsideLoaderScope,
39
+ } from "../../server/context.js";
77
40
 
78
41
  // ---------------------------------------------------------------------------
79
42
  // Fresh path (full match, no revalidation)
@@ -112,7 +75,9 @@ export async function resolveLoaders<TEnv>(
112
75
  params: ctx.params,
113
76
  loaderId: loader.$$id,
114
77
  loaderData: deps.wrapLoaderPromise(
115
- resolveLoaderData(loaderEntry, ctx, ctx.pathname),
78
+ runInsideLoaderScope(() =>
79
+ resolveLoaderData(loaderEntry, ctx, ctx.pathname),
80
+ ),
116
81
  entry,
117
82
  segmentId,
118
83
  ctx.pathname,
@@ -126,16 +91,32 @@ export async function resolveLoaders<TEnv>(
126
91
 
127
92
  // Loading disabled: still start all loaders in parallel, but only emit
128
93
  // settled promises so handlers don't stream loading placeholders.
129
- const pendingLoaderData = loaderEntries.map((loaderEntry) => {
94
+ //
95
+ // Wrap each loader promise with wrapLoaderPromise BEFORE awaiting. The wrapped
96
+ // promise resolves to a LoaderDataResult and never rejects, routing a failed
97
+ // loader to its own per-loader error boundary. Awaiting the RAW promises here
98
+ // instead would (1) propagate a rejection to the segment-level boundary,
99
+ // collapsing the whole entry and discarding successful sibling data, and
100
+ // (2) leave the other in-flight raw promises without a .catch, producing
101
+ // unhandled rejections. Mirrors the loading path and intercept-resolution.
102
+ const pendingLoaderData = loaderEntries.map((loaderEntry, i) => {
103
+ const { loader } = loaderEntry;
104
+ const segmentId = `${shortCode}D${i}.${loader.$$id}`;
130
105
  const start = performance.now();
131
- const promise = resolveLoaderData(loaderEntry, ctx, ctx.pathname);
132
- return { promise, start, loaderId: loaderEntry.loader.$$id };
106
+ const wrapped = deps.wrapLoaderPromise(
107
+ runInsideLoaderScope(() =>
108
+ resolveLoaderData(loaderEntry, ctx, ctx.pathname),
109
+ ),
110
+ entry,
111
+ segmentId,
112
+ ctx.pathname,
113
+ );
114
+ return { wrapped, start, segmentId, loaderId: loader.$$id };
133
115
  });
134
- await Promise.all(pendingLoaderData.map((p) => p.promise));
116
+ await Promise.all(pendingLoaderData.map((p) => p.wrapped));
135
117
 
136
118
  return loaderEntries.map((loaderEntry, i) => {
137
119
  const { loader } = loaderEntry;
138
- const segmentId = `${shortCode}D${i}.${loader.$$id}`;
139
120
  const pending = pendingLoaderData[i]!;
140
121
  if (ms && !ms.metrics.some((m) => m.label === `loader:${loader.$$id}`)) {
141
122
  // All loaders ran in parallel via Promise.all — each span covers
@@ -151,19 +132,14 @@ export async function resolveLoaders<TEnv>(
151
132
  );
152
133
  }
153
134
  return {
154
- id: segmentId,
135
+ id: pending.segmentId,
155
136
  namespace: entry.id,
156
137
  type: "loader" as const,
157
138
  index: i,
158
139
  component: null,
159
140
  params: ctx.params,
160
141
  loaderId: loader.$$id,
161
- loaderData: deps.wrapLoaderPromise(
162
- pending.promise,
163
- entry,
164
- segmentId,
165
- ctx.pathname,
166
- ),
142
+ loaderData: pending.wrapped,
167
143
  belongsToRoute,
168
144
  };
169
145
  });
@@ -216,7 +192,10 @@ export async function resolveSegment<TEnv>(
216
192
  index: 0,
217
193
  component,
218
194
  loading: entry.loading === false ? null : entry.loading,
219
- transition: entry.transition,
195
+ transition: applyViewTransitionDefault(
196
+ entry.transition,
197
+ deps.viewTransitionDefault,
198
+ ),
220
199
  params,
221
200
  belongsToRoute: false,
222
201
  layoutName: entry.id,
@@ -276,10 +255,16 @@ export async function resolveSegment<TEnv>(
276
255
  entry.shortCode,
277
256
  );
278
257
  if (component === undefined) {
258
+ // For Passthrough routes at runtime, use the live handler instead of
259
+ // the build handler. At build time (context.build === true), always
260
+ // use the build handler from entry.handler.
261
+ const handler =
262
+ !context.build && entry.liveHandler ? entry.liveHandler : entry.handler;
279
263
  const doneRouteHandler = track(`handler:${entry.id}`, 2);
280
264
  if (entry.loading) {
281
- const result = handleHandlerResult(entry.handler(context));
265
+ const result = handleHandlerResult(handler(context));
282
266
  if (result instanceof Promise) {
267
+ warnOnStreamedResponse(result, entry.id);
283
268
  result.finally(doneRouteHandler).catch(() => {});
284
269
  const tracked = deps.trackHandler(result, {
285
270
  segmentId: entry.shortCode,
@@ -299,7 +284,7 @@ export async function resolveSegment<TEnv>(
299
284
  component = result;
300
285
  }
301
286
  } else {
302
- component = handleHandlerResult(await entry.handler(context));
287
+ component = handleHandlerResult(await handler(context));
303
288
  doneRouteHandler();
304
289
  }
305
290
  }
@@ -314,6 +299,7 @@ export async function resolveSegment<TEnv>(
314
299
  deps,
315
300
  options,
316
301
  routeKey,
302
+ entry,
317
303
  );
318
304
  segments.push(...orphanSegments);
319
305
  }
@@ -345,7 +331,10 @@ export async function resolveSegment<TEnv>(
345
331
  index: 0,
346
332
  component: component ?? null,
347
333
  loading: entry.loading === false ? null : entry.loading,
348
- transition: entry.transition,
334
+ transition: applyViewTransitionDefault(
335
+ entry.transition,
336
+ deps.viewTransitionDefault,
337
+ ),
349
338
  params,
350
339
  belongsToRoute: true,
351
340
  ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
@@ -369,6 +358,9 @@ export async function resolveOrphanLayout<TEnv>(
369
358
  deps: SegmentResolutionDeps<TEnv>,
370
359
  options?: ResolveSegmentOptions,
371
360
  routeKey?: string,
361
+ /** Parent route entry — its loaders are inherited by the layout so
362
+ * parallel slots inside this layout can access them via useLoader(). */
363
+ parentRouteEntry?: EntryData,
372
364
  ): Promise<ResolvedSegment[]> {
373
365
  invariant(
374
366
  orphan.type === "layout" || orphan.type === "cache",
@@ -384,6 +376,30 @@ export async function resolveOrphanLayout<TEnv>(
384
376
  deps,
385
377
  );
386
378
  segments.push(...loaderSegments);
379
+
380
+ // Inherit parent route's loaders so parallel slots inside this layout
381
+ // can access them via useLoader(). Without this, the route's loaders
382
+ // are only in the route's OutletProvider (rendered as <Outlet /> content),
383
+ // which is a child — not a parent — of the layout's context.
384
+ if (
385
+ parentRouteEntry &&
386
+ parentRouteEntry.loader &&
387
+ parentRouteEntry.loader.length > 0 &&
388
+ Object.keys(orphan.parallel).length > 0
389
+ ) {
390
+ const inheritedLoaders = await resolveLoaders(
391
+ parentRouteEntry,
392
+ context,
393
+ belongsToRoute,
394
+ deps,
395
+ orphan.shortCode,
396
+ );
397
+ // Tag as inherited so buildMatchResult can deduplicate when safe
398
+ for (const s of inheritedLoaders) {
399
+ s._inherited = true;
400
+ }
401
+ segments.push(...inheritedLoaders);
402
+ }
387
403
  }
388
404
 
389
405
  // Handler-first: orphan layout handler executes before its parallels
@@ -402,7 +418,10 @@ export async function resolveOrphanLayout<TEnv>(
402
418
  belongsToRoute,
403
419
  layoutName: orphan.id,
404
420
  loading: orphan.loading === false ? null : orphan.loading,
405
- transition: orphan.transition,
421
+ transition: applyViewTransitionDefault(
422
+ orphan.transition,
423
+ deps.viewTransitionDefault,
424
+ ),
406
425
  ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
407
426
  });
408
427
 
@@ -474,6 +493,14 @@ export async function resolveParallelEntry<TEnv>(
474
493
  if (handler === undefined) {
475
494
  continue;
476
495
  }
496
+ // Pin `_currentSegmentId` to the slot's own id so handle pushes from
497
+ // inside the slot handler get their own bucket in the HandleStore.
498
+ // Parent-keying would collapse them into the parent layout's bucket;
499
+ // the partial-update merge then replaces the parent's bucket on a
500
+ // slot-only revalidation and drops layout-pushed Meta/Breadcrumbs.
501
+ // filterSegmentOrder() retains slot ids so the client preserves them.
502
+ (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
503
+ `${parentShortCode}.${slot}`;
477
504
  const doneParallelHandler = track(
478
505
  `handler:${parallelEntry.id}.${slot}`,
479
506
  2,
@@ -516,7 +543,10 @@ export async function resolveParallelEntry<TEnv>(
516
543
  index: 0,
517
544
  component,
518
545
  loading: parallelEntry.loading === false ? null : parallelEntry.loading,
519
- transition: parallelEntry.transition,
546
+ transition: applyViewTransitionDefault(
547
+ parallelEntry.transition,
548
+ deps.viewTransitionDefault,
549
+ ),
520
550
  params,
521
551
  slot,
522
552
  belongsToRoute,
@@ -583,7 +613,7 @@ export async function resolveAllSegments<TEnv>(
583
613
  // can guard non-cacheable variable reads. Also guards response-level
584
614
  // side effects (headers.set). Persists for all descendant entries.
585
615
  if (entry.type === "cache") {
586
- const store = RSCRouterContext.getStore();
616
+ const store = RangoContext.getStore();
587
617
  if (store) store.insideCacheScope = true;
588
618
  }
589
619
  const doneEntry = track(`segment:${entry.id}`, 1);
@@ -672,6 +702,30 @@ export async function resolveLoadersOnly<TEnv>(
672
702
  const childBelongsToRoute = belongsToRoute || entry.type === "route";
673
703
  for (const layoutEntry of entry.layout) {
674
704
  await collectEntryLoaders(layoutEntry, childBelongsToRoute);
705
+ // Inherit route loaders for orphan layouts with parallels.
706
+ // Resolve directly — do NOT re-enter collectEntryLoaders with the
707
+ // route entry, as that would re-iterate route.layout and loop.
708
+ if (
709
+ entry.type === "route" &&
710
+ entry.loader &&
711
+ entry.loader.length > 0 &&
712
+ Object.keys(layoutEntry.parallel).length > 0
713
+ ) {
714
+ const inherited = await resolveLoaders(
715
+ entry,
716
+ context,
717
+ childBelongsToRoute,
718
+ deps,
719
+ layoutEntry.shortCode,
720
+ );
721
+ for (const seg of inherited) {
722
+ if (!seenIds.has(seg.id)) {
723
+ seenIds.add(seg.id);
724
+ seg._inherited = true;
725
+ loaderSegments.push(seg);
726
+ }
727
+ }
728
+ }
675
729
  }
676
730
  }
677
731
 
@@ -52,6 +52,40 @@ export function handleHandlerResult(
52
52
  return result;
53
53
  }
54
54
 
55
+ /**
56
+ * Dev-only: warn when a handler on a route that declares loading() resolves or
57
+ * rejects with a Response (e.g. redirect()).
58
+ *
59
+ * On a non-loading route a returned/thrown Response short-circuits to an HTTP
60
+ * redirect. But when the route declares loading(), the handler result is
61
+ * streamed (not awaited at the resolution boundary), so the Response surfaces
62
+ * only during RSC serialization and is rendered into the stream instead of
63
+ * becoming a 302/308 — a silent failure mode. Issue redirects from middleware,
64
+ * a loader, or a synchronous handler return instead. Compiled out in production.
65
+ */
66
+ export function warnOnStreamedResponse(
67
+ result: Promise<unknown>,
68
+ entryId: string,
69
+ ): void {
70
+ if (process.env.NODE_ENV === "production") return;
71
+ // A Response can surface either as a rejection (handleHandlerResult rethrows a
72
+ // resolved Response) or as a resolved value (the raw parallel-slot handler is
73
+ // not run through handleHandlerResult). Check both so every streamed path is
74
+ // covered. Each handler is an independent observer; it does not consume the
75
+ // rejection for the trackHandler/observeStreamedHandler chains.
76
+ const check = (value: unknown) => {
77
+ if (value instanceof Response) {
78
+ console.warn(
79
+ `[rango] Handler for "${entryId}" returned a Response (e.g. ` +
80
+ `redirect()), but it declares loading(): the Response is rendered ` +
81
+ `into the RSC stream, NOT sent as an HTTP redirect. Issue redirects ` +
82
+ `from middleware, a loader, or a synchronous handler return.`,
83
+ );
84
+ }
85
+ };
86
+ result.then(check, check);
87
+ }
88
+
55
89
  // ---------------------------------------------------------------------------
56
90
  // Static handler interception
57
91
  // ---------------------------------------------------------------------------
@@ -8,7 +8,7 @@
8
8
  * Cache key resolution (3-tier, matching CacheScope.resolveKey):
9
9
  * 1. options.key(requestCtx) — full override
10
10
  * 2. store.keyGenerator(requestCtx, defaultKey) — store-level modification
11
- * 3. loader:{loaderId}:{pathname}:{sortedParams} — default
11
+ * 3. loader:{loaderId}:{host}{pathname}:{sortedParams} — default
12
12
  *
13
13
  * Values are serialized via RSC Flight (serializeResult/deserializeResult),
14
14
  * supporting ReactNode, Promises, null, and all RSC-serializable types.
@@ -19,7 +19,7 @@
19
19
  */
20
20
 
21
21
  import type { LoaderEntry } from "../../server/context.js";
22
- import type { HandlerContext } from "../../types.js";
22
+ import type { HandlerContext, InternalHandlerContext } from "../../types.js";
23
23
  import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
24
24
  import { getRequestContext } from "../../server/request-context.js";
25
25
  import { sortedRouteParams } from "../../cache/cache-key-utils.js";
@@ -28,9 +28,11 @@ import {
28
28
  resolveSwrWindow,
29
29
  resolveCacheKey,
30
30
  resolveCacheStore,
31
+ resolveTagsOption,
31
32
  DEFAULT_ROUTE_TTL,
32
33
  } from "../../cache/cache-policy.js";
33
34
  import { readThroughItem } from "../../cache/read-through-swr.js";
35
+ import { recordRequestTags } from "../../cache/cache-tag.js";
34
36
  // Lazy-loaded to avoid pulling @vitejs/plugin-rsc/rsc into modules that
35
37
  // import segment-resolution but never use loader caching.
36
38
  let _serializeResult: typeof import("../../cache/segment-codec.js").serializeResult;
@@ -55,12 +57,13 @@ function debugLoaderCacheLog(message: string): void {
55
57
 
56
58
  function getDefaultLoaderCacheKey(
57
59
  loaderId: string,
60
+ host: string,
58
61
  pathname: string,
59
62
  params: Record<string, string>,
60
63
  ): string {
61
64
  const paramStr = sortedRouteParams(params);
62
65
  const base = paramStr ? `${pathname}:${paramStr}` : pathname;
63
- return `loader:${loaderId}:${base}`;
66
+ return `loader:${loaderId}:${host}${base}`;
64
67
  }
65
68
 
66
69
  /**
@@ -74,7 +77,13 @@ async function resolveLoaderKey(
74
77
  params: Record<string, string>,
75
78
  ): Promise<string> {
76
79
  const options = loaderEntry.cache!.options;
77
- const defaultKey = getDefaultLoaderCacheKey(loaderId, pathname, params);
80
+ // The host is part of the loader cache identity, matching the route-level
81
+ // cache (cache-scope getCacheKeyBase: `${host}${pathname}`) and "use cache"
82
+ // (cache-runtime pushes ctx.url.host). Without it, a multi-tenant host router
83
+ // serving the same pathname for different hosts would leak one host's cached
84
+ // loader data to another.
85
+ const host = getRequestContext()?.url?.host ?? "localhost";
86
+ const defaultKey = getDefaultLoaderCacheKey(loaderId, host, pathname, params);
78
87
  if (options === false) return defaultKey;
79
88
  return resolveCacheKey(options.key, store, defaultKey, "LoaderCache");
80
89
  }
@@ -87,23 +96,8 @@ async function resolveLoaderKey(
87
96
  */
88
97
  function resolveTags(loaderEntry: LoaderEntry): string[] | undefined {
89
98
  const options = loaderEntry.cache?.options;
90
- if (!options || !options.tags) return undefined;
91
-
92
- if (typeof options.tags === "function") {
93
- const requestCtx = getRequestContext();
94
- if (!requestCtx) return undefined;
95
- try {
96
- return options.tags(requestCtx);
97
- } catch (error) {
98
- console.error(
99
- `[LoaderCache] Tags function failed, caching without tags:`,
100
- error,
101
- );
102
- return undefined;
103
- }
104
- }
105
-
106
- return options.tags;
99
+ if (!options) return undefined;
100
+ return resolveTagsOption(options.tags, getRequestContext(), "LoaderCache");
107
101
  }
108
102
 
109
103
  function getLoaderStore(
@@ -152,11 +146,30 @@ export function resolveLoaderData<TEnv>(
152
146
  const swrWindow = resolveSwrWindow(options.swr, store.defaults);
153
147
  const swr = swrWindow || undefined;
154
148
  const tags = resolveTags(loaderEntry);
149
+ recordRequestTags(tags);
150
+
151
+ // A handler that later awaits this same loader via ctx.use(loader) must get
152
+ // THIS memoized promise, not a fresh execution. Rather than rebind ctx.use
153
+ // once per cached loader (O(N) chained wrappers + a synchronous
154
+ // capture-before-overwrite invariant), install a single stable interceptor on
155
+ // the first cached loader that consults a per-ctx override table, then just
156
+ // prime the table for each subsequent cached loader. The captured pre-
157
+ // interceptor `originalUse` (whatever setup mode installed it) runs the
158
+ // cache-miss execute, so a loader never awaits its own in-flight promise.
159
+ const internal = ctx as InternalHandlerContext<any, TEnv>;
160
+ let overrides = internal._loaderCacheOverrides;
161
+ if (!overrides) {
162
+ overrides = internal._loaderCacheOverrides = new Map();
163
+ const originalUse = ctx.use;
164
+ internal._loaderCacheOriginalUse = originalUse;
165
+ ctx.use = ((item: any) => {
166
+ const cached = overrides!.get(item?.$$id);
167
+ if (cached) return cached;
168
+ return originalUse(item);
169
+ }) as typeof ctx.use;
170
+ }
171
+ const runMiss = internal._loaderCacheOriginalUse!;
155
172
 
156
- // Wrap ctx.use() so cache HIT primes the handler's memoization map.
157
- // ctx.use() closes over the match context's loaderPromises (not request context's).
158
- // By intercepting ctx.use(), we inject cached data into the correct map.
159
- const originalUse = ctx.use;
160
173
  const dataPromise = (async () => {
161
174
  const codec = await getCodec();
162
175
  const key = await resolveLoaderKey(
@@ -171,7 +184,7 @@ export function resolveLoaderData<TEnv>(
171
184
  getItem: (k) => store.getItem!(k),
172
185
  setItem: (k, v, o) => store.setItem!(k, v, o),
173
186
  key,
174
- execute: () => originalUse(loaderEntry.loader),
187
+ execute: () => runMiss(loaderEntry.loader),
175
188
  serialize: (d) => codec.serializeResult(d),
176
189
  deserialize: (v) => codec.deserializeResult(v),
177
190
  storeOptions: { ttl, swr, tags },
@@ -183,17 +196,7 @@ export function resolveLoaderData<TEnv>(
183
196
  });
184
197
  })();
185
198
 
186
- // Temporarily replace ctx.use() so the handler's call returns cached data.
187
- // This is needed because ctx.use() closes over the match context's loaderPromises
188
- // map which is separate from the request context. By wrapping use(), we intercept
189
- // the handler's call and return the shared dataPromise.
190
- const wrappedUse = ((item: any) => {
191
- if (item === loaderEntry.loader || item?.$$id === loaderId) {
192
- return dataPromise;
193
- }
194
- return originalUse(item);
195
- }) as typeof ctx.use;
196
- ctx.use = wrappedUse;
199
+ overrides.set(loaderId, dataPromise);
197
200
 
198
201
  return dataPromise;
199
202
  }