@timber-js/app 0.2.0-alpha.220 → 0.2.0-alpha.222

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 (236) hide show
  1. package/dist/_chunks/{actions-BwkmAYXq.js → actions-vBHr2vqd.js} +3 -3
  2. package/dist/_chunks/{actions-BwkmAYXq.js.map → actions-vBHr2vqd.js.map} +1 -1
  3. package/dist/_chunks/{cache-api-LA3sBpUS.js → cache-api-DdcDLpBj.js} +72 -145
  4. package/dist/_chunks/cache-api-DdcDLpBj.js.map +1 -0
  5. package/dist/_chunks/chains-B8TCLved.js +1 -0
  6. package/dist/_chunks/{chains-e_Buf9vg.js → chains-BchW_AtW.js} +2 -2
  7. package/dist/_chunks/{chains-e_Buf9vg.js.map → chains-BchW_AtW.js.map} +1 -1
  8. package/dist/_chunks/{classify-2Yp3xJY1.js → classify-IqzMpxMs.js} +2 -2
  9. package/dist/_chunks/{classify-2Yp3xJY1.js.map → classify-IqzMpxMs.js.map} +1 -1
  10. package/dist/_chunks/{cli-check-DDwCkeDY.js → cli-check-DQne_YhU.js} +3 -3
  11. package/dist/_chunks/{cli-check-DDwCkeDY.js.map → cli-check-DQne_YhU.js.map} +1 -1
  12. package/dist/_chunks/{cli-schema-sync-BdIebmk3.js → cli-schema-sync-BS-RFGE2.js} +2 -2
  13. package/dist/_chunks/{cli-schema-sync-BdIebmk3.js.map → cli-schema-sync-BS-RFGE2.js.map} +1 -1
  14. package/dist/_chunks/{cli-schema-sync-CLNfXQDK.js → cli-schema-sync-v872sHms.js} +1 -1
  15. package/dist/_chunks/{client-dep-entries-BOkpKjj1.js → client-dep-entries-BJyP9SIu.js} +2 -2
  16. package/dist/_chunks/{client-dep-entries-BOkpKjj1.js.map → client-dep-entries-BJyP9SIu.js.map} +1 -1
  17. package/dist/_chunks/{convention-lint-ByKJ6aqD.js → convention-lint-VwzrtjIt.js} +3 -3
  18. package/dist/_chunks/{convention-lint-ByKJ6aqD.js.map → convention-lint-VwzrtjIt.js.map} +1 -1
  19. package/dist/_chunks/{dev-server-DnODXuNM.js → dev-server-BNr5drEO.js} +57 -8
  20. package/dist/_chunks/dev-server-BNr5drEO.js.map +1 -0
  21. package/dist/_chunks/dev-server-CUg7Mqh_.js +1 -0
  22. package/dist/_chunks/dev-store-BOa304m_.js +283 -0
  23. package/dist/_chunks/dev-store-BOa304m_.js.map +1 -0
  24. package/dist/_chunks/{error-boundary-xxxLtXt6.js → error-boundary-Bc8QPZuq.js} +71 -21
  25. package/dist/_chunks/error-boundary-Bc8QPZuq.js.map +1 -0
  26. package/dist/_chunks/{flight-source-node-0dE-t3kq.js → flight-source-node-BdHUOUqg.js} +6 -7
  27. package/dist/_chunks/flight-source-node-BdHUOUqg.js.map +1 -0
  28. package/dist/_chunks/global-context-B9PFncvb.js +48 -0
  29. package/dist/_chunks/global-context-B9PFncvb.js.map +1 -0
  30. package/dist/_chunks/{json-lossy-check-C8zBY2uZ.js → json-lossy-check-C3Sht92C.js} +2 -2
  31. package/dist/_chunks/{json-lossy-check-C8zBY2uZ.js.map → json-lossy-check-C3Sht92C.js.map} +1 -1
  32. package/dist/_chunks/{live-graph-tSWrv8eH.js → live-graph-DEu_GWbc.js} +4 -4
  33. package/dist/_chunks/{live-graph-tSWrv8eH.js.map → live-graph-DEu_GWbc.js.map} +1 -1
  34. package/dist/_chunks/{logger-CbLdcy-W.js → logger-CI_hThfy.js} +10 -2
  35. package/dist/_chunks/{logger-CbLdcy-W.js.map → logger-CI_hThfy.js.map} +1 -1
  36. package/dist/_chunks/{node-response-Dibufw_b.js → node-response-bF0bKoig.js} +49 -3
  37. package/dist/_chunks/node-response-bF0bKoig.js.map +1 -0
  38. package/dist/_chunks/{poison-scan-C4FgMxFl.js → poison-scan-DTWIfNgD.js} +2 -2
  39. package/dist/_chunks/{poison-scan-C4FgMxFl.js.map → poison-scan-DTWIfNgD.js.map} +1 -1
  40. package/dist/_chunks/{purge-store-Byr8XOjU.js → purge-store-WZaxu-3m.js} +2 -2
  41. package/dist/_chunks/purge-store-WZaxu-3m.js.map +1 -0
  42. package/dist/_chunks/{render-timeout-DOf_BBcO.js → render-timeout-Ln_u7fX-.js} +19 -11
  43. package/dist/_chunks/render-timeout-Ln_u7fX-.js.map +1 -0
  44. package/dist/_chunks/{resolve-schema-CBR6Lm4i.js → resolve-schema-CkAInout.js} +2 -2
  45. package/dist/_chunks/{resolve-schema-CBR6Lm4i.js.map → resolve-schema-CkAInout.js.map} +1 -1
  46. package/dist/_chunks/{scanner-Cb3fSjAC.js → scanner-C8fdKvKG.js} +2 -2
  47. package/dist/_chunks/{scanner-Cb3fSjAC.js.map → scanner-C8fdKvKG.js.map} +1 -1
  48. package/dist/_chunks/{schema-bridge-C83xa9lT.js → schema-bridge-DpOmvZlI.js} +60 -23
  49. package/dist/_chunks/schema-bridge-DpOmvZlI.js.map +1 -0
  50. package/dist/_chunks/{segment-context-xtPUGfdq.js → segment-context-D3DNxKFq.js} +4 -8
  51. package/dist/_chunks/segment-context-D3DNxKFq.js.map +1 -0
  52. package/dist/_chunks/{sizeof-QPE5nd3u.js → sizeof-CO3dk0V1.js} +2 -2
  53. package/dist/_chunks/{sizeof-QPE5nd3u.js.map → sizeof-CO3dk0V1.js.map} +1 -1
  54. package/dist/_chunks/{walkers-qu8TpiLh.js → walkers-BqzxnwGC.js} +3 -3
  55. package/dist/_chunks/{walkers-qu8TpiLh.js.map → walkers-BqzxnwGC.js.map} +1 -1
  56. package/dist/adapters/cloudflare-kv-cache.js +1 -1
  57. package/dist/analyze/crawl-entry.js +3 -3
  58. package/dist/analyze/graph-command.js +2 -2
  59. package/dist/cache/cache-api.d.ts.map +1 -1
  60. package/dist/cache/guarded-read.d.ts +29 -0
  61. package/dist/cache/guarded-read.d.ts.map +1 -0
  62. package/dist/cache/handler-store.d.ts +13 -1
  63. package/dist/cache/handler-store.d.ts.map +1 -1
  64. package/dist/cache/index.js +3 -2
  65. package/dist/cache/invalidation-epoch.d.ts +7 -0
  66. package/dist/cache/invalidation-epoch.d.ts.map +1 -1
  67. package/dist/cache/stores/memory.js +1 -1
  68. package/dist/cache/timber-cache.d.ts.map +1 -1
  69. package/dist/cdn/index.js +1 -1
  70. package/dist/cdn/purge-store.d.ts +10 -1
  71. package/dist/cdn/purge-store.d.ts.map +1 -1
  72. package/dist/cli.js +3 -3
  73. package/dist/client/browser-entry/router-init.d.ts.map +1 -1
  74. package/dist/client/error-boundary.js +1 -1
  75. package/dist/client/global-context.d.ts +21 -1
  76. package/dist/client/global-context.d.ts.map +1 -1
  77. package/dist/client/index.js +9 -27
  78. package/dist/client/index.js.map +1 -1
  79. package/dist/client/internal.js +38 -65
  80. package/dist/client/internal.js.map +1 -1
  81. package/dist/client/link.d.ts.map +1 -1
  82. package/dist/client/navigation-context.d.ts.map +1 -1
  83. package/dist/client/navigation-transition.d.ts +68 -14
  84. package/dist/client/navigation-transition.d.ts.map +1 -1
  85. package/dist/client/params-context.d.ts.map +1 -1
  86. package/dist/client/router-effects.d.ts +35 -31
  87. package/dist/client/router-effects.d.ts.map +1 -1
  88. package/dist/client/router-pipeline.d.ts +2 -6
  89. package/dist/client/router-pipeline.d.ts.map +1 -1
  90. package/dist/client/router-types.d.ts +10 -30
  91. package/dist/client/router-types.d.ts.map +1 -1
  92. package/dist/client/router.d.ts.map +1 -1
  93. package/dist/client/slot-context.d.ts +2 -2
  94. package/dist/client/slot-context.d.ts.map +1 -1
  95. package/dist/codec.js +1 -1
  96. package/dist/cookies/index.js +1 -1
  97. package/dist/dev-tools/logs.d.ts +2 -2
  98. package/dist/dev-tools/logs.d.ts.map +1 -1
  99. package/dist/index.js +149 -56
  100. package/dist/index.js.map +1 -1
  101. package/dist/params/index.js +1 -1
  102. package/dist/plugins/dev-server.d.ts +1 -1
  103. package/dist/plugins/dev-server.d.ts.map +1 -1
  104. package/dist/plugins/dev-store-clear.d.ts +28 -0
  105. package/dist/plugins/dev-store-clear.d.ts.map +1 -0
  106. package/dist/plugins/entries.d.ts +5 -0
  107. package/dist/plugins/entries.d.ts.map +1 -1
  108. package/dist/plugins/orphaned-modules.d.ts +57 -0
  109. package/dist/plugins/orphaned-modules.d.ts.map +1 -0
  110. package/dist/plugins/prebuilt.d.ts +6 -6
  111. package/dist/plugins/prerender-sugar.d.ts.map +1 -1
  112. package/dist/plugins/routing.d.ts +1 -1
  113. package/dist/plugins/routing.d.ts.map +1 -1
  114. package/dist/routing/index.js +2 -2
  115. package/dist/rsc-runtime/dev-reference-cache.d.ts +47 -0
  116. package/dist/rsc-runtime/dev-reference-cache.d.ts.map +1 -0
  117. package/dist/rsc-runtime/rsc.d.ts +0 -15
  118. package/dist/rsc-runtime/rsc.d.ts.map +1 -1
  119. package/dist/rsc-runtime/ssr.d.ts +0 -11
  120. package/dist/rsc-runtime/ssr.d.ts.map +1 -1
  121. package/dist/schema-bridge.d.ts +28 -19
  122. package/dist/schema-bridge.d.ts.map +1 -1
  123. package/dist/search-params/define.d.ts +1 -1
  124. package/dist/search-params/define.d.ts.map +1 -1
  125. package/dist/search-params/index.js +7 -8
  126. package/dist/search-params/index.js.map +1 -1
  127. package/dist/search-params/wrappers.d.ts +3 -3
  128. package/dist/server/abort-scope.d.ts +27 -0
  129. package/dist/server/abort-scope.d.ts.map +1 -0
  130. package/dist/server/flight-source-node.d.ts.map +1 -1
  131. package/dist/server/index.js +2 -2
  132. package/dist/server/instrumentation.d.ts +2 -1
  133. package/dist/server/instrumentation.d.ts.map +1 -1
  134. package/dist/server/internal.d.ts +1 -1
  135. package/dist/server/internal.d.ts.map +1 -1
  136. package/dist/server/internal.js +350 -151
  137. package/dist/server/internal.js.map +1 -1
  138. package/dist/server/logger.d.ts +9 -0
  139. package/dist/server/logger.d.ts.map +1 -1
  140. package/dist/server/pipeline-helpers.d.ts.map +1 -1
  141. package/dist/server/pipeline.d.ts +10 -7
  142. package/dist/server/pipeline.d.ts.map +1 -1
  143. package/dist/server/prebuilt/cache-key.d.ts +26 -0
  144. package/dist/server/prebuilt/cache-key.d.ts.map +1 -1
  145. package/dist/server/prebuilt/capture-render.d.ts +9 -4
  146. package/dist/server/prebuilt/capture-render.d.ts.map +1 -1
  147. package/dist/server/prebuilt/capture-routes.d.ts +1 -1
  148. package/dist/server/prebuilt/dev-store.d.ts +103 -0
  149. package/dist/server/prebuilt/dev-store.d.ts.map +1 -0
  150. package/dist/server/prebuilt/overlay.d.ts +14 -3
  151. package/dist/server/prebuilt/overlay.d.ts.map +1 -1
  152. package/dist/server/prebuilt/payload-source.d.ts +8 -0
  153. package/dist/server/prebuilt/payload-source.d.ts.map +1 -1
  154. package/dist/server/prebuilt/slots.d.ts +5 -6
  155. package/dist/server/prebuilt/slots.d.ts.map +1 -1
  156. package/dist/server/prebuilt-builder.d.ts.map +1 -1
  157. package/dist/server/prebuilt-runtime.d.ts +5 -10
  158. package/dist/server/prebuilt-runtime.d.ts.map +1 -1
  159. package/dist/server/render-timeout.d.ts.map +1 -1
  160. package/dist/server/rsc-entry/action-dispatcher.d.ts.map +1 -1
  161. package/dist/server/rsc-entry/index.d.ts.map +1 -1
  162. package/dist/server/ssr-render.d.ts.map +1 -1
  163. package/docs/api/32-api-cache.mdx +2 -0
  164. package/docs/api/33-api-search-params.mdx +3 -1
  165. package/docs/learn/06-typed-params.mdx +2 -2
  166. package/docs/learn/10-caching.mdx +12 -0
  167. package/docs/learn/11-middleware.mdx +2 -0
  168. package/package.json +1 -1
  169. package/src/cache/cache-api.ts +7 -1
  170. package/src/cache/guarded-read.ts +44 -0
  171. package/src/cache/handler-store.ts +38 -1
  172. package/src/cache/invalidation-epoch.ts +18 -6
  173. package/src/cache/timber-cache.ts +9 -3
  174. package/src/cdn/purge-store.ts +29 -1
  175. package/src/client/browser-entry/action-dispatch.ts +5 -5
  176. package/src/client/browser-entry/router-init.ts +2 -4
  177. package/src/client/global-context.ts +42 -14
  178. package/src/client/link.tsx +14 -18
  179. package/src/client/navigation-context.ts +4 -11
  180. package/src/client/navigation-transition.ts +86 -33
  181. package/src/client/params-context.ts +5 -17
  182. package/src/client/router-effects.ts +70 -45
  183. package/src/client/router-lifecycle.ts +1 -1
  184. package/src/client/router-pipeline.ts +52 -65
  185. package/src/client/router-types.ts +11 -31
  186. package/src/client/router.ts +98 -104
  187. package/src/client/segment-update-context.ts +1 -1
  188. package/src/client/slot-content-cache-context.ts +1 -1
  189. package/src/client/slot-context.ts +6 -17
  190. package/src/dev-tools/logs.ts +76 -50
  191. package/src/plugins/dev-server.ts +58 -9
  192. package/src/plugins/dev-store-clear.ts +47 -0
  193. package/src/plugins/entries.ts +6 -0
  194. package/src/plugins/orphaned-modules.ts +78 -0
  195. package/src/plugins/prebuilt.ts +17 -17
  196. package/src/plugins/prerender-sugar.ts +38 -6
  197. package/src/plugins/routing.ts +23 -1
  198. package/src/rsc-runtime/dev-reference-cache.ts +115 -0
  199. package/src/rsc-runtime/rsc.ts +10 -0
  200. package/src/rsc-runtime/ssr.ts +10 -0
  201. package/src/rsc-runtime/vendor-types.d.ts +8 -0
  202. package/src/schema-bridge.ts +93 -38
  203. package/src/search-params/define.ts +5 -6
  204. package/src/search-params/wrappers.ts +3 -3
  205. package/src/server/abort-scope.ts +49 -0
  206. package/src/server/action-handler.ts +18 -2
  207. package/src/server/flight-source-node.ts +5 -4
  208. package/src/server/instrumentation.ts +32 -8
  209. package/src/server/internal.ts +1 -6
  210. package/src/server/logger.ts +9 -0
  211. package/src/server/pipeline-helpers.ts +5 -3
  212. package/src/server/pipeline.ts +31 -20
  213. package/src/server/prebuilt/cache-key.ts +41 -0
  214. package/src/server/prebuilt/capture-render.ts +10 -6
  215. package/src/server/prebuilt/capture-routes.ts +1 -1
  216. package/src/server/prebuilt/dev-store.ts +173 -0
  217. package/src/server/prebuilt/overlay.ts +21 -5
  218. package/src/server/prebuilt/payload-source.ts +19 -0
  219. package/src/server/prebuilt/slots.ts +5 -6
  220. package/src/server/prebuilt-builder.ts +3 -2
  221. package/src/server/prebuilt-runtime.ts +194 -177
  222. package/src/server/render-timeout.ts +12 -17
  223. package/src/server/rsc-entry/action-dispatcher.ts +3 -1
  224. package/src/server/rsc-entry/index.ts +47 -13
  225. package/src/server/ssr-render.ts +9 -11
  226. package/dist/_chunks/cache-api-LA3sBpUS.js.map +0 -1
  227. package/dist/_chunks/chains-CDK1AWZQ.js +0 -1
  228. package/dist/_chunks/dev-server-DkytOEG2.js +0 -1
  229. package/dist/_chunks/dev-server-DnODXuNM.js.map +0 -1
  230. package/dist/_chunks/error-boundary-xxxLtXt6.js.map +0 -1
  231. package/dist/_chunks/flight-source-node-0dE-t3kq.js.map +0 -1
  232. package/dist/_chunks/node-response-Dibufw_b.js.map +0 -1
  233. package/dist/_chunks/purge-store-Byr8XOjU.js.map +0 -1
  234. package/dist/_chunks/render-timeout-DOf_BBcO.js.map +0 -1
  235. package/dist/_chunks/schema-bridge-C83xa9lT.js.map +0 -1
  236. package/dist/_chunks/segment-context-xtPUGfdq.js.map +0 -1
