@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
@@ -1,25 +1,72 @@
1
1
  /**
2
2
  * Prefetch Cache
3
3
  *
4
- * In-memory cache storing prefetched Response objects for instant cache hits
5
- * on subsequent navigation. Cache key is source-dependent (includes the
6
- * current page URL) because the server's diff-based response depends on
7
- * where the user navigates from.
4
+ * In-memory cache storing eagerly-decoded prefetch payloads for instant,
5
+ * already-warm cache hits on subsequent navigation. A prefetch fetches the
6
+ * RSC partial AND decodes it (createFromFetch) up front — decoding the Flight
7
+ * stream resolves the route's client references, so the route's JS chunks are
8
+ * imported during prefetch rather than on click. The decoded payload is reused
9
+ * verbatim by navigation, so a prefetched click loads no new code. Two key
10
+ * scopes are in play:
11
+ * - Wildcard (default): built by `buildPrefetchKey(rangoState, target)` —
12
+ * shape `rangoState\0/target?...`. Shared across all source pages and
13
+ * invalidated automatically when Rango state bumps (deploy or
14
+ * server-action invalidation).
15
+ * - Source-scoped: built by `buildSourceKey(rangoState, sourceHref, target)`
16
+ * — shape `rangoState\0sourceHref\0/target?...`. Embeds the Rango state
17
+ * (so rotation invalidates source-scoped entries too) plus the source
18
+ * href (so each originating page gets its own slot). Populated when the
19
+ * server tags a response with `X-RSC-Prefetch-Scope: source` (intercept
20
+ * modals etc.), OR when a Link opts in with `prefetchKey=":source"` — in
21
+ * both cases so source-sensitive responses cannot bleed into navigations
22
+ * from other pages.
8
23
  *
9
24
  * Also tracks in-flight prefetch promises. Each promise resolves to the
10
- * navigation branch of a tee'd Response, allowing navigation to adopt a
11
- * still-downloading prefetch without reparsing or buffering the body.
25
+ * decoded prefetch entry (or null), letting navigation adopt a
26
+ * still-downloading prefetch without issuing a duplicate request. A
27
+ * single promise can be registered under multiple alias keys (see
28
+ * `setInflightPromiseWithAliases`) so same-source navigations adopt via
29
+ * their source key while cross-source ones fall through to the wildcard
30
+ * alias — with consume/clear atomically removing every alias.
12
31
  *
13
32
  * Replaces the previous browser HTTP cache approach which was unreliable
14
33
  * due to response draining race conditions and browser inconsistencies.
34
+ *
35
+ * State here lives in module-level singletons (cache, inflight, generation,
36
+ * cacheTTL, etc.) rather than a per-instance factory. This is correct because
37
+ * exactly one router is live per document — an SPA navigation crossing a
38
+ * host-router boundary forces a full document reload — so the singletons are
39
+ * effectively per-document. Unit tests reset them via clearPrefetchCache().
15
40
  */
16
41
 
17
42
  import { abortAllPrefetches } from "./queue.js";
18
43
  import { invalidateRangoState } from "../rango-state.js";
44
+ import type { RscPayload } from "../types.js";
45
+
46
+ /**
47
+ * A prefetch that has been fetched AND eagerly decoded. Storing the decoded
48
+ * payload (not the raw Response) is what makes a prefetched navigation "warm":
49
+ * decoding the Flight stream during prefetch pulls the route's client chunks,
50
+ * so the click reuses ready elements and loads no new JS.
51
+ */
52
+ export interface DecodedPrefetch {
53
+ /** The eagerly-decoded RSC payload. Reused verbatim by navigation. */
54
+ payload: Promise<RscPayload>;
55
+ /**
56
+ * Resolves when the underlying RSC stream finishes draining. Navigation
57
+ * forwards this as its streamComplete so scroll/revalidation gating is
58
+ * unchanged from the fresh-fetch path.
59
+ */
60
+ streamComplete: Promise<void>;
61
+ /**
62
+ * Prefetch scope as tagged by the server via `X-RSC-Prefetch-Scope`.
63
+ * `"source"` means the response is source-page-sensitive and must not be
64
+ * reused by a navigation from a different page — navigation enforces this
65
+ * when it adopted an inflight entry through the wildcard key.
66
+ */
67
+ scope: "source" | "wildcard";
68
+ }
19
69
 
