@rangojs/router 0.0.0-experimental.20 → 0.0.0-experimental.204030a9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (293) hide show
  1. package/AGENTS.md +4 -0
  2. package/README.md +242 -55
  3. package/dist/bin/rango.js +277 -99
  4. package/dist/vite/index.js +2929 -1132
  5. package/dist/vite/index.js.bak +5448 -0
  6. package/dist/vite/plugins/cloudflare-protocol-loader-hook.mjs +76 -0
  7. package/package.json +68 -21
  8. package/skills/breadcrumbs/SKILL.md +252 -0
  9. package/skills/bundle-analysis/SKILL.md +159 -0
  10. package/skills/cache-guide/SKILL.md +243 -21
  11. package/skills/caching/SKILL.md +159 -10
  12. package/skills/composability/SKILL.md +27 -2
  13. package/skills/document-cache/SKILL.md +78 -55
  14. package/skills/handler-use/SKILL.md +364 -0
  15. package/skills/hooks/SKILL.md +262 -51
  16. package/skills/host-router/SKILL.md +243 -0
  17. package/skills/i18n/SKILL.md +276 -0
  18. package/skills/intercept/SKILL.md +46 -4
  19. package/skills/layout/SKILL.md +28 -7
  20. package/skills/links/SKILL.md +249 -17
  21. package/skills/loader/SKILL.md +291 -31
  22. package/skills/middleware/SKILL.md +49 -12
  23. package/skills/migrate-nextjs/SKILL.md +562 -0
  24. package/skills/migrate-react-router/SKILL.md +769 -0
  25. package/skills/mime-routes/SKILL.md +27 -0
  26. package/skills/observability/SKILL.md +137 -0
  27. package/skills/parallel/SKILL.md +197 -6
  28. package/skills/prerender/SKILL.md +125 -102
  29. package/skills/rango/SKILL.md +242 -23
  30. package/skills/react-compiler/SKILL.md +168 -0
  31. package/skills/response-routes/SKILL.md +66 -9
  32. package/skills/route/SKILL.md +91 -8
  33. package/skills/router-setup/SKILL.md +98 -8
  34. package/skills/server-actions/SKILL.md +751 -0
  35. package/skills/streams-and-websockets/SKILL.md +283 -0
  36. package/skills/testing/SKILL.md +511 -188
  37. package/skills/typesafety/SKILL.md +354 -50
  38. package/skills/use-cache/SKILL.md +34 -5
  39. package/skills/view-transitions/SKILL.md +294 -0
  40. package/src/__augment-tests__/augment.ts +81 -0
  41. package/src/__augment-tests__/augmented.check.ts +117 -0
  42. package/src/__internal.ts +92 -0
  43. package/src/browser/action-coordinator.ts +53 -36
  44. package/src/browser/app-shell.ts +52 -0
  45. package/src/browser/app-version.ts +14 -0
  46. package/src/browser/event-controller.ts +91 -70
  47. package/src/browser/history-state.ts +21 -0
  48. package/src/browser/index.ts +3 -3
  49. package/src/browser/link-interceptor.ts +4 -0
  50. package/src/browser/navigation-bridge.ts +183 -18
  51. package/src/browser/navigation-client.ts +187 -57
  52. package/src/browser/navigation-store.ts +75 -17
  53. package/src/browser/navigation-transaction.ts +21 -37
  54. package/src/browser/partial-update.ts +143 -40
  55. package/src/browser/prefetch/cache.ts +275 -28
  56. package/src/browser/prefetch/fetch.ts +191 -46
  57. package/src/browser/prefetch/policy.ts +6 -0
  58. package/src/browser/prefetch/queue.ts +123 -20
  59. package/src/browser/prefetch/resource-ready.ts +77 -0
  60. package/src/browser/rango-state.ts +53 -13
  61. package/src/browser/react/Link.tsx +98 -14
  62. package/src/browser/react/NavigationProvider.tsx +110 -33
  63. package/src/browser/react/context.ts +7 -2
  64. package/src/browser/react/filter-segment-order.ts +51 -7
  65. package/src/browser/react/index.ts +3 -0
  66. package/src/browser/react/location-state-shared.ts +175 -4
  67. package/src/browser/react/location-state.ts +39 -13
  68. package/src/browser/react/use-handle.ts +23 -64
  69. package/src/browser/react/use-navigation.ts +22 -2
  70. package/src/browser/react/use-params.ts +20 -8
  71. package/src/browser/react/use-reverse.ts +106 -0
  72. package/src/browser/react/use-router.ts +43 -10
  73. package/src/browser/react/use-segments.ts +11 -8
  74. package/src/browser/response-adapter.ts +25 -0
  75. package/src/browser/rsc-router.tsx +200 -75
  76. package/src/browser/scroll-restoration.ts +46 -39
  77. package/src/browser/segment-reconciler.ts +36 -9
  78. package/src/browser/segment-structure-assert.ts +2 -2
  79. package/src/browser/server-action-bridge.ts +31 -36
  80. package/src/browser/types.ts +81 -5
  81. package/src/build/collect-fallback-refs.ts +107 -0
  82. package/src/build/generate-manifest.ts +65 -40
  83. package/src/build/generate-route-types.ts +5 -0
  84. package/src/build/index.ts +2 -0
  85. package/src/build/route-trie.ts +69 -26
  86. package/src/build/route-types/codegen.ts +4 -4
  87. package/src/build/route-types/include-resolution.ts +9 -2
  88. package/src/build/route-types/per-module-writer.ts +7 -4
  89. package/src/build/route-types/router-processing.ts +278 -88
  90. package/src/build/route-types/scan-filter.ts +9 -2
  91. package/src/build/route-types/source-scan.ts +118 -0
  92. package/src/build/runtime-discovery.ts +9 -20
  93. package/src/cache/cache-runtime.ts +15 -11
  94. package/src/cache/cache-scope.ts +76 -49
  95. package/src/cache/cf/cf-cache-store.ts +501 -18
  96. package/src/cache/cf/index.ts +5 -1
  97. package/src/cache/document-cache.ts +17 -7
  98. package/src/cache/index.ts +1 -0
  99. package/src/cache/taint.ts +55 -0
  100. package/src/client.rsc.tsx +5 -1
  101. package/src/client.tsx +95 -284
  102. package/src/context-var.ts +72 -2
  103. package/src/debug.ts +2 -2
  104. package/src/decode-loader-results.ts +36 -0
  105. package/src/errors.ts +30 -1
  106. package/src/handle.ts +65 -12
  107. package/src/handles/breadcrumbs.ts +66 -0
  108. package/src/handles/index.ts +1 -0
  109. package/src/host/index.ts +2 -5
  110. package/src/host/router.ts +129 -57
  111. package/src/host/types.ts +31 -2
  112. package/src/host/utils.ts +1 -1
  113. package/src/href-client.ts +140 -20
  114. package/src/index.rsc.ts +15 -40
  115. package/src/index.ts +92 -76
  116. package/src/loader-store.ts +500 -0
  117. package/src/loader.rsc.ts +2 -5
  118. package/src/loader.ts +3 -10
  119. package/src/missing-id-error.ts +68 -0
  120. package/src/outlet-context.ts +1 -1
  121. package/src/prerender/store.ts +57 -15
  122. package/src/prerender.ts +141 -80
  123. package/src/response-utils.ts +37 -0
  124. package/src/reverse.ts +65 -15
  125. package/src/route-content-wrapper.tsx +6 -28
  126. package/src/route-definition/dsl-helpers.ts +435 -260
  127. package/src/route-definition/helper-factories.ts +29 -139
  128. package/src/route-definition/helpers-types.ts +110 -34
  129. package/src/route-definition/index.ts +3 -3
  130. package/src/route-definition/redirect.ts +11 -3
  131. package/src/route-definition/resolve-handler-use.ts +155 -0
  132. package/src/route-definition/use-item-types.ts +32 -0
  133. package/src/route-map-builder.ts +7 -1
  134. package/src/route-types.ts +37 -41
  135. package/src/router/basename.ts +14 -0
  136. package/src/router/content-negotiation.ts +113 -1
  137. package/src/router/error-handling.ts +1 -1
  138. package/src/router/find-match.ts +4 -2
  139. package/src/router/handler-context.ts +105 -39
  140. package/src/router/intercept-resolution.ts +15 -22
  141. package/src/router/lazy-includes.ts +12 -9
  142. package/src/router/loader-resolution.ts +175 -23
  143. package/src/router/logging.ts +5 -2
  144. package/src/router/manifest.ts +31 -16
  145. package/src/router/match-api.ts +129 -193
  146. package/src/router/match-handlers.ts +63 -20
  147. package/src/router/match-middleware/background-revalidation.ts +30 -2
  148. package/src/router/match-middleware/cache-lookup.ts +136 -106
  149. package/src/router/match-middleware/cache-store.ts +54 -10
  150. package/src/router/match-middleware/intercept-resolution.ts +9 -7
  151. package/src/router/match-middleware/segment-resolution.ts +61 -5
  152. package/src/router/match-result.ts +124 -18
  153. package/src/router/metrics.ts +239 -14
  154. package/src/router/middleware-types.ts +61 -31
  155. package/src/router/middleware.ts +226 -124
  156. package/src/router/navigation-snapshot.ts +182 -0
  157. package/src/router/pattern-matching.ts +118 -19
  158. package/src/router/prerender-match.ts +114 -10
  159. package/src/router/preview-match.ts +32 -102
  160. package/src/router/request-classification.ts +286 -0
  161. package/src/router/revalidation.ts +85 -9
  162. package/src/router/route-snapshot.ts +245 -0
  163. package/src/router/router-context.ts +6 -1
  164. package/src/router/router-interfaces.ts +91 -29
  165. package/src/router/router-options.ts +89 -19
  166. package/src/router/router-registry.ts +2 -5
  167. package/src/router/segment-resolution/fresh.ts +240 -23
  168. package/src/router/segment-resolution/helpers.ts +30 -25
  169. package/src/router/segment-resolution/loader-cache.ts +1 -0
  170. package/src/router/segment-resolution/revalidation.ts +483 -289
  171. package/src/router/segment-resolution/view-transition-default.ts +36 -0
  172. package/src/router/segment-wrappers.ts +2 -0
  173. package/src/router/substitute-pattern-params.ts +56 -0
  174. package/src/router/telemetry.ts +99 -0
  175. package/src/router/trie-matching.ts +38 -15
  176. package/src/router/types.ts +9 -0
  177. package/src/router/url-params.ts +49 -0
  178. package/src/router.ts +120 -32
  179. package/src/rsc/handler-context.ts +2 -2
  180. package/src/rsc/handler.ts +524 -370
  181. package/src/rsc/helpers.ts +91 -43
  182. package/src/rsc/index.ts +1 -21
  183. package/src/rsc/loader-fetch.ts +23 -3
  184. package/src/rsc/manifest-init.ts +5 -1
  185. package/src/rsc/origin-guard.ts +28 -10
  186. package/src/rsc/progressive-enhancement.ts +39 -10
  187. package/src/rsc/response-route-handler.ts +46 -53
  188. package/src/rsc/rsc-rendering.ts +69 -89
  189. package/src/rsc/runtime-warnings.ts +9 -10
  190. package/src/rsc/server-action.ts +39 -47
  191. package/src/rsc/ssr-setup.ts +144 -0
  192. package/src/rsc/types.ts +19 -3
  193. package/src/search-params.ts +20 -17
  194. package/src/segment-content-promise.ts +67 -0
  195. package/src/segment-loader-promise.ts +122 -0
  196. package/src/segment-system.tsx +219 -67
  197. package/src/serialize.ts +243 -0
  198. package/src/server/context.ts +285 -63
  199. package/src/server/cookie-store.ts +28 -4
  200. package/src/server/handle-store.ts +19 -0
  201. package/src/server/loader-registry.ts +9 -8
  202. package/src/server/request-context.ts +228 -65
  203. package/src/server.ts +6 -0
  204. package/src/ssr/index.tsx +9 -1
  205. package/src/static-handler.ts +19 -7
  206. package/src/testing/cache-status.ts +166 -0
  207. package/src/testing/collect-handle.ts +63 -0
  208. package/src/testing/dispatch.ts +440 -0
  209. package/src/testing/dom.entry.ts +22 -0
  210. package/src/testing/e2e/fixture.ts +154 -0
  211. package/src/testing/e2e/index.ts +149 -0
  212. package/src/testing/e2e/matchers.ts +51 -0
  213. package/src/testing/e2e/page-helpers.ts +272 -0
  214. package/src/testing/e2e/parity.ts +306 -0
  215. package/src/testing/e2e/server.ts +183 -0
  216. package/src/testing/flight-matchers.ts +104 -0
  217. package/src/testing/flight-runtime.d.ts +21 -0
  218. package/src/testing/flight.entry.ts +22 -0
  219. package/src/testing/flight.ts +182 -0
  220. package/src/testing/generated-routes.ts +223 -0
  221. package/src/testing/index.ts +98 -0
  222. package/src/testing/internal/context.ts +151 -0
  223. package/src/testing/render-route.tsx +536 -0
  224. package/src/testing/run-loader.ts +296 -0
  225. package/src/testing/run-middleware.ts +170 -0
  226. package/src/testing/vitest-stubs/cloudflare-email.ts +9 -0
  227. package/src/testing/vitest-stubs/cloudflare-workers.ts +21 -0
  228. package/src/testing/vitest-stubs/plugin-rsc.ts +16 -0
  229. package/src/testing/vitest-stubs/version.ts +5 -0
  230. package/src/testing/vitest.ts +112 -0
  231. package/src/theme/index.ts +4 -13
  232. package/src/types/cache-types.ts +4 -4
  233. package/src/types/global-namespace.ts +39 -26
  234. package/src/types/handler-context.ts +197 -79
  235. package/src/types/index.ts +1 -0
  236. package/src/types/loader-types.ts +41 -15
  237. package/src/types/request-scope.ts +126 -0
  238. package/src/types/route-config.ts +17 -8
  239. package/src/types/route-entry.ts +19 -1
  240. package/src/types/segments.ts +37 -6
  241. package/src/urls/include-helper.ts +34 -67
  242. package/src/urls/index.ts +0 -3
  243. package/src/urls/path-helper-types.ts +50 -9
  244. package/src/urls/path-helper.ts +63 -63
  245. package/src/urls/pattern-types.ts +48 -19
  246. package/src/urls/response-types.ts +25 -22
  247. package/src/urls/type-extraction.ts +26 -116
  248. package/src/urls/urls-function.ts +1 -5
  249. package/src/use-loader.tsx +487 -44
  250. package/src/vite/debug.ts +185 -0
  251. package/src/vite/discovery/bundle-postprocess.ts +63 -91
  252. package/src/vite/discovery/discover-routers.ts +106 -53
  253. package/src/vite/discovery/discovery-errors.ts +194 -0
  254. package/src/vite/discovery/gate-state.ts +171 -0
  255. package/src/vite/discovery/prerender-collection.ts +222 -107
  256. package/src/vite/discovery/route-types-writer.ts +40 -84
  257. package/src/vite/discovery/self-gen-tracking.ts +27 -1
  258. package/src/vite/discovery/state.ts +50 -13
  259. package/src/vite/discovery/virtual-module-codegen.ts +13 -23
  260. package/src/vite/index.ts +10 -3
  261. package/src/vite/plugin-types.ts +111 -72
  262. package/src/vite/plugins/cjs-to-esm.ts +8 -7
  263. package/src/vite/plugins/client-ref-dedup.ts +16 -0
  264. package/src/vite/plugins/client-ref-hashing.ts +28 -5
  265. package/src/vite/plugins/cloudflare-protocol-loader-hook.d.mts +23 -0
  266. package/src/vite/plugins/cloudflare-protocol-loader-hook.mjs +76 -0
  267. package/src/vite/plugins/cloudflare-protocol-stub.ts +214 -0
  268. package/src/vite/plugins/expose-action-id.ts +55 -33
  269. package/src/vite/plugins/expose-id-utils.ts +24 -8
  270. package/src/vite/plugins/expose-ids/export-analysis.ts +100 -20
  271. package/src/vite/plugins/expose-ids/handler-transform.ts +12 -35
  272. package/src/vite/plugins/expose-ids/loader-transform.ts +3 -5
  273. package/src/vite/plugins/expose-ids/router-transform.ts +20 -3
  274. package/src/vite/plugins/expose-internal-ids.ts +544 -317
  275. package/src/vite/plugins/performance-tracks.ts +92 -0
  276. package/src/vite/plugins/refresh-cmd.ts +127 -0
  277. package/src/vite/plugins/use-cache-transform.ts +65 -50
  278. package/src/vite/plugins/version-injector.ts +39 -23
  279. package/src/vite/plugins/version-plugin.ts +72 -3
  280. package/src/vite/plugins/virtual-entries.ts +2 -2
  281. package/src/vite/rango.ts +265 -226
  282. package/src/vite/router-discovery.ts +924 -137
  283. package/src/vite/utils/ast-handler-extract.ts +15 -15
  284. package/src/vite/utils/banner.ts +4 -4
  285. package/src/vite/utils/bundle-analysis.ts +4 -2
  286. package/src/vite/utils/client-chunks.ts +190 -0
  287. package/src/vite/utils/forward-user-plugins.ts +193 -0
  288. package/src/vite/utils/manifest-utils.ts +21 -5
  289. package/src/vite/utils/package-resolution.ts +41 -1
  290. package/src/vite/utils/prerender-utils.ts +98 -5
  291. package/src/vite/utils/shared-utils.ts +109 -27
  292. package/src/browser/action-response-classifier.ts +0 -99
  293. package/src/route-definition/route-function.ts +0 -119
