@rangojs/router 0.0.0-experimental.9 → 0.0.0-experimental.98d9a51b

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 (299) hide show
  1. package/AGENTS.md +9 -0
  2. package/README.md +884 -4
  3. package/dist/bin/rango.js +1532 -155
  4. package/dist/vite/index.js +4444 -2235
  5. package/package.json +69 -62
  6. package/skills/breadcrumbs/SKILL.md +250 -0
  7. package/skills/cache-guide/SKILL.md +262 -0
  8. package/skills/caching/SKILL.md +85 -23
  9. package/skills/composability/SKILL.md +172 -0
  10. package/skills/debug-manifest/SKILL.md +12 -8
  11. package/skills/document-cache/SKILL.md +18 -16
  12. package/skills/fonts/SKILL.md +6 -4
  13. package/skills/hooks/SKILL.md +333 -71
  14. package/skills/host-router/SKILL.md +218 -0
  15. package/skills/intercept/SKILL.md +131 -8
  16. package/skills/layout/SKILL.md +100 -3
  17. package/skills/links/SKILL.md +74 -15
  18. package/skills/loader/SKILL.md +388 -38
  19. package/skills/middleware/SKILL.md +171 -34
  20. package/skills/mime-routes/SKILL.md +15 -11
  21. package/skills/parallel/SKILL.md +78 -1
  22. package/skills/prerender/SKILL.md +405 -45
  23. package/skills/rango/SKILL.md +85 -21
  24. package/skills/response-routes/SKILL.md +144 -91
  25. package/skills/route/SKILL.md +226 -14
  26. package/skills/router-setup/SKILL.md +123 -30
  27. package/skills/theme/SKILL.md +9 -8
  28. package/skills/typesafety/SKILL.md +316 -87
  29. package/skills/use-cache/SKILL.md +324 -0
  30. package/src/__internal.ts +102 -4
  31. package/src/bin/rango.ts +312 -15
  32. package/src/browser/action-coordinator.ts +97 -0
  33. package/src/browser/action-response-classifier.ts +99 -0
  34. package/src/browser/event-controller.ts +87 -64
  35. package/src/browser/history-state.ts +80 -0
  36. package/src/browser/intercept-utils.ts +52 -0
  37. package/src/browser/link-interceptor.ts +24 -4
  38. package/src/browser/logging.ts +55 -0
  39. package/src/browser/merge-segment-loaders.ts +20 -12
  40. package/src/browser/navigation-bridge.ts +282 -557
  41. package/src/browser/navigation-client.ts +169 -73
  42. package/src/browser/navigation-store.ts +33 -50
  43. package/src/browser/navigation-transaction.ts +297 -0
  44. package/src/browser/network-error-handler.ts +61 -0
  45. package/src/browser/partial-update.ts +292 -310
  46. package/src/browser/prefetch/cache.ts +206 -0
  47. package/src/browser/prefetch/fetch.ts +145 -0
  48. package/src/browser/prefetch/observer.ts +65 -0
  49. package/src/browser/prefetch/policy.ts +48 -0
  50. package/src/browser/prefetch/queue.ts +128 -0
  51. package/src/browser/rango-state.ts +112 -0
  52. package/src/browser/react/Link.tsx +190 -70
  53. package/src/browser/react/NavigationProvider.tsx +78 -11
  54. package/src/browser/react/context.ts +6 -0
  55. package/src/browser/react/filter-segment-order.ts +11 -0
  56. package/src/browser/react/index.ts +12 -12
  57. package/src/browser/react/location-state-shared.ts +95 -53
  58. package/src/browser/react/location-state.ts +60 -15
  59. package/src/browser/react/mount-context.ts +6 -1
  60. package/src/browser/react/nonce-context.ts +23 -0
  61. package/src/browser/react/shallow-equal.ts +27 -0
  62. package/src/browser/react/use-action.ts +29 -51
  63. package/src/browser/react/use-client-cache.ts +5 -3
  64. package/src/browser/react/use-handle.ts +29 -70
  65. package/src/browser/react/use-link-status.ts +6 -5
  66. package/src/browser/react/use-navigation.ts +22 -63
  67. package/src/browser/react/use-params.ts +65 -0
  68. package/src/browser/react/use-pathname.ts +47 -0
  69. package/src/browser/react/use-router.ts +63 -0
  70. package/src/browser/react/use-search-params.ts +56 -0
  71. package/src/browser/react/use-segments.ts +80 -97
  72. package/src/browser/response-adapter.ts +73 -0
  73. package/src/browser/rsc-router.tsx +106 -27
  74. package/src/browser/scroll-restoration.ts +117 -44
  75. package/src/browser/segment-reconciler.ts +216 -0
  76. package/src/browser/segment-structure-assert.ts +16 -0
  77. package/src/browser/server-action-bridge.ts +504 -599
  78. package/src/browser/shallow.ts +6 -1
  79. package/src/browser/types.ts +116 -47
  80. package/src/browser/validate-redirect-origin.ts +29 -0
  81. package/src/build/generate-manifest.ts +82 -21
  82. package/src/build/generate-route-types.ts +36 -752
  83. package/src/build/index.ts +6 -5
  84. package/src/build/route-trie.ts +39 -13
  85. package/src/build/route-types/ast-helpers.ts +25 -0
  86. package/src/build/route-types/ast-route-extraction.ts +98 -0
  87. package/src/build/route-types/codegen.ts +102 -0
  88. package/src/build/route-types/include-resolution.ts +411 -0
  89. package/src/build/route-types/param-extraction.ts +48 -0
  90. package/src/build/route-types/per-module-writer.ts +128 -0
  91. package/src/build/route-types/router-processing.ts +479 -0
  92. package/src/build/route-types/scan-filter.ts +78 -0
  93. package/src/build/runtime-discovery.ts +231 -0
  94. package/src/cache/background-task.ts +34 -0
  95. package/src/cache/cache-key-utils.ts +44 -0
  96. package/src/cache/cache-policy.ts +125 -0
  97. package/src/cache/cache-runtime.ts +338 -0
  98. package/src/cache/cache-scope.ts +122 -303
  99. package/src/cache/cf/cf-cache-store.ts +571 -17
  100. package/src/cache/cf/index.ts +13 -3
  101. package/src/cache/document-cache.ts +101 -72
  102. package/src/cache/handle-capture.ts +81 -0
  103. package/src/cache/handle-snapshot.ts +41 -0
  104. package/src/cache/index.ts +1 -15
  105. package/src/cache/memory-segment-store.ts +191 -13
  106. package/src/cache/profile-registry.ts +73 -0
  107. package/src/cache/read-through-swr.ts +134 -0
  108. package/src/cache/segment-codec.ts +256 -0
  109. package/src/cache/taint.ts +98 -0
  110. package/src/cache/types.ts +72 -122
  111. package/src/client.rsc.tsx +3 -1
  112. package/src/client.tsx +84 -126
  113. package/src/component-utils.ts +4 -4
  114. package/src/components/DefaultDocument.tsx +5 -1
  115. package/src/context-var.ts +86 -0
  116. package/src/debug.ts +17 -7
  117. package/src/errors.ts +77 -7
  118. package/src/handle.ts +15 -10
  119. package/src/handles/MetaTags.tsx +73 -20
  120. package/src/handles/breadcrumbs.ts +66 -0
  121. package/src/handles/index.ts +1 -0
  122. package/src/handles/meta.ts +30 -13
  123. package/src/host/cookie-handler.ts +21 -15
  124. package/src/host/errors.ts +8 -8
  125. package/src/host/index.ts +4 -7
  126. package/src/host/pattern-matcher.ts +27 -27
  127. package/src/host/router.ts +61 -39
  128. package/src/host/testing.ts +8 -8
  129. package/src/host/types.ts +15 -7
  130. package/src/host/utils.ts +1 -1
  131. package/src/href-client.ts +65 -45
  132. package/src/index.rsc.ts +133 -21
  133. package/src/index.ts +164 -52
  134. package/src/internal-debug.ts +11 -0
  135. package/src/loader.rsc.ts +25 -143
  136. package/src/loader.ts +27 -10
  137. package/src/network-error-thrower.tsx +3 -1
  138. package/src/outlet-provider.tsx +45 -0
  139. package/src/prerender/param-hash.ts +4 -2
  140. package/src/prerender/store.ts +158 -13
  141. package/src/prerender.ts +333 -26
  142. package/src/reverse.ts +184 -121
  143. package/src/root-error-boundary.tsx +41 -29
  144. package/src/route-content-wrapper.tsx +7 -4
  145. package/src/route-definition/dsl-helpers.ts +934 -0
  146. package/src/route-definition/helper-factories.ts +200 -0
  147. package/src/route-definition/helpers-types.ts +430 -0
  148. package/src/route-definition/index.ts +52 -0
  149. package/src/route-definition/redirect.ts +93 -0
  150. package/src/route-definition.ts +1 -1431
  151. package/src/route-map-builder.ts +162 -123
  152. package/src/route-name.ts +53 -0
  153. package/src/route-types.ts +48 -9
  154. package/src/router/content-negotiation.ts +116 -0
  155. package/src/router/debug-manifest.ts +72 -0
  156. package/src/router/error-handling.ts +9 -9
  157. package/src/router/find-match.ts +160 -0
  158. package/src/router/handler-context.ts +374 -81
  159. package/src/router/intercept-resolution.ts +26 -16
  160. package/src/router/lazy-includes.ts +236 -0
  161. package/src/router/loader-resolution.ts +215 -122
  162. package/src/router/logging.ts +251 -0
  163. package/src/router/manifest.ts +85 -32
  164. package/src/router/match-api.ts +118 -119
  165. package/src/router/match-context.ts +4 -2
  166. package/src/router/match-handlers.ts +440 -0
  167. package/src/router/match-middleware/background-revalidation.ts +80 -93
  168. package/src/router/match-middleware/cache-lookup.ts +336 -84
  169. package/src/router/match-middleware/cache-store.ts +43 -24
  170. package/src/router/match-middleware/intercept-resolution.ts +45 -20
  171. package/src/router/match-middleware/segment-resolution.ts +17 -8
  172. package/src/router/match-pipelines.ts +10 -45
  173. package/src/router/match-result.ts +34 -28
  174. package/src/router/metrics.ts +235 -15
  175. package/src/router/middleware-cookies.ts +55 -0
  176. package/src/router/middleware-types.ts +222 -0
  177. package/src/router/middleware.ts +327 -369
  178. package/src/router/pattern-matching.ts +197 -41
  179. package/src/router/prerender-match.ts +402 -0
  180. package/src/router/preview-match.ts +170 -0
  181. package/src/router/revalidation.ts +137 -38
  182. package/src/router/router-context.ts +40 -21
  183. package/src/router/router-interfaces.ts +452 -0
  184. package/src/router/router-options.ts +592 -0
  185. package/src/router/router-registry.ts +24 -0
  186. package/src/router/segment-resolution/fresh.ts +570 -0
  187. package/src/router/segment-resolution/helpers.ts +263 -0
  188. package/src/router/segment-resolution/loader-cache.ts +198 -0
  189. package/src/router/segment-resolution/revalidation.ts +1242 -0
  190. package/src/router/segment-resolution/static-store.ts +67 -0
  191. package/src/router/segment-resolution.ts +21 -1315
  192. package/src/router/segment-wrappers.ts +291 -0
  193. package/src/router/telemetry-otel.ts +299 -0
  194. package/src/router/telemetry.ts +300 -0
  195. package/src/router/timeout.ts +148 -0
  196. package/src/router/trie-matching.ts +96 -29
  197. package/src/router/types.ts +16 -9
  198. package/src/router.ts +595 -1984
  199. package/src/rsc/handler-context.ts +45 -0
  200. package/src/rsc/handler.ts +680 -1027
  201. package/src/rsc/helpers.ts +140 -6
  202. package/src/rsc/index.ts +0 -20
  203. package/src/rsc/loader-fetch.ts +209 -0
  204. package/src/rsc/manifest-init.ts +86 -0
  205. package/src/rsc/nonce.ts +14 -0
  206. package/src/rsc/origin-guard.ts +141 -0
  207. package/src/rsc/progressive-enhancement.ts +379 -0
  208. package/src/rsc/response-error.ts +37 -0
  209. package/src/rsc/response-route-handler.ts +347 -0
  210. package/src/rsc/rsc-rendering.ts +237 -0
  211. package/src/rsc/runtime-warnings.ts +42 -0
  212. package/src/rsc/server-action.ts +348 -0
  213. package/src/rsc/ssr-setup.ts +128 -0
  214. package/src/rsc/types.ts +38 -11
  215. package/src/search-params.ts +230 -0
  216. package/src/segment-system.tsx +25 -13
  217. package/src/server/context.ts +173 -48
  218. package/src/server/cookie-store.ts +190 -0
  219. package/src/server/fetchable-loader-store.ts +37 -0
  220. package/src/server/handle-store.ts +94 -15
  221. package/src/server/loader-registry.ts +15 -56
  222. package/src/server/request-context.ts +439 -73
  223. package/src/server.ts +35 -155
  224. package/src/ssr/index.tsx +100 -31
  225. package/src/static-handler.ts +114 -0
  226. package/src/theme/ThemeProvider.tsx +21 -15
  227. package/src/theme/ThemeScript.tsx +5 -5
  228. package/src/theme/constants.ts +5 -2
  229. package/src/theme/index.ts +4 -14
  230. package/src/theme/theme-context.ts +4 -30
  231. package/src/theme/theme-script.ts +21 -18
  232. package/src/types/boundaries.ts +158 -0
  233. package/src/types/cache-types.ts +198 -0
  234. package/src/types/error-types.ts +192 -0
  235. package/src/types/global-namespace.ts +100 -0
  236. package/src/types/handler-context.ts +687 -0
  237. package/src/types/index.ts +88 -0
  238. package/src/types/loader-types.ts +183 -0
  239. package/src/types/route-config.ts +170 -0
  240. package/src/types/route-entry.ts +109 -0
  241. package/src/types/segments.ts +148 -0
  242. package/src/types.ts +1 -1757
  243. package/src/urls/include-helper.ts +197 -0
  244. package/src/urls/index.ts +53 -0
  245. package/src/urls/path-helper-types.ts +339 -0
  246. package/src/urls/path-helper.ts +329 -0
  247. package/src/urls/pattern-types.ts +95 -0
  248. package/src/urls/response-types.ts +106 -0
  249. package/src/urls/type-extraction.ts +372 -0
  250. package/src/urls/urls-function.ts +98 -0
  251. package/src/urls.ts +1 -1282
  252. package/src/use-loader.tsx +85 -77
  253. package/src/vite/discovery/bundle-postprocess.ts +184 -0
  254. package/src/vite/discovery/discover-routers.ts +344 -0
  255. package/src/vite/discovery/prerender-collection.ts +385 -0
  256. package/src/vite/discovery/route-types-writer.ts +258 -0
  257. package/src/vite/discovery/self-gen-tracking.ts +47 -0
  258. package/src/vite/discovery/state.ts +108 -0
  259. package/src/vite/discovery/virtual-module-codegen.ts +203 -0
  260. package/src/vite/index.ts +11 -1963
  261. package/src/vite/plugin-types.ts +48 -0
  262. package/src/vite/plugins/cjs-to-esm.ts +93 -0
  263. package/src/vite/plugins/client-ref-dedup.ts +115 -0
  264. package/src/vite/plugins/client-ref-hashing.ts +105 -0
  265. package/src/vite/{expose-action-id.ts → plugins/expose-action-id.ts} +72 -53
  266. package/src/vite/plugins/expose-id-utils.ts +287 -0
  267. package/src/vite/plugins/expose-ids/export-analysis.ts +296 -0
  268. package/src/vite/plugins/expose-ids/handler-transform.ts +179 -0
  269. package/src/vite/plugins/expose-ids/loader-transform.ts +74 -0
  270. package/src/vite/plugins/expose-ids/router-transform.ts +110 -0
  271. package/src/vite/plugins/expose-ids/types.ts +45 -0
  272. package/src/vite/plugins/expose-internal-ids.ts +569 -0
  273. package/src/vite/plugins/refresh-cmd.ts +65 -0
  274. package/src/vite/plugins/use-cache-transform.ts +323 -0
  275. package/src/vite/plugins/version-injector.ts +83 -0
  276. package/src/vite/plugins/version-plugin.ts +254 -0
  277. package/src/vite/{virtual-entries.ts → plugins/virtual-entries.ts} +27 -14
  278. package/src/vite/plugins/virtual-stub-plugin.ts +29 -0
  279. package/src/vite/rango.ts +445 -0
  280. package/src/vite/router-discovery.ts +777 -0
  281. package/src/vite/utils/ast-handler-extract.ts +517 -0
  282. package/src/vite/utils/banner.ts +36 -0
  283. package/src/vite/utils/bundle-analysis.ts +137 -0
  284. package/src/vite/utils/manifest-utils.ts +70 -0
  285. package/src/vite/{package-resolution.ts → utils/package-resolution.ts} +25 -29
  286. package/src/vite/utils/prerender-utils.ts +189 -0
  287. package/src/vite/utils/shared-utils.ts +169 -0
  288. package/CLAUDE.md +0 -43
  289. package/src/browser/lru-cache.ts +0 -69
  290. package/src/browser/request-controller.ts +0 -164
  291. package/src/cache/memory-store.ts +0 -253
  292. package/src/href-context.ts +0 -33
  293. package/src/router.gen.ts +0 -6
  294. package/src/urls.gen.ts +0 -8
  295. package/src/vite/expose-handle-id.ts +0 -209
  296. package/src/vite/expose-loader-id.ts +0 -426
  297. package/src/vite/expose-location-state-id.ts +0 -177
  298. package/src/vite/expose-prerender-handler-id.ts +0 -429
  299. /package/src/vite/{version.d.ts → plugins/version.d.ts} +0 -0
