@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
@@ -0,0 +1,44 @@
1
+ /**
2
+ * Cache reads never fail a request.
3
+ *
4
+ * A cache is an optimization: when the store is down, slow, or returns
5
+ * garbage, the request must still succeed by doing the work the cache would
6
+ * have skipped. Writes already follow this rule (timber-cache.ts swallows a
7
+ * failed handler.set, TIM-1046); reads go through here so a throwing or hung
8
+ * handler.get costs a live fetch or render, never a failed or stalled request.
9
+ *
10
+ * The timeout matters as much as the catch. Shared-store clients often queue
11
+ * commands while disconnected (ioredis retries each one up to 20 times by
12
+ * default), so an outage shows up as a read that never settles, not an error.
13
+ *
14
+ * Invalidation is deliberately NOT guarded: a failed invalidate that looked
15
+ * like success would leave stale data in place silently.
16
+ *
17
+ * See design/06-caching.md §"Store failures".
18
+ */
19
+
20
+ import { logCacheReadFailed } from '../server/logger.ts';
21
+ import { withTimeout } from '../server/render-timeout.ts';
22
+
23
+ /** Ceiling for a single cache read. A healthy store answers in milliseconds. */
24
+ export const CACHE_READ_TIMEOUT_MS = 1_000;
25
+
26
+ /**
27
+ * Run a cache read. A throw, a rejection, or no answer within
28
+ * CACHE_READ_TIMEOUT_MS logs a warning and resolves to `onFailure`, which the
29
+ * caller picks: `null` where a failed read means "miss", a distinct value
30
+ * where a miss would fall back to something the failed read might have
31
+ * overridden (an invalidated build seed — server/prebuilt/overlay.ts).
32
+ */
33
+ export async function guardedRead<T, F>(
34
+ cacheKey: string,
35
+ read: () => Promise<T>,
36
+ onFailure: F
37
+ ): Promise<T | F> {
38
+ try {
39
+ return await withTimeout(read(), CACHE_READ_TIMEOUT_MS, `cache read for "${cacheKey}"`);
40
+ } catch (error) {
41
+ logCacheReadFailed({ cacheKey, error });
42
+ return onFailure;
43
+ }
44
+ }
@@ -18,10 +18,47 @@ let handler: CacheHandlerLike | null = null;
18
18
 
19
19
  let explicitlyConfigured = false;
20
20
 
21
- /** Replace the active cache handler. Called by the framework at boot. */
21
+ /** Whether `handler` came from timber.cache.ts (applyConfiguredCacheHandler). */
22
+ let fromCacheConfig = false;
23
+
24
+ /** The handler last installed by a direct setCacheHandler() call, if any. */
25
+ let directHandler: CacheHandlerLike | null = null;
26
+
27
+ /** Replace the active cache handler. */
22
28
  export function setCacheHandler(h: CacheHandlerLike): void {
23
29
  handler = h;
24
30
  explicitlyConfigured = true;
31
+ fromCacheConfig = false;
32
+ directHandler = h;
33
+ }
34
+
35
+ /**
36
+ * Apply the handler timber.cache.ts exports, or `null` when it exports none.
37
+ * Called on every run of the RSC entry. In dev the entry re-runs after an
38
+ * edit while this module keeps its state (design/21 §HMR Wiring), so a
39
+ * handler removed from timber.cache.ts must be dropped here, not kept
40
+ * serving. A handler installed by a direct setCacheHandler() call (from
41
+ * register(), say) is left in place when the file exports none, and comes
42
+ * back when a configured handler that replaced it is removed.
43
+ */
44
+ export function applyConfiguredCacheHandler(h: CacheHandlerLike | null): void {
45
+ if (h) {
46
+ handler = h;
47
+ explicitlyConfigured = true;
48
+ fromCacheConfig = true;
49
+ } else if (fromCacheConfig) {
50
+ handler = directHandler;
51
+ explicitlyConfigured = directHandler !== null;
52
+ fromCacheConfig = false;
53
+ }
54
+ }
55
+
56
+ /** @internal — reset for tests only. */
57
+ export function _resetCacheHandler(): void {
58
+ handler = null;
59
+ explicitlyConfigured = false;
60
+ fromCacheConfig = false;
61
+ directHandler = null;
25
62
  }
