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

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 (152) hide show
  1. package/dist/_chunks/{actions-BwkmAYXq.js → actions-BDqn4Oxj.js} +2 -2
  2. package/dist/_chunks/{actions-BwkmAYXq.js.map → actions-BDqn4Oxj.js.map} +1 -1
  3. package/dist/_chunks/{cache-api-LA3sBpUS.js → cache-api-GE4AOe2H.js} +30 -151
  4. package/dist/_chunks/cache-api-GE4AOe2H.js.map +1 -0
  5. package/dist/_chunks/dev-server-BiWNMBVU.js +1 -0
  6. package/dist/_chunks/{dev-server-DnODXuNM.js → dev-server-DIy-SY-J.js} +11 -6
  7. package/dist/_chunks/{dev-server-DnODXuNM.js.map → dev-server-DIy-SY-J.js.map} +1 -1
  8. package/dist/_chunks/dev-store-BOa304m_.js +283 -0
  9. package/dist/_chunks/dev-store-BOa304m_.js.map +1 -0
  10. package/dist/_chunks/{error-boundary-xxxLtXt6.js → error-boundary-Bc8QPZuq.js} +71 -21
  11. package/dist/_chunks/error-boundary-Bc8QPZuq.js.map +1 -0
  12. package/dist/_chunks/{flight-source-node-0dE-t3kq.js → flight-source-node-HptmGMT8.js} +6 -7
  13. package/dist/_chunks/flight-source-node-HptmGMT8.js.map +1 -0
  14. package/dist/_chunks/{node-response-Dibufw_b.js → node-response-rkQqcFGq.js} +48 -2
  15. package/dist/_chunks/node-response-rkQqcFGq.js.map +1 -0
  16. package/dist/_chunks/{purge-store-Byr8XOjU.js → purge-store-WZaxu-3m.js} +2 -2
  17. package/dist/_chunks/purge-store-WZaxu-3m.js.map +1 -0
  18. package/dist/_chunks/{render-timeout-DOf_BBcO.js → render-timeout-joFhz4KH.js} +1 -10
  19. package/dist/_chunks/render-timeout-joFhz4KH.js.map +1 -0
  20. package/dist/cache/cache-api.d.ts.map +1 -1
  21. package/dist/cache/handler-store.d.ts +13 -1
  22. package/dist/cache/handler-store.d.ts.map +1 -1
  23. package/dist/cache/index.js +2 -1
  24. package/dist/cache/invalidation-epoch.d.ts +7 -0
  25. package/dist/cache/invalidation-epoch.d.ts.map +1 -1
  26. package/dist/cache/timber-cache.d.ts.map +1 -1
  27. package/dist/cdn/index.js +1 -1
  28. package/dist/cdn/purge-store.d.ts +10 -1
  29. package/dist/cdn/purge-store.d.ts.map +1 -1
  30. package/dist/cli.js +1 -1
  31. package/dist/client/browser-entry/router-init.d.ts.map +1 -1
  32. package/dist/client/error-boundary.js +1 -1
  33. package/dist/client/index.js +6 -15
  34. package/dist/client/index.js.map +1 -1
  35. package/dist/client/internal.js +37 -64
  36. package/dist/client/internal.js.map +1 -1
  37. package/dist/client/link.d.ts.map +1 -1
  38. package/dist/client/navigation-transition.d.ts +68 -14
  39. package/dist/client/navigation-transition.d.ts.map +1 -1
  40. package/dist/client/router-effects.d.ts +35 -31
  41. package/dist/client/router-effects.d.ts.map +1 -1
  42. package/dist/client/router-pipeline.d.ts +2 -6
  43. package/dist/client/router-pipeline.d.ts.map +1 -1
  44. package/dist/client/router-types.d.ts +10 -30
  45. package/dist/client/router-types.d.ts.map +1 -1
  46. package/dist/client/router.d.ts.map +1 -1
  47. package/dist/dev-tools/logs.d.ts +2 -2
  48. package/dist/dev-tools/logs.d.ts.map +1 -1
  49. package/dist/index.js +144 -51
  50. package/dist/index.js.map +1 -1
  51. package/dist/plugins/dev-server.d.ts.map +1 -1
  52. package/dist/plugins/entries.d.ts +5 -0
  53. package/dist/plugins/entries.d.ts.map +1 -1
  54. package/dist/plugins/orphaned-modules.d.ts +57 -0
  55. package/dist/plugins/orphaned-modules.d.ts.map +1 -0
  56. package/dist/plugins/prebuilt.d.ts +6 -6
  57. package/dist/plugins/prerender-sugar.d.ts.map +1 -1
  58. package/dist/plugins/routing.d.ts +1 -1
  59. package/dist/plugins/routing.d.ts.map +1 -1
  60. package/dist/rsc-runtime/dev-reference-cache.d.ts +47 -0
  61. package/dist/rsc-runtime/dev-reference-cache.d.ts.map +1 -0
  62. package/dist/rsc-runtime/rsc.d.ts +0 -15
  63. package/dist/rsc-runtime/rsc.d.ts.map +1 -1
  64. package/dist/rsc-runtime/ssr.d.ts +0 -11
  65. package/dist/rsc-runtime/ssr.d.ts.map +1 -1
  66. package/dist/server/abort-scope.d.ts +27 -0
  67. package/dist/server/abort-scope.d.ts.map +1 -0
  68. package/dist/server/flight-source-node.d.ts.map +1 -1
  69. package/dist/server/index.js +1 -1
  70. package/dist/server/instrumentation.d.ts +2 -1
  71. package/dist/server/instrumentation.d.ts.map +1 -1
  72. package/dist/server/internal.d.ts +1 -1
  73. package/dist/server/internal.d.ts.map +1 -1
  74. package/dist/server/internal.js +328 -132
  75. package/dist/server/internal.js.map +1 -1
  76. package/dist/server/pipeline-helpers.d.ts.map +1 -1
  77. package/dist/server/pipeline.d.ts +10 -7
  78. package/dist/server/pipeline.d.ts.map +1 -1
  79. package/dist/server/prebuilt/cache-key.d.ts +26 -0
  80. package/dist/server/prebuilt/cache-key.d.ts.map +1 -1
  81. package/dist/server/prebuilt/capture-render.d.ts +9 -4
  82. package/dist/server/prebuilt/capture-render.d.ts.map +1 -1
  83. package/dist/server/prebuilt/capture-routes.d.ts +1 -1
  84. package/dist/server/prebuilt/dev-store.d.ts +103 -0
  85. package/dist/server/prebuilt/dev-store.d.ts.map +1 -0
  86. package/dist/server/prebuilt/overlay.d.ts +5 -0
  87. package/dist/server/prebuilt/overlay.d.ts.map +1 -1
  88. package/dist/server/prebuilt/payload-source.d.ts +8 -0
  89. package/dist/server/prebuilt/payload-source.d.ts.map +1 -1
  90. package/dist/server/prebuilt/slots.d.ts +5 -6
  91. package/dist/server/prebuilt/slots.d.ts.map +1 -1
  92. package/dist/server/prebuilt-builder.d.ts.map +1 -1
  93. package/dist/server/prebuilt-runtime.d.ts +5 -10
  94. package/dist/server/prebuilt-runtime.d.ts.map +1 -1
  95. package/dist/server/render-timeout.d.ts.map +1 -1
  96. package/dist/server/rsc-entry/action-dispatcher.d.ts.map +1 -1
  97. package/dist/server/rsc-entry/index.d.ts.map +1 -1
  98. package/dist/server/ssr-render.d.ts.map +1 -1
  99. package/docs/api/32-api-cache.mdx +2 -0
  100. package/docs/learn/10-caching.mdx +12 -0
  101. package/docs/learn/11-middleware.mdx +2 -0
  102. package/package.json +1 -1
  103. package/src/cache/cache-api.ts +7 -1
  104. package/src/cache/handler-store.ts +38 -1
  105. package/src/cache/invalidation-epoch.ts +18 -6
  106. package/src/cache/timber-cache.ts +6 -2
  107. package/src/cdn/purge-store.ts +29 -1
  108. package/src/client/browser-entry/action-dispatch.ts +5 -5
  109. package/src/client/browser-entry/router-init.ts +2 -4
  110. package/src/client/link.tsx +14 -18
  111. package/src/client/navigation-transition.ts +86 -33
  112. package/src/client/router-effects.ts +70 -45
  113. package/src/client/router-lifecycle.ts +1 -1
  114. package/src/client/router-pipeline.ts +52 -65
  115. package/src/client/router-types.ts +11 -31
  116. package/src/client/router.ts +98 -104
  117. package/src/dev-tools/logs.ts +76 -50
  118. package/src/plugins/dev-server.ts +23 -8
  119. package/src/plugins/entries.ts +6 -0
  120. package/src/plugins/orphaned-modules.ts +78 -0
  121. package/src/plugins/prebuilt.ts +17 -17
  122. package/src/plugins/prerender-sugar.ts +38 -6
  123. package/src/plugins/routing.ts +23 -1
  124. package/src/rsc-runtime/dev-reference-cache.ts +115 -0
  125. package/src/rsc-runtime/rsc.ts +10 -0
  126. package/src/rsc-runtime/ssr.ts +10 -0
  127. package/src/server/abort-scope.ts +49 -0
  128. package/src/server/flight-source-node.ts +5 -4
  129. package/src/server/instrumentation.ts +32 -8
  130. package/src/server/internal.ts +1 -6
  131. package/src/server/pipeline-helpers.ts +5 -3
  132. package/src/server/pipeline.ts +31 -20
  133. package/src/server/prebuilt/cache-key.ts +41 -0
  134. package/src/server/prebuilt/capture-render.ts +10 -6
  135. package/src/server/prebuilt/capture-routes.ts +1 -1
  136. package/src/server/prebuilt/dev-store.ts +173 -0
  137. package/src/server/prebuilt/overlay.ts +7 -1
  138. package/src/server/prebuilt/payload-source.ts +19 -0
  139. package/src/server/prebuilt/slots.ts +5 -6
  140. package/src/server/prebuilt-builder.ts +3 -2
  141. package/src/server/prebuilt-runtime.ts +174 -176
  142. package/src/server/render-timeout.ts +12 -17
  143. package/src/server/rsc-entry/action-dispatcher.ts +3 -1
  144. package/src/server/rsc-entry/index.ts +47 -13
  145. package/src/server/ssr-render.ts +9 -11
  146. package/dist/_chunks/cache-api-LA3sBpUS.js.map +0 -1
  147. package/dist/_chunks/dev-server-DkytOEG2.js +0 -1
  148. package/dist/_chunks/error-boundary-xxxLtXt6.js.map +0 -1
  149. package/dist/_chunks/flight-source-node-0dE-t3kq.js.map +0 -1
  150. package/dist/_chunks/node-response-Dibufw_b.js.map +0 -1
  151. package/dist/_chunks/purge-store-Byr8XOjU.js.map +0 -1
  152. package/dist/_chunks/render-timeout-DOf_BBcO.js.map +0 -1
