@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
package/src/host/types.ts CHANGED
@@ -35,12 +35,24 @@ export type Middleware = (
35
35
  */
36
36
  export type HostPattern = string | string[];
37
37
 
38
+ /**
39
+ * Whether a route entry is an inline request handler or a lazy module mount.
40
+ *
41
+ * Stored on the entry so discovery and runtime act on the consumer's declared
42
+ * intent instead of inferring it from the function's shape (arity/return value),
43
+ * which is ambiguous: a lazy loader may declare an ignored param, and an inline
44
+ * handler may be async. `.map()` registers `"handler"`, `.lazy()` registers
45
+ * `"lazy"`.
46
+ */
47
+ export type RouteEntryKind = "handler" | "lazy";
48
+
38
49
  /**
39
50
  * Result from testing a hostname against patterns
40
51
  */
41
52
  export interface HostMatchResult {
42
53
  pattern: string;
43
54
  handler: Handler | LazyHandler;
55
+ kind: RouteEntryKind;
44
56
  }
45
57
 
46
58
  /**
@@ -53,9 +65,24 @@ export interface HostRouteBuilder {
53
65
  use(...middleware: Middleware[]): HostRouteBuilder;
54
66
 
55
67
  /**
56
- * Map to a handler or lazy import
68
+ * Map to an inline request handler `(request, input) => Response`.
69
+ *
70
+ * For a lazily-imported sub-app or handler module, use {@link lazy} instead -
71
+ * `.map(() => import(...))` is rejected (the return type is not a `Response`)
72
+ * and would not be discovered at build time.
73
+ */
74
+ map(handler: Handler): HostRouter;
75
+
76
+ /**
77
+ * Mount a lazily-imported handler or host router:
78
+ * `.lazy(() => import("./sub-app"))`.
79
+ *
80
+ * The loader takes no arguments and resolves to a module whose `default`
81
+ * export is a request `Handler` or a nested `HostRouter`. Only `.lazy()`
82
+ * entries are invoked during build-time discovery to trigger the sub-app's
83
+ * `createRouter()` registration.
57
84
  */
58
- map(handler: Handler | LazyHandler): HostRouter;
85
+ lazy(handler: LazyHandler): HostRouter;
59
86
  }
60
87
 
61
88
  /**
@@ -134,6 +161,8 @@ export interface RouteEntry {
134
161
  patterns: string[];
135
162
  middleware: Middleware[];
136
163
  handler: Handler | LazyHandler;
164
+ /** Whether `handler` is an inline request handler or a lazy module mount. */
165
+ kind: RouteEntryKind;
137
166
  isFallback?: boolean;
138
167
  }
139
168
 
package/src/host/utils.ts CHANGED
@@ -15,7 +15,7 @@
15
15
  * app: ['*', 'www.*']
16
16
  * });
17
17
  *
