@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
@@ -12,7 +12,10 @@ import type {
12
12
  ActionStateListener,
13
13
  HandleData,
14
14
  } from "./types.js";
15
- import { clearPrefetchCache } from "./prefetch/cache.js";
15
+ import {
16
+ clearPrefetchCache,
17
+ clearPrefetchCacheLocal,
18
+ } from "./prefetch/cache.js";
16
19
 
17
20
  /**
18
21
  * Default action state (idle with no payload)
@@ -28,9 +31,15 @@ const DEFAULT_ACTION_STATE: TrackedActionState = {
28
31
  // Maximum number of history entries to cache (URLs visited)
29
32
  const HISTORY_CACHE_SIZE = 20;
30
33
 
31
- // Cache entry: [url-key, segments, stale, handleData?]
34
+ // Cache entry: [url-key, segments, stale, handleData?, routerId?]
32
35
  // stale=true means the data may be outdated and should be revalidated on access
33
- type HistoryCacheEntry = [string, ResolvedSegment[], boolean, HandleData?];
36
+ type HistoryCacheEntry = [
37
+ string,
38
+ ResolvedSegment[],
39
+ boolean,
40
+ HandleData?,
41
+ string?,
42
+ ];
34
43
 
35
44
  /**
36
45
  * Shallow clone handleData to avoid reference sharing between cache entries.
@@ -258,6 +267,11 @@ export function createNavigationStore(
258
267
  // Used to maintain intercept context during action revalidation
259
268
  let interceptSourceUrl: string | null = null;
260
269
 
270
+ // Router identity - tracks which router is currently active.
271
+ // When this changes on a partial response, the client forces a full
272
+ // tree replacement instead of reconciling with stale segments.
273
+ let currentRouterId: string | undefined;
274
+
261
275
  // Action state tracking (for useAction hook)
262
276
  // Maps action function ID to its tracked state
263
277
  const actionStates = new Map<string, TrackedActionState>();
@@ -269,18 +283,17 @@ export function createNavigationStore(
269
283
  /**
270
284
  * Create a debounced function that batches rapid calls
271
285
  */
286
+ // A non-keyed notifier is the keyed one restricted to a single constant key;
287
+ // its own keyed instance means the "" key never collides with action keys.
272
288
  function createDebouncedNotifier<T extends (...args: any[]) => void>(
273
289
  fn: T,
274
290
  ms: number = 20,
275
291
  ): T {
276
- let timeout: ReturnType<typeof setTimeout> | null = null;
277
- return ((...args: Parameters<T>) => {
278
- if (timeout !== null) clearTimeout(timeout);
279
- timeout = setTimeout(() => {
280
- timeout = null;
281
- fn(...args);
282
- }, ms);
283
- }) as T;
292
+ const keyed = createKeyedDebouncedNotifier(
293
+ (_key: string, ...args: any[]) => fn(...args),
294
+ ms,
295
+ );
296
+ return ((...args: Parameters<T>) => keyed("", ...args)) as T;
284
297
  }
285
298
 
286
299
  /**
@@ -324,6 +337,18 @@ export function createNavigationStore(
324
337
  clearPrefetchCache();
325
338
  }
326
339
 
340
+ /**
341
+ * Drop this tab's navigation + prefetch caches without broadcasting or
342
+ * rotating shared state. Used when the local session changes in a way that
343
+ * doesn't affect other tabs — e.g. this tab crosses into a different app
344
+ * via a cross-router navigation. Other tabs in the old app keep their
345
+ * caches and their X-Rango-State token.
346
+ */
347
+ function clearCacheInternalLocal(): void {
348
+ historyCache.length = 0;
349
+ clearPrefetchCacheLocal();
350
+ }
351
+
327
352
  /**
328
353
  * Mark all cache entries as stale (internal - does not broadcast)
329
354
  */
@@ -571,10 +596,17 @@ export function createNavigationStore(
571
596
  segments,
572
597
  false,
573
598
  clonedHandleData,
599
+ currentRouterId,
574
600
  ];