@@ -34,6 +34,7 @@ import React, { createElement, useMemo, use } from 'react';
34
34
  import { toNullProtoRecord, type CoercedParams } from '../shared/param-value.ts';
35
35
  import { readPublishedParams, type PublishedParams } from '../shared/payload-root.ts';
36
36
  import type { SlotParamsRecord } from '../shared/slot-params.ts';
37
+ import { createGlobalContext } from './global-context.ts';
37
38
 
38
39
  // ─── Types ───────────────────────────────────────────────────────
39
40
 
@@ -72,23 +73,10 @@ export type ParamsContextValue = PublishedParams;
72
73
  *
73
74
  * See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
74
75
  */
75
- const PARAMS_CTX_KEY = Symbol.for('__timber_params_ctx');
76
-
77
- function getOrCreateContext(): React.Context<ParamsContextValue | null> {
78
- const store = globalThis as Record<symbol, unknown>;
79
- const existing = store[PARAMS_CTX_KEY] as React.Context<ParamsContextValue | null> | undefined;
80
- if (existing !== undefined) return existing;
81
- if (typeof React.createContext !== 'function') {
82
- // RSC environment — no contexts here. Nothing in this module runs on that
83
- // side; it only has to import cleanly.
84
- return undefined as unknown as React.Context<ParamsContextValue | null>;
85
- }
86
- const ctx = React.createContext<ParamsContextValue | null>(null);
87
- store[PARAMS_CTX_KEY] = ctx;
88
- return ctx;
89
- }
90
-
91
- const ParamsContext = getOrCreateContext();
76
+ const ParamsContext = createGlobalContext<ParamsContextValue | null>(
77
+ Symbol.for('__timber_params_ctx'),
78
+ null
79
+ );
92
80
 