18
- * router.host(hosts.admin).map(...); // Type-safe!
18
+ * router.host(hosts.admin).lazy(() => import("./apps/admin")); // Type-safe!
19
19
  * ```
20
20
  */
21
21
  export function defineHosts<T extends Record<string, string | string[]>>(
@@ -15,6 +15,7 @@
15
15
  */
16
16
 
17
17
  import type { GetRegisteredRoutes } from "./types.js";
18
+ import type { JsonSerialize } from "./serialize.js";
18
19
  import type { ResponseEnvelope } from "./urls.js";
19
20
 
20
21
  /**
@@ -103,29 +104,75 @@ type NameForPattern<TPattern extends string, TRoutes = GetRegisteredRoutes> = {
103
104
  }[keyof TRoutes];
104
105
 
105
106
  /**
106
- * Look up the response data type for a route pattern from RegisteredRoutes.
107
- *
108
- * Works by reverse-looking up the route name for the given pattern,
109
- * then extracting the response type from the route entry.
107
+ * Strip a query (`?…`) and/or hash (`#…`) suffix before matching, so a concrete
108
+ * URL like `/api/health?ts=1` still resolves to its route's response. Removes
109
+ * from the earliest of `?`/`#`: a `#` before the first `?` (the query is part of
110
+ * a fragment, e.g. `/health#top?x=1`) is handled, as is a `/:` that only appears
111
+ * inside the query (e.g. `/health?next=/:id`).
112
+ */
113
+ type StripPathSuffix<T extends string> = T extends `${infer Base}?${string}`
114
+ ? Base extends `${infer Frag}#${string}`
115
+ ? Frag
116
+ : Base
117
+ : T extends `${infer Base}#${string}`
118
+ ? Base
119
+ : T;
120
+
121
+ /** Extract a route entry's response payload (or `never` for RSC routes). */
122
+ type ResponsePayloadOf<TRoutes, K extends keyof TRoutes> = TRoutes[K] extends {
123
+ readonly response: infer R;
124
+ }
125
+ ? Exclude<R, Response>
126
+ : never;
127
+
128
+ /**
129
+ * Look up the response payload for a route, keyed by either a route pattern
130
+ * (`/api/products/:id`) or a concrete path (`/api/products/123`). The same type
131
+ * serves a pattern lookup and a typed `fetch` wrapper that forwards a concrete
132
+ * `Rango.Path`:
110
133
  *
111
- * For static routes (no params), pattern === path:
112
- * PathResponse<"/api/health"> → { status: string; timestamp: number }
134
+ * PathResponse<"/api/products/:id"> → Product // by pattern
135
+ * PathResponse<"/api/products/123"> → Product // by concrete path
113
136
  *
114
- * For dynamic routes, use the pattern:
115
- * PathResponse<"/api/products/:id"> → Product
137
+ * The query/hash suffix is stripped first; the stripped key is then treated as a
138
+ * pattern when it contains a `/:param` segment and matched exactly (precise even
139
+ * for nested dynamic routes), otherwise as a concrete path matched against each
140
+ * route's `PatternToPath` template. Because those holes are `${string}`
141
+ * (slash-greedy), a concrete path under a *nested* dynamic route can match several
142
+ * patterns and union their responses — pattern lookups do not have this
143
+ * looseness. RSC routes (no response) and unmatched keys resolve to `never`.
144
+ */
145
+ type ResponsePayloadFor<
146
+ TPath extends string,
147
+ TRoutes = GetRegisteredRoutes,
148
+ > = ResponsePayloadForKey<StripPathSuffix<TPath>, TRoutes>;
149
+
150
+ type ResponsePayloadForKey<
151
+ TKey extends string,
152
+ TRoutes,
153
+ > = TKey extends `${string}/:${string}`
154
+ ? {
155
+ [K in keyof TRoutes]: RoutePattern<TRoutes, K> extends TKey
156
+ ? ResponsePayloadOf<TRoutes, K>
157
+ : never;
158
+ }[keyof TRoutes]
159
+ : {
160
+ [K in keyof TRoutes]: TKey extends PatternToPath<RoutePattern<TRoutes, K>>
161
+ ? ResponsePayloadOf<TRoutes, K>
162
+ : never;
163
+ }[keyof TRoutes];
164
+
165
+ /**
166
+ * Public response type for a route, keyed by pattern or concrete path. The
167
+ * payload is wrapped in `JsonSerialize` so it describes the JSON **wire** value a
168
+ * consumer receives from `fetch().then(r => r.json())`, not the handler's raw
169
+ * return type — e.g. a handler returning `{ createdAt: Date }` resolves here to
170
+ * `ResponseEnvelope<{ createdAt: string }>`.
116
171
  */
117
172
  export type PathResponse<
118
- TPattern extends string,
173
+ TPath extends string,
119
174
  TRoutes = GetRegisteredRoutes,