26
63
 
27
64
  /** Whether the handler was explicitly configured (vs the default in-memory fallback). */
@@ -34,11 +34,12 @@ const lastInvalidated = new Map<string, number>();
34
34
  const MAX_TRACKED_ENTRIES = 10_000;
35
35
 
36
36
  /**
37
- * Highest epoch evicted from the map. Any execution that started at or
38
- * before this epoch conservatively counts as invalidated — history was
39
- * truncated, so we can no longer prove it wasn't.
37
+ * Every execution that started at or before this epoch counts as
38
+ * invalidated. Raised by eviction (history was truncated, so we can no
39
+ * longer prove an execution wasn't invalidated) and by
40
+ * `recordInvalidationOfAll()`.
40
41
  */
41
- let evictedEpochFloor = 0;
42
+ let invalidatedEpochFloor = 0;
42
43
 
43
44
  /** The current epoch. Capture before running fn(), pass to wasInvalidatedSince. */
44
45
  export function currentInvalidationEpoch(): number {
@@ -55,13 +56,24 @@ export function recordInvalidation(opts: { key?: string; tag?: string }): void {
55
56
  if (opts.tag) track(`tag:${opts.tag}`);
56
57
  }
57
58
 
59
+ /**
60
+ * Record an invalidation of every key and tag at once. The dev server
61
+ * calls this on a source change (server/prebuilt/dev-store.ts): any cached
62
+ * render in flight may have loaded the pre-change code, so none of them may
63
+ * store, and a caller arriving after the change must not join their flight.
64
+ */
65
+ export function recordInvalidationOfAll(): void {
66
+ epoch++;
67
+ invalidatedEpochFloor = epoch;
68
+ }
69
+
58
70
  function track(entry: string): void {
59
71
  lastInvalidated.delete(entry);
60
72
  lastInvalidated.set(entry, epoch);
61
73
  while (lastInvalidated.size > MAX_TRACKED_ENTRIES) {
62
74
  const oldest = lastInvalidated.entries().next().value;
63
75
  if (oldest === undefined) break;
64
- evictedEpochFloor = Math.max(evictedEpochFloor, oldest[1]);
76
+ invalidatedEpochFloor = Math.max(invalidatedEpochFloor, oldest[1]);
65
77
  lastInvalidated.delete(oldest[0]);
66
78
  }
67
79
  }
@@ -82,7 +94,7 @@ export function wasInvalidatedSince(startEpoch: number, key: string, tags: strin
82
94
  * issued to discard.
83
95
  */
84
96
  export function lastInvalidationEpochFor(key: string, tags: string[]): number {
85
- let last = evictedEpochFloor;
97
+ let last = invalidatedEpochFloor;
86
98
  const keyEpoch = lastInvalidated.get(`key:${key}`);
87
99
  if (keyEpoch !== undefined && keyEpoch > last) last = keyEpoch;
88
100
  for (const tag of tags) {
@@ -7,9 +7,11 @@ import {
7
7
  wasInvalidatedSince,
8
8
  } from './invalidation-epoch.ts';
9
9
  import { addSpanEventSync } from '../server/tracing.ts';
10
- import { logSwrRefetchFailed, swallow } from '../server/logger.ts';
10
+ import { logCacheMiss, logSwrRefetchFailed, swallow } from '../server/logger.ts';
11
+ import { guardedRead } from './guarded-read.ts';
11
12
  import { getWaitUntil } from '../server/waituntil-bridge.ts';
12
13
  import { fnv1aHash } from './fast-hash.ts';
14
+ import { devDataCacheKey } from '../server/prebuilt/dev-store.ts';
13
15
 
14
16
  let defaultSingleflight = createSingleflight();
15
17
 
@@ -152,8 +154,11 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
152
154
  const sf = perCallSf ?? defaultSingleflight;
153
155
  const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId as string, args);
154
156
 
157
+ // The key the handler sees: in dev, scoped to the source generation.
158
+ const storeKey = devDataCacheKey(key);
159
+
155
160
  const cacheStart = performance.now();
156
- const cached = await getHandler().get(key);
161
+ const cached = await guardedRead(key, () => getHandler().get(storeKey), null);
157
162
 
158
163
  if (cached && !cached.stale) {
159
164
  // Record as OTEL span event on enclosing span (not a child span).
@@ -190,7 +195,7 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
190
195
  const result = await fn(...args);
191
196
  if (!signal.aborted && !wasInvalidatedSince(startEpoch, key, tags)) {
192
197
  try {
193
- await getHandler().set(key, result, { ttl: opts.ttl, tags, generation });
198
+ await getHandler().set(storeKey, result, { ttl: opts.ttl, tags, generation });
194
199
  } catch (err) {
195
200
  // Cache-write failure must not fail the request (TIM-1046).
196
201
  // JSON-serializing handlers (Redis, KV) throw on BigInt; network
@@ -242,6 +247,7 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
242
247
  key,
243
248
  duration_ms: Math.round(performance.now() - cacheStart),
244
249
  });
250
+ logCacheMiss({ cacheKey: key });
245
251
 
246
252
  return result;
247
253
  }) as unknown as Fn;
@@ -18,9 +18,35 @@ export interface CdnPurgeHandler {
18
18
 
19
19
  let handler: CdnPurgeHandler | undefined;
20
20
 
21
- /** Install a CDN purge handler. Called by the framework at boot from timber.config.ts. */
21
+ /** Whether `handler` came from boot wiring (applyConfiguredCdnPurgeHandler). */
22
+ let fromBoot = false;
23
+
24
+ /** The handler last installed by a direct setCdnPurgeHandler() call, if any. */
25
+ let directHandler: CdnPurgeHandler | undefined;
26
+
27
+ /** Install a CDN purge handler. */
22
28
  export function setCdnPurgeHandler(h: CdnPurgeHandler): void {
23
29
  handler = h;
30
+ fromBoot = false;
31
+ directHandler = h;
32
+ }
33
+
34
+ /**
35
+ * Apply the purge handler boot resolves (timber.cache.ts's `cdnPurge`, or
36
+ * the Workers default), or `undefined` when there is none. Called on every
37
+ * run of the RSC entry; like applyConfiguredCacheHandler, it drops a handler
38
+ * a dev edit removed, and leaves one installed by a direct
39
+ * setCdnPurgeHandler() call in place (restoring it when a boot handler that
40
+ * replaced it is removed).
41
+ */
42
+ export function applyConfiguredCdnPurgeHandler(h: CdnPurgeHandler | undefined): void {
43
+ if (h) {
44
+ handler = h;
45
+ fromBoot = true;
46
+ } else if (fromBoot) {
47
+ handler = directHandler;
48
+ fromBoot = false;
49
+ }
24
50
  }
25
51
 
26
52
  /** Get the current CDN purge handler, if configured. */
@@ -31,4 +57,6 @@ export function getCdnPurgeHandler(): CdnPurgeHandler | undefined {
31
57
  /** @internal — reset for tests only. */
32
58
  export function _resetCdnPurgeHandler(): void {
33
59
  handler = undefined;
60
+ fromBoot = false;
61
+ directHandler = undefined;
34
62
  }
@@ -180,7 +180,7 @@ export function setupServerActions(): void {
180
180
  // the action, so settling commits both together: the form resets onto
181
181
  // the destination's defaults. The wait always ends: the navigation
182
182
  // hands off, or fails, or a navigation the user starts supersedes it
183
- // (its promise settles either way), or DEFAULT_HOLD_TIMEOUT_MS
183
+ // (`handedOff` resolves either way), or DEFAULT_HOLD_TIMEOUT_MS
184
184
  // passes. Every transition waits while an action is pending, so this
185
185
  // must not hang on a stalled fetch.
186
186
  //
@@ -206,9 +206,9 @@ export function setupServerActions(): void {
206
206
  // still suspended — can commit afterwards, and must not release
207
207
  // the latch: it is the departing page again (codex on #1211).
208
208
  const redirectSeq = r.epoch().seq + 1;
209
- let handOff!: () => void;
210
- const handedOff = new Promise<void>((resolve) => (handOff = resolve));
211
- r.navigate(wrapper._redirect, { onHandOff: handOff }).then(handOff, handOff);
209
+ const navigation = r.navigate(wrapper._redirect);
210
+ // The hand-off is awaited below, and resolves on failure too.
211
+ void navigation.catch(() => {});
212
212
  // Released once the departing page can no longer be on screen:
213
213
  // when any navigation's tree commits (a streamed destination
214
214
  // commits its shell before its stream finishes, and is live from
@@ -233,7 +233,7 @@ export function setupServerActions(): void {
233
233
  if (r.epoch().idle) arrive();
234
234
  let timer: ReturnType<typeof setTimeout> | undefined;
235
235
  await Promise.race([
236
- handedOff,
236
+ navigation.handedOff,
237
237
  new Promise<void>((resolve) => (timer = setTimeout(resolve, DEFAULT_HOLD_TIMEOUT_MS))),
238
238
  ]);
239
239
  clearTimeout(timer);
@@ -297,7 +297,7 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
297
297
  //
298
298
  // `_url` names the pending URL the router already published to its own
299
299
  // pending store before calling here; the transition has no use for it.
300
- navigateTransition: (_url: string, owner: RenderOwner, types, perform, onCommit, onHandOff) => {
300
+ navigateTransition: (_url: string, owner: RenderOwner, types, perform) => {
301
301
  return navigateTransition(
302
302
  owner,
303
303
  async () => {
@@ -333,9 +333,7 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
333
333
  };
334
334
  },
335
335
  render,
336
- types,
337
- onCommit,
338
- onHandOff
336
+ types
339
337
  );
340
338
  },
341
339
 
@@ -8,24 +8,52 @@
8
8
  * level would create separate instances per chunk. globalThis guarantees a
9
9
  * single instance regardless of duplication.
10
10
  *
11
+ * One context per React instance, not per process. Duplicated chunks share
12
+ * one React, so they share the context. A dev SSR program reload evaluates
13
+ * React and react-dom/server again, in the same process: the new renderer
14
+ * must get a context of its own. Handed the previous one, React logs
15
+ * "Detected multiple renderers concurrently rendering the same context
16
+ * provider" on every client-component edit, and the stale context keeps a
17
+ * piece of the discarded copy alive (TIM-1590).
18
+ *
11
19
  * See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
12
20
  */
13
21
 
14
- 'use client';
15
-
16
22
  import React from 'react';
17
23
 
18
- export function createGlobalContext<T>(key: string, defaultValue: T): React.Context<T> {
19
- const g = globalThis as Record<symbol, unknown>;
20
- const sym = Symbol.for(key);
21
- const existing = g[sym] as React.Context<T> | undefined;
22
- if (existing !== undefined) return existing;
23
- if (typeof React.createContext === 'function') {
24
- const ctx = React.createContext<T>(defaultValue);
25
- g[sym] = ctx;
26
- return ctx;
24
+ /** The part of a React instance a context comes from. */
25
+ export interface ContextFactory {
26
+ createContext?: typeof React.createContext;
27
+ }
28
+
29
+ /**
30
+ * The context `key` names for this React instance, created on first use.
31
+ * Pass the key as a `Symbol.for('…')` literal at the call site, so each key
32
+ * stays greppable in the build output (tests/bundle-singleton-audit.test.ts
33
+ * checks `__timber_nav_ctx`).
34
+ */
35
+ export function createGlobalContext<T>(key: symbol, defaultValue: T): React.Context<T> {
36
+ return createGlobalContextFor(React, key, defaultValue);
37
+ }
38
+
39
+ /** createGlobalContext for a given React instance. Exported for tests. */
40
+ export function createGlobalContextFor<T>(
41
+ react: ContextFactory,
42
+ key: symbol,
43
+ defaultValue: T
44
+ ): React.Context<T> {
45
+ if (typeof react.createContext !== 'function') {
46
+ // RSC environment — createContext not available. Return a dummy that
47
+ // won't be used (the consumers only render on the client / during SSR).
48
+ return undefined as unknown as React.Context<T>;
49
+ }
50
+ const slot: unknown = Reflect.get(globalThis, key);
51
+ const byReact = slot instanceof WeakMap ? slot : new WeakMap<object, React.Context<T>>();
52
+ if (byReact !== slot) Reflect.set(globalThis, key, byReact);
53
+ let ctx: React.Context<T> | undefined = byReact.get(react);
54
+ if (!ctx) {
55
+ ctx = react.createContext<T>(defaultValue);
56
+ byReact.set(react, ctx);
27
57
  }
28
- // RSC environment — createContext not available. Return a dummy that
29
- // won't be used (the consumers only render on the client / during SSR).
30
- return undefined as unknown as React.Context<T>;
58
+ return ctx;
31
59
  }
@@ -26,6 +26,7 @@ import {
26
26
  type ReactNode,
27
27
  type MouseEvent as ReactMouseEvent,
28
28
  } from 'react';
29
+ import { flushSync } from 'react-dom';
29
30
  import type { LinkFunction } from './index.ts';
30
31
  import { classifyUrlSegment, type UrlSegment } from '../routing/segment-classify.ts';
31
32
  import {
@@ -533,7 +534,7 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
533
534
  //
534
535
  // `isPending` runs from the click until BOTH `router.navigate()` has settled
535
536
  // (after `decodePromise` — the lifecycle the router's pending store and the
536
- // TopLoader use) AND the navigation's `onCommit` has fired. The second
537
+ // TopLoader use) AND the navigation's `committed` has settled. The second
537
538
  // condition is what keeps the flag honest: the promise resolves on decode,
538
539
  // and a destination with a pending Suspense boundary is still off screen
539
540
  // then. A clear scheduled at that point — urgent or in its own transition —
@@ -544,17 +545,17 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
544
545
  // click-time `root.render` never do. (Next.js gets the shared lane because
545
546
  // it hands React the tree in the click event; timber fetches first.) The
546
547
  // commit itself is the only signal that cannot beat the commit, and it is
547
- // the router's to give: `onCommit` fires exactly once, on the commit or
548
+ // the router's to give: `committed` settles exactly once, on the commit or
548
549
  // when the navigation is abandoned — superseded or failed — so the link
549
550
  // can never be left pending for a commit that will not come.
550
551
  //
551
552
  // Order is not fixed: a destination that does not suspend commits before
552
- // decode finishes (streaming reveal), so whichever of settle/commit comes
553
- // second clears.
553
+ // decode finishes (streaming reveal), so the clear waits on both — and
554
+ // renders synchronously, so it lands in the commit's frame (below).
554
555
  //
555
556
  // `clickSeq` guards the same-link double click: the first navigation is
556
557
  // superseded (its promise RESOLVES — `runNavigation` swallows AbortErrors —
557
- // and its `onCommit` fires) while the second is still in flight, and only
558
+ // and its `committed` settles) while the second is still in flight, and only
558
559
  // the newest click for this link may clear its flag. Written on click and
559
560
  // nowhere else, so there is no reset for a settle handler to race.
560
561
  const [isPending, setIsPending] = useState(false);
@@ -630,27 +631,22 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
630
631
  const absoluteHref = resolved.pathname + stripRscCacheKey(resolved.search) + resolved.hash;
631
632
 
632
633
  const seq = ++clickSeq.current;
633
- let settled = false;
634
- let committed = false;
634
+ // Rendered at once rather than scheduled. The clear runs from
635
+ // promise callbacks, outside any event, so a plain update would
636
+ // render in a later Scheduler task — and when the commit is the
637
+ // second ending, a frame could paint the destination beside a link
638
+ // still showing pending. The commit's own microtasks run before the
639
+ // browser can paint, so rendering here keeps the two in one frame.
635
640
  const clear = () => {
636
- if (clickSeq.current === seq) setIsPending(false);
637
- };
638
- const onCommit = () => {
639
- committed = true;
640
- if (settled) clear();
641
- };
642
- const settle = () => {
643
- settled = true;
644
- if (committed) clear();
641
+ if (clickSeq.current === seq) flushSync(() => setIsPending(false));
645
642
  };
646
643
  setIsPending(true);
647
644
  const navigation = router.navigate(absoluteHref, {
648
645
  scroll: shouldScroll,
649
646
  replace,
650
647
  transitionTypes,
651
- onCommit,
652
648
  });
653
- navigation.then(settle, (error: unknown) => {
649
+ Promise.all([navigation, navigation.committed]).then(clear, (error: unknown) => {
654
650
  clear();
655
651
  // Rethrow, so a navigation error that the router did not already
656
652
  // recover from surfaces as an unhandled rejection — the same
@@ -42,7 +42,8 @@
42
42
  * See design/19-client-navigation.md §"NavigationContext"
43
43
  */
44
44
 
45
- import { createContext, useContext, createElement, type ReactNode } from 'react';
45
+ import { useContext, createElement, type ReactNode } from 'react';
46
+ import { createGlobalContext } from './global-context.ts';
46
47
 
47
48
  // ---------------------------------------------------------------------------
48
49
  // Context type
@@ -80,19 +81,11 @@ export interface NavigationState {
80
81
  * The shims plugin resolves next/navigation to navigation-rsc.ts in RSC,
81
82
  * which has throwing stubs for the hooks (TIM-1420).
82
83
  *
83
- * See design/27-chunking-strategy.md §"Singleton Safety"
84
+ * See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
84
85
  */
85
86
 
86
- const NAV_CTX_KEY = Symbol.for('__timber_nav_ctx');
87
-
88
87
  function getOrCreateContext(): import('react').Context<NavigationState | null> {
89
- const existing = (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] as
90
- | import('react').Context<NavigationState | null>
91
- | undefined;
92
- if (existing !== undefined) return existing;
93
- const ctx = createContext<NavigationState | null>(null);
94
- (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] = ctx;
95
- return ctx;
88
+ return createGlobalContext<NavigationState | null>(Symbol.for('__timber_nav_ctx'), null);
96
89
  }
97
90
 
98
91
  /**
@@ -47,7 +47,7 @@
47
47
  *
48
48
  * Nothing here may reopen an action scope: no `startTransition` callback in
49
49
  * this path may return a thenable, and no caller may invoke this from inside
50
- * a React action scope — except one that settles that action at `onHandOff`,
50
+ * a React action scope — except one that settles that action at `handedOff`,
51
51
  * which commits the action and the tree together on purpose (a server action
52
52
  * redirect, TIM-1573). That is a rule about `startTransition`, not about
53
53
  * `perform` — `perform` is async by contract and is awaited OUTSIDE any
@@ -99,6 +99,62 @@ export interface TransitionResult<E = ReactNode> {
99
99
  /** What happened to this navigation's tree. */
100
100
  export type CommitOutcome = 'committed' | 'superseded' | 'failed';
101
101
 
102
+ /**
103
+ * A navigation as its caller sees it: three endings, which arrive in either
104
+ * order.
105
+ *
106
+ * The handle itself is the promise that settles when the payload has
107
+ * **decoded** — or the navigation was superseded or failed. Scroll
108
+ * restoration, the Navigation API deferred and the router's pending store
109
+ * are timed against it. It does not mean the destination is on screen: a
110
+ * destination that streams commits before its decode finishes, and one
111
+ * waiting on a Suspense boundary commits after.
112
+ *
113
+ * Built by attaching the other two endings to that promise, so awaiting a
114
+ * navigation keeps meaning what it always has, and a caller that wants more
115
+ * than one ending awaits them side by side instead of combining callbacks
116
+ * by hand (TIM-1462).
117
+ */
118
+ export interface NavigationHandle extends Promise<void> {
119
+ /**
120
+ * Resolves once the navigation's final tree — after any redirect the
121
+ * router follows — has been handed to React: its transition is scheduled,
122
+ * and React has not yet committed it. Never rejects.
123
+ *
124
+ * A navigation that ends without handing a tree over (superseded or
125
+ * failed first) resolves it as it settles, so `router.navigate()` and
126
+ * `refresh()` never leave it pending past the handle itself.
127
+ * `navigateTransition`'s own handle does not — a redirect the router
128
+ * follows hands its tree over later — so there it may never settle.
129
+ *
130
+ * A server action that redirects settles its `useActionState` here, so
131
+ * React commits the action's result and the destination together
132
+ * (TIM-1573).
133
+ */
134
+ readonly handedOff: Promise<void>;
135
+ /**
136
+ * Resolves exactly once, never rejects: `'committed'` when React commits
137
+ * this navigation's tree, or — so nothing waits on a commit that will
138
+ * never come — `'superseded'` or `'failed'` when it is abandoned:
139
+ * superseded by a newer navigation (before or after its tree was handed
140
+ * to React) or failed. A followed redirect is one logical navigation, so
141
+ * this is the redirect hop's outcome. `<Link>` holds `isPending` until
142
+ * both this and the decode have settled (TIM-1418).
143
+ *
144
+ * The one exception is a stale client, which leaves the SPA before it
145
+ * navigates at all: the document is being replaced, and nothing on the
146
+ * handle settles. A navigation that fails into a document load
147
+ * (a server error, a non-RSC response, a version skew) settles this
148
+ * `'failed'` before it leaves.
149
+ */
150
+ readonly committed: Promise<CommitOutcome>;
151
+ }
152
+
153
+ /** The outcome of a render that ended without committing. */
154
+ export function abandonedOutcome(owner: RenderOwner): CommitOutcome {
155
+ return owner.outcome === 'superseded' ? 'superseded' : 'failed';
156
+ }
157
+
102
158
  // ─── RenderOwner ────────────────────────────────────────────────
103
159
 
104
160
  /**
@@ -202,8 +258,9 @@ export function createRenderOwner(kind: 'navigation' | 'revalidation'): RenderOw
202
258
  * action scope that entangles the update and defers the commit until the
203
259
  * action settles (TIM-1306, TIM-1307).
204
260
  *
205
- * Returns a Promise that resolves when the async work completes — the payload
206
- * is fetched, decoded, and handed to React. It does **not** wait for React to
261
+ * Returns a `NavigationHandle` whose promise resolves when the async work
262
+ * completes — the payload is fetched, decoded, and handed to React. It does
263
+ * **not** wait for React to
207
264
  * commit the tree, so the state that publishes on that commit (address bar,
208
265
  * segment cache, history entry, pathname) may still be a beat behind when it
209
266
  * resolves. Anything that needs the destination to be current should listen
@@ -218,10 +275,10 @@ export function createRenderOwner(kind: 'navigation' | 'revalidation'): RenderOw
218
275
  * one's `perform()` was in flight — the stale tree is never handed to React
219
276
  * and its `commit` never runs (TIM-629, TIM-1301).
220
277
  *
221
- * `onCommit` is the caller's hook on the *commit*, which the returned promise
222
- * deliberately does not wait for. It runs exactly once: when React commits
223
- * this navigation's tree, or — so nothing waits on a commit that will never
224
- * come — when the navigation is abandoned instead: superseded by a newer
278
+ * The commit is the handle's `committed`, a separate promise that nothing is
279
+ * forced to await — so it can depend on React where the decode promise must
280
+ * not. It settles exactly once: when React commits this navigation's tree,
281
+ * or when the navigation is abandoned instead — superseded by a newer
225
282
  * transition (before or after its tree was handed to React) or failed. It is
226
283
  * how `<Link>` keeps `isPending` up until the destination is on screen
227
284
  * without scheduling anything against React's lanes (TIM-1418).
@@ -235,12 +292,13 @@ export function createRenderOwner(kind: 'navigation' | 'revalidation'): RenderOw
235
292
  * detected via `owner.outcome` (sync) and `owner.displaced` (async).
236
293
  * No module-level state; no globalThis singleton.
237
294
  *
238
- * `onHandOff` runs synchronously right after `render` has scheduled the
239
- * tree, before React can commit it. A caller inside a React action scope may
240
- * settle that action here (and only here): the render is already entangled
241
- * with the scope, so settling commits the action and this tree together,
242
- * where settling earlier commits the action alone and settling on the commit
243
- * deadlocks. The server action redirect is that caller (TIM-1573).
295
+ * `handedOff` resolves right after `render` has scheduled the tree — in a
296
+ * microtask, so before the Scheduler task that renders and commits it — and not
297
+ * at all when the navigation ends first. A caller inside a React action scope
298
+ * may settle that action there (and only there): the render is already
299
+ * entangled with the scope, so settling commits the action and this tree
300
+ * together, where settling earlier commits the action alone and settling on
301
+ * the commit deadlocks. The server action redirect is that caller (TIM-1573).
244
302
  *
245
303
  * Used for: navigate(), refresh(), popstate with fetch.
246
304
  */
@@ -248,29 +306,23 @@ export function navigateTransition(
248
306
  owner: RenderOwner,
249
307
  perform: () => Promise<TransitionResult>,
250
308
  render: NavigationRender,
251
- types: readonly string[],
252
- onCommit?: (outcome: CommitOutcome) => void,
253
- onHandOff?: () => void
254
- ): Promise<void> {
309
+ types: readonly string[]
310
+ ): NavigationHandle {
255
311
  const superseded = () => new DOMException('Navigation superseded', 'AbortError');
256
312
 
257
- // `onCommit`, exactly once, on whichever comes first: the commit, a
258
- // supersession, or a failure.
259
- let commitSettled = onCommit === undefined;
260
- const settleCommit = (outcome: CommitOutcome): void => {
261
- if (commitSettled) return;
262
- commitSettled = true;
263
- onCommit?.(outcome);
264
- };
313
+ let handOff!: () => void;
314
+ const handedOff = new Promise<void>((resolve) => (handOff = resolve));
315
+ // Exactly once, on whichever comes first — a promise settles only once:
316
+ // the commit, a supersession, or a failure.
317
+ let settleCommit!: (outcome: CommitOutcome) => void;
318
+ const committed = new Promise<CommitOutcome>((resolve) => (settleCommit = resolve));
265
319
 
266
320
  // Watch for displacement from outside (a successor taking the slot).
267
- if (!commitSettled) {
268
- void owner.displaced.then(() => {
269
- if (owner.outcome === 'superseded') settleCommit('superseded');
270
- });
271
- }
321
+ void owner.displaced.then(() => {
322
+ if (owner.outcome === 'superseded') settleCommit('superseded');
323
+ });
272
324
 
273
- return (async () => {
325
+ const decoded = (async () => {
274
326
  try {
275
327
  const { element, decodePromise, commit } = await perform();
276
328
  if (owner.outcome !== null) {
@@ -294,7 +346,7 @@ export function navigateTransition(
294
346
  },
295
347
  types
296
348
  );
297
- onHandOff?.();
349
+ handOff();
298
350
  // React may commit the tree before this settles — that is the point:
299
351
  // the destination reveals as React is able to render it
300
352
  // rather than waiting for the whole Flight stream. The await is here so
@@ -311,10 +363,11 @@ export function navigateTransition(
311
363
  throw superseded();
312
364
  }
313
365
  } catch (error) {
314
- settleCommit('failed');
366
+ settleCommit(abandonedOutcome(owner));
315
367
  throw error;
316
368
  }
317
369
  })();
370
+ return Object.assign(decoded, { handedOff, committed });
318
371
  }
319
372
 
320
373
  /**