@@ -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
@@ -22,7 +22,8 @@ import {
22
22
  createScrollEffects,
23
23
  createSpaExits,
24
24
  createNavigationRecovery,
25
- holdCommit,
25
+ runAsHandle,
26
+ type NavigationEndings,
26
27
  } from './router-effects.ts';
27
28
  import { createNavigationLifecycle } from './router-lifecycle.ts';
28
29
  import { createNavigationPipeline, prefetchKeyFor } from './router-pipeline.ts';
@@ -35,7 +36,7 @@ import type {
35
36
  RouterInstance,
36
37
  TraverseDirection,
37
38
  } from './router-types.ts';
38
- import { createRenderOwner, type CommitOutcome } from './navigation-transition.ts';
39
+ import { createRenderOwner, type NavigationHandle } from './navigation-transition.ts';
39
40
 
40
41
  // ─── Router Factory ──────────────────────────────────────────────
41
42
 
@@ -107,11 +108,19 @@ export function createRouter(deps: RouterDeps): RouterInstance {
107
108
  currentOwner,
108
109
  leaveSpaIfOwned,
109
110
  // Hoisted — `navigate` is a function declaration below.
110
- navigate: (url, { types, replace, scroll, onCommit, onHandOff }) =>
111
- navigate(url, { replace, scroll, _renderTypes: types, onCommit, onHandOff }),
111
+ navigate: (url, { types, replace, scroll }) =>
112
+ navigate(url, { replace, scroll, _renderTypes: types }),
112
113
  });