120
- > = ResponseEnvelope<
121
- {
122
- [K in keyof TRoutes]: RoutePattern<TRoutes, K> extends TPattern
123
- ? TRoutes[K] extends { readonly response: infer R }
124
- ? Exclude<R, Response>
125
- : never
126
- : never;
127
- }[keyof TRoutes]
128
- >;
175
+ > = ResponseEnvelope<JsonSerialize<ResponsePayloadFor<TPath, TRoutes>>>;
129
176
 
130
177
  /**
131
178
  * Strip trailing slash from a path (e.g., "/blog/" -> "/blog" | "/blog/")
@@ -140,7 +187,7 @@ type OptionalTrailingSlash<T extends string> = T extends `${infer Base}/`
140
187
  /**
141
188
  * Union of all valid paths from registered routes
142
189
  *
143
- * Generated from RSCRouter.RegisteredRoutes via module augmentation.
190
+ * Generated from Rango.RegisteredRoutes via module augmentation.
144
191
  * Allows optional query strings and hash fragments.
145
192
  */
146
193
  export type ValidPaths<TRoutes = GetRegisteredRoutes> =
@@ -154,6 +201,76 @@ export type ValidPaths<TRoutes = GetRegisteredRoutes> =
154
201
  }[keyof TRoutes]
155
202
  >;
156
203
 