20
- // Default TTL: 5 minutes. Overridden by initPrefetchCache() with
21
- // the server-configured prefetchCacheTTL from router options.
22
- // 0 disables the in-memory cache entirely.
23
70
  let cacheTTL = 300_000;
24
71
 
25
72
  /**
@@ -41,33 +88,73 @@ export function isPrefetchCacheDisabled(): boolean {
41
88
  const MAX_PREFETCH_CACHE_SIZE = 50;
42
89
 
43
90
  interface PrefetchCacheEntry {
44
- response: Response;
91
+ entry: DecodedPrefetch;
45
92
  timestamp: number;
46
93
  }
47
94
 
48
95
  const cache = new Map<string, PrefetchCacheEntry>();
49
96
  const inflight = new Set<string>();
50
97
 
98
+ const inflightPromises = new Map<string, Promise<DecodedPrefetch | null>>();
99
+
100
+ const inflightAliases = new Map<string, string[]>();
101
+
102
+ const adoptedKeys = new Set<string>();
103
+
104
+ let generation = 0;
105
+
51
106
  /**
52
- * In-flight promise map. When a prefetch fetch is in progress, its
53
- * Promise<Response | null> is stored here so navigation can await
54
- * it instead of starting a duplicate request.
107
+ * Build a cache key by combining a scope prefix with the target URL.
108
+ *
109
+ * Low-level primitive — callers that want a specific scope should use
110
+ * one of:
111
+ * - Wildcard (source-agnostic): prefix is the Rango state value from
112
+ * `getRangoState()`. Shared across all source pages. Invalidated
113
+ * automatically when Rango state bumps (deploy or server-action).
114
+ * Key shape: `rangoState\0/target?...`.
115
+ * - Source-scoped: use `buildSourceKey()`. Key shape:
116
+ * `rangoState\0sourceHref\0/target?...` — embeds the Rango state so
117
+ * rotation invalidates source-scoped entries alongside wildcard ones,
118
+ * plus the source page href so the key is unique per originating page.
119
+ * Populated either when the server tags a response with
120
+ * `X-RSC-Prefetch-Scope: source` (intercept modals, etc.) or when a
121
+ * Link opts in via `prefetchKey=":source"`.
122
+ *
123
+ * The `_rsc_segments` query param that travels in the target URL means
124
+ * clients with different mounted segment trees naturally get different
125
+ * keys — so segment-level diffs remain consistent across both scopes.
55
126
  */
56
- const inflightPromises = new Map<string, Promise<Response | null>>();
127
+ export function buildPrefetchKey(prefix: string, targetUrl: URL): string {
128
+ return prefix + "\0" + targetUrl.pathname + targetUrl.search;
129
+ }
57
130
 
58
- // Generation counter incremented on each clearPrefetchCache(). Fetches that
59
- // started before a clear carry a stale generation and must not store their
60
- // response (the data may be stale due to a server action invalidation).
61
- let generation = 0;
131
+ /**
132
+ * Build a source-scoped cache key. Key shape:
133
+ * `rangoState\0sourceHref\0/target?...`.
134
+ *
135
+ * - `rangoState` is included so state rotation invalidates source-scoped
136
+ * entries alongside wildcard ones.
137
+ * - `sourceHref` makes the key unique per originating page.
138
+ */
139
+ export function buildSourceKey(
140
+ rangoState: string,
141
+ sourceHref: string,
142
+ targetUrl: URL,
143
+ ): string {
144
+ return buildPrefetchKey(rangoState + "\0" + sourceHref, targetUrl);
145
+ }
62
146
 
63
147
  /**
64
- * Build a source-dependent cache key.
65
- * Includes the source page href so the same target prefetched from
66
- * different pages gets separate entries — the server response varies
67
- * based on the source page context (diff-based rendering).
148
+ * Walk an inflight key plus any sibling aliases registered via
149
+ * `setInflightPromiseWithAliases`, invoking `fn` for each.
68
150
  */