@@ -55,14 +55,22 @@ type Simplify<T> = { [K in keyof T]: T[K] };
55
55
  /**
56
56
  * Resolve a SearchSchema to its typed object.
57
57
  *
58
+ * Both required and optional params resolve to `T | undefined` at the handler
59
+ * level. The required/optional distinction is a consumer-facing contract
60
+ * (e.g., for href() and reverse() autocomplete) — it tells callers which
61
+ * params the route expects, but the handler must still check for undefined
62
+ * since the framework cannot trust the client to send all required params.
63
+ *
58
64
  * @example
59
65
  * type S = { q: "string"; page: "number?"; sort: "string?" };
60
66
  * type R = ResolveSearchSchema<S>;
61
- * // { q: string; page?: number; sort?: string }
67
+ * // { q: string | undefined; page?: number; sort?: string }
62
68
  */
63
69
  export type ResolveSearchSchema<T extends SearchSchema> = Simplify<
64
70
  {
65
- [K in RequiredKeys<T> & string]: ResolveBaseType<BaseType<T[K]>>;
71
+ [K in RequiredKeys<T> & string]:
72
+ | ResolveBaseType<BaseType<T[K]>>
73
+ | undefined;
66
74
  } & {
67
75
  [K in OptionalKeys<T> & string]?: ResolveBaseType<BaseType<T[K]>>;
68
76
  }