93
81
  /**
94
82
  * Read the params provided by the tree. Returns null only when no provider
@@ -10,7 +10,12 @@
10
10
  */
11
11
 
12
12
  import { setHardNavigating } from './navigation-root.tsx';
13
- import type { CommitOutcome, RenderOwner } from './navigation-transition.ts';
13
+ import {
14
+ abandonedOutcome,
15
+ type CommitOutcome,
16
+ type NavigationHandle,
17
+ type RenderOwner,
18
+ } from './navigation-transition.ts';
14
19
  import { RedirectError, ServerErrorResponse, NonRscResponse } from './rsc-fetch.ts';
15
20
  import { recordSkew } from './router-skew.ts';
16
21
 
@@ -150,7 +155,7 @@ export interface NavigationRecoveryDeps {
150
155
  * Follow a redirect to `url` — the router's own `navigate()`, carrying
151
156
  * the interrupted navigation's {@link RedirectHop}.
152
157
  */
153
- navigate: (url: string, hop: RedirectHop) => Promise<void>;
158
+ navigate: (url: string, hop: RedirectHop) => NavigationHandle;
154
159
  }
155
160
 
156
161
  /**
@@ -177,54 +182,69 @@ export interface RedirectHop {
177
182
  * scroll position; the hop would otherwise default to scrolling to the top.
178
183
  */
