@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
@@ -10,7 +10,11 @@
10
10
  */
11
11
 
12
12
  // Public API
13
- export { CFCacheStore, type CFCacheStoreOptions } from "./cf-cache-store.js";
13
+ export {
14
+ CFCacheStore,
15
+ type CFCacheStoreOptions,
16
+ type KVNamespace,
17
+ } from "./cf-cache-store.js";
14
18
 
15
19
  // Header constants for debugging and inspection
16
20
  export {
@@ -13,6 +13,7 @@
13
13
 
14
14
  import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
15
15
  import { getRequestContext } from "../server/request-context.js";
16
+ import { mayNeedSSR } from "../rsc/ssr-setup.js";
16
17
  import { sortedSearchString } from "./cache-key-utils.js";
17
18
  import { runBackground } from "./background-task.js";
18
19
 
@@ -204,18 +205,24 @@ export function createDocumentCacheMiddleware<TEnv = any>(
204
205
  ): Promise<Response> {
205
206
  const url = ctx.url;
206
207
 
208
+ // Use the original request URL for _rsc* param detection and cache key
209
+ // differentiation. ctx.url is stripped of _rsc* params by the middleware
210
+ // pipeline (stripInternalParams), so _rsc_partial, _rsc_segments, etc.
211
+ // are not visible on ctx.url in production.
212
+ const rawUrl = new URL(ctx.request.url);
213
+
207
214
  // Only cache GET requests — mutations and other methods must not be cached
208
215
  if (ctx.request.method !== "GET") {
209
216
  return next();
210
217
  }
211
218
 
212
219
  // Skip RSC action requests (mutations shouldn't be cached)
213
- if (url.searchParams.has("_rsc_action")) {
220
+ if (rawUrl.searchParams.has("_rsc_action")) {
214
221
  return next();
215
222
  }
216
223
 
217
224
  // Skip loader requests (have their own caching)
218
- if (url.searchParams.has("_rsc_loader")) {
225
+ if (rawUrl.searchParams.has("_rsc_loader")) {
219
226
  return next();
220
227
  }
221
228
 
@@ -241,9 +248,12 @@ export function createDocumentCacheMiddleware<TEnv = any>(
241
248
  return next();
242
249
  }
243
250
 
244
- // Determine request type for cache key differentiation
245
- const isPartial = url.searchParams.has("_rsc_partial");
246
- const typeLabel = isPartial ? "RSC" : "HTML";
251
+ // Determine request type for cache key differentiation.
252
+ // Uses rawUrl for _rsc* param checks and mayNeedSSR for Accept-based
253
+ // detection. Full-document RSC fetches must not share the HTML cache slot.
254
+ const isPartial = rawUrl.searchParams.has("_rsc_partial");
255
+ const isRscRequest = !mayNeedSSR(ctx.request, rawUrl);
256
+ const typeLabel = isRscRequest ? "RSC" : "HTML";
247
257
 
248
258
  // Track whether next() has been called so the catch block knows
249
259
  // whether it is safe to fall through to the handler.
@@ -254,10 +264,10 @@ export function createDocumentCacheMiddleware<TEnv = any>(
254
264
  // gracefully to the origin handler instead of rejecting the request.
255
265
  // This is a deliberate fail-open-to-origin policy: the fallback is
256
266
  // "serve uncached from origin", not "use a different cache key".
257
- const clientSegments = url.searchParams.get("_rsc_segments") || "";
267
+ const clientSegments = rawUrl.searchParams.get("_rsc_segments") || "";
258
268
  const segmentHash =
259
269
  isPartial && clientSegments ? `:${hashSegmentIds(clientSegments)}` : "";
260
- const typeSuffix = isPartial ? ":rsc" : ":html";
270
+ const typeSuffix = isRscRequest ? ":rsc" : ":html";
261
271
 
262
272
  let searchSuffix = "";
263
273
  if (!keyGenerator) {
@@ -29,6 +29,7 @@ export { MemorySegmentCacheStore } from "./memory-segment-store.js";
29
29
  export {
30
30
  CFCacheStore,
31
31
  type CFCacheStoreOptions,
32
+ type KVNamespace,
32
33
  CACHE_STALE_AT_HEADER,
33
34
  CACHE_STATUS_HEADER,
34
35
  } from "./cf/index.js";
@@ -81,6 +81,61 @@ export function assertNotInsideCacheExec(
81
81
  }
82
82
  }
83
83
 
84
+ /**
85
+ * Symbol stamped on ctx when resolving handlers inside a cache() DSL boundary.
86
+ * Separate from INSIDE_CACHE_EXEC ("use cache") because cache() allows
87
+ * ctx.set() (children are also cached) but blocks response-level side effects
88
+ * (headers, cookies, status) which are lost on cache hit.
89
+ */
90
+ export const INSIDE_CACHE_SCOPE: unique symbol = Symbol.for(
91
+ "rango:inside-cache-scope",
92
+ ) as any;
93
+
94
+ /**
95
+ * Mark ctx as inside a cache() scope. Must be paired with unstampCacheScope.
96
+ */
97
+ export function stampCacheScope(obj: object): void {
98
+ const current = (obj as any)[INSIDE_CACHE_SCOPE] ?? 0;
99
+ (obj as any)[INSIDE_CACHE_SCOPE] = current + 1;
100
+ }
101
+
102
+ /**
103
+ * Remove cache() scope mark.
104
+ */
105
+ export function unstampCacheScope(obj: object): void {
106
+ const current = (obj as any)[INSIDE_CACHE_SCOPE] ?? 0;
107
+ if (current <= 1) {
108
+ delete (obj as any)[INSIDE_CACHE_SCOPE];
109
+ } else {
110
+ (obj as any)[INSIDE_CACHE_SCOPE] = current - 1;
111
+ }
112
+ }
113
+
114
+ /**
115
+ * Throw if ctx is inside a cache() DSL boundary.
116
+ * Call from response-level side effects (header, setCookie, setStatus, etc.)
117
+ * which are lost on cache hit because the handler body is skipped.
118
+ * ctx.set() is allowed inside cache() — children are also cached and can
119
+ * read the value.
120
+ */
121
+ export function assertNotInsideCacheScope(
122
+ ctx: unknown,
123
+ methodName: string,
124
+ ): void {
125
+ if (
126
+ ctx !== null &&
127
+ ctx !== undefined &&
128
+ typeof ctx === "object" &&
129
+ (INSIDE_CACHE_SCOPE as symbol) in (ctx as Record<symbol, unknown>)
130
+ ) {
131
+ throw new Error(
132
+ `ctx.${methodName}() cannot be called inside a cache() boundary. ` +
133
+ `On cache hit the handler is skipped, so this side effect would be lost. ` +
134
+ `Move ctx.${methodName}() to a middleware or layout outside the cache() scope.`,
135
+ );
136
+ }
137
+ }
138
+
84
139
  /**
85
140
  * Brand symbol for functions wrapped by registerCachedFunction().
86
141
  * Used at runtime to detect when a "use cache" function is misused
@@ -17,7 +17,6 @@ export {
17
17
  OutletProvider,
18
18
  useOutlet,
19
19
  useLoader,
20
- useLoaderData,
21
20
  ErrorBoundary,
22
21
  type ErrorBoundaryProps,
23
22
  } from "./client.js";
@@ -64,6 +63,8 @@ export { Meta } from "./handles/meta.js";
64
63
  // MetaTags is a "use client" component that can be imported from RSC
65
64
  export { MetaTags } from "./handles/MetaTags.js";
66
65
  export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
66
+ // Breadcrumbs handle works in RSC context
67
+ export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
67
68
 
68
69
  // Location state - createLocationState works in RSC (just creates definition)
69
70
  // useLocationState is NOT exported here as it uses client hooks
@@ -77,6 +78,9 @@ export {
77
78
  // Re-export useHref - it's a "use client" hook
78
79
  export { useHref } from "./browser/react/use-href.js";
79
80
 
81
+ // Re-export useReverse - it's a "use client" hook
82
+ export { useReverse } from "./browser/react/use-reverse.js";
83
+
80
84
  // Re-export useHandle - it's a "use client" hook
81
85
  export { useHandle } from "./browser/react/use-handle.js";
82
86
 
package/src/client.tsx CHANGED
@@ -13,7 +13,6 @@ import {
13
13
  type ClientErrorBoundaryFallbackProps,
14
14
  type ErrorInfo,
15
15
  type LoaderDefinition,
16
- type LoaderFn,
17
16
  type ResolvedSegment,
18
17
  } from "./types";
19
18
  import {
@@ -22,6 +21,83 @@ import {
22
21
  } from "./route-content-wrapper.js";
23
22
  import { OutletProvider } from "./outlet-provider.js";
24
23
  import { MountContextProvider } from "./browser/react/mount-context.js";
24
+ import { getMemoizedContentPromise } from "./segment-content-promise.js";
25
+
26
+ /**
27
+ * Render the content for a named parallel/intercept slot segment.
28
+ *
29
+ * Shared by Outlet (with `name` prop) and ParallelOutlet — both resolve a
30
+ * segment from context.parallel by slot name and then render it through the
31
+ * same layout/loader/mountPath wrapping pipeline.
32
+ */
33
+ function renderSlotContent(segment: ResolvedSegment | null): ReactNode {
34
+ if (!segment) return null;
35
+
36
+ const content: ReactNode =
37
+ segment.loading || segment.component instanceof Promise ? (
38
+ <RouteContentWrapper
39
+ content={getMemoizedContentPromise(segment.component)}
40
+ fallback={segment.loading}
41
+ segmentId={segment.id}
42
+ />
43
+ ) : (
44
+ (segment.component ?? null)
45
+ );
46
+
47
+ const hasOwnLoaders = !!(segment.loaderDataPromise && segment.loaderIds);
48
+ const loaderWrapped = hasOwnLoaders ? (
49
+ <LoaderBoundary
50
+ loaderDataPromise={segment.loaderDataPromise!}
51
+ loaderIds={segment.loaderIds!}
52
+ fallback={segment.loading}
53
+ outletKey={segment.id + "-loader"}
54
+ outletContent={null}
55
+ segment={segment}
56
+ >
57
+ {content}
58
+ </LoaderBoundary>
59
+ ) : null;
60
+
61
+ let result: ReactNode;
62
+ if (segment.layout) {
63
+ // Layout renders immediately; if loaders exist, the LoaderBoundary becomes
64
+ // the outlet content so layout's <Outlet /> suspends until loaders resolve.
65
+ result = (
66
+ <OutletProvider
67
+ content={hasOwnLoaders ? loaderWrapped : content}
68
+ segment={segment}
69
+ >
70
+ {segment.layout}
71
+ </OutletProvider>
72
+ );
73
+ } else if (hasOwnLoaders) {
74
+ // No layout but has loaders — wrap content with LoaderBoundary for useLoader context.
75
+ // Common for intercept routes that use useLoader without a custom layout.
76
+ result = loaderWrapped;
77
+ } else {
78
+ result = content;
79
+ }
80
+
81
+ if (segment.mountPath) {
82
+ return (
83
+ <MountContextProvider value={segment.mountPath}>
84
+ {result}
85
+ </MountContextProvider>
86
+ );
87
+ }
88
+
89
+ return result;
90
+ }
91
+
92
+ function useSlotSegment(
93
+ context: OutletContextValue | null,
94
+ name: `@${string}` | undefined,
95
+ ): ResolvedSegment | null {
96
+ return useMemo(() => {
97
+ if (!name || !context?.parallel) return null;
98
+ return context.parallel.find((seg) => seg.slot === name) ?? null;
99
+ }, [context, name]);
100
+ }
25
101
 
26
102
  /**
27
103
  * Outlet component - renders child content in layouts
@@ -62,95 +138,10 @@ import { MountContextProvider } from "./browser/react/mount-context.js";
62
138
  */
63
139
  export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
64
140
  const context = useContext(OutletContext);
141
+ const namedSegment = useSlotSegment(context, name);
65
142
 
66
- // If name provided, render parallel/intercept content for that slot
67
143
  if (name) {
68
- const segment = context?.parallel?.find((seg) => seg.slot === name) ?? null;
69
-
70
- if (!segment) return null;
71
-
72
- // Determine the content to render
73
- let content: ReactNode;
74
- if (segment.loading || segment.component instanceof Promise) {
75
- // Use RouteContentWrapper to handle Suspense wrapping properly
76
- content = (
77
- <RouteContentWrapper
78
- content={
79
- segment.component instanceof Promise
80
- ? segment.component
81
- : Promise.resolve(segment.component)
82
- }
83
- fallback={segment.loading}
84
- segmentId={segment.id}
85
- />
86
- );
87
- } else {
88
- content = segment.component ?? null;
89
- }
90
-
91
- let result: ReactNode;
92
-
93
- // If segment has a layout, wrap appropriately
94
- if (segment.layout) {
95
- // Check if this segment has loaders that need streaming
96
- // The layout renders immediately, LoaderBoundary becomes the outlet content
97
- // When layout renders <Outlet />, it gets the LoaderBoundary which suspends
98
- if (segment.loaderDataPromise && segment.loaderIds) {
99
- const loaderAwareContent = (
100
- <LoaderBoundary
101
- loaderDataPromise={segment.loaderDataPromise}
102
- loaderIds={segment.loaderIds}
103
- fallback={segment.loading}
104
- outletKey={segment.id + "-loader"}
105
- outletContent={null}
106
- segment={segment}
107
- >
108
- {content}
109
- </LoaderBoundary>
110
- );
111
-
112
- result = (
113
- <OutletProvider content={loaderAwareContent} segment={segment}>
114
- {segment.layout}
115
- </OutletProvider>
116
- );
117
- } else {
118
- // No loaders - wrap in OutletProvider so layout can use <Outlet />
119
- result = (
120
- <OutletProvider content={content} segment={segment}>
121
- {segment.layout}
122
- </OutletProvider>
123
- );
124
- }
125
- } else if (segment.loaderDataPromise && segment.loaderIds) {
126
- // No layout but has loaders - wrap content with LoaderBoundary for useLoader context
127
- // This is common for intercept routes that use useLoader without a custom layout
128
- result = (
129
- <LoaderBoundary
130
- loaderDataPromise={segment.loaderDataPromise}
131
- loaderIds={segment.loaderIds}
132
- fallback={segment.loading}
133
- outletKey={segment.id + "-loader"}
134
- outletContent={null}
135
- segment={segment}
136
- >
137
- {content}
138
- </LoaderBoundary>
139
- );
140
- } else {
141
- result = content;
142
- }
143
-
144
- // Wrap with MountContextProvider for include() scoped parallel/intercept slots
145
- if (segment.mountPath) {
146
- return (
147
- <MountContextProvider value={segment.mountPath}>
148
- {result}
149
- </MountContextProvider>
150
- );
151
- }
152
-
153
- return result;
144
+ return renderSlotContent(namedSegment);
154
145
  }
155
146
 
156
147
  // Default: render child content
@@ -164,6 +155,7 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
164
155
 
165
156
  return content;
166
157
  }
158
+
167
159
  /**
168
160
  * ParallelOutlet component - renders content for a named parallel slot
169
161
  *
@@ -188,94 +180,9 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
188
180
  */
189
181
  export function ParallelOutlet({ name }: { name: `@${string}` }): ReactNode {
190
182
  const context = useContext(OutletContext);
191
- const segment = useMemo(() => {
192
- if (!context?.parallel) return null;
193
- return context.parallel.find((seg) => seg.slot === name) ?? null;
194
- }, [context, name]);
195
-
196
- if (!segment) return null;
183
+ const segment = useSlotSegment(context, name);
197
184
 
198
- // Determine the content to render
199
- let content: ReactNode;
200
- if (segment.loading || segment.component instanceof Promise) {
201
- // Use RouteContentWrapper to handle Suspense wrapping properly
202
- content = (
203
- <RouteContentWrapper
204
- content={
205
- segment.component instanceof Promise
206
- ? segment.component
207
- : Promise.resolve(segment.component)
208
- }
209
- fallback={segment.loading}
210
- segmentId={segment.id}
211
- />
212
- );
213
- } else {
214
- content = segment.component ?? null;
215
- }
216
-
217
- let result: ReactNode;
218
-
219
- // If segment has a layout, wrap appropriately
220
- if (segment.layout) {
221
- // Check if this segment has loaders that need streaming
222
- // The layout renders immediately, LoaderBoundary becomes the outlet content
223
- if (segment.loaderDataPromise && segment.loaderIds) {
224
- const loaderAwareContent = (
225
- <LoaderBoundary
226
- loaderDataPromise={segment.loaderDataPromise}
227
- loaderIds={segment.loaderIds}
228
- fallback={segment.loading}
229
- outletKey={segment.id + "-loader"}
230
- outletContent={null}
231
- segment={segment}
232
- >
233
- {content}
234
- </LoaderBoundary>
235
- );
236
-
237
- result = (
238
- <OutletProvider content={loaderAwareContent} segment={segment}>
239
- {segment.layout}
240
- </OutletProvider>
241
- );
242
- } else {
243
- // No loaders - wrap in OutletProvider so layout can use <Outlet />
244
- result = (
245
- <OutletProvider content={content} segment={segment}>
246
- {segment.layout}
247
- </OutletProvider>
248
- );
249
- }
250
- } else if (segment.loaderDataPromise && segment.loaderIds) {
251
- // No layout but has loaders - wrap content with LoaderBoundary for useLoader context
252
- // This is common for intercept routes that use useLoader without a custom layout
253
- result = (
254
- <LoaderBoundary
255
- loaderDataPromise={segment.loaderDataPromise}
256
- loaderIds={segment.loaderIds}
257
- fallback={segment.loading}
258
- outletKey={segment.id + "-loader"}
259
- outletContent={null}
260
- segment={segment}
261
- >
262
- {content}
263
- </LoaderBoundary>
264
- );
265
- } else {
266
- result = content;
267
- }
268
-
269
- // Wrap with MountContextProvider for include() scoped parallel/intercept slots
270
- if (segment.mountPath) {
271
- return (
272
- <MountContextProvider value={segment.mountPath}>
273
- {result}
274
- </MountContextProvider>
275
- );
276
- }
277
-
278
- return result;
185
+ return renderSlotContent(segment);
279
186
  }
280
187
 
281
188
  // OutletProvider is defined in outlet-provider.tsx to break a circular
@@ -307,109 +214,13 @@ export function useOutlet(): ReactNode {
307
214
  export {
308
215
  useLoader,
309
216
  useFetchLoader,
217
+ useRefreshLoaders,
310
218
  type LoadFunction,
311
219
  type UseLoaderResult,
312
220
  type UseFetchLoaderResult,
313
221
  type UseLoaderOptions,
314
222
  } from "./use-loader.js";
315
223
 
316
- /**
317
- * Hook to access all loader data in the current context
318
- *
319
- * Returns a record of all loader data available in the current outlet context
320
- * and all parent contexts. Useful for debugging or when you need access to
321
- * multiple loaders.
322
- *
323
- * @returns Record of loader name to data, or empty object if no loaders
324
- *
325
- * @example
326
- * ```tsx
327
- * "use client";
328
- * import { useLoaderData } from "rsc-router/client";
329
- *
330
- * export function DebugPanel() {
331
- * const loaderData = useLoaderData();
332
- * return <pre>{JSON.stringify(loaderData, null, 2)}</pre>;
333
- * }
334
- * ```
335
- */
336
- export function useLoaderData(): Record<string, any> {
337
- const context = useContext(OutletContext);
338
-
339
- // Collect all loader data from the context chain
340
- // Child loaders override parent loaders with the same name
341
- const result: Record<string, any> = {};
342
- const stack: OutletContextValue[] = [];
343
-
344
- // Build stack from current to root
345
- let current: OutletContextValue | null | undefined = context;
346
- while (current) {
347
- stack.push(current);
348
- current = current.parent;
349
- }
350
-
351
- // Apply from root to current (so children override parents)
352
- for (let i = stack.length - 1; i >= 0; i--) {
353
- const ctx = stack[i];
354
- if (ctx.loaderData) {
355
- Object.assign(result, ctx.loaderData);
356
- }
357
- }
358
-
359
- return result;
360
- }
361
-
362
- /**
363
- * Client-safe createLoader factory
364
- *
365
- * Creates a loader definition that can be used with useLoader().
366
- * This is the client-side version that only stores the $$id - the function
367
- * is ignored since loaders only execute on the server.
368
- *
369
- * The $$id is injected by the exposeLoaderId Vite plugin. In most cases,
370
- * you should import the loader directly from the server file rather than
371
- * creating a reference manually.
372
- *
373
- * @param fn - Loader function (ignored on client, kept for API compatibility)
374
- * @param _fetchable - Optional fetchable flag (ignored on client)
375
- * @param __injectedId - $$id injected by Vite plugin
376
- *
377
- * @example
378
- * ```tsx
379
- * "use client";
380
- * import { useLoader } from "rsc-router/client";
381
- * import { CartLoader } from "../loaders/cart"; // Import from server file
382
- *
383
- * export function CartIcon() {
384
- * const cart = useLoader(CartLoader);
385
- * return <span>Cart ({cart?.items.length ?? 0})</span>;
386
- * }
387
- * ```
388
- */
389
- // Overload 1: With function only (not fetchable)
390
- export function createLoader<T>(
391
- fn: LoaderFn<T, Record<string, string | undefined>, any>,
392
- ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
393
-
394
- // Overload 2: With function and fetchable flag
395
- export function createLoader<T>(
396
- fn: LoaderFn<T, Record<string, string | undefined>, any>,
397
- fetchable: true,
398
- ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
399
-
400
- // Implementation - function is ignored at runtime on client
401
- // The $$id is injected by Vite plugin as hidden third parameter
402
- export function createLoader(
403
- _fn: LoaderFn<any, Record<string, string | undefined>, any>,
404
- _fetchable?: true,
405
- __injectedId?: string,
406
- ): LoaderDefinition<any, Record<string, string | undefined>> {
407
- return {
408
- __brand: "loader",
409
- $$id: __injectedId || "",
410
- };
411
- }
412
-
413
224
  /**
414
225
  * Props for the ErrorBoundary component
415
226
  */
@@ -580,16 +391,15 @@ export {
580
391
  type ScrollRestorationProps,
581
392
  } from "./browser/react/ScrollRestoration.js";
582
393
 
583
- // Handle API - for accumulating data across route segments
584
- export { createHandle, isHandle, type Handle } from "./handle.js";
585
-
586
- // Handle data hook
394
+ // Handle data hook (client-side only — createHandle/isHandle are server APIs from the root export)
395
+ export { type Handle } from "./handle.js";
587
396
  export { useHandle } from "./browser/react/use-handle.js";
588
397
 
589
398
  // Built-in handles
590
399
  export { Meta } from "./handles/meta.js";
591
400
  export { MetaTags } from "./handles/MetaTags.js";
592
401
  export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
402
+ export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
593
403
 
594
404
  // Location state - type-safe navigation state
595
405
  export {
@@ -600,13 +410,10 @@ export {
600
410
  type LocationStateOptions,
601
411
  } from "./browser/react/location-state.js";
602
412
 
603
- // Type-safe href for client-side path validation
604
- export {
605
- href,
606
- type ValidPaths,
607
- type PatternToPath,
608
- type PathResponse,
609
- } from "./href-client.js";
413
+ // Type-safe href for client-side path validation. The path and response types
414
+ // are ambient as `Rango.Path` / `Rango.PathResponse` (declared in
415
+ // href-client.ts) — no import needed.
416
+ export { href, type PatternToPath } from "./href-client.js";
610
417
 
611
418
  // Response envelope types for consuming JSON response routes
612
419
  export type { ResponseEnvelope, ResponseError } from "./urls.js";
@@ -639,8 +446,12 @@ export { MountContext } from "./browser/react/mount-context.js";
639
446
  // Mount-aware href hook - auto-prefixes paths with include() mount
640
447
  export { useHref } from "./browser/react/use-href.js";
641
448
 
449
+ // Mount-aware reverse hook - resolves dot-prefixed names against an imported
450
+ // generated routes map (from a urls() module's .gen.ts).
451
+ export { useReverse } from "./browser/react/use-reverse.js";
452
+
642
453
  // Type-safe scoped reverse function for scopedReverse<typeof patterns>()
643
- export type { ScopedReverseFunction } from "./reverse.js";
454
+ export type { ScopedReverseFunction, LocalReverseFunction } from "./reverse.js";
644
455
 
645
456
  // Loader definition type - for typing loader props in client components
646
457
  export type { LoaderDefinition } from "./types.js";