@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
@@ -7,7 +7,11 @@
7
7
 
8
8
  import type { ReactNode } from "react";
9
9
  import { invariant } from "../../errors";
10
- import type { EntryData } from "../../server/context";
10
+ import {
11
+ getParallelEntries,
12
+ getParallelSlotEntries,
13
+ type EntryData,
14
+ } from "../../server/context";
11
15
  import type {
12
16
  HandlerContext,
13
17
  InternalHandlerContext,
@@ -15,6 +19,8 @@ import type {
15
19
  } from "../../types";
16
20
  import type { SegmentResolutionDeps } from "../types.js";
17
21
  import { resolveLoaderData } from "./loader-cache.js";
22
+ import { _getRequestContext } from "../../server/request-context.js";
23
+ import { appendMetric } from "../metrics.js";
18
24
  import {
19
25
  handleHandlerResult,
20
26
  tryStaticHandler,
@@ -22,8 +28,14 @@ import {
22
28
  resolveLayoutComponent,
23
29
  resolveWithErrorBoundary,
24
30
  } from "./helpers.js";
31
+ import { applyViewTransitionDefault } from "./view-transition-default.js";
25
32
  import { getRouterContext } from "../router-context.js";
26
33
  import { resolveSink, safeEmit } from "../telemetry.js";
34
+ import {
35
+ track,
36
+ RangoContext,
37
+ runInsideLoaderScope,
38
+ } from "../../server/context.js";
27
39
 
28
40
  // ---------------------------------------------------------------------------
29
41
  // Streamed handler telemetry
@@ -89,9 +101,11 @@ export async function resolveLoaders<TEnv>(
89
101
  const shortCode = shortCodeOverride ?? entry.shortCode;
90
102
  const hasLoading = "loading" in entry && entry.loading !== undefined;
91
103
  const loadingDisabled = hasLoading && entry.loading === false;
104
+ const ms = _getRequestContext()?._metricsStore;
92
105
 
93
106
  if (!loadingDisabled) {
94
- return loaderEntries.map((loaderEntry, i) => {
107
+ // Streaming loaders: promises kick off now, settle during RSC serialization.
108
+ const segments = loaderEntries.map((loaderEntry, i) => {
95
109
  const { loader } = loaderEntry;
96
110
  const segmentId = `${shortCode}D${i}.${loader.$$id}`;
97
111
  return {
@@ -103,7 +117,9 @@ export async function resolveLoaders<TEnv>(
103
117
  params: ctx.params,
104
118
  loaderId: loader.$$id,
105
119
  loaderData: deps.wrapLoaderPromise(
106
- resolveLoaderData(loaderEntry, ctx, ctx.pathname),
120
+ runInsideLoaderScope(() =>
121
+ resolveLoaderData(loaderEntry, ctx, ctx.pathname),
122
+ ),
107
123
  entry,
108
124
  segmentId,
109
125
  ctx.pathname,
@@ -111,18 +127,38 @@ export async function resolveLoaders<TEnv>(
111
127
  belongsToRoute,
112
128
  };
113
129
  });
130
+
131
+ return segments;
114
132
  }
115
133
 
116
134
  // Loading disabled: still start all loaders in parallel, but only emit
117
135
  // settled promises so handlers don't stream loading placeholders.
118
- const pendingLoaderData = loaderEntries.map((loaderEntry) =>
119
- resolveLoaderData(loaderEntry, ctx, ctx.pathname),
120
- );
121
- await Promise.all(pendingLoaderData);
136
+ const pendingLoaderData = loaderEntries.map((loaderEntry) => {
137
+ const start = performance.now();
138
+ const promise = runInsideLoaderScope(() =>
139
+ resolveLoaderData(loaderEntry, ctx, ctx.pathname),
140
+ );
141
+ return { promise, start, loaderId: loaderEntry.loader.$$id };
142
+ });
143
+ await Promise.all(pendingLoaderData.map((p) => p.promise));
122
144
 
123
145
  return loaderEntries.map((loaderEntry, i) => {
124
146
  const { loader } = loaderEntry;
125
147
  const segmentId = `${shortCode}D${i}.${loader.$$id}`;
148
+ const pending = pendingLoaderData[i]!;
149
+ if (ms && !ms.metrics.some((m) => m.label === `loader:${loader.$$id}`)) {
150
+ // All loaders ran in parallel via Promise.all — each span covers
151
+ // from its own kickoff to the batch settlement, giving a ceiling
152
+ // on that loader's contribution to the overall wait.
153
+ const batchEnd = performance.now();
154
+ appendMetric(
155
+ ms,
156
+ `loader:${loader.$$id}`,
157
+ pending.start,
158
+ batchEnd - pending.start,
159
+ 2,
160
+ );
161
+ }
126
162
  return {
127
163
  id: segmentId,
128
164
  namespace: entry.id,
@@ -132,7 +168,7 @@ export async function resolveLoaders<TEnv>(
132
168
  params: ctx.params,
133
169
  loaderId: loader.$$id,
134
170
  loaderData: deps.wrapLoaderPromise(
135
- pendingLoaderData[i]!,
171
+ pending.promise,
136
172
  entry,
137
173
  segmentId,
138
174
  ctx.pathname,
@@ -178,7 +214,9 @@ export async function resolveSegment<TEnv>(
178
214
  (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
179
215
  entry.shortCode;
180
216
 
217
+ const doneLayoutHandler = track(`handler:${entry.id}`, 2);
181
218
  const component = await resolveLayoutComponent(entry, context);
219
+ doneLayoutHandler();
182
220
 
183
221
  segments.push({
184
222
  id: entry.shortCode,
@@ -187,14 +225,20 @@ export async function resolveSegment<TEnv>(
187
225
  index: 0,
188
226
  component,
189
227
  loading: entry.loading === false ? null : entry.loading,
190
- transition: entry.transition,
228
+ transition: applyViewTransitionDefault(
229
+ entry.transition,
230
+ deps.viewTransitionDefault,
231
+ ),
191
232
  params,
192
233
  belongsToRoute: false,
193
234
  layoutName: entry.id,
194
235
  ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
195
236
  });
196
237
 
197
- for (const parallelEntry of entry.parallel) {
238
+ const resolvedParallelEntries = new Set<string>();
239
+ for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
240
+ entry.parallel,
241
+ )) {
198
242
  const parallelSegments = await resolveParallelEntry(
199
243
  parallelEntry,
200
244
  params,
@@ -204,8 +248,11 @@ export async function resolveSegment<TEnv>(
204
248
  deps,
205
249
  options,
206
250
  routeKey,
251
+ [slot],
252
+ !resolvedParallelEntries.has(parallelEntry.id),
207
253
  );
208
254
  segments.push(...parallelSegments);
255
+ resolvedParallelEntries.add(parallelEntry.id);
209
256
  }
210
257
 
211
258
  for (const orphan of entry.layout) {
@@ -241,9 +288,16 @@ export async function resolveSegment<TEnv>(
241
288
  entry.shortCode,
242
289
  );
243
290
  if (component === undefined) {
291
+ // For Passthrough routes at runtime, use the live handler instead of
292
+ // the build handler. At build time (context.build === true), always
293
+ // use the build handler from entry.handler.
294
+ const handler =
295
+ !context.build && entry.liveHandler ? entry.liveHandler : entry.handler;
296
+ const doneRouteHandler = track(`handler:${entry.id}`, 2);
244
297
  if (entry.loading) {
245
- const result = handleHandlerResult(entry.handler(context));
298
+ const result = handleHandlerResult(handler(context));
246
299
  if (result instanceof Promise) {
300
+ result.finally(doneRouteHandler).catch(() => {});
247
301
  const tracked = deps.trackHandler(result, {
248
302
  segmentId: entry.shortCode,
249
303
  segmentType: entry.type,
@@ -258,10 +312,12 @@ export async function resolveSegment<TEnv>(
258
312
  );
259
313
  component = tracked;
260
314
  } else {
315
+ doneRouteHandler();
261
316
  component = result;
262
317
  }
263
318
  } else {
264
- component = handleHandlerResult(await entry.handler(context));
319
+ component = handleHandlerResult(await handler(context));
320
+ doneRouteHandler();
265
321
  }
266
322
  }
267
323
 
@@ -275,11 +331,15 @@ export async function resolveSegment<TEnv>(
275
331
  deps,
276
332
  options,
277
333
  routeKey,
334
+ entry,
278
335
  );
279
336
  segments.push(...orphanSegments);
280
337
  }
281
338
 
282
- for (const parallelEntry of entry.parallel) {
339
+ const resolvedParallelEntries = new Set<string>();
340
+ for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
341
+ entry.parallel,
342
+ )) {
283
343
  const parallelSegments = await resolveParallelEntry(
284
344
  parallelEntry,
285
345
  params,
@@ -289,8 +349,11 @@ export async function resolveSegment<TEnv>(
289
349
  deps,
290
350
  options,
291
351
  routeKey,
352
+ [slot],
353
+ !resolvedParallelEntries.has(parallelEntry.id),
292
354
  );
293
355
  segments.push(...parallelSegments);
356
+ resolvedParallelEntries.add(parallelEntry.id);
294
357
  }
295
358
 
296
359
  segments.push({
@@ -298,9 +361,12 @@ export async function resolveSegment<TEnv>(
298
361
  namespace: entry.id,
299
362
  type: "route",
300
363
  index: 0,
301
- component,
364
+ component: component ?? null,
302
365
  loading: entry.loading === false ? null : entry.loading,
303
- transition: entry.transition,
366
+ transition: applyViewTransitionDefault(
367
+ entry.transition,
368
+ deps.viewTransitionDefault,
369
+ ),
304
370
  params,
305
371
  belongsToRoute: true,
306
372
  ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
@@ -324,6 +390,9 @@ export async function resolveOrphanLayout<TEnv>(
324
390
  deps: SegmentResolutionDeps<TEnv>,
325
391
  options?: ResolveSegmentOptions,
326
392
  routeKey?: string,
393
+ /** Parent route entry — its loaders are inherited by the layout so
394
+ * parallel slots inside this layout can access them via useLoader(). */
395
+ parentRouteEntry?: EntryData,
327
396
  ): Promise<ResolvedSegment[]> {
328
397
  invariant(
329
398
  orphan.type === "layout" || orphan.type === "cache",
@@ -339,11 +408,37 @@ export async function resolveOrphanLayout<TEnv>(
339
408
  deps,
340
409
  );
341
410
  segments.push(...loaderSegments);
411
+
412
+ // Inherit parent route's loaders so parallel slots inside this layout
413
+ // can access them via useLoader(). Without this, the route's loaders
414
+ // are only in the route's OutletProvider (rendered as <Outlet /> content),
415
+ // which is a child — not a parent — of the layout's context.
416
+ if (
417
+ parentRouteEntry &&
418
+ parentRouteEntry.loader &&
419
+ parentRouteEntry.loader.length > 0 &&
420
+ Object.keys(orphan.parallel).length > 0
421
+ ) {
422
+ const inheritedLoaders = await resolveLoaders(
423
+ parentRouteEntry,
424
+ context,
425
+ belongsToRoute,
426
+ deps,
427
+ orphan.shortCode,
428
+ );
429
+ // Tag as inherited so buildMatchResult can deduplicate when safe
430
+ for (const s of inheritedLoaders) {
431
+ s._inherited = true;
432
+ }
433
+ segments.push(...inheritedLoaders);
434
+ }
342
435
  }
343
436
 
344
437
  // Handler-first: orphan layout handler executes before its parallels
345
438
  // so that ctx.set() values are visible to parallel children.
439
+ const doneOrphanHandler = track(`handler:${orphan.id}`, 2);
346
440
  const component = await resolveLayoutComponent(orphan, context);
441
+ doneOrphanHandler();
347
442
 
348
443
  segments.push({
349
444
  id: orphan.shortCode,
@@ -355,11 +450,17 @@ export async function resolveOrphanLayout<TEnv>(
355
450
  belongsToRoute,
356
451
  layoutName: orphan.id,
357
452
  loading: orphan.loading === false ? null : orphan.loading,
358
- transition: orphan.transition,
453
+ transition: applyViewTransitionDefault(
454
+ orphan.transition,
455
+ deps.viewTransitionDefault,
456
+ ),
359
457
  ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
360
458
  });
361
459
 
362
- for (const parallelEntry of orphan.parallel) {
460
+ const resolvedParallelEntries = new Set<string>();
461
+ for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
462
+ orphan.parallel,
463
+ )) {
363
464
  const parallelSegments = await resolveParallelEntry(
364
465
  parallelEntry,
365
466
  params,
@@ -369,8 +470,11 @@ export async function resolveOrphanLayout<TEnv>(
369
470
  deps,
370
471
  options,
371
472
  routeKey,
473
+ [slot],
474
+ !resolvedParallelEntries.has(parallelEntry.id),
372
475
  );
373
476
  segments.push(...parallelSegments);
477
+ resolvedParallelEntries.add(parallelEntry.id);
374
478
  }
375
479
 
376
480
  return segments;
@@ -388,6 +492,8 @@ export async function resolveParallelEntry<TEnv>(
388
492
  deps: SegmentResolutionDeps<TEnv>,
389
493
  options?: ResolveSegmentOptions,
390
494
  routeKey?: string,
495
+ slotNames?: `@${string}`[],
496
+ includeLoaders: boolean = true,
391
497
  ): Promise<ResolvedSegment[]> {
392
498
  invariant(
393
499
  parallelEntry.type === "parallel",
@@ -402,7 +508,12 @@ export async function resolveParallelEntry<TEnv>(
402
508
  | ReactNode
403
509
  >;
404
510
 
405
- for (const [slot, handler] of Object.entries(slots)) {
511
+ const slotsToResolve = slotNames ?? (Object.keys(slots) as `@${string}`[]);
512
+
513
+ for (const slot of slotsToResolve) {
514
+ // Try static lookup first — in production, handler bodies are evicted
515
+ // and replaced with stubs that have no .handler property (undefined).
516
+ // The static store holds the pre-rendered component for these slots.
406
517
  let component: ReactNode | undefined = await tryStaticSlot(
407
518
  parallelEntry,
408
519
  slot,
@@ -410,12 +521,29 @@ export async function resolveParallelEntry<TEnv>(
410
521
  );
411
522
 
412
523
  if (component === undefined) {
524
+ const handler = slots[slot];
525
+ if (handler === undefined) {
526
+ continue;
527
+ }
528
+ // Pin `_currentSegmentId` to the slot's own id so handle pushes from
529
+ // inside the slot handler get their own bucket in the HandleStore.
530
+ // Parent-keying would collapse them into the parent layout's bucket;
531
+ // the partial-update merge then replaces the parent's bucket on a
532
+ // slot-only revalidation and drops layout-pushed Meta/Breadcrumbs.
533
+ // filterSegmentOrder() retains slot ids so the client preserves them.
534
+ (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
535
+ `${parentShortCode}.${slot}`;
536
+ const doneParallelHandler = track(
537
+ `handler:${parallelEntry.id}.${slot}`,
538
+ 2,
539
+ );
413
540
  const hasLoadingFallback =
414
541
  parallelEntry.loading !== undefined && parallelEntry.loading !== false;
415
542
  if (hasLoadingFallback) {
416
543
  const result =
417
544
  typeof handler === "function" ? handler(context) : handler;
418
545
  if (result instanceof Promise) {
546
+ result.finally(doneParallelHandler).catch(() => {});
419
547
  const tracked = deps.trackHandler(result, {
420
548
  segmentId: `${parentShortCode}.${slot}`,
421
549
  segmentType: "parallel",
@@ -430,11 +558,13 @@ export async function resolveParallelEntry<TEnv>(
430
558
  );
431
559
  component = tracked as ReactNode;
432
560
  } else {
561
+ doneParallelHandler();
433
562
  component = result as ReactNode;
434
563
  }
435
564
  } else {
436
565
  component =
437
566
  typeof handler === "function" ? await handler(context) : handler;
567
+ doneParallelHandler();
438
568
  }
439
569
  }
440
570
 
@@ -445,7 +575,10 @@ export async function resolveParallelEntry<TEnv>(
445
575
  index: 0,
446
576
  component,
447
577
  loading: parallelEntry.loading === false ? null : parallelEntry.loading,
448
- transition: parallelEntry.transition,
578
+ transition: applyViewTransitionDefault(
579
+ parallelEntry.transition,
580
+ deps.viewTransitionDefault,
581
+ ),
449
582
  params,
450
583
  slot,
451
584
  belongsToRoute,
@@ -456,7 +589,7 @@ export async function resolveParallelEntry<TEnv>(
456
589
  });
457
590
  }
458
591
 
459
- if (!parallelEntry.loading && !options?.skipLoaders) {
592
+ if (!options?.skipLoaders && includeLoaders) {
460
593
  const loaderSegments = await resolveLoaders(
461
594
  parallelEntry,
462
595
  context,
@@ -464,6 +597,15 @@ export async function resolveParallelEntry<TEnv>(
464
597
  deps,
465
598
  parentShortCode,
466
599
  );
600
+ // Tag parallel-owned loaders so renderSegments can stream them
601
+ // using the parallel's loading() instead of awaiting on the layout
602
+ const parallelLoading =
603
+ parallelEntry.loading === false ? undefined : parallelEntry.loading;
604
+ if (parallelLoading) {
605
+ for (const seg of loaderSegments) {
606
+ seg.parallelLoading = parallelLoading;
607
+ }
608
+ }
467
609
  segments.push(...loaderSegments);
468
610
  }
469
611
 
@@ -499,6 +641,14 @@ export async function resolveAllSegments<TEnv>(
499
641
  } catch {}
500
642
 
501
643
  for (const entry of entries) {
644
+ // Set ALS flag when entering a cache() boundary so that ctx.get()
645
+ // can guard non-cacheable variable reads. Also guards response-level
646
+ // side effects (headers.set). Persists for all descendant entries.
647
+ if (entry.type === "cache") {
648
+ const store = RangoContext.getStore();
649
+ if (store) store.insideCacheScope = true;
650
+ }
651
+ const doneEntry = track(`segment:${entry.id}`, 1);
502
652
  const resolvedSegments = await resolveWithErrorBoundary(
503
653
  entry,
504
654
  params,
@@ -518,6 +668,7 @@ export async function resolveAllSegments<TEnv>(
518
668
  { request: safeRequest, url: context.url, routeKey, telemetry },
519
669
  context.pathname,
520
670
  );
671
+ doneEntry();
521
672
  // Deduplicate by segment ID. include() scopes can produce entries that
522
673
  // resolve the same shared layout/loader segment. Duplicates in the segment
523
674
  // array propagate to the client's matched[] and change the React tree depth.
@@ -541,11 +692,77 @@ export async function resolveLoadersOnly<TEnv>(
541
692
  deps: SegmentResolutionDeps<TEnv>,
542
693
  ): Promise<ResolvedSegment[]> {
543
694
  const loaderSegments: ResolvedSegment[] = [];
695
+ const seenIds = new Set<string>();
696
+
697
+ async function collectEntryLoaders(
698
+ entry: EntryData,
699
+ belongsToRoute: boolean,
700
+ shortCodeOverride?: string,
701
+ ): Promise<void> {
702
+ // Skip if all loaders from this entry have already been resolved
703
+ // via a parent (e.g., cache boundary wrapping a layout with shared loaders).
704
+ const entryLoaders = entry.loader ?? [];
705
+ const sc = shortCodeOverride ?? entry.shortCode;
706
+ const allAlreadySeen =
707
+ entryLoaders.length > 0 &&
708
+ entryLoaders.every((le, i) =>
709
+ seenIds.has(`${sc}D${i}.${le.loader.$$id}`),
710
+ );
711
+ if (!allAlreadySeen) {
712
+ const segments = await resolveLoaders(
713
+ entry,
714
+ context,
715
+ belongsToRoute,
716
+ deps,
717
+ shortCodeOverride,
718
+ );
719
+ for (const seg of segments) {
720
+ if (!seenIds.has(seg.id)) {
721
+ seenIds.add(seg.id);
722
+ loaderSegments.push(seg);
723
+ }
724
+ }
725
+ }
726
+
727
+ const seenParallelEntryIds = new Set<string>();
728
+ for (const parallelEntry of getParallelEntries(entry.parallel)) {
729
+ if (seenParallelEntryIds.has(parallelEntry.id)) continue;
730
+ seenParallelEntryIds.add(parallelEntry.id);
731
+ await collectEntryLoaders(parallelEntry, belongsToRoute, entry.shortCode);
732
+ }
733
+
734
+ const childBelongsToRoute = belongsToRoute || entry.type === "route";
735
+ for (const layoutEntry of entry.layout) {
736
+ await collectEntryLoaders(layoutEntry, childBelongsToRoute);
737
+ // Inherit route loaders for orphan layouts with parallels.
738
+ // Resolve directly — do NOT re-enter collectEntryLoaders with the
739
+ // route entry, as that would re-iterate route.layout and loop.
740
+ if (
741
+ entry.type === "route" &&
742
+ entry.loader &&
743
+ entry.loader.length > 0 &&
744
+ Object.keys(layoutEntry.parallel).length > 0
745
+ ) {
746
+ const inherited = await resolveLoaders(
747
+ entry,
748
+ context,
749
+ childBelongsToRoute,
750
+ deps,
751
+ layoutEntry.shortCode,
752
+ );
753
+ for (const seg of inherited) {
754
+ if (!seenIds.has(seg.id)) {
755
+ seenIds.add(seg.id);
756
+ seg._inherited = true;
757
+ loaderSegments.push(seg);
758
+ }
759
+ }
760
+ }
761
+ }
762
+ }
544
763
 
545
764
  for (const entry of entries) {
546
- const belongsToRoute = entry.type === "route";
547
- const segments = await resolveLoaders(entry, context, belongsToRoute, deps);
548
- loaderSegments.push(...segments);
765
+ await collectEntryLoaders(entry, entry.type === "route");
549
766
  }
550
767
 
551
768
  return loaderSegments;
@@ -8,7 +8,7 @@
8
8
  * - Error boundary segment creation
9
9
  */
10
10
 
11
- import type { ReactNode } from "react";
11
+ import { createElement, type ReactNode } from "react";
12
12
  import { DataNotFoundError } from "../../errors";
13
13
  import {
14
14
  createErrorInfo,
@@ -174,40 +174,45 @@ export function catchSegmentError<TEnv>(
174
174
  const setResponseStatus = (status: number) => {
175
175
  const reqCtx = getRequestContext();
176
176
  if (reqCtx) {
177
- reqCtx.setStatus(status);
177
+ reqCtx._setStatus(status);
178
178
  }
179
179
  };
180
180
 
181
181
  if (error instanceof DataNotFoundError) {
182
182
  const notFoundFallback = deps.findNearestNotFoundBoundary(entry);
183
+ // Fall back to router's notFound component, then a plain default
184
+ const notFoundOption = deps.notFoundComponent;
185
+ const defaultFallback =
186
+ typeof notFoundOption === "function"
187
+ ? notFoundOption({ pathname: pathname ?? "" })
188
+ : (notFoundOption ?? createElement("h1", null, "Not Found"));
189
+ const effectiveNotFoundFallback = notFoundFallback ?? defaultFallback;
183
190
 
184
- if (notFoundFallback) {
185
- const notFoundInfo = createNotFoundInfo(
186
- error,
187
- entry.shortCode,
188
- entry.type,
189
- pathname,
190
- );
191
+ const notFoundInfo = createNotFoundInfo(
192
+ error,
193
+ entry.shortCode,
194
+ entry.type,
195
+ pathname,
196
+ );
191
197
 
192
- reportError(true, {
193
- notFound: true,
194
- message: notFoundInfo.message,
195
- });
198
+ reportError(true, {
199
+ notFound: true,
200
+ message: notFoundInfo.message,
201
+ });
196
202
 
197
- debugLog("segment", "notFound boundary handled error", {
198
- segmentId: entry.shortCode,
199
- message: notFoundInfo.message,
200
- });
203
+ debugLog("segment", "notFound boundary handled error", {
204
+ segmentId: entry.shortCode,
205
+ message: notFoundInfo.message,
206
+ });
201
207
 
202
- setResponseStatus(404);
208
+ setResponseStatus(404);
203
209
 
204
- return createNotFoundSegment(
205
- notFoundInfo,
206
- notFoundFallback,
207
- entry,
208
- params,
209
- );
210
- }
210
+ return createNotFoundSegment(
211
+ notFoundInfo,
212
+ effectiveNotFoundFallback,
213
+ entry,
214
+ params,
215
+ );
211
216
  }
212
217
 
213
218
  const fallback = deps.findNearestErrorBoundary(entry);
@@ -147,6 +147,7 @@ export function resolveLoaderData<TEnv>(
147
147
  }
148
148
 
149
149
  const loaderId = loaderEntry.loader.$$id;
150
+
150
151
  const ttl = resolveTtl(options.ttl, store.defaults, DEFAULT_ROUTE_TTL);
151
152
  const swrWindow = resolveSwrWindow(options.swr, store.defaults);
152
153
  const swr = swrWindow || undefined;