@@ -0,0 +1,251 @@
1
+ import { AsyncLocalStorage } from "node:async_hooks";
2
+ import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
3
+
4
+ // -- Revalidation trace types --
5
+
6
+ export interface RevalidationTraceEntry {
7
+ segmentId: string;
8
+ segmentType: string;
9
+ belongsToRoute: boolean;
10
+ source:
11
+ | "segment-resolution"
12
+ | "cache-hit"
13
+ | "loader"
14
+ | "parallel"
15
+ | "orphan-layout"
16
+ | "route-handler"
17
+ | "layout-handler"
18
+ | "intercept-loader";
19
+ defaultShouldRevalidate: boolean;
20
+ finalShouldRevalidate: boolean;
21
+ reason: string;
22
+ customRevalidators?: number;
23
+ }
24
+
25
+ export interface RevalidationTraceMeta {
26
+ method: string;
27
+ prevUrl: string;
28
+ nextUrl: string;
29
+ routeKey: string;
30
+ isAction: boolean;
31
+ stale?: boolean;
32
+ }
33
+
34
+ export interface RevalidationTrace {
35
+ meta: RevalidationTraceMeta;
36
+ entries: RevalidationTraceEntry[];
37
+ }
38
+
39
+ // -- Log context --
40
+
41
+ interface RouterLogContext {
42
+ requestId: string;
43
+ transactionId: string;
44
+ depth: number;
45
+ revalidationTrace?: RevalidationTrace;
46
+ }
47
+
48
+ interface RouterLogOptions {
49
+ request: Request;
50
+ transaction: string;
51
+ }
52
+
53
+ interface LogDetails {
54
+ [key: string]: unknown;
55
+ }
56
+
57
+ const routerLogContext = new AsyncLocalStorage<RouterLogContext>();
58
+ const requestIds = new WeakMap<Request, string>();
59
+
60
+ let requestCounter = 0;
61
+ let transactionCounter = 0;
62
+
63
+ function nextId(prefix: string, counter: number): string {
64
+ return `${prefix}${counter.toString(36)}`;
65
+ }
66
+
67
+ function getHeaderRequestId(request: Request): string | null {
68
+ const candidate =
69
+ request.headers.get("x-rsc-router-request-id") ??
70
+ request.headers.get("x-request-id") ??
71
+ request.headers.get("cf-ray");
72
+ if (!candidate) return null;
73
+ const trimmed = candidate.trim();
74
+ return trimmed.length > 0 ? trimmed : null;
75
+ }
76
+
77
+ function getOrCreateRequestId(request: Request): string {
78
+ const existing = requestIds.get(request);
79
+ if (existing) return existing;
80
+
81
+ const fromHeaders = getHeaderRequestId(request);
82
+ if (fromHeaders) {
83
+ requestIds.set(request, fromHeaders);
84
+ return fromHeaders;
85
+ }
86
+
87
+ requestCounter += 1;
88
+ const generated = nextId("req-", requestCounter);
89
+ requestIds.set(request, generated);
90
+ return generated;
91
+ }
92
+
93
+ export function runWithRouterLogContext<T>(
94
+ options: RouterLogOptions,
95
+ fn: () => T,
96
+ ): T {
97
+ if (!INTERNAL_RANGO_DEBUG) {
98
+ return fn();
99
+ }
100
+
101
+ const requestId = getOrCreateRequestId(options.request);
102
+ transactionCounter += 1;
103
+ const transactionId = `${options.transaction}-${nextId("tx-", transactionCounter)}`;
104
+
105
+ return routerLogContext.run(
106
+ {
107
+ requestId,
108
+ transactionId,
109
+ depth: 0,
110
+ },
111
+ fn,
112
+ );
113
+ }
114
+
115
+ export function withRouterLogScope<T>(
116
+ label: string,
117
+ fn: () => Promise<T>,
118
+ ): Promise<T>;
119
+ export function withRouterLogScope<T>(label: string, fn: () => T): T;
120
+ export function withRouterLogScope<T>(
121
+ label: string,
122
+ fn: () => Promise<T> | T,
123
+ ): Promise<T> | T {
124
+ const ctx = routerLogContext.getStore();
125
+ if (!INTERNAL_RANGO_DEBUG || !ctx) {
126
+ return fn();
127
+ }
128
+
129
+ debugLog(label, "start");
130
+
131
+ return routerLogContext.run({ ...ctx, depth: ctx.depth + 1 }, () => {
132
+ try {
133
+ const result = fn();
134
+ if (result && typeof (result as Promise<T>).then === "function") {
135
+ return (result as Promise<T>).then(
136
+ (value) => {
137
+ debugLog(label, "end");
138
+ return value;
139
+ },
140
+ (error) => {
141
+ debugLog(label, "error", { error: String(error) });
142
+ throw error;
143
+ },
144
+ );
145
+ }
146
+ debugLog(label, "end");
147
+ return result;
148
+ } catch (error) {
149
+ debugLog(label, "error", { error: String(error) });
150
+ throw error;
151
+ }
152
+ });
153
+ }
154
+
155
+ export function isRouterDebugEnabled(): boolean {
156
+ return INTERNAL_RANGO_DEBUG && !!routerLogContext.getStore();
157
+ }
158
+
159
+ function formatPrefix(scope: string): string {
160
+ const ctx = routerLogContext.getStore();
161
+ if (!ctx) return `[Router][${scope}]`;
162
+ const indent = " ".repeat(ctx.depth);
163
+ return `[Router][req:${ctx.requestId}][tx:${ctx.transactionId}] ${indent}[${scope}]`;
164
+ }
165
+
166
+ export function debugLog(
167
+ scope: string,
168
+ message: string,
169
+ details?: LogDetails,
170
+ ): void {
171
+ if (!isRouterDebugEnabled()) return;
172
+
173
+ const prefix = formatPrefix(scope);
174
+ if (details) {
175
+ console.log(`${prefix} ${message}`, details);
176
+ return;
177
+ }
178
+
179
+ console.log(`${prefix} ${message}`);
180
+ }
181
+
182
+ export function debugWarn(
183
+ scope: string,
184
+ message: string,
185
+ details?: LogDetails,
186
+ ): void {
187
+ if (!isRouterDebugEnabled()) return;
188
+
189
+ const prefix = formatPrefix(scope);
190
+ if (details) {
191
+ console.warn(`${prefix} ${message}`, details);
192
+ return;
193
+ }
194
+
195
+ console.warn(`${prefix} ${message}`);
196
+ }
197
+
198
+ // -- Revalidation trace helpers --
199
+
200
+ export function isTraceActive(): boolean {
201
+ if (!INTERNAL_RANGO_DEBUG) return false;
202
+ const ctx = routerLogContext.getStore();
203
+ return !!ctx?.revalidationTrace;
204
+ }
205
+
206
+ export function startRevalidationTrace(meta: RevalidationTraceMeta): void {
207
+ const ctx = routerLogContext.getStore();
208
+ if (!ctx || !INTERNAL_RANGO_DEBUG) return;
209
+ ctx.revalidationTrace = { meta, entries: [] };
210
+ }
211
+
212
+ export function pushRevalidationTraceEntry(
213
+ entry: RevalidationTraceEntry,
214
+ ): void {
215
+ const ctx = routerLogContext.getStore();
216
+ if (!ctx?.revalidationTrace) return;
217
+ ctx.revalidationTrace.entries.push(entry);
218
+ }
219
+
220
+ export function flushRevalidationTrace(): RevalidationTrace | null {
221
+ const ctx = routerLogContext.getStore();
222
+ if (!ctx?.revalidationTrace) return null;
223
+ const trace = ctx.revalidationTrace;
224
+ ctx.revalidationTrace = undefined;
225
+
226
+ if (trace.entries.length === 0) return trace;
227
+
228
+ const revalidated = trace.entries.filter((e) => e.finalShouldRevalidate);
229
+ const skipped = trace.entries.filter((e) => !e.finalShouldRevalidate);
230
+
231
+ debugLog("revalidation-trace", "flush", {
232
+ method: trace.meta.method,
233
+ routeKey: trace.meta.routeKey,
234
+ isAction: trace.meta.isAction,
235
+ stale: trace.meta.stale,
236
+ prevUrl: trace.meta.prevUrl,
237
+ nextUrl: trace.meta.nextUrl,
238
+ total: trace.entries.length,
239
+ revalidated: revalidated.length,
240
+ skipped: skipped.length,
241
+ entries: trace.entries.map((e) => ({
242
+ segmentId: e.segmentId,
243
+ type: e.segmentType,
244
+ source: e.source,
245
+ revalidate: e.finalShouldRevalidate,
246
+ reason: e.reason,
247
+ })),
248
+ });
249
+
250
+ return trace;
251
+ }
@@ -6,7 +6,12 @@
6
6
 