575
601
  } else {
576
602
  // Add new entry at the end (not stale)
577
- historyCache.push([historyKey, segments, false, clonedHandleData]);
603
+ historyCache.push([
604
+ historyKey,
605
+ segments,
606
+ false,
607
+ clonedHandleData,
608
+ currentRouterId,
609
+ ]);
578
610
  // Remove oldest entries if over limit
579
611
  while (historyCache.length > cacheSize) {
580
612
  historyCache.shift();
@@ -586,14 +618,22 @@ export function createNavigationStore(
586
618
  * Get cached segments for a history entry
587
619
  * Returns { segments, stale, handleData } or undefined if not cached
588
620
  */
589
- getCachedSegments(
590
- historyKey: string,
591
- ):
592
- | { segments: ResolvedSegment[]; stale: boolean; handleData?: HandleData }
621
+ getCachedSegments(historyKey: string):
622
+ | {
623
+ segments: ResolvedSegment[];
624
+ stale: boolean;
625
+ handleData?: HandleData;
626
+ routerId?: string;
627
+ }
593
628
  | undefined {
594
629
  const entry = historyCache.find(([key]) => key === historyKey);
595
630
  if (!entry) return undefined;
596
- return { segments: entry[1], stale: entry[2], handleData: entry[3] };
631
+ return {
632
+ segments: entry[1],
633
+ stale: entry[2],
634
+ handleData: entry[3],
635
+ routerId: entry[4],
636
+ };
597
637
  },
598
638
 
599
639
  /**
@@ -621,6 +661,7 @@ export function createNavigationStore(
621
661
  entry[1],
622
662
  entry[2],
623
663
  clonedHandleData,
664
+ entry[4], // preserve routerId
624
665
  ];
625
666
  }
626
667
  },
@@ -641,6 +682,15 @@ export function createNavigationStore(
641
682
  clearCacheAndBroadcast();
642
683
  },
643
684
 
685
+ /**
686
+ * Drop this tab's navigation + prefetch caches locally without
687
+ * broadcasting or rotating shared state. Intended for cross-app
688
+ * transitions where the session state diverges for this tab only.
689
+ */
690
+ clearHistoryCacheLocal(): void {
691
+ clearCacheInternalLocal();
692
+ },
693
+
644
694
  /**
645
695
  * Mark cache as stale and broadcast to other tabs
646
696
  * Called after server actions - allows SWR pattern for popstate
@@ -687,6 +737,14 @@ export function createNavigationStore(
687
737
  interceptSourceUrl = url;
688
738
  },
689
739
 
740
+ getRouterId(): string | undefined {
741
+ return currentRouterId;
742
+ },
743
+
744
+ setRouterId(id: string): void {
745
+ currentRouterId = id;
746
+ },
747
+
690
748
  // ========================================================================
691
749
  // UI Update Notifications
692
750
  // ========================================================================
@@ -7,12 +7,11 @@ import type {
7
7
  import { generateHistoryKey } from "./navigation-store.js";
8
8
  import {
9
9
  handleNavigationStart,
10
- handleNavigationEnd,
11
10
  ensureHistoryKey,
12
11
  } from "./scroll-restoration.js";
13
12
  import type { EventController, NavigationHandle } from "./event-controller.js";
14
13
  import { debugLog } from "./logging.js";
15
- import { buildHistoryState } from "./history-state.js";
14
+ import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
16
15
 
17
16
  // Re-export for consumers that import from navigation-transaction
18
17
  export { resolveNavigationState } from "./history-state.js";
@@ -81,11 +80,12 @@ export interface BoundTransaction {
81
80
  readonly currentUrl: string;
82
81
  /** Start streaming and get a token to end it when the stream completes */
83
82
  startStreaming(): StreamingToken;
83
+ /** Commit the navigation. Returns the effective scroll option for the caller to handle. */
84
84
  commit(
85
85
  segmentIds: string[],
86
86
  segments: ResolvedSegment[],
87
87
  overrides?: BoundCommitOverrides,
88
- ): void;
88
+ ): { scroll?: boolean };
89
89
  }
90
90
 
91
91
  /**
@@ -93,7 +93,7 @@ export interface BoundTransaction {
93
93
  * Uses the event controller handle for lifecycle management
94
94
  */
95
95
  interface NavigationTransaction extends Disposable {
96
- commit(options: CommitOptions): void;
96
+ commit(options: CommitOptions): { scroll?: boolean };
97
97
  with(
98
98
  options: Omit<CommitOptions, "segmentIds" | "segments">,
99
99
  ): BoundTransaction;
@@ -120,7 +120,7 @@ export function createNavigationTransaction(
120
120
  /**
121
121
  * Commit the navigation - updates store and URL atomically
122
122
  */
123
- function commit(opts: CommitOptions): void {
123
+ function commit(opts: CommitOptions): { scroll?: boolean } {
124
124
  committed = true;
125
125
 
126
126
  const {
@@ -150,7 +150,7 @@ export function createNavigationTransaction(
150
150
  // Without this, the entry lingers and weakens state-machine invariants.
151
151
  handle.complete(parsedUrl);
152
152
  debugLog("[Browser] Cache-only commit, historyKey:", historyKey);
153
- return;
153
+ return { scroll: false };
154
154
  }
155
155
 
156
156
  // Save current scroll position before navigating
@@ -172,7 +172,7 @@ export function createNavigationTransaction(
172
172
  debugLog("[Browser] Store updated (action)");
173
173
  // Complete navigation to clear loading state
174
174
  handle.complete(parsedUrl);
175
- return;
175
+ return { scroll: false };
176
176
  }
177
177
 
178
178
  // Build history state - include user state, intercept info, and server-set state
@@ -186,12 +186,8 @@ export function createNavigationTransaction(
186
186
  // Used to detect when location state is being cleared.
187
187
  const oldState = window.history.state;
188
188
 
189
- // Update browser URL
190
- if (replace) {
191
- window.history.replaceState(historyState, "", url);
192
- } else {
193
- window.history.pushState(historyState, "", url);
194
- }
189
+ // Update browser URL (stamps history.state.idx for back() first-entry detection)
190
+ pushHistoryWithIdx(historyState, url, replace ?? false);
195
191
  // Ensure new history entry has a scroll restoration key
196
192
  ensureHistoryKey();
197
193
 
@@ -205,14 +201,16 @@ export function createNavigationTransaction(
205
201
  // Complete the navigation in event controller (sets idle state, updates location)
206
202
  handle.complete(parsedUrl);
207
203
 
208
- // Handle scroll after navigation
209
- handleNavigationEnd({ scroll });
204
+ // NOTE: Scroll is NOT handled here. The caller (partial-update.ts) handles
205
+ // scroll AFTER onUpdate() so React has the new content before we scroll.
210
206
 
211
207
  debugLog(
212
208
  "[Browser] Navigation committed, historyKey:",
213
209
  historyKey,
214
210
  intercept ? "(intercept)" : "",
215
211
  );
212
+
213
+ return { scroll };
216
214
  }
217
215
 
218
216
  return {
@@ -238,32 +236,18 @@ export function createNavigationTransaction(
238
236
  segments: ResolvedSegment[],
239
237
  overrides?: BoundCommitOverrides,
240
238
  ) => {
241
- // Allow overrides to disable scroll (e.g., for intercepts)
242
- const finalScroll =
243
- overrides?.scroll !== undefined ? overrides.scroll : opts.scroll;
244
- // Allow overrides to force replace (e.g., for intercepts)
245
- const finalReplace =
246
- overrides?.replace !== undefined ? overrides.replace : opts.replace;
247
- // Intercept info: overrides take precedence, fallback to opts
248
- const intercept =
249
- overrides?.intercept !== undefined
250
- ? overrides.intercept
251
- : opts.intercept;
239
+ const finalScroll = overrides?.scroll ?? opts.scroll;
240
+ const finalReplace = overrides?.replace ?? opts.replace;
241
+ const intercept = overrides?.intercept ?? opts.intercept;
252
242
  const interceptSourceUrl =
253
- overrides?.interceptSourceUrl !== undefined
254
- ? overrides.interceptSourceUrl
255
- : opts.interceptSourceUrl;
256
- // Cache-only mode: overrides take precedence, fallback to opts
257
- const cacheOnly =
258
- overrides?.cacheOnly !== undefined
259
- ? overrides.cacheOnly
260
- : opts.cacheOnly;
261
- // User state: overrides take precedence, fallback to opts
243
+ overrides?.interceptSourceUrl ?? opts.interceptSourceUrl;
244
+ const cacheOnly = overrides?.cacheOnly ?? opts.cacheOnly;
245
+ // state is `unknown` (null is meaningful) so `??` would wrongly drop a
246
+ // null override; serverState always comes from overrides, never opts.
262
247
  const state =
263
248
  overrides?.state !== undefined ? overrides.state : opts.state;
264
- // Server-set location state: only from overrides (set by partial-update)
265
249
  const serverState = overrides?.serverState;
266
- commit({
250
+ return commit({
267
251
  ...opts,
268
252
  segmentIds,
269
253
  segments,
@@ -14,11 +14,39 @@ const addTransitionType: ((type: string) => void) | undefined =
14
14
  import type { RenderSegmentsOptions } from "../segment-system.js";
15
15
  import { reconcileSegments } from "./segment-reconciler.js";
16
16
  import type { ReconcileActor } from "./segment-reconciler.js";
17
- import { hasActiveIntercept as hasActiveInterceptSlots } from "./intercept-utils.js";
17
+ import {
18
+ hasActiveIntercept as hasActiveInterceptSlots,
19
+ isInterceptSegment,
20
+ } from "./intercept-utils.js";
18
21
  import type { BoundTransaction } from "./navigation-transaction.js";
19
22
  import { ServerRedirect } from "../errors.js";
20
23
  import { debugLog } from "./logging.js";
21
24
  import { validateRedirectOrigin } from "./validate-redirect-origin.js";
25
+ import type { NavigationUpdate } from "./types.js";
26
+
27
+ /** Build a scroll payload from the commit's scroll option */
28
+ function toScrollPayload(
29
+ scroll: boolean | undefined,
30
+ ): NonNullable<NavigationUpdate["scroll"]> {
31
+ return { enabled: scroll !== false ? scroll : false };
32
+ }
33
+
34
+ /**
35
+ * Whether to wrap an update in startViewTransition.
36
+ *
37
+ * Intercept-driven updates only mutate the parallel slot — the main outlet
38
+ * shows the same content — so transitions on the underlying main segments
39
+ * shouldn't fire (otherwise their elements get hoisted above the modal).
40
+ */
41
+ function shouldStartViewTransition(segments: ResolvedSegment[]): boolean {
42
+ let hasIntercept = false;
43
+ let hasTransition = false;
44
+ for (const s of segments) {
45
+ if (isInterceptSegment(s)) hasIntercept = true;
46
+ else if (s.transition) hasTransition = true;
47
+ }
48
+ return !hasIntercept && hasTransition;
49
+ }
22
50
 
23
51
  /**
24
52
  * Configuration for creating a partial updater
@@ -31,8 +59,15 @@ export interface PartialUpdateConfig {
31
59
  segments: ResolvedSegment[],
32
60
  options?: RenderSegmentsOptions,
33
61
  ) => Promise<ReactNode> | ReactNode;
34
- /** RSC version received from server (from initial payload metadata) */
35
- version?: string;
62
+ /** RSC version getter — returns the current version (may change after HMR) */
63
+ getVersion?: () => string | undefined;
64
+ /**
65
+ * Replace the active app-shell when a cross-app navigation is detected.
66
+ * Called before the full-update tree replacement renders, so the new
67
+ * payload's rootLayout, basename, and version are picked up. Theme,
68
+ * warmup, and prefetch TTL are not part of the shell — see AppShell.
69
+ */
70
+ applyAppShell?: (next: import("./app-shell.js").AppShell) => void;
36
71
  }
37
72
 
38
73
  /**
@@ -68,7 +103,7 @@ export type UpdateMode =
68
103
  /** Source URL for intercept restore (popstate cache miss) */
69
104
  interceptSourceUrl?: string;
70
105
  }
71
- | { type: "leave-intercept" }
106
+ | { type: "leave-intercept"; interceptSourceUrl?: string }
72
107
  | { type: "stale-revalidation"; interceptSourceUrl?: string }
73
108
  | { type: "action"; interceptSourceUrl?: string };
74
109
 
@@ -96,7 +131,14 @@ export type PartialUpdater = (
96
131
  export function createPartialUpdater(
97
132
  config: PartialUpdateConfig,
98
133
  ): PartialUpdater {
99
- const { store, client, onUpdate, renderSegments, version } = config;
134
+ const {
135
+ store,
136
+ client,
137
+ onUpdate,
138
+ renderSegments,
139
+ getVersion = () => undefined,
140
+ applyAppShell,
141
+ } = config;
100
142
 
101
143
  /**
102
144
  * Get current page's cached segments as an array
@@ -127,13 +169,7 @@ export function createPartialUpdater(
127
169
  // Capture history key at start for stale revalidation consistency check
128
170
  const historyKeyAtStart = store.getHistoryKey();
129
171
 
130
- // Derive interceptSourceUrl from modes that carry it
131
- const interceptSourceUrl =
132
- mode.type === "stale-revalidation" ||
133
- mode.type === "action" ||
134
- mode.type === "navigate"
135
- ? mode.interceptSourceUrl
136
- : undefined;
172
+ const interceptSourceUrl = mode.interceptSourceUrl;
137
173
 
138
174
  // When leaving intercept, filter out intercept-specific segments
139
175
  let segments: string[];
@@ -153,9 +189,16 @@ export function createPartialUpdater(
153
189
  segments = segmentIds ?? segmentState.currentSegmentIds;
154
190
  }
155
191
 
156
- // For intercept revalidation, use the intercept source URL as previousUrl
192
+ // For intercept revalidation, use the intercept source URL as previousUrl.
193
+ // For leave-intercept, tx.currentUrl captures window.location.href at tx
194
+ // creation, which on popstate is already the destination URL and would
195
+ // tell the server "from == to". segmentState.currentUrl still points at
196
+ // the URL the cached segments render (the intercept URL), which is the
197
+ // correct "from" for the server's diff computation.
157
198
  const previousUrl =
158
- interceptSourceUrl || tx.currentUrl || segmentState.currentUrl;
199
+ mode.type === "leave-intercept"
200
+ ? segmentState.currentUrl || tx.currentUrl
201
+ : interceptSourceUrl || tx.currentUrl || segmentState.currentUrl;
159
202
 
160
203
  debugLog(`\n[Browser] >>> NAVIGATION`);
161
204
  debugLog(`[Browser] From: ${previousUrl}`);
@@ -169,11 +212,14 @@ export function createPartialUpdater(
169
212
  // When navigating with targetCacheSegments, use those for consistency.
170
213
  // Otherwise fall back to current page's segments (for same-route revalidation).
171
214
  const targetCache =
172
- mode.type === "navigate" ? mode.targetCacheSegments : undefined;
173
- const cachedSegs =
174
- targetCache && targetCache.length > 0
175
- ? targetCache
176
- : getCurrentCachedSegments();
215
+ mode.type === "navigate" && mode.targetCacheSegments?.length
216
+ ? mode.targetCacheSegments
217
+ : undefined;
218
+ const cachedSegs = targetCache ?? getCurrentCachedSegments();
219
+ const cachedSegsSource = targetCache ? "history-cache" : "current-page";
220
+ debugLog(
221
+ `[Browser] cachedSegs source: ${cachedSegsSource} (${cachedSegs.length} segments: ${cachedSegs.map((s) => s.id).join(", ")})`,
222
+ );
177
223
 
178
224
  // Fetch partial payload (no abort signal - RSC doesn't support it well)
179
225
  let fetchResult: Awaited<ReturnType<NavigationClient["fetchPartial"]>>;
@@ -185,7 +231,8 @@ export function createPartialUpdater(
185
231
  // (action redirect sends empty segments for a fresh render).
186
232
  staleRevalidation:
187
233
  mode.type === "stale-revalidation" || segments.length === 0,
188
- version,
234
+ version: getVersion(),
235
+ routerId: store.getRouterId?.(),
189
236
  });
190
237
  // Mark navigation as streaming (response received, now parsing RSC).
191
238
  // Called after fetchPartial so pendingUrl stays set during the network wait,
@@ -198,6 +245,32 @@ export function createPartialUpdater(
198
245
  streamingToken.end();
199
246
  });
200
247
 
248
+ // Detect app switch: if routerId changed, the navigation crossed into
249
+ // a different router (e.g., via host router path mount). Downgrade
250
+ // partial to full so the entire tree is replaced without reconciliation
251
+ // against stale segments from the previous app, and replace the app
252
+ // shell (rootLayout, basename, version) so the target app's document
253
+ // and router config take effect instead of remaining captured from the
254
+ // initial load. Theme, warmup, and prefetch TTL are intentionally
255
+ // document-lifetime (see AppShell doc); a new document navigation
256
+ // applies them.
257
+ if (payload.metadata?.routerId) {
258
+ const prevRouterId = store.getRouterId?.();
259
+ if (prevRouterId && prevRouterId !== payload.metadata.routerId) {
260
+ debugLog(
261
+ `[Browser] App switch detected (${prevRouterId} → ${payload.metadata.routerId}), forcing full update`,
262
+ );
263
+ payload.metadata.isPartial = false;
264
+ applyAppShell?.({
265
+ routerId: payload.metadata.routerId,
266
+ rootLayout: payload.metadata.rootLayout,
267
+ basename: payload.metadata.basename,
268
+ version: payload.metadata.version,
269
+ });
270
+ }
271
+ store.setRouterId?.(payload.metadata.routerId);
272
+ }
273
+
201
274
  // Handle server-side redirect with state
202
275
  if (payload.metadata?.redirect) {
203
276
  if (signal?.aborted) {
@@ -237,7 +310,7 @@ export function createPartialUpdater(
237
310
  .filter(Boolean) as ResolvedSegment[];
238
311
 
239
312
  // When navigating with cached segments to a different route, render them.
240
- if (mode.type === "navigate" && targetCache && targetCache.length > 0) {
313
+ if (mode.type === "navigate" && targetCache) {
241
314
  debugLog(
242
315
  "[Browser] No diff but navigating with cached segments - rendering target route",
243
316
  );
@@ -246,7 +319,21 @@ export function createPartialUpdater(
246
319
  forceAwait: true,
247
320
  });
248
321
 
249
- tx.commit(matchedIds, existingSegments);
322
+ const { scroll: commitScroll } = tx.commit(
323
+ matchedIds,
324
+ existingSegments,
325
+ );
326
+
327
+ // tx.commit() cached the source page's handleData because
328
+ // eventController hasn't been updated yet. Overwrite with the
329
+ // correct cached handleData to prevent cache corruption on
330
+ // subsequent navigations to this same URL.
331
+ if (mode.targetCacheHandleData) {
332
+ store.updateCacheHandleData(
333
+ store.getHistoryKey(),
334
+ mode.targetCacheHandleData,
335
+ );
336
+ }
250
337
 
251
338
  // Include cachedHandleData in metadata so NavigationProvider can restore
252
339
  // breadcrumbs and other handle data from cache.
@@ -260,12 +347,10 @@ export function createPartialUpdater(
260
347
  ...metadataWithoutHandles,
261
348
  cachedHandleData: mode.targetCacheHandleData,
262
349
  },
350
+ scroll: toScrollPayload(commitScroll),
263
351
  };
264
352
 
265
- const cachedHasTransition = existingSegments.some(
266
- (s) => s.transition,
267
- );
268
- if (cachedHasTransition) {
353
+ if (shouldStartViewTransition(existingSegments)) {
269
354
  startTransition(() => {
270
355
  if (addTransitionType) {
271
356
  addTransitionType("navigation");
@@ -290,11 +375,15 @@ export function createPartialUpdater(
290
375
  forceAwait: true,
291
376
  });
292
377
 
293
- tx.commit(matchedIds, existingSegments);
378
+ const { scroll: leaveScroll } = tx.commit(
379
+ matchedIds,
380
+ existingSegments,
381
+ );
294
382
 
295
383
  onUpdate({
296
384
  root: newTree,
297
385
  metadata: payload.metadata,
386
+ scroll: toScrollPayload(leaveScroll),
298
387
  });
299
388
 
300
389
  debugLog("[Browser] Navigation complete (left intercept)");
@@ -411,8 +500,10 @@ export function createPartialUpdater(
411
500
  }
412
501
  }
413
502
 
414
- // Commit navigation - transaction handles all store mutations atomically
415
- const allSegmentIds = reconciled.segments.map((s) => s.id);
503
+ // Commit navigation - use server's matched as the authoritative segment ID list.
504
+ // reconciled.segments may be missing IDs (e.g., loader segments not in diff or cache)
505
+ // but the server's matched always includes all expected segment IDs.
506
+ const allSegmentIds = matchedIds;
416
507
  const serverLocationState = payload.metadata?.locationState;
417
508
  const overrides: CommitOverrides | undefined = isInterceptResponse
418
509
  ? {
@@ -424,7 +515,11 @@ export function createPartialUpdater(
424
515
  : serverLocationState
425
516
  ? { serverState: serverLocationState }
426
517
  : undefined;
427
- tx.commit(allSegmentIds, reconciled.segments, overrides);
518
+ const { scroll: navScroll } = tx.commit(
519
+ allSegmentIds,
520
+ reconciled.segments,
521
+ overrides,
522
+ );
428
523
 
429
524
  // For stale revalidation: verify history key hasn't changed before updating UI
430
525
  if (mode.type === "stale-revalidation") {
@@ -439,8 +534,10 @@ export function createPartialUpdater(
439
534
 
440
535
  debugLog("[partial-update] updating document");
441
536
 
442
- // Emit update to trigger React render
443
- const hasTransition = reconciled.mainSegments.some((s) => s.transition);
537
+ // Emit update to trigger React render.
538
+ // Scroll info is included so NavigationProvider applies it after React commits.
539
+ const hasTransition = shouldStartViewTransition(reconciled.segments);
540
+ const scrollPayload = toScrollPayload(navScroll);
444
541
 
445
542
  if (mode.type === "action" || mode.type === "stale-revalidation") {
446
543
  startTransition(() => {
@@ -450,6 +547,7 @@ export function createPartialUpdater(
450
547
  onUpdate({
451
548
  root: newTree,
452
549
  metadata: payload.metadata!,
550
+ scroll: scrollPayload,
453
551
  });
454
552
  });
455
553
  } else if (hasTransition) {
@@ -460,12 +558,14 @@ export function createPartialUpdater(
460
558
  onUpdate({
461
559
  root: newTree,
462
560
  metadata: payload.metadata!,
561
+ scroll: scrollPayload,
463
562
  });
464
563
  });
465
564
  } else {
466
565
  onUpdate({
467
566
  root: newTree,
468
567
  metadata: payload.metadata!,
568
+ scroll: scrollPayload,
469
569
  });
470
570
  }
471
571
 
@@ -492,15 +592,14 @@ export function createPartialUpdater(
492
592
  }
493
593
 
494
594
  const fullUpdateServerState = payload.metadata?.locationState;
495
- if (fullUpdateServerState) {
496
- tx.commit(segmentIds, segments, { serverState: fullUpdateServerState });
497
- } else {
498
- tx.commit(segmentIds, segments);
499
- }
595
+ const { scroll: fullScroll } = fullUpdateServerState
596
+ ? tx.commit(segmentIds, segments, {
597
+ serverState: fullUpdateServerState,
598
+ })
599
+ : tx.commit(segmentIds, segments);
500
600
 
501
- const fullHasTransition = segments.some(
502
- (s: ResolvedSegment) => s.transition,
503
- );
601
+ const fullHasTransition = shouldStartViewTransition(segments);
602
+ const fullScrollPayload = toScrollPayload(fullScroll);
504
603
 
505
604
  if (mode.type === "stale-revalidation") {
506
605
  await rawStreamComplete;
@@ -511,6 +610,7 @@ export function createPartialUpdater(
511
610
  onUpdate({
512
611
  root: newTree,
513
612
  metadata: payload.metadata!,
613
+ scroll: fullScrollPayload,
514
614
  });
515
615
  });
516
616
  } else if (mode.type === "action") {
@@ -521,6 +621,7 @@ export function createPartialUpdater(
521
621
  onUpdate({
522
622
  root: newTree,
523
623
  metadata: payload.metadata!,
624
+ scroll: fullScrollPayload,
524
625
  });
525
626
  });
526
627
  } else if (fullHasTransition) {
@@ -531,12 +632,14 @@ export function createPartialUpdater(
531
632
  onUpdate({
532
633
  root: newTree,
533
634
  metadata: payload.metadata!,
635
+ scroll: fullScrollPayload,
534
636
  });
535
637
  });
536
638
  } else {
537
639
  onUpdate({
538
640
  root: newTree,
539
641
  metadata: payload.metadata!,
642
+ scroll: fullScrollPayload,
540
643
  });
541
644
  }
542
645