113
114
 
114
- async function navigate(url: string, options: NavigationOptions = {}): Promise<void> {
115
+ function navigate(url: string, options: NavigationOptions = {}): NavigationHandle {
116
+ return runAsHandle((endings) => navigateWith(url, options, endings));
117
+ }
118
+
119
+ async function navigateWith(
120
+ url: string,
121
+ options: NavigationOptions,
122
+ endings: NavigationEndings
123
+ ): Promise<void> {
115
124
  const scroll = options.scroll !== false;
116
125
  const replace = options.replace === true;
117
126
  // A push, a replace, and a server action redirect all move the user
@@ -157,25 +166,18 @@ export function createRouter(deps: RouterDeps): RouterInstance {
157
166
  await leaveSpaSuperseding(url, departingUrl);
158
167
  }
159
168
 
160
- // A redirect this navigation follows inherits its onCommit (RedirectHop).
161
- const heldCommit = holdCommit(options.onCommit);
162
-
163
169
  await runNavigation(url, async (owner) => {
164
170
  try {
165
- await renderViaTransition(
166
- fetchUrl,
167
- owner,
168
- types,
169
- () =>
170
- performNavigationFetch(fetchUrl, {
171
- replace,
172
- commitUrl: url,
173
- signal: owner.fetchAbort.signal,
174
- departingUrl,
175
- }),
176
- heldCommit.transition,
177
- options.onHandOff
171
+ const render = renderViaTransition(fetchUrl, owner, types, () =>
172
+ performNavigationFetch(fetchUrl, {
173
+ replace,
174
+ commitUrl: url,
175
+ signal: owner.fetchAbort.signal,
176
+ departingUrl,
177
+ })
178
178
  );
179
+ endings.track(render);
180
+ await render;
179
181
 
180
182
  // Scroll-to-top on forward navigation, scroll to the #fragment target
181
183
  // when the URL has one, or restore captured position for scroll={false}.
@@ -191,13 +193,14 @@ export function createRouter(deps: RouterDeps): RouterInstance {
191
193
  // instead would rebuild the page they were *leaving* and discard
192
194
  // the click (TIM-1275).
193
195
  if (
194
- await recoverFromNavigationError(error, owner, url, departingUrl, {
195
- types,
196
- replace,
197
- scroll,
198
- onCommit: heldCommit.settle,
199
- onHandOff: options.onHandOff,
200
- })
196
+ await recoverFromNavigationError(
197
+ error,
198
+ owner,
199
+ url,
200
+ departingUrl,
201
+ { types, replace, scroll },
202
+ endings
203
+ )
201
204
  ) {
202
205
  return;
203
206
  }
@@ -219,44 +222,38 @@ export function createRouter(deps: RouterDeps): RouterInstance {
219
222
  url: string,
220
223
  /** The view transition type the render adds. */
221
224
  type: NavigationTransitionType,
225
+ endings: NavigationEndings,
222
226
  opts: {
223
227
  /** Omitted by refresh(): the server renders the complete payload. */
224
228
  stateTree?: { segments: string[] };
225
229
  /** Restored after paint when present — traversals only. */
226
230
  scrollY?: number;
227
231
  externalSignal?: AbortSignal;
228
- /** Fires once when React commits, or when the navigation is abandoned. */
229
- onCommit?: (outcome: CommitOutcome) => void;
230
232
  } = {}
231
233
  ): Promise<void> {
232
- const heldCommit = holdCommit(opts.onCommit);
233
234
  await runNavigation(
234
235
  url,
235
236
  async (owner) => {
236
237
  try {
237
- await renderViaTransition(
238
- url,
239
- owner,
240
- [type],
241
- async () => {
242
- const result = await fetchRscPayload(
243
- url,
244
- deps,
245
- opts.stateTree,
246
- undefined,
247
- owner.fetchAbort.signal
248
- );
249
- const params = await result.params;
250
- const { navState, commit } = prepareNavigation(url, {
251
- payload: result.payload,
252
- params,
253
- segmentInfo: result.segmentInfo,
254
- skippedSegments: result.skippedSegments,
255
- });
256
- return { ...result, params, navState, commit };
257
- },
258
- heldCommit.transition
259
- );
238
+ const render = renderViaTransition(url, owner, [type], async () => {
239
+ const result = await fetchRscPayload(
240
+ url,
241
+ deps,
242
+ opts.stateTree,
243
+ undefined,
244
+ owner.fetchAbort.signal
245
+ );
246
+ const params = await result.params;
247
+ const { navState, commit } = prepareNavigation(url, {
248
+ payload: result.payload,
249
+ params,
250
+ segmentInfo: result.segmentInfo,
251
+ skippedSegments: result.skippedSegments,
252
+ });
253
+ return { ...result, params, navState, commit };
254
+ });
255
+ endings.track(render);
256
+ await render;
260
257
  } catch (error) {
261
258
  // Neither path is a navigate(), and neither has a caller that
262
259
  // handles a rejection — `refresh()` is `void`-called everywhere it
@@ -270,12 +267,14 @@ export function createRouter(deps: RouterDeps): RouterInstance {
270
267
  // where it already is. So `hardNavigate()` takes its same-document
271
268
  // branch and reloads rather than pushing an entry.
272
269
  if (
273
- await recoverFromNavigationError(error, owner, url, url, {
274
- types: [type],
275
- replace: true,
276
- scroll: true,
277
- onCommit: heldCommit.settle,
278
- })
270
+ await recoverFromNavigationError(
271
+ error,
272
+ owner,
273
+ url,
274
+ url,
275
+ { types: [type], replace: true, scroll: true },
276
+ endings
277
+ )
279
278
  )
280
279
  return;
281
280
  throw error;
@@ -287,7 +286,11 @@ export function createRouter(deps: RouterDeps): RouterInstance {
287
286
  );
288
287
  }
289
288
 
290
- async function refresh(options: RefreshOptions = {}): Promise<void> {
289
+ function refresh(options: RefreshOptions = {}): NavigationHandle {
290
+ return runAsHandle((endings) => refreshWith(options, endings));
291
+ }
292
+
293
+ async function refreshWith(options: RefreshOptions, endings: NavigationEndings): Promise<void> {
291
294
  const currentUrl = deps.getCurrentUrl();
292
295
 
293
296
  // A refresh on a stale client is a full document load of the current URL.
@@ -298,9 +301,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
298
301
  await leaveSpaSuperseding(currentUrl, currentUrl);
299
302
  }
300
303
 
301
- await fetchCommitAndRender(currentUrl, options.transitionType ?? 'refresh', {
302
- onCommit: options.onCommit,
303
- });
304
+ await fetchCommitAndRender(currentUrl, options.transitionType ?? 'refresh', endings);
304
305
  }
305
306
 
306
307
  async function handlePopState(
@@ -380,11 +381,13 @@ export function createRouter(deps: RouterDeps): RouterInstance {
380
381
  // This happens when navigating back to the initial SSR'd page
381
382
  // (its payload is null since it was rendered via SSR, not RSC fetch)
382
383
  // or when the entry doesn't exist at all.
383
- await fetchCommitAndRender(url, direction, {
384
- stateTree: currentStateTree(),
385
- scrollY,
386
- externalSignal,
387
- });
384
+ await runAsHandle((endings) =>
385
+ fetchCommitAndRender(url, direction, endings, {
386
+ stateTree: currentStateTree(),
387
+ scrollY,
388
+ externalSignal,
389
+ })
390
+ );
388
391
  }
389
392
  }
390
393
 
@@ -472,13 +475,9 @@ export function createRouter(deps: RouterDeps): RouterInstance {
472
475
  // distinguishes a committed refresh from one superseded by a
473
476
  // navigation the user started while the refresh was in flight
474
477
  // (TIM-1477).
475
- let outcomeResolve!: (o: CommitOutcome) => void;
476
- const outcomePromise = new Promise<CommitOutcome>((r) => (outcomeResolve = r));
477
- const [, outcome] = await Promise.all([
478
- refresh({ transitionType: 'revalidate', onCommit: outcomeResolve }).catch(() => {}),
479
- outcomePromise,
480
- ]);
481
- return outcome === 'committed';
478
+ const refreshed = refresh({ transitionType: 'revalidate' });
479
+ await refreshed.catch(() => {});
480
+ return (await refreshed.committed) === 'committed';
482
481
  }
483
482
  // Render the piggybacked payload from a server action response.
484
483
  // Routed through renderViaTransition so the piggybacked tree gets
@@ -494,40 +493,35 @@ export function createRouter(deps: RouterDeps): RouterInstance {
494
493
  // `window.location`'s (TIM-1541).
495
494
  const segmentInfo = committedSegmentInfo();
496
495
 
497
- let outcomeResolve!: (o: CommitOutcome) => void;
498
- const outcomePromise = new Promise<CommitOutcome>((r) => (outcomeResolve = r));
499
496
  // Place in the lifecycle's slot so a concurrent navigation supersedes
500
497
  // this owner. The epoch check above ensures the slot is idle. Don't use
501
498
  // createNavOwner — that bumps navigationSeq, which is reserved for
502
499
  // navigations (the epoch test pins this: TIM-1474).
503
500
  const owner = createRenderOwner('revalidation');
504
501
  lifecycle.placeRevalidationOwner(owner);
505
- const [, outcome] = await Promise.all([
506
- renderViaTransition(
507
- currentUrl,
508
- owner,
509
- ['revalidate' satisfies NavigationTransitionType],
510
- async () => {
511
- const { navState, commit } = prepareNavigation(currentUrl, {
512
- payload: payloadTree,
513
- params,
514
- segmentInfo,
515
- });
516
- return {
517
- payload: payloadTree,
518
- params,
519
- navState,
520
- commit,
521
- decodePromise: null,
522
- segmentInfo,
523
- skippedSegments: null,
524
- };
525
- },
526
- outcomeResolve
527
- ).catch(() => {}),
528
- outcomePromise,
529
- ]);
530
- return outcome === 'committed';
502
+ const render = renderViaTransition(
503
+ currentUrl,
504
+ owner,
505
+ ['revalidate' satisfies NavigationTransitionType],
506
+ async () => {
507
+ const { navState, commit } = prepareNavigation(currentUrl, {
508
+ payload: payloadTree,
509
+ params,
510
+ segmentInfo,
511
+ });
512
+ return {
513
+ payload: payloadTree,
514
+ params,
515
+ navState,
516
+ commit,
517
+ decodePromise: null,
518
+ segmentInfo,
519
+ skippedSegments: null,
520
+ };
521
+ }
522
+ );
523
+ await render.catch(() => {});
524
+ return (await render.committed) === 'committed';
531
525
  },
532
526
  runWhenIdle: (task: () => void) => lifecycle.runWhenIdle(task),
533
527
  onIdle: (listener) => lifecycle.onIdle(listener),