@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
@@ -4,8 +4,8 @@ import type {
4
4
  RscPayload,
5
5
  } from "./types.js";
6
6
  import { createPartialUpdater } from "./partial-update.js";
7
- import { createClientDebugChannel, DEBUG_ID_HEADER } from "./debug-channel.js";
8
- import { findSourceMapURL } from "../deps/browser.js";
7
+ import { enterActionFence, exitActionFence } from "./action-fence.js";
8
+ import { KEEP_CACHE_HEADER } from "./cookie-name.js";
9
9
  import { createNavigationTransaction } from "./navigation-transaction.js";
10
10
  import {
11
11
  reconcileSegments,
@@ -23,14 +23,20 @@ import {
23
23
  isBrowserDebugEnabled,
24
24
  startBrowserTransaction,
25
25
  } from "./logging.js";
26
- import { validateRedirectOrigin } from "./validate-redirect-origin.js";
26
+ import {
27
+ validateRedirectOrigin,
28
+ validateExternalRedirect,
29
+ } from "./validate-redirect-origin.js";
27
30
  import {
28
31
  extractRscHeaderUrl,
29
32
  emptyResponse,
33
+ handleReloadHeader,
30
34
  teeWithCompletion,
35
+ isForeignRouterId,
31
36
  } from "./response-adapter.js";
32
37
  import { mergeLocationState } from "./history-state.js";
33
38
  import { classifyActionOutcome } from "./action-coordinator.js";
39
+ import { getAppVersion } from "./app-version.js";
34
40
 
35
41
  // Polyfill Symbol.dispose/asyncDispose for Safari and older browsers
36
42
  if (typeof Symbol.dispose === "undefined") {
@@ -45,8 +51,6 @@ if (typeof Symbol.asyncDispose === "undefined") {
45
51
  */
46
52
  export interface ServerActionBridgeConfigWithController extends ServerActionBridgeConfig {
47
53
  eventController: EventController;
48
- /** RSC version from initial payload metadata */
49
- version?: string;
50
54
  /** Callback to trigger SPA navigation (for action redirects) */
51
55
  onNavigate?: (
52
56
  url: string,
@@ -77,10 +81,29 @@ export function createServerActionBridge(
77
81
  deps,
78
82
  onUpdate,
79
83
  renderSegments,
80
- version,
81
84
  onNavigate,
82
85
  } = config;
83
86
 
87
+ // SPA-navigate when onNavigate is set, else hard-reload. state is omitted (not
88
+ // passed as undefined) to match the header path's prior call shape.
89
+ // Callers pass an already same-origin-validated url; the hard-reload fallback
90
+ // re-validates defensively so this leaf cannot become an open redirect if a
91
+ // future caller forgets (the SPA path validates inside the navigation bridge).
92
+ async function dispatchRedirect(url: string, state?: unknown): Promise<void> {
93
+ if (onNavigate) {
94
+ await onNavigate(url, {
95
+ ...(state !== undefined ? { state } : {}),
96
+ replace: true,
97
+ _skipCache: true,
98
+ });
99
+ } else {
100
+ const safe = validateRedirectOrigin(url, window.location.origin);
101
+ if (safe) {
102
+ window.location.href = safe;
103
+ }
104
+ }
105
+ }
106
+
84
107
  let isRegistered = false;
85
108
 
86
109
  const fetchPartialUpdate = createPartialUpdater({
@@ -88,7 +111,7 @@ export function createServerActionBridge(
88
111
  client,
89
112
  onUpdate,
90
113
  renderSegments,
91
- version,
114
+ getVersion: getAppVersion,
92
115
  });
93
116
 
94
117
  /**
@@ -144,12 +167,52 @@ export function createServerActionBridge(
144
167
 
145
168
  // Start action in event controller - handles lifecycle tracking
146
169
  const handle = eventController.startAction(id, args);
170
+ // Whether the action's response carried the keepClientCache() directive.
171
+ // Set when the response arrives; gates the deferred invalidation below.
172
+ let keepCache = false;
173
+ // Whether a Response actually settled from the network (the server saw the
174
+ // request). Set true as the first statement in the fetch .then() below.
175
+ // Gates the automatic invalidation: a pre-dispatch failure (encodeReply
176
+ // throw or a fetch rejection — server unreachable/DNS/connection refused)
177
+ // leaves this false, so finalizeAction() must NOT invalidate or broadcast —
178
+ // nothing reached the server, so nothing could have mutated. A failed Flight
179
+ // DECODE after the response arrived keeps it true (the mutation may have
180
+ // committed, so invalidating the now-possibly-stale client cache is correct).
181
+ let responseReceived = false;
182
+ // Single deferred invalidation + fence release, run exactly ONCE however the
183
+ // action terminates (normal, redirect, error, abort, intercept, concurrent).
184
+ // This replaces main's eager clear at action start: every directive-free
185
+ // action invalidates once; keepClientCache() suppresses only the automatic
186
+ // invalidation, so a concurrent directive-free action still invalidates via
187
+ // its own latch. Latched so the finally AND the early SPA-redirect returns
188
+ // (whose Flight stream never settles) can both call it safely.
189
+ let actionFinalized = false;
190
+ // skipInvalidation: the version-mismatch reload terminal released nothing
191
+ // server-side, so it releases the fence without invalidating.
192
+ const finalizeAction = (skipInvalidation = false): void => {
193
+ if (actionFinalized) return;
194
+ actionFinalized = true;
195
+ // finally so a throw in invalidation cannot leak the fence (latch is set).
196
+ try {
197
+ // responseReceived gates the automatic invalidation: a pre-dispatch
198
+ // failure (serialize throw / fetch reject) never reached the server, so
199
+ // marking the cache stale + broadcasting cross-tab would be spurious.
200
+ if (responseReceived && !keepCache && !skipInvalidation) {
201
+ store.markCacheAsStaleAndBroadcast();
202
+ }
203
+ } finally {
204
+ exitActionFence();
205
+ }
206
+ };
147
207
  try {
148
208
  const segmentState = store.getSegmentState();
149
209
 
150
- // Mark cache as stale immediately when action starts
151
- // This ensures SWR pattern kicks in if user navigates away during action
152
- store.markCacheAsStaleAndBroadcast();
210
+ // Raise the action fence (replaces the old eager clear). Nothing is wiped,
211
+ // rotated, or broadcast yet: navigations during the flight fetch fresh
212
+ // (no-store) and popstate is treated as SWR, but the decision to
213
+ // invalidate is deferred to the response so a no-op action (keepClientCache)
214
+ // can leave the caches and the jar untouched.
215
+ enterActionFence();
153
216
 
154
217
  // Create temporary references for serialization
155
218
  const temporaryReferences = deps.createTemporaryReferenceSet();
@@ -167,9 +230,15 @@ export function createServerActionBridge(
167
230
  segmentState.currentSegmentIds.join(","),
168
231
  );
169
232
  // Add version param for version mismatch detection
233
+ const version = getAppVersion();
170
234
  if (version) {
171
235
  url.searchParams.set("_rsc_v", version);
172
236
  }
237
+ // Add router ID for app switch detection
238
+ const rid = store.getRouterId?.();
239
+ if (rid) {
240
+ url.searchParams.set("_rsc_rid", rid);
241
+ }
173
242
 
174
243
  // Encode arguments
175
244
  const encodedBody = await deps.encodeReply(args, { temporaryReferences });
@@ -201,14 +270,6 @@ export function createServerActionBridge(
201
270
  const onHandleAbort = () => fetchAbort.abort();
202
271
  handle.signal.addEventListener("abort", onHandleAbort, { once: true });
203
272
 
204
- // Dev-only: create debug channel for React Performance Tracks
205
- const debugId = (import.meta as any).hot
206
- ? crypto.randomUUID()
207
- : undefined;
208
- const debugChannel = debugId
209
- ? createClientDebugChannel(debugId)
210
- : undefined;
211
-
212
273
  // Send action request with stream tracking
213
274
  const responsePromise = fetch(url, {
214
275
  method: "POST",
@@ -216,32 +277,41 @@ export function createServerActionBridge(
216
277
  "rsc-action": id,
217
278
  "X-RSC-Router-Client-Path": segmentState.currentUrl,
218
279
  ...(tx && { "X-RSC-Router-Request-Id": tx.requestId }),
219
- // Send intercept source URL so server can maintain intercept context
220
280
  ...(interceptSourceUrl && {
221
281
  "X-RSC-Router-Intercept-Source": interceptSourceUrl,
222
282
  }),
223
- ...(debugId && { [DEBUG_ID_HEADER]: debugId }),
224
283
  },
225
284
  body: encodedBody,
226
285
  signal: fetchAbort.signal,
227
286
  }).then(async (response) => {
287
+ // A settled fetch promise means the request reached the server and a
288
+ // Response came back (true for 2xx, 4xx, AND 5xx — fetch only rejects
289
+ // on network-layer failure, never on HTTP status). Record it as the
290
+ // first statement so every downstream terminal can invalidate; a
291
+ // pre-dispatch failure never gets here and stays gated out.
292
+ responseReceived = true;
228
293
  // Response arrived — disconnect fetch abort from handle abort so
229
294
  // abortAllActions() doesn't disrupt the in-progress Flight stream.
230
295
  handle.signal.removeEventListener("abort", onHandleAbort);
231
296
 
297
+ // Did the action call keepClientCache()? If so the deferred invalidation
298
+ // below is suppressed for THIS action (a concurrent directive-free
299
+ // action still invalidates via its own response).
300
+ keepCache = response.headers.get(KEEP_CACHE_HEADER) === "1";
301
+
232
302
  // Check for version mismatch - server wants us to reload
233
- const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
234
- if (reload === "blocked") {
235
- resolveStreamComplete();
236
- return emptyResponse();
237
- }
238
- if (reload) {
239
- log("version mismatch on action, reloading", {
240
- reloadUrl: reload.url,
241
- });
242
- window.location.href = reload.url;
243
- return new Promise<Response>(() => {});
244
- }
303
+ const reloadResult = handleReloadHeader(response, {
304
+ onBlocked: resolveStreamComplete,
305
+ onReload: (url) => {
306
+ log("version mismatch on action, reloading", { reloadUrl: url });
307
+ // Never-settling terminal (navigates away), so the finally never
308
+ // runs: release the fence here. skipInvalidation — the mismatch
309
+ // short-circuits the action server-side, so nothing mutated and a
310
+ // broadcast would only risk hard-reloading a sibling mid-task.
311
+ finalizeAction(true);
312
+ },
313
+ });
314
+ if (reloadResult) return reloadResult;
245
315
 
246
316
  // Simple redirect from action (no state, no RSC payload).
247
317
  // Short-circuits before createFromFetch — no Flight deserialization needed.
@@ -251,14 +321,11 @@ export function createServerActionBridge(
251
321
  if (redirect && redirect !== "blocked" && !handle.signal.aborted) {
252
322
  log("action simple redirect", { url: redirect.url });
253
323
  handle.complete(undefined);
254
- if (onNavigate) {
255
- await onNavigate(redirect.url, {
256
- replace: true,
257
- _skipCache: true,
258
- });
259
- } else {
260
- window.location.href = redirect.url;
261
- }
324
+ // This path returns a never-settling promise, so the finally never
325
+ // runs: invalidate + release the fence here (the mutation committed
326
+ // and we're navigating away). Latched, so the finally is a no-op.
327
+ finalizeAction();
328
+ await dispatchRedirect(redirect.url);
262
329
  return new Promise<Response>(() => {});
263
330
  }
264
331
  if (redirect === "blocked") {
@@ -266,6 +333,29 @@ export function createServerActionBridge(
266
333
  return emptyResponse();
267
334
  }
268
335
 
336
+ // Integrity check (pre-decode): a foreign app's action response must
337
+ // not be decoded + applied here. This is the one decode-and-apply path
338
+ // the post-decode partial-update guard does NOT cover (the action
339
+ // bridge has its own createFromFetch -> onUpdate). Ordered after the
340
+ // reload/redirect handlers, which steer control responses first.
341
+ // Reloads via window.location.reload() rather than navigating to a
342
+ // target (as the navigation-client guard does): an action has no
343
+ // navigation target, so reloading the current URL re-syncs the
344
+ // document against the server-applied action effect.
345
+ if (
346
+ !handle.signal.aborted &&
347
+ isForeignRouterId(response, store.getRouterId?.())
348
+ ) {
349
+ log("action router id mismatch, reloading to re-sync");
350
+ handle.complete(undefined);
351
+ resolveStreamComplete();
352
+ // Never-settling return: release the fence before the reload (the
353
+ // reload resets module state anyway, but stay balanced). Latched.
354
+ finalizeAction();
355
+ window.location.reload();
356
+ return new Promise<Response>(() => {});
357
+ }
358
+
269
359
  // Start streaming immediately when response arrives
270
360
  if (!handle.signal.aborted) {
271
361
  streamingToken = handle.startStreaming();
@@ -283,7 +373,6 @@ export function createServerActionBridge(
283
373
  try {
284
374
  payload = await deps.createFromFetch<RscPayload>(responsePromise, {
285
375
  temporaryReferences,
286
- ...(debugChannel && { debugChannel, findSourceMapURL }),
287
376
  });
288
377
  } catch (error) {
289
378
  // Clean up streaming token on error (may be null if fetch failed before .then() ran)
@@ -321,7 +410,6 @@ export function createServerActionBridge(
321
410
  matchedCount: payload.metadata?.matched?.length ?? 0,
322
411
  diffCount: payload.metadata?.diff?.length ?? 0,
323
412
  });
324
-
325
413
  // Guard: if the action was aborted while streaming (e.g., user navigated
326
414
  // away or abortAllActions fired), bail out before any reconcile/render/cache
327
415
  // writes to avoid overwriting the current UI with stale action results.
@@ -338,6 +426,27 @@ export function createServerActionBridge(
338
426
  // Check handle.signal.aborted to avoid redirecting from a stale action
339
427
  // when the user has already navigated away.
340
428
  if (metadata?.redirect && !handle.signal.aborted) {
429
+ // Explicit off-host redirect (redirect(url, { external: true })):
430
+ // hard-navigate, but still scheme-validate (http/https only). external
431
+ // waives the same-origin check, NOT scheme safety, so a forged payload
432
+ // carrying a javascript:/data: URL cannot script via location.assign.
433
+ if (metadata.redirect.external) {
434
+ const externalUrl = validateExternalRedirect(
435
+ metadata.redirect.url,
436
+ window.location.origin,
437
+ );
438
+ if (!externalUrl) {
439
+ log("blocked external action redirect payload", {
440
+ url: metadata.redirect.url,
441
+ });
442
+ handle.complete(returnValue?.data);
443
+ return returnValue?.data;
444
+ }
445
+ log("external action redirect", { url: externalUrl });
446
+ handle.complete(returnValue?.data);
447
+ window.location.assign(externalUrl);
448
+ return returnValue?.data;
449
+ }
341
450
  const redirectUrl = validateRedirectOrigin(
342
451
  metadata.redirect.url,
343
452
  window.location.origin,
@@ -349,18 +458,9 @@ export function createServerActionBridge(
349
458
  handle.complete(returnValue?.data);
350
459
  return returnValue?.data;
351
460
  }
352
- const redirectState = metadata.locationState;
353
461
  log("action redirect", { url: redirectUrl });
354
462
  handle.complete(returnValue?.data);
355
- if (onNavigate) {
356
- await onNavigate(redirectUrl, {
357
- state: redirectState,
358
- replace: true,
359
- _skipCache: true,
360
- });
361
- } else {
362
- window.location.href = redirectUrl;
363
- }
463
+ await dispatchRedirect(redirectUrl, metadata.locationState);
364
464
  return returnValue?.data;
365
465
  }
366
466
 
@@ -538,8 +638,9 @@ export function createServerActionBridge(
538
638
  handle.clearConsolidation();
539
639
 
540
640
  if (scenario.historyKeyChanged) {
541
- if (!scenario.onInterceptRoute) {
542
- store.markCacheAsStaleAndBroadcast();
641
+ // Invalidation is deferred to finalizeAction(); here we only trigger
642
+ // the revalidation refetch of the new route (suppressed on keep).
643
+ if (!scenario.onInterceptRoute && !keepCache) {
543
644
  refetchRoute().catch((error) => {
544
645
  if (isBackgroundSuppressible(error)) return;
545
646
  console.error(
@@ -551,11 +652,14 @@ export function createServerActionBridge(
551
652
  break;
552
653
  }
553
654
 
554
- // Same history key but different pathname - safe to refetch current route
555
- store.markCacheAsStaleAndBroadcast();
556
- await refetchRoute({
557
- interceptSourceUrl: store.getInterceptSourceUrl(),
558
- });
655
+ // Same history key but different pathname - safe to refetch current
656
+ // route. Invalidation is deferred to finalizeAction(); here we only
657
+ // trigger the revalidation refetch (suppressed on keep).
658
+ if (!keepCache) {
659
+ await refetchRoute({
660
+ interceptSourceUrl: store.getInterceptSourceUrl(),
661
+ });
662
+ }
559
663
  break;
560
664
  }
561
665
 
@@ -563,8 +667,11 @@ export function createServerActionBridge(
563
667
  console.warn(
564
668
  `[Browser] Missing segments after action (HMR detected), refetching...`,
565
669
  );
670
+ // Repair (not revalidation), so ungated on keepCache: a keep action
671
+ // resolving last must discharge a directive-free sibling's repair.
672
+ // See the keep row in docs/design/rango-state-cookie.md (the all-keep
673
+ // edge, and the benign re-mark-stale-after-refetch end-state delta).
566
674
  await refetchRoute({ interceptSourceUrl });
567
- store.broadcastCacheInvalidation();
568
675
  break;
569
676
  }
570
677
 
@@ -581,11 +688,11 @@ export function createServerActionBridge(
581
688
  // Clear consolidation tracking before fetch
582
689
  handle.clearConsolidation();
583
690
 
691
+ // Ungated on keepCache, same as hmr-missing above (see the keep row).
584
692
  await refetchRoute({
585
693
  segments: segmentsToSend,
586
694
  interceptSourceUrl,
587
695
  });
588
- store.broadcastCacheInvalidation();
589
696
  break;
590
697
  }
591
698
 
@@ -649,7 +756,9 @@ export function createServerActionBridge(
649
756
  fullSegments,
650
757
  currentHandleData,
651
758
  );
652
- store.markCacheAsStaleAndBroadcast();
759
+ // Invalidation deferred to finalizeAction() (runs after this caches
760
+ // the fresh segments), suppressed when the action called
761
+ // keepClientCache().
653
762
  break;
654
763
  }
655
764
  }
@@ -657,6 +766,11 @@ export function createServerActionBridge(
657
766
  handle.complete(returnData);
658
767
  return returnData;
659
768
  } finally {
769
+ // The single deferred invalidation + fence release for this action. Runs
770
+ // for every terminal that settles (normal, navigated-away, error, abort,
771
+ // intercept, concurrent); the SPA-redirect paths above already ran it.
772
+ // Latched, so it fires exactly once.
773
+ finalizeAction();
660
774
  handle[Symbol.dispose]();
661
775
  }
662
776
  }
@@ -14,7 +14,6 @@ import type { RenderSegmentsOptions } from "../segment-system.js";
14
14
  export interface RscPayload<TMetadata = RscMetadata> {
15
15
  metadata?: TMetadata;
16
16
  returnValue?: ActionResult;
17
- formState?: unknown;
18
17
  }
19
18
 
20
19
  /**
@@ -32,10 +31,21 @@ export type HandleData = Record<string, Record<string, unknown[]>>;
32
31
  export interface RscMetadata {
33
32
  pathname: string;
34
33
  segments: ResolvedSegment[];
34
+ /** Router instance ID — the current app's identity. A mismatch with the
35
+ * client's id (sent as _rsc_rid) is detected server-side and answered with
36
+ * X-RSC-Reload (full document load), so the client never swaps apps
37
+ * in-session; within a session this always equals the current app. */
38
+ routerId?: string;
35
39
  isPartial?: boolean;
36
40
  isError?: boolean;
37
41
  matched?: string[];
38
42
  diff?: string[];
43
+ /**
44
+ * All segment ids re-resolved on the server, including null-component
45
+ * ones excluded from `segments`/`diff`. Drives client-side handle-bucket
46
+ * cleanup. Superset of `diff`. See MatchResult.resolvedIds.
47
+ */
48
+ resolvedIds?: string[];
39
49
  /** Merged route params from the matched route */
40
50
  params?: Record<string, string>;
41
51
  /**
@@ -60,6 +70,12 @@ export interface RscMetadata {
60
70
  * Sent on initial render so the browser can configure its cache duration.
61
71
  */
62
72
  prefetchCacheTTL?: number;
73
+ /**
74
+ * Server-resolved rango state cookie name (`{prefix}_{routerId}`). The client
75
+ * reads it verbatim and binds the rango state cookie to it; composition
76
+ * happens only server-side.
77
+ */
78
+ stateCookieName?: string;
63
79
  /**
64
80
  * Theme configuration from router.
65
81
  * Included when theme is enabled in router config.
@@ -70,10 +86,16 @@ export interface RscMetadata {
70
86
  * Included when theme is enabled in router config.
71
87
  */
72
88
  initialTheme?: Theme;
89
+ /** URL prefix for all routes (from createRouter({ basename })). */
90
+ basename?: string;
73
91
  /** Whether connection warmup is enabled */
74
92
  warmupEnabled?: boolean;
75
- /** Server-side redirect with optional state (for partial requests) */
76
- redirect?: { url: string };
93
+ /**
94
+ * Server-side redirect with optional state (for partial requests).
95
+ * `external: true` (from redirect(url, { external: true })) tells the client
96
+ * to hard-navigate to an off-host target instead of validating same-origin.
97
+ */
98
+ redirect?: { url: string; external?: boolean };
77
99
  /** Server-set location state to include in history.pushState */
78
100
  locationState?: Record<string, unknown>;
79
101
  }
@@ -174,6 +196,15 @@ export interface TrackedActionState {
174
196
  result: unknown | null;
175
197
  }
176
198
 
199
+ /**
200
+ * The value returned by {@link useAction} when called without a selector.
201
+ *
202
+ * This is the stable, public name for the action-state shape; consumers can
203
+ * name it in their own signatures (e.g. a wrapper hook). It aliases the
204
+ * internal {@link TrackedActionState}.
205
+ */
206
+ export type ActionState = TrackedActionState;
207
+
177
208
  /**
178
209
  * Listener for action state changes
179
210
  *
@@ -311,8 +342,14 @@ export interface RouterInstance {
311
342
  replace(url: string, options?: RouterNavigateOptions): Promise<void>;
312
343
  /** Refresh the current route (re-fetch server data, preserve client state) */
313
344
  refresh(): Promise<void>;
314
- /** Prefetch a URL for faster client-side transition */
315
- prefetch(url: string): void;
345
+ /**
346
+ * Prefetch a URL for faster client-side transition.
347
+ *
348
+ * Pass `{ key: ":source" }` to source-scope the prefetch cache entry (parity
349
+ * with `<Link prefetchKey=":source">`) when the target's response can differ
350
+ * by source page.
351
+ */
352
+ prefetch(url: string, options?: { key?: ":source" }): void;
316
353
  /** Go back in browser history */
317
354
  back(): void;
318
355
  /** Go forward in browser history */
@@ -343,7 +380,6 @@ export interface RscBrowserDependencies {
343
380
  response: Promise<Response>,
344
381
  options?: {
345
382
  temporaryReferences?: any;
346
- debugChannel?: { readable?: ReadableStream; writable?: WritableStream };
347
383
  findSourceMapURL?: (
348
384
  filename: string,
349
385
  environmentName: string,
@@ -410,17 +446,20 @@ export interface NavigationStore {
410
446
  segments: ResolvedSegment[],
411
447
  handleData?: HandleData,
412
448
  ): void;
413
- getCachedSegments(
414
- historyKey: string,
415
- ):
416
- | { segments: ResolvedSegment[]; stale: boolean; handleData?: HandleData }
449
+ getCachedSegments(historyKey: string):
450
+ | {
451
+ segments: ResolvedSegment[];
452
+ stale: boolean;
453
+ handleData?: HandleData;
454
+ routerId?: string;
455
+ }
417
456
  | undefined;
418
457
  hasHistoryCache(historyKey: string): boolean;
419
458
  updateCacheHandleData(historyKey: string, handleData: HandleData): void;
420
459
  markCacheAsStale(): void;
460
+ markHistoryCacheStale(): void;
421
461
  markCacheAsStaleAndBroadcast(): void;
422
462
  clearHistoryCache(): void;
423
- broadcastCacheInvalidation(): void;
424
463
 
425
464
  // Cross-tab refresh callback (set by navigation bridge)
426
465
  setCrossTabRefreshCallback(callback: () => void): void;
@@ -429,6 +468,10 @@ export interface NavigationStore {
429
468
  getInterceptSourceUrl(): string | null;
430
469
  setInterceptSourceUrl(url: string | null): void;
431
470
 
471
+ // Router identity tracking (for cross-app navigation detection)
472
+ getRouterId?(): string | undefined;
473
+ setRouterId?(id: string): void;
474
+
432
475
  // UI update notifications
433
476
  onUpdate(callback: UpdateSubscriber): () => void;
434
477
  emitUpdate(update: NavigationUpdate): void;
@@ -459,6 +502,8 @@ export interface FetchPartialOptions {
459
502
  interceptSourceUrl?: string;
460
503
  /** RSC version for cache invalidation detection */
461
504
  version?: string;
505
+ /** Current router ID — server detects app switch and returns full response */
506
+ routerId?: string;
462
507
  /** If true, this is an HMR refetch - server should invalidate manifest cache */
463
508
  hmr?: boolean;
464
509
  }
@@ -527,6 +572,10 @@ export interface NavigationBridge {
527
572
  refresh(): Promise<void>;
528
573
  handlePopstate(): Promise<void>;
529
574
  registerLinkInterception(): () => void;
575
+ /** Current RSC version (live, reflects the latest updateVersion). */
576
+ getVersion(): string | undefined;
577
+ /** Update the RSC version (e.g. after HMR). Clears prefetch cache. */
578
+ updateVersion(newVersion: string): void;
530
579
  }
531
580
 
532
581
  /**
@@ -1,29 +1,56 @@
1
+ import {
2
+ resolveSameOriginRedirect,
3
+ resolveExternalRedirect,
4
+ } from "../redirect-origin.js";
5
+
1
6
  /**
2
7
  * Validate that a client-consumed redirect URL (from headers or Flight payload)
3
8
  * targets the same origin as the current page. Prevents open-redirect attacks
4
9
  * via crafted responses.
5
10
  *
11
+ * Thin wrapper over the shared {@link resolveSameOriginRedirect} rule (also used
12
+ * by the server guard in `rsc/redirect-guard.ts`) so client and server enforce
13
+ * the identical same-origin contract. Adds the client-side `console.error` on a
14
+ * block; the resolver itself stays pure.
15
+ *
6
16
  * @returns The canonical (normalized) URL string on success, or null if blocked.
7
17
  */
8
18
  export function validateRedirectOrigin(
9
19
  url: string,
10
20
  currentOrigin: string,
11
21
  ): string | null {
12
- try {
13
- const target = new URL(url, currentOrigin);
14
- if (target.origin !== currentOrigin) {
15
- console.error(
16
- `[rango] Redirect blocked: origin mismatch (${target.origin})`,
17
- );
18
- return null;
19
- }
20
- // Return pathname+search+hash for relative inputs, full href for absolute.
21
- // This normalizes protocol-relative and other ambiguous forms.
22
- return target.href.startsWith(currentOrigin)
23
- ? target.href
24
- : target.pathname + target.search + target.hash;
25
- } catch {
26
- console.error(`[rango] Redirect blocked: invalid URL "${url}"`);
27
- return null;
22
+ const resolved = resolveSameOriginRedirect(url, currentOrigin);
23
+ if (resolved === null) {
24
+ console.error(
25
+ `[rango] Redirect blocked: cross-origin or invalid target "${url}"`,
26
+ );
27
+ }
28
+ return resolved;
29
+ }
30
+
31
+ /**
32
+ * Validate an explicit off-origin redirect (`redirect(url, { external: true })`)
33
+ * the client is about to hard-navigate to via `window.location.assign()`.
34
+ *
35
+ * Thin wrapper over the shared {@link resolveExternalRedirect} rule (also used by
36
+ * the server guard in `rsc/redirect-guard.ts`) so client and server enforce the
37
+ * identical contract: `external` allows an off-origin target but only an
38
+ * http(s) scheme. This stops a forged or mistaken external payload carrying a
39
+ * `javascript:`/`data:` URL from turning `location.assign` into a scriptable
40
+ * navigation. Adds the client-side `console.error` on a block; the resolver
41
+ * itself stays pure.
42
+ *
43
+ * @returns The normalized URL string on success, or null if blocked.
44
+ */
45
+ export function validateExternalRedirect(
46
+ url: string,
47
+ currentOrigin: string,
48
+ ): string | null {
49
+ const resolved = resolveExternalRedirect(url, currentOrigin);
50
+ if (resolved === null) {
51
+ console.error(
52
+ `[rango] External redirect blocked: non-http(s) target "${url}"`,
53
+ );
28
54
  }
55
+ return resolved;
29
56
  }