204
+ // Module-scoped alias so the ambient `Rango.PathResponse` below can reference
205
+ // the module-level `PathResponse` without the global namespace shadowing the
206
+ // name when both are called `PathResponse`.
207
+ type GlobalPathResponse<
208
+ TPattern extends string,
209
+ TRoutes = GetRegisteredRoutes,
210
+ > = PathResponse<TPattern, TRoutes>;
211
+
212
+ /**
213
+ * Ambient path types on the `Rango` namespace.
214
+ *
215
+ * These live on the same global namespace consumers already augment for
216
+ * `Rango.Env` / `Rango.Vars`, so they are reachable with no import wherever the
217
+ * router's types are in scope. They are the public, recommended surface for
218
+ * typing anything that wraps `href()`. `ValidPaths` / `PathResponse` stay as the
219
+ * internal building blocks behind them.
220
+ */
221
+ declare global {
222
+ namespace Rango {
223
+ /**
224
+ * Union of every valid route path accepted by `href()`.
225
+ *
226
+ * Type a wrapper's path parameter as `Rango.Path` so it shares `href()`'s
227
+ * compile-time validation against the registered routes:
228
+ *
229
+ * ```ts
230
+ * import { href } from "@rangojs/router/client";
231
+ *
232
+ * export const appHref = (path: Rango.Path) => href(path);
233
+ * ```
234
+ *
235
+ * Resolves from `Rango.RegisteredRoutes` when augmented, otherwise the
236
+ * auto-generated `Rango.GeneratedRouteMap`, otherwise a permissive
237
+ * `/${string}` fallback.
238
+ */
239
+ type Path<TRoutes = GetRegisteredRoutes> = ValidPaths<TRoutes>;
240
+
241
+ /**
242
+ * Response payload for a route, looked up from the global route map by
243
+ * either a route pattern (`/api/products/:id`) or a concrete path
244
+ * (`/api/products/123`). Because it accepts a concrete `Rango.Path`, it
245
+ * doubles as the return type of a typed `fetch` wrapper:
246
+ *
247
+ * ```ts
248
+ * type Product = Rango.PathResponse<"/api/products/:id">; // by pattern
249
+ * type Same = Rango.PathResponse<"/api/products/42">; // by concrete path
250
+ *
251
+ * const get = async <T extends Rango.Path>(
252
+ * path: T,
253
+ * ): Promise<Rango.PathResponse<T>> =>
254
+ * fetch(href(path)).then((r) => r.json());
255
+ * ```
256
+ *
257
+ * The payload is the JSON **wire** shape (via `Rango.JsonSerialize`), not the
258
+ * handler's raw return — a handler returning `{ createdAt: Date }` resolves
259
+ * here to `ResponseEnvelope<{ createdAt: string }>`, matching what
260
+ * `fetch().then(r => r.json())` actually yields.
261
+ *
262
+ * Only resolves once `Rango.RegisteredRoutes` carries response metadata (the
263
+ * generated map has paths and search but no payloads). Pass an explicit route
264
+ * map as the second argument to look up against a non-global map (rarely
265
+ * needed in app code).
266
+ */
267
+ type PathResponse<
268
+ TPath extends string,
269
+ TRoutes = GetRegisteredRoutes,
270
+ > = GlobalPathResponse<TPath, TRoutes>;
271
+ }
272
+ }
273
+
157
274
  /**
158
275
  * Type-safe href function for client-side use
159
276
  *
@@ -186,7 +303,10 @@ export function href<T extends ValidPaths>(path: T, mount?: string): string {
186
303
  const normalizedMount = mount.endsWith("/") ? mount.slice(0, -1) : mount;
187
304
  return normalizedMount + path;
188
305
  }
189
- return path;
306
+ // ValidPaths is built from template literals so T does extend string at
307
+ // runtime, but the inference can fail past a certain route-union complexity
308
+ // and TypeScript reports T as not assignable to string.
309
+ return path as string;
190
310
  }
191
311
 
192
312
  /**
package/src/index.rsc.ts CHANGED
@@ -11,8 +11,6 @@
11
11
 
12
12
  // Re-export all universal exports from index.ts
13
13
  export {
14
- // Universal rendering utilities
15
- renderSegments,
16
14
  // Error classes
17
15
  RouteNotFoundError,
18
16
  DataNotFoundError,
@@ -20,10 +18,8 @@ export {
20
18
  MiddlewareError,
21
19
  HandlerError,
22
20
  BuildError,
21
+ DslContextError,
23
22
  InvalidHandlerError,
24
- NetworkError,
25
- isNetworkError,
26
- sanitizeError,
27
23
  RouterError,
28
24
  Skip,
29
25
  isSkip,
@@ -40,7 +36,6 @@ export type {
40
36
  TrailingSlashMode,
41
37
  // Handler types
42
38
  Handler,
43
- ScopedRouteMap,
44
39
  HandlerContext,
45
40
  ExtractParams,
46
41
  GenericParams,
@@ -49,6 +44,7 @@ export type {
49
44
  // Revalidation types
50
45
  RevalidateParams,
51
46
  Revalidate,
47
+ ActionRef,
52
48
  RouteKeys,
53
49
  // Loader types
54
50
  LoaderDefinition,
@@ -73,7 +69,7 @@ export type {
73
69
 
74
70
  // Router options type (server-only, so import directly)
75
71
  export type {
76
- RSCRouterOptions,
72
+ RangoOptions,
77
73
  SSRStreamMode,
78
74
  SSROptions,
79
75
  ResolveStreamingContext,
@@ -106,6 +102,7 @@ export type {
106
102
  LayoutUseItem,
107
103
  AllUseItems,
108
104
  UseItems,
105
+ HandlerUseItem,
109
106
  } from "./route-types.js";
110
107
 
111
108
  // Handle API
@@ -120,9 +117,9 @@ export { nonce } from "./rsc/nonce.js";
120
117
  // Pre-render handler API
121
118
  export {
122
119
  Prerender,
123
- isPrerenderHandler,
120
+ Passthrough,
124
121
  type PrerenderHandlerDefinition,
125
- type PrerenderPassthroughContext,
122
+ type PassthroughHandlerDefinition,
126
123
  type PrerenderOptions,
127
124
  type BuildContext,
128
125
  type StaticBuildContext,
@@ -130,16 +127,11 @@ export {
130
127
  } from "./prerender.js";
131
128
 
132
129
  // Static handler API
133
- export {
134
- Static,
135
- isStaticHandler,
136
- type StaticHandlerDefinition,
137
- } from "./static-handler.js";
130
+ export { Static, type StaticHandlerDefinition } from "./static-handler.js";
138
131
 
139
132
  // Django-style URL patterns (RSC/server context)
140
133
  export {
141
134
  urls,
142
- RESPONSE_TYPE,
143
135
  type PathHelpers,
144
136
  type PathOptions,
145
137
  type UrlPatterns,
@@ -161,7 +153,7 @@ export {
161
153
  // Core router (server-side)
162
154
  export {
163
155
  createRouter,
164
- type RSCRouter,
156
+ type Rango,
165
157
  type RootLayoutProps,
166
158
  type RouterRequestInput,
167
159
  } from "./router.js";
@@ -171,6 +163,7 @@ export type { HandlerCacheConfig } from "./rsc/types.js";
171
163
 
172
164
  // Built-in handles (server-side)
173
165
  export { Meta } from "./handles/meta.js";
166
+ export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
174
167
 
175
168
  // Request context (for accessing request data in server actions/components).
176
169
  // Re-exported with a narrowed return type so that public consumers only see
@@ -181,6 +174,9 @@ export type { PublicRequestContext as RequestContext } from "./server/request-co
181
174
  import type { PublicRequestContext } from "./server/request-context.js";
182
175
  import type { DefaultEnv } from "./types/global-namespace.js";
183
176
 
177
+ // Shared base for every user-facing request context (mirrors index.ts).
178
+ export type { RequestScope, ExecutionContext } from "./types/request-scope.js";
179
+
184
180
  export const getRequestContext: <
185
181
  TEnv = DefaultEnv,
186
182
  >() => PublicRequestContext<TEnv> = _getRequestContextInternal;
@@ -206,8 +202,6 @@ export type {
206
202
  ReverseFunction,
207
203
  ExtractLocalRoutes,
208
204
  ParamsFor,
209
- SanitizePrefix,
210
- MergeRoutes,
211
205
  } from "./reverse.js";
212
206
  export { scopedReverse, createReverse } from "./reverse.js";
213
207
 
@@ -220,12 +214,6 @@ export type {
220
214
  RouteParams,
221
215
  } from "./search-params.js";
222
216
 
223
- // Debug utilities for route matching (development only)
224
- export {
225
- enableMatchDebug,
226
- getMatchDebugStats,
227
- } from "./router/pattern-matching.js";
228
-
229
217
  // Location state (universal)
230
218
  export {
231
219
  createLocationState,
@@ -234,27 +222,14 @@ export {
234
222
  type LocationStateOptions,
235
223
  } from "./browser/react/location-state-shared.js";
236
224
 
237
- // Path-based response type lookup from RegisteredRoutes
238
- export type { PathResponse } from "./href-client.js";
225
+ // Path and response types are ambient on the `Rango` namespace (`Rango.Path`,
226
+ // `Rango.PathResponse`, declared in href-client.ts) — no import needed.
239
227
 
240
228
  // Telemetry sink
241
229
  export { createConsoleSink } from "./router/telemetry.js";
242
230
  export { createOTelSink } from "./router/telemetry-otel.js";
243
231
  export type { OTelTracer, OTelSpan } from "./router/telemetry-otel.js";
244
- export type {
245
- TelemetrySink,
246
- TelemetryEvent,
247
- RequestStartEvent,
248
- RequestEndEvent,
249
- RequestErrorEvent,
250
- RequestTimeoutEvent,
251
- LoaderStartEvent,
252
- LoaderEndEvent,
253
- LoaderErrorEvent,
254
- HandlerErrorEvent,
255
- CacheDecisionEvent,
256
- RevalidationDecisionEvent,
257
- } from "./router/telemetry.js";
232
+ export type { TelemetrySink, TelemetryEvent } from "./router/telemetry.js";
258
233
 
259
234
  // Timeout types and error class
260
235
  export { RouterTimeoutError } from "./router/timeout.js";