179
184
  scroll: boolean;
180
- /**
181
- * The interrupted navigation's `onCommit`, as {@link HeldCommit.settle}.
182
- * A followed redirect is one logical navigation: the hop's commit is the
183
- * one the caller is waiting for. `<Link>` holds `isPending` until it, and
184
- * a `'failed'` from the interrupted render would release it on the hop's
185
- * decode, ahead of a commit React is still holding (TIM-1571). Recovery
186
- * delivers it itself on every path that does not follow the redirect.
187
- */
188
- onCommit?: (outcome: CommitOutcome) => void;
189
- /**
190
- * The interrupted navigation's `onHandOff`: a server action redirect
191
- * waits for the tree that is finally handed to React, which is the
192
- * redirected one (TIM-1573).
193
- */
194
- onHandOff?: () => void;
195
185
  }
196
186
 
197
187
  /**
198
- * A navigation's `onCommit`, split around its failure.
188
+ * The endings a navigation reports beside its decode — the `handedOff` and
189
+ * `committed` of its {@link NavigationHandle} — fed by the renders it runs.
199
190
  *
200
- * `navigateTransition` settles `onCommit` `'failed'` as soon as `perform`
201
- * throws — before the router has seen the error, so before it knows the
202
- * failure is a redirect it will follow. `transition` is what the render
203
- * gets: every outcome but `'failed'` reaches the caller at once, and
204
- * `'failed'` is left to recovery, which either hands `settle` to the
205
- * redirect hop or delivers it. `settle` runs the caller's callback at most
206
- * once, so a commit or supersession already delivered wins over a later
207
- * `'failed'`.
191
+ * A followed redirect is one logical navigation, so its endings are the
192
+ * redirect hop's: the hop's commit is the one the caller is waiting for.
193
+ * `<Link>` holds `isPending` until it, and a `'failed'` from the
194
+ * interrupted render would release it on the hop's decode, ahead of a
195
+ * commit React is still holding (TIM-1571). A server action redirect waits
196
+ * for the tree that is finally handed to React, which is the redirected one
197
+ * (TIM-1573). So a render's `'failed'` is not this navigation's:
198
+ * `navigateTransition` settles it as soon as `perform` throws, before the
199
+ * router knows the failure is a redirect it will follow. Recovery decides,
200
+ * and either adopts the hop or settles the outcome itself.
208
201
  */