69
- export function buildPrefetchKey(sourceHref: string, targetUrl: URL): string {
70
- return sourceHref + "\0" + targetUrl.pathname + targetUrl.search;
151
+ function forEachAlias(key: string, fn: (k: string) => void): void {
152
+ const aliases = inflightAliases.get(key);
153
+ if (aliases) {
154
+ for (const k of aliases) fn(k);
155
+ } else {
156
+ fn(key);
157
+ }
71
158
  }
72
159
 
73
160
  /**
@@ -86,14 +173,14 @@ export function hasPrefetch(key: string): boolean {
86
173
  }
87
174
 
88
175
  /**
89
- * Consume a cached prefetch response. Returns null if not found or expired.
90
- * One-time consumption: the entry is deleted after retrieval.
176
+ * Consume a cached, eagerly-decoded prefetch. Returns null if not found or
177
+ * expired. One-time consumption: the entry is deleted after retrieval.
91
178
  * Returns null when caching is disabled (TTL <= 0).
92
179
  *
93
180
  * Does NOT check in-flight prefetches — use consumeInflightPrefetch()
94
- * for that (returns a Promise instead of a Response).
181
+ * for that (returns a Promise instead of a resolved entry).
95
182
  */
96
- export function consumePrefetch(key: string): Response | null {
183
+ export function consumePrefetch(key: string): DecodedPrefetch | null {
97
184
  if (cacheTTL <= 0) return null;
98
185
  const entry = cache.get(key);
99
186
  if (!entry) return null;
@@ -102,52 +189,72 @@ export function consumePrefetch(key: string): Response | null {
102
189
  return null;
103
190
  }
104
191
  cache.delete(key);
105
- return entry.response;
192
+ return entry.entry;
106
193
  }
107
194
 
108
195
  /**
109
196
  * Consume an in-flight prefetch promise. Returns null if no prefetch is
110
- * in-flight for this key. The returned Promise resolves to the buffered
111
- * Response (or null if the fetch failed/was aborted).
197
+ * in-flight for this key. The returned Promise resolves to the decoded
198
+ * prefetch entry (or null if the fetch failed/was aborted, or carried a
199
+ * control header the navigation must re-fetch to honor).
112
200
  *
113
- * One-time consumption: the promise entry is removed so a second call
114
- * returns null. The `inflight` set entry is intentionally kept so that
115
- * hasPrefetch() continues to return true while the underlying fetch is
116
- * still downloading — this prevents prefetchDirect() or other callers
117
- * from starting a duplicate request during the handoff window. The
118
- * inflight flag is cleaned up naturally by clearPrefetchInflight() in
119
- * the fetch's .finally().
201
+ * One-time consumption: the promise entry is removed (along with any
202
+ * sibling aliases registered via `setInflightPromiseWithAliases`) so a
203
+ * second call on any alias returns null — only one caller can adopt the
204
+ * shared Response stream. The `inflight` set entry is intentionally
205
+ * kept so that `hasPrefetch()` continues to return true while the
206
+ * underlying fetch is still downloading — this prevents
207
+ * `prefetchDirect()` or other callers from starting a duplicate request
208
+ * during the handoff window. The inflight flag is cleaned up naturally
209
+ * by `clearPrefetchInflight()` in the fetch's `.finally()`.
120
210
  */
121
211
  export function consumeInflightPrefetch(
122
212
  key: string,
123
- ): Promise<Response | null> | null {
213
+ ): Promise<DecodedPrefetch | null> | null {
124
214
  const promise = inflightPromises.get(key);
125
215
  if (!promise) return null;
126
- // Remove the promise (one-time consumption) but keep the inflight flag.
127
- inflightPromises.delete(key);
216
+ // Remove the promise under every alias so a second consumer cannot
217
+ // adopt the same stream and race on the body, and mark every alias as
218
+ // adopted so the pending `storePrefetch` (which resolves later, after this
219
+ // adoption) does not leave the now-owned, single-use entry in the cache map.
220
+ // `inflightAliases` is intentionally preserved — `clearPrefetchInflight()` in
221
+ // the fetch's `.finally()` still needs it to clear every inflight flag and
222
+ // adopted marker; deleting here would strand the sibling's flag forever.
223
+ forEachAlias(key, (k) => {
224
+ inflightPromises.delete(k);
225
+ adoptedKeys.add(k);
226
+ });
128
227
  return promise;
129
228
  }
130
229
 
131
230
  /**
132
- * Store a prefetch response in the in-memory cache.
133
- * The response should be a clone() of the original so the caller can
134
- * still consume the body. The clone's body streams independently.
231
+ * Store an eagerly-decoded prefetch in the in-memory cache.
135
232
  *
136
233
  * Skips storage if the generation has changed since the fetch started
137
234
  * (a server action invalidated the cache mid-flight).
138
235
  */
139
236
  export function storePrefetch(
140
237
  key: string,
141
- response: Response,
238
+ entry: DecodedPrefetch,
142
239
  fetchGeneration: number,
143
240
  ): void {
144
241
  if (cacheTTL <= 0) return;
145
242
  if (fetchGeneration !== generation) return;
146
243
 
244
+ // If a navigation already adopted this prefetch's in-flight promise, it owns
245
+ // the single-use entry (and has drained its handle generator). Do NOT also
246
+ // publish it to the cache map, or a later navigation would be served the
247
+ // exhausted entry and lose that route's handles. Clear the marker (under all
248
+ // aliases) now that the decision is made.
249
+ if (adoptedKeys.has(key)) {
250
+ forEachAlias(key, (k) => adoptedKeys.delete(k));
251
+ return;
252
+ }
253
+
147
254
  // Evict expired entries
148
255
  const now = Date.now();
149
- for (const [k, entry] of cache) {
150
- if (now - entry.timestamp > cacheTTL) {
256
+ for (const [k, cached] of cache) {
257
+ if (now - cached.timestamp > cacheTTL) {
151
258
  cache.delete(k);
152
259
  }
153
260
  }
@@ -158,7 +265,7 @@ export function storePrefetch(
158
265
  if (oldest) cache.delete(oldest);
159
266
  }
160
267
 
161
- cache.set(key, { response, timestamp: now });
268
+ cache.set(key, { entry, timestamp: now });
162
269
  }
163
270
 
164
271
  /**
@@ -173,33 +280,44 @@ export function markPrefetchInflight(key: string): void {
173
280
  inflight.add(key);
174
281
  }
175
282
 
176
- /**
177
- * Store the in-flight Promise for a prefetch so navigation can reuse it.
178
- */
179
283
  export function setInflightPromise(
180
284
  key: string,
181
- promise: Promise<Response | null>,
285
+ promise: Promise<DecodedPrefetch | null>,
182
286
  ): void {
183
287
  inflightPromises.set(key, promise);
184
288
  }
185
289
 
290
+ /**
291
+ * Store the same in-flight Promise under multiple keys, recording them
292
+ * as sibling aliases. Consuming or clearing any one alias atomically
293
+ * removes every entry, guaranteeing the shared Response stream has a
294
+ * single consumer even when navigation looks up either key.
295
+ */
296
+ export function setInflightPromiseWithAliases(
297
+ keys: string[],
298
+ promise: Promise<DecodedPrefetch | null>,
299
+ ): void {
300
+ for (const k of keys) {
301
+ inflightPromises.set(k, promise);
302
+ inflightAliases.set(k, keys);
303
+ }
304
+ }
305
+
186
306
  export function clearPrefetchInflight(key: string): void {
187
- inflight.delete(key);
188
- inflightPromises.delete(key);
307
+ forEachAlias(key, (k) => {
308
+ inflight.delete(k);
309
+ inflightPromises.delete(k);
310
+ inflightAliases.delete(k);
311
+ adoptedKeys.delete(k);
312
+ });
189
313
  }
190
314
 
191
- /**
192
- * Invalidate all prefetch state. Called when server actions mutate data.
193
- * Clears the in-memory cache, cancels in-flight prefetches, and rotates
194
- * the Rango state key so CDN-cached responses are also invalidated.
195
- *
196
- * Uses abortAllPrefetches (hard cancel) because in-flight responses
197
- * may contain stale data after a mutation.
198
- */
199
315
  export function clearPrefetchCache(): void {
200
316
  generation++;
201
317
  inflight.clear();
202
318
  inflightPromises.clear();
319
+ inflightAliases.clear();
320
+ adoptedKeys.clear();
203
321
  cache.clear();
204
322
  abortAllPrefetches();
205
323
  invalidateRangoState();