@@ -73,11 +81,11 @@ export type ResolveSearchSchema<T extends SearchSchema> = Simplify<
73
81
  // ============================================================================
74
82
 
75
83
  /** Resolve the global route map from RegisteredRoutes or GeneratedRouteMap. */
76
- type GlobalRouteMap = keyof RSCRouter.RegisteredRoutes extends never
77
- ? keyof RSCRouter.GeneratedRouteMap extends never
84
+ type GlobalRouteMap = keyof Rango.RegisteredRoutes extends never
85
+ ? keyof Rango.GeneratedRouteMap extends never
78
86
  ? Record<string, string>
79
- : RSCRouter.GeneratedRouteMap
80
- : RSCRouter.RegisteredRoutes;
87
+ : Rango.GeneratedRouteMap
88
+ : Rango.RegisteredRoutes;
81
89
 
82
90
  /**
83
91
  * Extract the resolved search params type for a named route.
@@ -166,7 +174,9 @@ type ExtractParamsFromPattern<T extends string> =
166
174
  * - `"number"` / `"number?"` - coerced via `Number()`; NaN treated as missing
167
175
  * - `"boolean"` / `"boolean?"` - `"true"` / `"1"` -> true, `"false"` / `"0"` / `""` -> false
168
176
  *
169
- * Missing required params are set to their zero value (empty string / 0 / false).
177
+ * Missing params (both required and optional) are omitted from the result
178
+ * (undefined). The required/optional distinction is a consumer-facing contract
179
+ * only — the handler must check for undefined.
170
180
  */