209
- export interface HeldCommit {
210
- transition: ((outcome: CommitOutcome) => void) | undefined;
211
- settle: ((outcome: CommitOutcome) => void) | undefined;
202
+ export interface NavigationEndings {
203
+ /** Report a render's endings — every outcome but `'failed'` at once. */
204
+ track(render: NavigationHandle): void;
205
+ /** Make a redirect hop's endings this navigation's. */
206
+ adopt(hop: NavigationHandle): void;
207
+ /** Settle `committed`. The first outcome wins. */
208
+ settle(outcome: CommitOutcome): void;
212
209
  }
213
210
 
214
- export function holdCommit(onCommit?: (outcome: CommitOutcome) => void): HeldCommit {
215
- if (!onCommit) return { transition: undefined, settle: undefined };
216
- let settled = false;
217
- const settle = (outcome: CommitOutcome): void => {
218
- if (settled) return;
219
- settled = true;
220
- onCommit(outcome);
221
- };
222
- return {
223
- transition: (outcome) => {
224
- if (outcome !== 'failed') settle(outcome);
211
+ /**
212
+ * Run a navigation as a {@link NavigationHandle}. `run` is the navigation:
213
+ * its promise is the handle's decode, and it reports its renders' other
214
+ * endings into the {@link NavigationEndings} it is given.
215
+ *
216
+ * A navigation that ends without reporting — superseded, or failed, before
217
+ * any render — settles them as it ends: `committed` as `'failed'` if it
218
+ * rejected (an outcome already reported wins), and `handedOff` either way,
219
+ * so neither waits on a render that will not come.
220
+ */
221
+ export function runAsHandle(run: (endings: NavigationEndings) => Promise<void>): NavigationHandle {
222
+ let handOff!: () => void;
223
+ const handedOff = new Promise<void>((resolve) => (handOff = resolve));
224
+ let settle!: (outcome: CommitOutcome) => void;
225
+ const committed = new Promise<CommitOutcome>((resolve) => (settle = resolve));
226
+ const endings: NavigationEndings = {
227
+ track(render) {
228
+ void render.handedOff.then(handOff);
229
+ void render.committed.then((outcome) => {
230
+ if (outcome !== 'failed') settle(outcome);
231
+ });
232
+ },
233
+ adopt(hop) {
234
+ void hop.handedOff.then(handOff);
235
+ void hop.committed.then(settle);
225
236
  },
226
237
  settle,
227
238
  };
239
+ // Handled here and rethrown, so a caller that ignores the handle still
240
+ // sees the rejection as unhandled — the regime `useRouter().push()` relies
241
+ // on.
242
+ const decoded = run(endings).then(handOff, (error: unknown) => {
243
+ settle('failed');
244
+ handOff();
245
+ throw error;
246
+ });
247
+ return Object.assign(decoded, { handedOff, committed });
228
248
  }
229
249
 
230
250
  /**
@@ -272,20 +292,25 @@ export function createNavigationRecovery({
272
292
  url: string,
273
293
  fromUrl: string,
274
294
  /** What a redirect hop inherits from the navigation that failed. */
275
- hop: RedirectHop
295
+ hop: RedirectHop,
296
+ /** The failed navigation's endings; a followed redirect's become them. */
297
+ endings: NavigationEndings
276
298
  ): Promise<boolean> {
277
299
  if (error instanceof RedirectError) {
278
300
  // Same ownership rule as leaving the SPA: a superseded navigation must
279
301
  // not steer the document to the destination it was abandoned for.
280
302
  if (currentOwner() !== owner) {
281
- hop.onCommit?.('superseded');
303
+ endings.settle('superseded');
282
304
  return true;
283
305
  }
284
- await navigate(redirectHopUrl(error.redirectUrl, url), hop);
306
+ const redirected = navigate(redirectHopUrl(error.redirectUrl, url), hop);
307
+ endings.adopt(redirected);
308
+ await redirected;
285
309
  return true;
286
310
  }
287
- // Anything else ends this navigation here: its held `'failed'`.
288
- hop.onCommit?.('failed');
311
+ // Anything else ends this navigation here — superseded if a successor
312
+ // took the router, failed otherwise.
313
+ endings.settle(abandonedOutcome(owner));
289
314
  // A server error, a non-RSC response and a version skew all end the same
290
315
  // way: hand `url` back to the server as a document load, so it can render
291
316
  // the outcome as HTML (design/10-error-handling.md §"Error Page Rendering
@@ -193,7 +193,7 @@ export function createNavigationLifecycle(): NavigationLifecycle {
193
193
  current.settle('superseded');
194
194
  }
195
195
  // A handed-off owner whose runNavigation has already finished but whose
196
- // tree hasn't committed yet. Settle it so its onCommit fires.
196
+ // tree hasn't committed yet. Settle it so its `committed` resolves.
197
197
  if (pendingCommit) {
198
198
  pendingCommit.settle('superseded');
199
199
  pendingCommit = null;
@@ -22,7 +22,7 @@ import type { StateTree } from '../shared/segment-info.ts';
22
22
  import type { NavigationState } from './navigation-context.ts';
23
23
  import { isPartialNavigation, type NavigationCommitter } from './navigation-commit.ts';
24
24
  import type { RouterDeps } from './router-types.ts';
25
- import type { CommitOutcome, RenderOwner } from './navigation-transition.ts';
25
+ import type { NavigationHandle, RenderOwner } from './navigation-transition.ts';
26
26
  import { recordSkew } from './router-skew.ts';
27
27
  import { parseRouterUrl } from './router-url.ts';
28
28
  import { SingleflightTimeoutError } from '../cache/singleflight.ts';
@@ -82,12 +82,8 @@ export interface NavigationPipeline {
82
82
  owner: RenderOwner,
83
83
  /** The view transition types the render adds (`NavigationRender`). */
84
84
  types: readonly string[],
85
- perform: () => Promise<NavigationPayload>,
86
- /** See `NavigationOptions.onCommit`. */
87
- onCommit?: (outcome: CommitOutcome) => void,
88
- /** See `NavigationOptions.onHandOff`. */
89
- onHandOff?: () => void
90
- ) => Promise<void>;
85
+ perform: () => Promise<NavigationPayload>
86
+ ) => NavigationHandle;
91
87
  }
92
88
 
93
89
  /**
@@ -183,14 +179,12 @@ export function createNavigationPipeline({
183
179
  * the far side of the supersession check, which only NavigationRoot can
184
180
  * make (TIM-1301).
185
181
  */
186
- async function renderViaTransition(
182
+ function renderViaTransition(
187
183
  url: string,
188
184
  owner: RenderOwner,
189
185
  types: readonly string[],
190
- perform: () => Promise<NavigationPayload>,
191
- onCommit?: (outcome: CommitOutcome) => void,
192
- onHandOff?: () => void
193
- ): Promise<void> {
186
+ perform: () => Promise<NavigationPayload>
187
+ ): NavigationHandle {
194
188
  // Record that THIS navigation's payload has reached React, at the moment
195
189
  // the tree is built and handed back for `navigateTransition` to give to
196
190
  // React — NOT on commit, which is a whole commit phase too late. See
@@ -205,67 +199,60 @@ export function createNavigationPipeline({
205
199
  commit();
206
200
  };
207
201
 
208
- await deps.navigateTransition(
209
- url,
210
- owner,
211
- types,
212
- async (wrapPayload) => {
213
- const result = await perform();
214
- // Await the payload's *root row* — the same thing React would suspend
215
- // on to render the tree, and the first thing Flight emits. The
216
- // previous UI stays on screen while this resolves: nothing has been
217
- // handed to React yet, and when it is, NavigationRoot hands it over
218
- // inside a transition so a tree that is still streaming does not
219
- // displace the departing page (TIM-1306).
220
- //
221
- // Reading them here rather than with `use()` above the tree is what
222
- // keeps a decode failure contained: `result.params` never rejects, so
223
- // it can never take down the provider above every error boundary
224
- // (TIM-1297). A failure after the root row reaches React through the
225
- // tree, inside whatever boundary the app put around it.
226
- const params = await result.params;
227
- // And the tree itself — settled by the same root row, so this adds no
228
- // wait, but it is the half that *rejects*: a root row that fails to
229
- // decode fails this navigation here, before anything is wrapped or
230
- // handed over, and the router takes its recovery path (TIM-1541).
231
- // This used to happen by accident — the payload went through an
232
- // `async` identity helper whose return adopted the thenable — and
233
- // only on the paths that called it.
234
- const payload = await result.payload;
202
+ return deps.navigateTransition(url, owner, types, async (wrapPayload) => {
203
+ const result = await perform();
204
+ // Await the payload's *root row* — the same thing React would suspend
205
+ // on to render the tree, and the first thing Flight emits. The
206
+ // previous UI stays on screen while this resolves: nothing has been
207
+ // handed to React yet, and when it is, NavigationRoot hands it over
208
+ // inside a transition so a tree that is still streaming does not
209
+ // displace the departing page (TIM-1306).
210
+ //
211
+ // Reading them here rather than with `use()` above the tree is what
212
+ // keeps a decode failure contained: `result.params` never rejects, so
213
+ // it can never take down the provider above every error boundary
214
+ // (TIM-1297). A failure after the root row reaches React through the
215
+ // tree, inside whatever boundary the app put around it.
216
+ const params = await result.params;
217
+ // And the tree itself — settled by the same root row, so this adds no
218
+ // wait, but it is the half that *rejects*: a root row that fails to
219
+ // decode fails this navigation here, before anything is wrapped or
220
+ // handed over, and the router takes its recovery path (TIM-1541).
221
+ // This used to happen by accident — the payload went through an
222
+ // `async` identity helper whose return adopted the thenable — and
223
+ // only on the paths that called it.
224
+ const payload = await result.payload;
235
225
 
236
- if (isPartialNavigation(result.skippedSegments)) {
237
- const segmentUpdates = buildSegmentUpdates(result, payload);
226
+ if (isPartialNavigation(result.skippedSegments)) {
227
+ const segmentUpdates = buildSegmentUpdates(result, payload);
238
228
 
239
- // Re-wrap the CURRENT element with new context values.
240
- // SegmentOutlets read updates from SegmentUpdateContext;
241
- // NavigationProvider gets the new pathname; the params published
242
- // above the retained tree are the *incoming* route's.
243
- const element = wrapPayload(
244
- deps._getCurrentPayload?.() ?? payload,
245
- result.navState,
246
- params,
247
- segmentUpdates
248
- );
249
- handOff();
250
- return {
251
- element,
252
- decodePromise: observeSkew(result.decodePromise),
253
- commit: commitAndForget(result.commit),
254
- };
255
- }
256
-
257
- // Full navigation — empty updates, render the new tree.
258
- const element = wrapPayload(payload, result.navState, params);
229
+ // Re-wrap the CURRENT element with new context values.
230
+ // SegmentOutlets read updates from SegmentUpdateContext;
231
+ // NavigationProvider gets the new pathname; the params published
232
+ // above the retained tree are the *incoming* route's.
233
+ const element = wrapPayload(
234
+ deps._getCurrentPayload?.() ?? payload,
235
+ result.navState,
236
+ params,
237
+ segmentUpdates
238
+ );
259
239
  handOff();
260
240
  return {
261
241
  element,
262
242
  decodePromise: observeSkew(result.decodePromise),
263
243
  commit: commitAndForget(result.commit),
264
244
  };
265
- },
266
- onCommit,
267
- onHandOff
268
- );
245
+ }
246
+
247
+ // Full navigation — empty updates, render the new tree.
248
+ const element = wrapPayload(payload, result.navState, params);
249
+ handOff();
250
+ return {
251
+ element,
252
+ decodePromise: observeSkew(result.decodePromise),
253
+ commit: commitAndForget(result.commit),
254
+ };
255
+ });
269
256
  }
270
257
 
271
258
  /**
@@ -13,7 +13,7 @@ import type { NavigationState } from './navigation-context.ts';
13
13
  import type { ParamsSource } from '../shared/payload-root.ts';
14
14
  import type { SegmentInfo } from '../shared/segment-info.ts';
15
15
  import type { SegmentCache, PrefetchCache } from './segment-cache.ts';
16
- import type { TransitionResult, CommitOutcome, RenderOwner } from './navigation-transition.ts';
16
+ import type { TransitionResult, NavigationHandle, RenderOwner } from './navigation-transition.ts';
17
17
  import type { NavigationEpoch } from './router-lifecycle.ts';
18
18
 
19
19
  /**
@@ -50,8 +50,6 @@ export type TraverseDirection = Extract<
50
50
 
51
51
  /** Options for `RouterInstance.refresh`. */
52
52
  export interface RefreshOptions {
53
- /** See `NavigationOptions.onCommit`. */
54
- onCommit?: (outcome: CommitOutcome) => void;
55
53
  /**
56
54
  * Why the page is being re-fetched, as the view transition type the render
57
55
  * adds: `refresh` (the default) when the user asked, `revalidate` when a
@@ -80,24 +78,6 @@ export interface NavigationOptions {
80
78
  * follows a redirect, which keeps the types of the render it interrupted.
81
79
  */
82
80
  _renderTypes?: readonly string[];
83
- /**
84
- * Runs exactly once, when React commits this navigation's tree — or when
85
- * the navigation is abandoned (superseded or failed) and no such commit
86
- * will come. The returned promise resolves on decode, which can be before
87
- * OR after the commit; this is the hook for the other event. `<Link>`
88
- * holds `isPending` until both have happened (TIM-1418). The outcome says
89
- * which of the three it was.
90
- */
91
- onCommit?: (outcome: CommitOutcome) => void;
92
- /**
93
- * @internal Runs once, synchronously after this navigation's tree is handed
94
- * to React (its transition scheduled) and before React can commit it. Not
95
- * at all if the navigation is superseded or fails first; the returned
96
- * promise settles then. A server action that redirects settles its
97
- * `useActionState` here, so React commits the action's result and the
98
- * destination together (TIM-1573).
99
- */
100
- onHandOff?: () => void;
101
81
  }
102
82
 
103
83
  /**
@@ -162,12 +142,8 @@ export interface RouterDeps {
162
142
  params: ParamsSource,
163
143
  segmentUpdates?: Map<string, unknown>
164
144
  ) => unknown
165
- ) => Promise<TransitionResult<unknown>>,
166
- /** See `NavigationOptions.onCommit`; forwarded to `navigateTransition`. */
167
- onCommit?: (outcome: CommitOutcome) => void,
168
- /** See `NavigationOptions.onHandOff`; forwarded to `navigateTransition`. */
169
- onHandOff?: () => void
170
- ) => Promise<void>;
145
+ ) => Promise<TransitionResult<unknown>>
146
+ ) => NavigationHandle;
171
147
 
172
148
  /**
173
149
  * Save scroll position via the Navigation API's per-entry state.
@@ -204,10 +180,14 @@ export interface RouterDeps {
204
180
  }
205
181
 
206
182
  export interface RouterInstance {
207
- /** Navigate to a new URL (forward navigation) */
208
- navigate(url: string, options?: NavigationOptions): Promise<void>;
209
- /** Full re-render of the current URL — no state tree sent */
210
- refresh(options?: RefreshOptions): Promise<void>;
183
+ /**
184
+ * Navigate to a new URL (forward navigation). Awaiting the handle waits for
185
+ * the payload to decode; its `committed` and `handedOff` are the other two
186
+ * endings (`NavigationHandle`).
187
+ */
188
+ navigate(url: string, options?: NavigationOptions): NavigationHandle;
189
+ /** Full re-render of the current URL — no state tree sent. See `navigate`. */
190
+ refresh(options?: RefreshOptions): NavigationHandle;
211
191
  /**
212
192
  * Handle a traversal (back/forward button). scrollY is read from the
213
193
  * destination entry's state. `direction` is the transition type the