7
7
  import { invariant, RouteNotFoundError } from "../errors";
8
8
  import { createRouteHelpers } from "../route-definition";
9
- import { getContext, runWithPrefixes, type EntryData, type MetricsStore } from "../server/context";
9
+ import {
10
+ getContext,
11
+ runWithPrefixes,
12
+ type EntryData,
13
+ type MetricsStore,
14
+ } from "../server/context";
10
15
  import MapRootLayout from "../server/root-layout";
11
16
  import type { RouteEntry } from "../types";
12
17
  import type { UrlPatterns } from "../urls";
@@ -60,7 +65,9 @@ export async function loadManifest(
60
65
  const mountIndex = entry.mountIndex;
61
66
 
62
67
  // Check module-level cache (persists across requests within same isolate)
63
- const cacheKey = `${VERSION}:${mountIndex ?? ''}:${routeKey}:${isSSR ? 1 : 0}`;
68
+ // Include routerId so multi-router setups (host routing) don't share cached
69
+ // EntryData across routers with overlapping mountIndex + routeKey combinations.
70
+ const cacheKey = `${VERSION}:${entry.routerId ?? ""}:${mountIndex ?? ""}:${routeKey}:${isSSR ? 1 : 0}`;
64
71
  const cached = manifestModuleCache.get(cacheKey);
65
72
  if (cached) {
66
73
  const cacheStart = performance.now();
@@ -100,14 +107,43 @@ export async function loadManifest(
100
107
 
101
108
  try {
102
109
  // Include mountIndex in namespace to ensure unique cache keys per mount
103
- const namespaceWithMount = mountIndex !== undefined
104
- ? `#router.M${mountIndex}`
105
- : "#router";
110
+ const namespaceWithMount =
111
+ mountIndex !== undefined ? `#router.M${mountIndex}` : "#router";
106
112
 
107
113
  // For lazy entries, use the captured parent from include() context
108
114
  // This ensures routes are registered under the correct layout hierarchy
109
- const lazyContext = entry.lazy && entry.lazyPatterns ? entry.lazyContext : null;
110
- const parentForContext = lazyContext?.parent as EntryData | null ?? Store.parent;
115
+ const lazyContext =
116
+ entry.lazy && entry.lazyPatterns ? entry.lazyContext : null;
117
+ const parentForContext =
118
+ (lazyContext?.parent as EntryData | null) ?? Store.parent;
119
+
120
+ // For lazy entries, merge captured counters from include() so the
121
+ // handler's entries get shortCode indices after sibling entries that
122
+ // were created during pattern extraction. This prevents shortCode
123
+ // collisions between lazy and non-lazy entries under the same parent
124
+ // (e.g., ArticlesLayout and BlogLayout both under NavLayout).
125
+ if (lazyContext && (lazyContext as any).counters) {
126
+ const captured = (lazyContext as any).counters as Record<string, number>;
127
+ for (const [key, value] of Object.entries(captured)) {
128
+ Store.counters[key] = Math.max(Store.counters[key] ?? 0, value);
129
+ }
130
+ }
131
+
132
+ // Propagate cache profiles for DSL-time cache("profileName") resolution.
133
+ // Non-lazy entries carry profiles directly; lazy entries carry them
134
+ // in the captured lazyContext from include() time.
135
+ const entryProfiles =
136
+ entry.cacheProfiles ?? (lazyContext as any)?.cacheProfiles;
137
+ if (entryProfiles) {
138
+ Store.cacheProfiles = entryProfiles;
139
+ }
140
+
141
+ // Propagate rootScoped from lazyContext so that routes inside
142
+ // nested { name: "sub" } under { name: "" } keep inherited root scope
143
+ // when the manifest is rebuilt on each request.
144
+ if (lazyContext && (lazyContext as any).rootScoped !== undefined) {
145
+ Store.rootScoped = (lazyContext as any).rootScoped;
146
+ }
111
147
 
112
148
  const handlerExecStart = performance.now();
113
149
  const useItems = await getContext().runWithStore(
@@ -118,25 +154,23 @@ export async function loadManifest(
118
154
  // Create helpers for lazy-loaded handlers that need them
119
155
  const helpers = createRouteHelpers();
120
156
 
121
- // For lazy entries, use lazyPatterns.handler() with proper prefixes
157
+ // For lazy entries, use lazyPatterns.handler() with proper prefixes.
158
+ // Do NOT wrap in MapRootLayout here: the captured parent chain from
159
+ // pattern extraction already includes the synthetic MapRootLayout
160
+ // parent, so adding another would create an extra level that does
161
+ // not exist in the non-lazy (root handler) path and would produce
162
+ // mismatched shortCodes.
122
163
  if (entry.lazy && entry.lazyPatterns) {
123
164
  const lazyPatterns = entry.lazyPatterns as UrlPatterns<any>;
124
165
  const includePrefix = (entry as any)._lazyPrefix || "";
125
166
  const fullPrefix = (lazyContext?.urlPrefix || "") + includePrefix;
126
167
 
127
- // Wrap in root layout and run with prefixes
128
- const wrappedItems = helpers.layout(MapRootLayout, () => {
129
- if (fullPrefix || lazyContext?.namePrefix) {
130
- return runWithPrefixes(
131
- fullPrefix,
132
- lazyContext?.namePrefix,
133
- () => lazyPatterns.handler()
134
- );
135
- }
136
- return lazyPatterns.handler();
137
- });
138
-
139
- return [wrappedItems].flat(3);
168
+ if (fullPrefix || lazyContext?.namePrefix) {
169
+ return runWithPrefixes(fullPrefix, lazyContext?.namePrefix, () =>
170
+ lazyPatterns.handler(),
171
+ );
172
+ }
173
+ return lazyPatterns.handler();
140
174
  }
141
175
 
142
176
  // Wrap handler execution in root layout so routes get correct parent
@@ -162,36 +196,55 @@ export async function loadManifest(
162
196
  "default" in load
163
197
  ) {
164
198
  // Promise<{ default: () => Array }> - e.g., dynamic import
165
- // Lazy-loaded handlers may need helpers (passed as optional arg)
199
+ if (typeof load.default !== "function") {
200
+ throw new Error(
201
+ `[@rangojs/router] Unsupported async handler: { default } must be a function, ` +
202
+ `got ${typeof load.default}. Use () => import('./urls') for lazy loading.`,
203
+ );
204
+ }
166
205
  return (load.default as (h?: any) => any)(helpers);
167
206
  }
168
207
  if (typeof load === "function") {
169
208
  // Promise<() => Array>
170
209
  return (load as (h?: any) => any)(helpers);
171
210
  }
172
- // Promise<Array> - direct array from async handler
173
- return load;
211
+ // Reject unsupported async handler results. Supported shapes are:
212
+ // Promise<{ default: fn }> — dynamic import
213
+ // Promise<fn> — lazy function
214
+ // Direct Promise<Array> is not supported; use a function wrapper.
215
+ throw new Error(
216
+ `[@rangojs/router] Unsupported async handler result (${typeof load}). ` +
217
+ `Lazy route handlers must resolve to a function or { default: fn }, ` +
218
+ `not a direct array. Wrap your handler: () => import('./urls') or ` +
219
+ `() => Promise.resolve((h) => [...])`,
220
+ );
174
221
  }
175
222
 
176
223
  // Inline handler - routes were registered with correct parent inside layout
177
224
  return [wrappedItems].flat(3);
178
- }
225
+ },
179
226
  );
180
227
  pushMetric?.("manifest:handler-exec", handlerExecStart);
181
228
 
182
229
  const validationStart = performance.now();
183
230
  invariant(
184
231
  useItems && useItems.length > 0,
185
- "Did not receive any handler from router.map()"
186
- );
187
- invariant(
188
- useItems.some((item: { type: string }) => item.type === "layout"),
189
- "Top-level handler must be a layout"
232
+ "Did not receive any handler from router.map()",
190
233
  );
234
+ // For non-lazy entries the root handler is wrapped in MapRootLayout,
235
+ // so the result always contains a layout item. Lazy entries run the
236
+ // included patterns handler directly (no MapRootLayout wrapper) so
237
+ // we skip this check -- the layout is in the captured parent chain.
238
+ if (!lazyContext) {
239
+ invariant(
240
+ useItems.some((item: { type: string }) => item.type === "layout"),
241
+ "Top-level handler must be a layout",
242
+ );
243
+ }
191
244
 
192
245
  invariant(
193
246
  Store.manifest.has(routeKey),
194
- `Route must be registered for ${routeKey}`
247
+ `Route must be registered for ${routeKey}`,
195
248
  );
196
249
  pushMetric?.("manifest:validation", validationStart);
197
250
 
@@ -210,7 +263,7 @@ export async function loadManifest(
210
263
  routeKey,
211
264
  },
212
265
  },
213
- }
266
+ },
214
267
  );
215
268
  }
216
269
  }