171
181
  export function parseSearchParams<T extends SearchSchema>(
172
182
  searchParams: URLSearchParams,
@@ -180,13 +190,7 @@ export function parseSearchParams<T extends SearchSchema>(
180
190
  const raw = searchParams.get(key);
181
191
 
182
192
  if (raw === null) {
183
- if (!isOptional) {
184
- // Required param missing: use zero value
185
- if (baseType === "string") result[key] = "";
186
- else if (baseType === "number") result[key] = 0;
187
- else if (baseType === "boolean") result[key] = false;
188
- }
189
- // Optional params are omitted (undefined)
193
+ // Missing params are omitted (undefined) regardless of required/optional
190
194
  continue;
191
195
  }
192
196
 
@@ -194,11 +198,10 @@ export function parseSearchParams<T extends SearchSchema>(
194
198
  result[key] = raw;
195
199
  } else if (baseType === "number") {
196
200
  const num = Number(raw);
197
- if (Number.isNaN(num)) {
198
- if (!isOptional) result[key] = 0;
199
- } else {
201
+ if (!Number.isNaN(num)) {
200
202
  result[key] = num;
201
203
  }
204
+ // NaN treated as missing (undefined)
202
205
  } else if (baseType === "boolean") {
203
206
  result[key] = raw === "true" || raw === "1";
204
207
  }
@@ -0,0 +1,67 @@
1
+ import type { ReactNode } from "react";
2
+
3
+ /**
4
+ * Stable Promise wrappers keyed on the component itself. Objects (React
5
+ * elements, functions, lazy payloads) land in a WeakMap so entries GC when
6
+ * the underlying component is released; primitives (string, number, boolean,
7
+ * null) land in a Map so memoization still applies to text-/null-backed
8
+ * segments like those in partial-update flows. Keeping this cache outside
9
+ * the segment eliminates preservation fields on ResolvedSegment — it survives
10
+ * reconciliation naturally because the component ref is what's stable.
11
+ *
12
+ * Browser-only. On the server each SSR render needs a fresh pending promise
13
+ * so Suspense can emit the loading fallback HTML before content streams. A
14
+ * shared already-resolved promise has `.status === "fulfilled"` attached by
15
+ * React on its first observation — subsequent `use()` calls return
16
+ * synchronously without suspending, so the Suspense fallback never makes it
17
+ * into the initial HTML. Route-definition components share refs across
18
+ * requests, so a global cache would leak tracked state between renders.
19
+ */
20
+ const IS_BROWSER = typeof window !== "undefined";
21
+ const objectContentCache = IS_BROWSER
22
+ ? new WeakMap<object, Promise<ReactNode>>()
23
+ : null;
24
+ const primitiveContentCache = IS_BROWSER
25
+ ? new Map<unknown, Promise<ReactNode>>()
26
+ : null;
27
+
28
+ /**
29
+ * Return a stable Promise wrapping `component`, memoized on the component ref.
30
+ *
31
+ * A fresh `Promise.resolve(component)` each render would suspend for one
32
+ * microtask and briefly commit the loading fallback inside Suspender — the
33
+ * intercept / parallel-slot flicker this indirection prevents. Reusing the
34
+ * same Promise ref keeps React's `use()` in "known fulfilled" state after
35
+ * the first observation.
36
+ *
37
+ * @internal
38
+ */
39
+ export function getMemoizedContentPromise(
40
+ component: ReactNode,
41
+ ): Promise<ReactNode> {
42
+ if (component instanceof Promise) {
43
+ return component as Promise<ReactNode>;
44
+ }
45
+
46
+ if (!objectContentCache || !primitiveContentCache) {
47
+ return Promise.resolve(component);
48
+ }
49
+
50
+ if (component !== null && typeof component === "object") {
51
+ const cached = objectContentCache.get(component);
52
+ if (cached) {
53
+ return cached;
54
+ }
55
+ const promise = Promise.resolve(component);
56
+ objectContentCache.set(component, promise);
57
+ return promise;
58
+ }
59
+
60
+ const cached = primitiveContentCache.get(component);
61
+ if (cached) {
62
+ return cached;
63
+ }
64
+ const promise = Promise.resolve(component);
65
+ primitiveContentCache.set(component, promise);
66
+ return promise;
67
+ }
@@ -0,0 +1,122 @@
1
+ import type { ResolvedSegment } from "./types.js";
2
+
3
+ /**
4
+ * Cache of aggregate Promise.all results keyed on the first loader's
5
+ * `loaderData` reference. Each entry holds the source refs it was built from
6
+ * plus the resulting Promise/array; lookup scans entries for the matching
7
+ * source array (typically a single entry, since distinct loader groups rarely
8
+ * share a first source). Object first-refs live in a WeakMap (auto-GC);
9
+ * primitive first-refs (strings/numbers/booleans/null) live in a Map so
10
+ * loaders that resolve to primitive data are memoized too — bounded in
11
+ * practice by the application's loader set.
12
+ *
13
+ * Keying externally means reconciliation's fresh segment objects no longer
14
+ * drop memoization — the cache survives as long as the underlying loader
15
+ * segments do, and GC collects entries when those loaders are released
16
+ * (object keys only).
17
+ *
18
+ * Browser-only. On the server each SSR render needs a fresh Promise so
19
+ * Suspense can actually suspend and emit the loading fallback HTML before
20
+ * content streams. A shared already-resolved promise has `.status` attached
21
+ * by React on first `use()`; subsequent observations return synchronously
22
+ * and skip the fallback. The zero-loader case is especially prone because
23
+ * every empty-loader site would otherwise share one promise across requests.
24
+ */
25
+ const IS_BROWSER = typeof window !== "undefined";
26
+
27
+ interface LoaderCacheEntry {
28
+ sources: any[];
29
+ promise: Promise<any[]> | any[];
30
+ }
31
+
32
+ const objectLoaderCache = IS_BROWSER
33
+ ? new WeakMap<object, LoaderCacheEntry[]>()
34
+ : null;
35
+ const primitiveLoaderCache = IS_BROWSER
36
+ ? new Map<unknown, LoaderCacheEntry[]>()
37
+ : null;
38
+
39
+ // In the browser, a single shared empty aggregate is safe (and desirable) —
40
+ // reusing the same resolved promise keeps React's `use()` in a known-fulfilled
41
+ // state across renders. On the server it would leak `.status = "fulfilled"`
42
+ // across requests and skip the Suspense fallback, so we rebuild on each call.
43
+ const SHARED_EMPTY_LOADER_PROMISE: Promise<any[]> | null = IS_BROWSER
44
+ ? Promise.resolve([])
45
+ : null;
46
+
47
+ function hasSameReferences(a: any[], b: any[]): boolean {
48
+ if (a.length !== b.length) {
49
+ return false;
50
+ }
51
+ for (let i = 0; i < a.length; i++) {
52
+ if (a[i] !== b[i]) {
53
+ return false;
54
+ }
55
+ }
56
+ return true;
57
+ }
58
+
59
+ function buildLoaderPromise(loaders: ResolvedSegment[]): Promise<any[]> {
60
+ if (loaders.length === 0) {
61
+ return Promise.resolve([]);
62
+ }
63
+ return Promise.all(
64
+ loaders.map((loader) =>
65
+ loader.loaderData instanceof Promise
66
+ ? loader.loaderData
67
+ : Promise.resolve(loader.loaderData),
68
+ ),
69
+ );
70
+ }
71
+
72
+ function isObjectLike(value: unknown): value is object {
73
+ return (
74
+ value !== null && (typeof value === "object" || typeof value === "function")
75
+ );
76
+ }
77
+
78
+ /**
79
+ * Memoize an aggregate Promise.all for a set of loader segments. Reusing the
80
+ * same aggregate across renders — invalidated only when any underlying
81
+ * loader.loaderData ref changes — keeps React's `use()` in "known fulfilled"
82
+ * state and prevents a fresh Promise.all from suspending (and briefly
83
+ * committing the Suspense fallback) on every partial update that doesn't
84
+ * actually change loader data.
85
+ *
86
+ * @internal
87
+ */
88
+ export function getMemoizedLoaderPromise(
89
+ loaders: ResolvedSegment[],
90
+ ): Promise<any[]> | any[] {
91
+ if (loaders.length === 0) {
92
+ return SHARED_EMPTY_LOADER_PROMISE ?? buildLoaderPromise(loaders);
93
+ }
94
+ if (!objectLoaderCache || !primitiveLoaderCache) {
95
+ return buildLoaderPromise(loaders);
96
+ }
97
+
98
+ const sources = loaders.map((loader) => loader.loaderData);
99
+ const first = sources[0];
100
+ const entries = isObjectLike(first)
101
+ ? objectLoaderCache.get(first)
102
+ : primitiveLoaderCache.get(first);
103
+
104
+ if (entries) {
105
+ for (const entry of entries) {
106
+ if (hasSameReferences(entry.sources, sources)) {
107
+ return entry.promise;
108
+ }
109
+ }
110
+ }
111
+
112
+ const promise = buildLoaderPromise(loaders);
113
+ const newEntry: LoaderCacheEntry = { sources, promise };
114
+ if (entries) {
115
+ entries.push(newEntry);
116
+ } else if (isObjectLike(first)) {
117
+ objectLoaderCache.set(first, [newEntry]);
118
+ } else {
119
+ primitiveLoaderCache.set(first, [newEntry]);
120
+ }
121
+ return promise;
122
+ }
@@ -2,58 +2,61 @@ import * as React from "react";
2
2
  import { createElement, type ReactNode, type ComponentType } from "react";
3
3
  import { OutletProvider } from "./client.js";
4
4
  import { MountContextProvider } from "./browser/react/mount-context.js";
5
- import type {
6
- ResolvedSegment,
7
- LoaderDataResult,
8
- RootLayoutProps,
9
- } from "./types.js";
10
- import { isLoaderDataResult } from "./types.js";
5
+ import type { ResolvedSegment, RootLayoutProps } from "./types.js";
6
+ import { decodeLoaderResults } from "./decode-loader-results.js";
11
7
  import { invariant } from "./errors.js";
12
8
  import {
13
9
  RouteContentWrapper,
14
10
  LoaderBoundary,
15
11
  } from "./route-content-wrapper.js";
16
12
  import { RootErrorBoundary } from "./root-error-boundary.js";
13
+ import { getMemoizedContentPromise } from "./segment-content-promise.js";
14
+ import { getMemoizedLoaderPromise } from "./segment-loader-promise.js";
17
15
 
18
16
  // ViewTransition is only available in React experimental.
19
17
  // Access via namespace import to avoid compile-time errors on stable React.
20
18
  const ReactViewTransition: any =
21
19
  "ViewTransition" in React ? (React as any).ViewTransition : null;
22
20
 
23
- /**
24
- * Resolve loader data from raw results, unwrapping LoaderDataResult wrappers
25
- */
26
- function resolveLoaderData(
27
- resolvedData: any[],
28
- loaderIds: string[],
29
- ): { loaderData: Record<string, any>; errorFallback: ReactNode } {
30
- const loaderData: Record<string, any> = {};
31
- let errorFallback: ReactNode = null;
32
-
33
- for (let i = 0; i < loaderIds.length; i++) {
34
- const id = loaderIds[i];
35
- const result = resolvedData[i];
36
-
37
- if (!isLoaderDataResult(result)) {
38
- // Legacy format - direct data
39
- loaderData[id] = result;
21
+ function restoreParallelLoaderMarkers(
22
+ segments: ResolvedSegment[],
23
+ ): ResolvedSegment[] {
24
+ const parallelLoadingByNamespace = new Map<string, ReactNode>();
25
+ let nextSegments: ResolvedSegment[] | null = null;
26
+
27
+ for (let i = 0; i < segments.length; i++) {
28
+ const segment = segments[i];
29
+
30
+ if (segment.type === "parallel") {
31
+ if (
32
+ segment.namespace &&
33
+ segment.loading !== undefined &&
34
+ segment.loading !== null &&
35
+ segment.loading !== false
36
+ ) {
37
+ parallelLoadingByNamespace.set(segment.namespace, segment.loading);
38
+ }
40
39
  continue;
41
40
  }
42
41
 
43
- if (result.ok) {
44
- loaderData[id] = result.data;
42
+ if (segment.type !== "loader" || segment.parallelLoading !== undefined) {
45
43
  continue;
46
44
  }
47
45
 
48
- // Error case
49
- if (result.fallback) {
50
- errorFallback = result.fallback;
51
- } else {
52
- throw new Error(result.error.message);
46
+ const parallelLoading = segment.namespace
47
+ ? parallelLoadingByNamespace.get(segment.namespace)
48
+ : undefined;
49
+ if (parallelLoading === undefined) {
50
+ continue;
51
+ }
52
+
53
+ if (!nextSegments) {
54
+ nextSegments = segments.slice();
53
55
  }
56
+ nextSegments[i] = { ...segment, parallelLoading };
54
57
  }
55
58
 
56
- return { loaderData, errorFallback };
59
+ return nextSegments ?? segments;
57
60
  }
58
61
 
59
62
  /**
@@ -92,6 +95,50 @@ export interface RenderSegmentsOptions {
92
95
  rootLayout?: ComponentType<RootLayoutProps>;
93
96
  }
94
97
 
98
+ function createViewTransitionBoundary(
99
+ transition: NonNullable<ResolvedSegment["transition"]>,
100
+ children: ReactNode,
101
+ ): ReactNode {
102
+ // `viewTransition` is a router-specific flag (boundary opt-out), not a React
103
+ // <ViewTransition> prop — strip it so it never reaches React.
104
+ const { viewTransition: _viewTransition, ...vtProps } = transition;
105
+ return createElement(ReactViewTransition, {
106
+ ...vtProps,
107
+ children,
108
+ });
109
+ }
110
+
111
+ function wrapDefaultOutletContent(
112
+ content: ReactNode,
113
+ transition: NonNullable<ResolvedSegment["transition"]>,
114
+ ): ReactNode {
115
+ if (!React.isValidElement(content)) {
116
+ return createViewTransitionBoundary(transition, content);
117
+ }
118
+
119
+ const props = content.props as any;
120
+
121
+ if (content.type === MountContextProvider) {
122
+ return React.cloneElement(content, {
123
+ children: wrapDefaultOutletContent(props.children, transition),
124
+ } as any);
125
+ }
126
+
127
+ if (content.type === OutletProvider && props.segment?.type === "layout") {
128
+ return React.cloneElement(content, {
129
+ content: wrapDefaultOutletContent(props.content, transition),
130
+ } as any);
131
+ }
132
+
133
+ if (content.type === LoaderBoundary && props.segment?.type === "layout") {
134
+ return React.cloneElement(content, {
135
+ outletContent: wrapDefaultOutletContent(props.outletContent, transition),
136
+ } as any);
137
+ }
138
+
139
+ return createViewTransitionBoundary(transition, content);
140
+ }
141
+
95
142
  /**
96
143
  * Render segments into a React tree with proper layout nesting
97
144
  *
@@ -143,6 +190,10 @@ export async function renderSegments(
143
190
  } = options || {};
144
191
 
145
192
  const temporalLazyRefs: Promise<any>[] = [];
193
+ const normalizedSegments = restoreParallelLoaderMarkers(segments);
194
+ const normalizedInterceptSegments = interceptSegments
195
+ ? restoreParallelLoaderMarkers(interceptSegments)
196
+ : undefined;
146
197
 
147
198
  /**
148
199
  * Registers promises from lazy/async components for awaiting.
@@ -167,7 +218,26 @@ export async function renderSegments(
167
218
  );
168
219
  }
169
220
  // Separate segments by type, passing intercept segments for explicit injection
170
- const tree = segmentTreeWalk(segments, interceptSegments);
221
+ const tree = segmentTreeWalk(normalizedSegments, normalizedInterceptSegments);
222
+
223
+ // A route is "in a transition scope" when its own segment OR any layout in
224
+ // its matched chain declares transition(). Both transition() forms land here:
225
+ // the per-route item form sets transition on the route entry, and the block
226
+ // wrapper form sets it on a transparent ancestor layout (dsl-helpers.ts). When
227
+ // in scope, the route and its route-owned layouts use param-agnostic keys so a
228
+ // same-route navigation reconciles (holds content) instead of remounting. The
229
+ // value is a static property of the route's position in the tree, so it is the
230
+ // same on every render of that route (SSR, navigation, action) — the keys
231
+ // never drift. Cross-route navigation still remounts: different routes have
232
+ // different segment ids regardless of transition scope.
233
+ const inTransitionScope = normalizedSegments.some(
234
+ (s) =>
235
+ s.transition != null &&
236
+ (s.type === "layout" ||
237
+ s.type === "route" ||
238
+ s.type === "error" ||
239
+ s.type === "notFound"),
240
+ );
171
241
  // Render content segments as siblings
172
242
  let content: ReactNode = null;
173
243
  for (const node of tree) {
@@ -180,17 +250,31 @@ export async function renderSegments(
180
250
  );
181
251
  const { component, id, params, loading } = node.segment;
182
252
 
183
- // Only include params in key for segments that belong to the route
184
- // - Routes: always include params (they render param-specific content)
185
- // - Error/notFound segments: always include params (they replace failed route content)
186
- // - Route's layouts (orphans): include params (children of parameterized route)
187
- // - Parent chain layouts: exclude params (shared across routes, param-agnostic)
188
- // This prevents unnecessary unmounting when params change
253
+ // Param-agnostic keys are opt-in via the transition() DSL (see
254
+ // inTransitionScope above). A route (and its route-owned layouts) inside a
255
+ // transition scope drops the param from its key, so navigating between two
256
+ // param values of the SAME route (e.g. /product/1 -> /product/2) reconciles
257
+ // the route subtree instead of remounting it. Combined with the
258
+ // startTransition wrap that shouldStartViewTransition already applies to
259
+ // transition routes (browser/partial-update.ts), the previous content stays
260
+ // on screen while the new loaders resolve (stale-while-revalidate) instead
261
+ // of flashing the loading skeleton. This works on stable React; experimental
262
+ // React adds the animated <ViewTransition> cross-fade on top.
263
+ //
264
+ // Outside a transition scope the key stays param-bearing and the route
265
+ // remounts on param change (the default: a fresh skeleton and fresh
266
+ // component state).
267
+ //
268
+ // error/notFound always keep param-bearing keys: createErrorSegment reuses
269
+ // the boundary layout's shortCode as the error segment id (router/
270
+ // error-handling.ts), so a param-agnostic error key could collide with that
271
+ // layout's key within the same render.
189
272
  const includeParams =
190
- node.segment.type === "route" ||
191
273
  node.segment.type === "error" ||
192
274
  node.segment.type === "notFound" ||
193
- (node.segment.type === "layout" && node.segment.belongsToRoute);
275
+ ((node.segment.type === "route" ||
276
+ (node.segment.type === "layout" && node.segment.belongsToRoute)) &&
277
+ !inTransitionScope);
194
278
 
195
279
  const paramStr =
196
280
  includeParams && params && Object.keys(params).length > 0
@@ -219,10 +303,7 @@ export async function renderSegments(
219
303
  loading !== null && loading !== undefined && loading !== false
220
304
  ? createElement(RouteContentWrapper, {
221
305
  key: `suspense-loading-${id}`,
222
- content:
223
- resolvedComponent instanceof Promise
224
- ? resolvedComponent
225
- : Promise.resolve(resolvedComponent),
306
+ content: getMemoizedContentPromise(resolvedComponent),
226
307
  fallback: loading,
227
308
  segmentId: id,
228
309
  })
@@ -233,35 +314,51 @@ export async function renderSegments(
233
314
  // in transitions without adding custom animation classes. Named element-level
234
315
  // <ViewTransition> components inside (with name/share props) morph independently
235
316
  // from the parent's default cross-fade.
236
- if (ReactViewTransition && node.segment.transition) {
237
- nodeContent = createElement(ReactViewTransition, {
238
- ...node.segment.transition,
239
- children: nodeContent,
240
- });
241
- }
242
-
243
- // Common props for OutletProvider
244
- const outletContent: ReactNode =
317
+ //
318
+ // For layouts, wrap the outlet content (what `<Outlet />` renders) rather
319
+ // than the layout component itself. Parallel slots like `<ParallelOutlet
320
+ // name="@modal" />` read from a separate context channel and end up as
321
+ // siblings of the VT in the rendered tree, so modal mounts don't trigger a
322
+ // subtree update on the layout-level VT — which would otherwise make
323
+ // React's commit walker fire `document.startViewTransition` and apply
324
+ // view-transition-names to the underlying main subtree (cover/title/etc.).
325
+ //
326
+ // `transition.viewTransition === false` opts out of the router-owned
327
+ // boundary only. Driving (the startTransition wrap in browser/partial-update.ts
328
+ // and the param-agnostic key/hold below) keys off transition *presence*, not
329
+ // this flag, so a boundary-less transition still holds content and lets
330
+ // consumer-placed <ViewTransition> elements animate. The global
331
+ // createRouter({ viewTransition }) default is resolved into this field
332
+ // during segment resolution (only `false` is stamped; unset/"auto" is left
333
+ // as-is and means "wrap"), so this gate needs no router-option threading.
334
+ let outletContent: ReactNode =
245
335
  node.segment.type === "layout" ? content : null;
246
336
 
337
+ const transition = node.segment.transition;
338
+
339
+ if (
340
+ ReactViewTransition &&
341
+ transition &&
342
+ transition.viewTransition !== false
343
+ ) {
344
+ if (node.segment.type === "layout") {
345
+ outletContent = wrapDefaultOutletContent(outletContent, transition);
346
+ } else {
347
+ nodeContent = createViewTransitionBoundary(transition, nodeContent);
348
+ }
349
+ }
350
+
247
351
  // Prepare loader data if there are loaders
248
352
  const loaderIds = loaderEntries.map((loader) => loader.loaderId!);
249
- const loaderDataPromise =
250
- loaderEntries.length > 0
251
- ? Promise.all(
252
- loaderEntries.map((loader) =>
253
- loader.loaderData instanceof Promise
254
- ? loader.loaderData
255
- : Promise.resolve(loader.loaderData),
256
- ),
257
- )
258
- : Promise.resolve([]);
259
353
 
260
354
  // Use LoaderBoundary when loading is defined to maintain consistent tree structure
261
355
  // This ensures cached segments (which may not have loader segments) have the same
262
356
  // tree structure as fresh segments, preventing React remounts
263
357
  // If forceAwait or isAction is set, pre-resolve promises so LoaderBoundary won't suspend
264
358
  if (loading !== undefined && loading !== null) {
359
+ // Aggregate built here only — the loaderless and no-loading branches don't
360
+ // read it (the latter builds its own per-parallel promises).
361
+ const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);
265
362
  content = createElement(LoaderBoundary, {
266
363
  key: `loader-boundary-${key}`,
267
364
  loaderDataPromise:
@@ -284,13 +381,68 @@ export async function renderSegments(
284
381
  children: nodeContent,
285
382
  });
286
383
  } else {
287
- // Has loaders but no loading skeleton - await loaders and render directly
288
- const resolvedData = await loaderDataPromise;
289
- const { loaderData, errorFallback } = resolveLoaderData(
384
+ // Has loaders but no loading skeleton.
385
+ // Split: parallel-owned loaders stream (their parallel has loading()),
386
+ // layout-owned loaders are awaited (they gate the layout content).
387
+ const layoutLoaders = loaderEntries.filter((l) => !l.parallelLoading);
388
+ const parallelOwnedLoaders = loaderEntries.filter(
389
+ (l) => !!l.parallelLoading,
390
+ );
391
+
392
+ // Await only layout-owned loaders
393
+ const layoutLoaderIds = layoutLoaders.map((l) => l.loaderId!);
394
+ const layoutLoaderDataPromise =
395
+ layoutLoaders.length > 0
396
+ ? Promise.all(
397
+ layoutLoaders.map((l) =>
398
+ l.loaderData instanceof Promise
399
+ ? l.loaderData
400
+ : Promise.resolve(l.loaderData),
401
+ ),
402
+ )
403
+ : Promise.resolve([]);
404
+ const resolvedData = await layoutLoaderDataPromise;
405
+ const { loaderData, errorFallback } = decodeLoaderResults(
290
406
  resolvedData,
291
- loaderIds,
407
+ layoutLoaderIds,
292
408
  );
293
409
 
410
+ // Parallel-owned loaders: attach to their owning parallel segment
411
+ // as loaderDataPromise so ParallelOutlet wraps in LoaderBoundary
412
+ if (parallelOwnedLoaders.length > 0) {
413
+ const loadersByParallelNamespace = new Map<string, ResolvedSegment[]>();
414
+
415
+ for (const loader of parallelOwnedLoaders) {
416
+ if (!loader.namespace) {
417
+ continue;
418
+ }
419
+ const existing = loadersByParallelNamespace.get(loader.namespace);
420
+ if (existing) {
421
+ existing.push(loader);
422
+ } else {
423
+ loadersByParallelNamespace.set(loader.namespace, [loader]);
424
+ }
425
+ }
426
+
427
+ for (const p of node.parallel) {
428
+ if (!p.loading || !p.namespace) {
429
+ continue;
430
+ }
431
+
432
+ const ownedLoaders = loadersByParallelNamespace.get(p.namespace);
433
+ if (!ownedLoaders || ownedLoaders.length === 0) {
434
+ continue;
435
+ }
436
+
437
+ p.loaderIds = ownedLoaders.map((l) => l.loaderId!);
438
+ const aggregated = getMemoizedLoaderPromise(ownedLoaders);
439
+ p.loaderDataPromise =
440
+ (forceAwait || isAction) && aggregated instanceof Promise
441
+ ? await aggregated
442
+ : aggregated;
443
+ }
444
+ }
445
+
294
446
  content = createElement(OutletProvider, {
295
447
  key,
296
448
  content: outletContent,