@timber-js/app 0.2.0-alpha.240 → 0.2.0-alpha.241

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 (333) hide show
  1. package/dist/_chunks/{actions-DIgnvDrG.js → actions-BCYVyoFl.js} +117 -11
  2. package/dist/_chunks/actions-BCYVyoFl.js.map +1 -0
  3. package/dist/_chunks/{als-registry-PPYstxK0.js → als-registry-fabsRnPY.js} +4 -2
  4. package/dist/_chunks/{als-registry-PPYstxK0.js.map → als-registry-fabsRnPY.js.map} +1 -1
  5. package/dist/_chunks/{als-slots-kbQrHTzm.js → als-slots-CVTF-AMz.js} +3 -3
  6. package/dist/_chunks/als-slots-CVTF-AMz.js.map +1 -0
  7. package/dist/_chunks/{cache-api-uWQwuxWb.js → cache-api-n5FL4wFs.js} +5 -5
  8. package/dist/_chunks/{cache-api-uWQwuxWb.js.map → cache-api-n5FL4wFs.js.map} +1 -1
  9. package/dist/_chunks/chains-DPZAMMav.js +1 -0
  10. package/dist/_chunks/{chains-C7CExrUI.js → chains-IswOWMnq.js} +2 -2
  11. package/dist/_chunks/{chains-C7CExrUI.js.map → chains-IswOWMnq.js.map} +1 -1
  12. package/dist/_chunks/{classify-Cj9EeZoL.js → classify-B08RCF6s.js} +2 -2
  13. package/dist/_chunks/{classify-Cj9EeZoL.js.map → classify-B08RCF6s.js.map} +1 -1
  14. package/dist/_chunks/{cli-check-C3QOAru7.js → cli-check-tpFb6pBU.js} +7 -6
  15. package/dist/_chunks/cli-check-tpFb6pBU.js.map +1 -0
  16. package/dist/_chunks/{cli-schema-sync-BRxZz66D.js → cli-schema-sync-C0pXBtzG.js} +1 -1
  17. package/dist/_chunks/{cli-schema-sync-DQUS_o3V.js → cli-schema-sync-DRNJutey.js} +2 -2
  18. package/dist/_chunks/{cli-schema-sync-DQUS_o3V.js.map → cli-schema-sync-DRNJutey.js.map} +1 -1
  19. package/dist/_chunks/{client-dep-entries-ZETBdLgv.js → client-dep-entries-Dw5Dvatr.js} +2 -2
  20. package/dist/_chunks/{client-dep-entries-ZETBdLgv.js.map → client-dep-entries-Dw5Dvatr.js.map} +1 -1
  21. package/dist/_chunks/{cloudflare-Dk5Hqo-O.js → cloudflare-9dbhVOxS.js} +2 -2
  22. package/dist/_chunks/{cloudflare-Dk5Hqo-O.js.map → cloudflare-9dbhVOxS.js.map} +1 -1
  23. package/dist/_chunks/{convention-lint-BoVISNS6.js → convention-lint-BfC_dAhZ.js} +364 -10
  24. package/dist/_chunks/convention-lint-BfC_dAhZ.js.map +1 -0
  25. package/dist/_chunks/dev-server-3DNTXQV-.js +1 -0
  26. package/dist/_chunks/{dev-server-C5R6jx8Q.js → dev-server-3R6Bl9_R.js} +9 -2
  27. package/dist/_chunks/dev-server-3R6Bl9_R.js.map +1 -0
  28. package/dist/_chunks/{dist-C1Rjlo6s.js → dist-GyaJm4GA.js} +18 -2
  29. package/dist/_chunks/dist-GyaJm4GA.js.map +1 -0
  30. package/dist/_chunks/{error-boundary-DB51f9ih.js → error-boundary-Dfhxigko.js} +8 -4
  31. package/dist/_chunks/error-boundary-Dfhxigko.js.map +1 -0
  32. package/dist/_chunks/{flight-source-node-D9cHBhjP.js → flight-source-node-QOpWZATb.js} +2 -2
  33. package/dist/_chunks/{flight-source-node-D9cHBhjP.js.map → flight-source-node-QOpWZATb.js.map} +1 -1
  34. package/dist/_chunks/{json-lossy-check-Y1GxqVX_.js → json-lossy-check-5KFcC1yt.js} +2 -2
  35. package/dist/_chunks/{json-lossy-check-Y1GxqVX_.js.map → json-lossy-check-5KFcC1yt.js.map} +1 -1
  36. package/dist/_chunks/{live-graph-BDQWvnMm.js → live-graph-D1dfVqoT.js} +4 -4
  37. package/dist/_chunks/{live-graph-BDQWvnMm.js.map → live-graph-D1dfVqoT.js.map} +1 -1
  38. package/dist/_chunks/{logger-DmRR9tmZ.js → logger-BvGxPd1e.js} +2 -2
  39. package/dist/_chunks/{logger-DmRR9tmZ.js.map → logger-BvGxPd1e.js.map} +1 -1
  40. package/dist/_chunks/metadata-routes-MXNjWOt5.js.map +1 -1
  41. package/dist/_chunks/{node-response-yp8zdyRp.js → node-response-D5cfiyWP.js} +2 -2
  42. package/dist/_chunks/{node-response-yp8zdyRp.js.map → node-response-D5cfiyWP.js.map} +1 -1
  43. package/dist/_chunks/{poison-scan-WQgUydF_.js → poison-scan-CX02ilxN.js} +2 -2
  44. package/dist/_chunks/{poison-scan-WQgUydF_.js.map → poison-scan-CX02ilxN.js.map} +1 -1
  45. package/dist/_chunks/{rsc-cache-key-D0cb0Gmc.js → rsc-cache-key-BGvUtMtN.js} +40 -4
  46. package/dist/_chunks/{rsc-cache-key-D0cb0Gmc.js.map → rsc-cache-key-BGvUtMtN.js.map} +1 -1
  47. package/dist/_chunks/{scanner-C9Lrf77z.js → scanner-DneYxQoY.js} +14 -81
  48. package/dist/_chunks/scanner-DneYxQoY.js.map +1 -0
  49. package/dist/_chunks/{sizeof-BISkSaU0.js → sizeof-BtQ3ErLf.js} +2 -2
  50. package/dist/_chunks/{sizeof-BISkSaU0.js.map → sizeof-BtQ3ErLf.js.map} +1 -1
  51. package/dist/_chunks/{walkers-Bxv4v7tX.js → walkers-C9R2A4jN.js} +3 -3
  52. package/dist/_chunks/{walkers-Bxv4v7tX.js.map → walkers-C9R2A4jN.js.map} +1 -1
  53. package/dist/adapters/cloudflare-dev.js +1 -1
  54. package/dist/adapters/cloudflare-kv-cache.js +2 -2
  55. package/dist/adapters/cloudflare.js +1 -1
  56. package/dist/analyze/crawl-entry.js +3 -3
  57. package/dist/analyze/graph-command.js +2 -2
  58. package/dist/cache/index.js +2 -2
  59. package/dist/cache/stores/memory.js +1 -1
  60. package/dist/cdn/workers-cache-purge.js +1 -1
  61. package/dist/cli-check.d.ts +3 -0
  62. package/dist/cli-check.d.ts.map +1 -1
  63. package/dist/cli.js +3 -3
  64. package/dist/client/error-boundary.js +1 -1
  65. package/dist/client/index.js +1 -1
  66. package/dist/client/internal.js +3 -2
  67. package/dist/client/internal.js.map +1 -1
  68. package/dist/client/navigation-commit.d.ts +5 -0
  69. package/dist/client/navigation-commit.d.ts.map +1 -1
  70. package/dist/client/outlet-content-cache.d.ts +28 -7
  71. package/dist/client/outlet-content-cache.d.ts.map +1 -1
  72. package/dist/client/router.d.ts.map +1 -1
  73. package/dist/client/segment-outlet.d.ts +3 -1
  74. package/dist/client/segment-outlet.d.ts.map +1 -1
  75. package/dist/config-types.d.ts +24 -0
  76. package/dist/config-types.d.ts.map +1 -1
  77. package/dist/config-validation.d.ts.map +1 -1
  78. package/dist/cookies/define-cookie.d.ts.map +1 -1
  79. package/dist/cookies/index.js +5 -2
  80. package/dist/cookies/index.js.map +1 -1
  81. package/dist/index.d.ts +1 -0
  82. package/dist/index.d.ts.map +1 -1
  83. package/dist/index.js +109 -25
  84. package/dist/index.js.map +1 -1
  85. package/dist/native/rsc/cookies/define-cookie.js +6 -2
  86. package/dist/native/rsc/cookies/define-cookie.js.map +1 -1
  87. package/dist/native/rsc/manifest.json +10 -0
  88. package/dist/native/rsc/routing/segment-keys.js +11 -1
  89. package/dist/native/rsc/routing/segment-keys.js.map +1 -1
  90. package/dist/native/rsc/search-params/define.js +4 -1
  91. package/dist/native/rsc/search-params/define.js.map +1 -1
  92. package/dist/native/rsc/server/als-registry.js +2 -1
  93. package/dist/native/rsc/server/als-registry.js.map +1 -1
  94. package/dist/native/rsc/server/client-state-tree.js +14 -9
  95. package/dist/native/rsc/server/client-state-tree.js.map +1 -1
  96. package/dist/native/rsc/server/cookie-context.js +12 -0
  97. package/dist/native/rsc/server/cookie-context.js.map +1 -1
  98. package/dist/native/rsc/server/flight-source.js +5 -2
  99. package/dist/native/rsc/server/flight-source.js.map +1 -1
  100. package/dist/native/rsc/server/framework-stack-frames.js +18 -0
  101. package/dist/native/rsc/server/framework-stack-frames.js.map +1 -0
  102. package/dist/native/rsc/server/prebuilt-builder.js +15 -1
  103. package/dist/native/rsc/server/prebuilt-builder.js.map +1 -1
  104. package/dist/native/rsc/server/request-context.js +10 -4
  105. package/dist/native/rsc/server/request-context.js.map +1 -1
  106. package/dist/native/rsc/server/route-element-builder.js +25 -7
  107. package/dist/native/rsc/server/route-element-builder.js.map +1 -1
  108. package/dist/native/rsc/server/route-module-loader.js +14 -6
  109. package/dist/native/rsc/server/route-module-loader.js.map +1 -1
  110. package/dist/native/rsc/server/rsc-cache-key-guard.js +5 -1
  111. package/dist/native/rsc/server/rsc-cache-key-guard.js.map +1 -1
  112. package/dist/native/rsc/server/rsc-entry/render-route.js +8 -1
  113. package/dist/native/rsc/server/rsc-entry/render-route.js.map +1 -1
  114. package/dist/native/rsc/server/rsc-entry/revalidate-renderer.js +8 -1
  115. package/dist/native/rsc/server/rsc-entry/revalidate-renderer.js.map +1 -1
  116. package/dist/native/rsc/server/segment-hash/outlet.js +28 -8
  117. package/dist/native/rsc/server/segment-hash/outlet.js.map +1 -1
  118. package/dist/native/rsc/server/segment-lifetime/document-outlet.js +24 -0
  119. package/dist/native/rsc/server/segment-lifetime/document-outlet.js.map +1 -0
  120. package/dist/native/rsc/server/segment-lifetime/key-digest.js +74 -0
  121. package/dist/native/rsc/server/segment-lifetime/key-digest.js.map +1 -0
  122. package/dist/native/rsc/server/segment-lifetime/read-rule.js +56 -0
  123. package/dist/native/rsc/server/segment-lifetime/read-rule.js.map +1 -0
  124. package/dist/native/rsc/server/segment-lifetime/read-scope.js +40 -0
  125. package/dist/native/rsc/server/segment-lifetime/read-scope.js.map +1 -0
  126. package/dist/native/rsc/server/segment-lifetime/segment-key.js +50 -0
  127. package/dist/native/rsc/server/segment-lifetime/segment-key.js.map +1 -0
  128. package/dist/native/rsc/server/segment-lifetime/slot-outlets.js +72 -0
  129. package/dist/native/rsc/server/segment-lifetime/slot-outlets.js.map +1 -0
  130. package/dist/native/rsc/server/slot-resolver.js +50 -26
  131. package/dist/native/rsc/server/slot-resolver.js.map +1 -1
  132. package/dist/native/rsc/server/slot-subtree-contain.js +17 -89
  133. package/dist/native/rsc/server/slot-subtree-contain.js.map +1 -1
  134. package/dist/native/rsc/server/subtree-walk.js +140 -0
  135. package/dist/native/rsc/server/subtree-walk.js.map +1 -0
  136. package/dist/native/rsc/shared/als-slots.js +2 -2
  137. package/dist/native/rsc/shared/als-slots.js.map +1 -1
  138. package/dist/native/rsc/shared/cookie-read-through.js +5 -0
  139. package/dist/native/rsc/shared/cookie-read-through.js.map +1 -0
  140. package/dist/native/rsc/shared/outlet-decision.js.map +1 -1
  141. package/dist/native/rsc/shared/route-options-export.js +8 -0
  142. package/dist/native/rsc/shared/route-options-export.js.map +1 -0
  143. package/dist/native/rsc/shared/rsc-cache-key.js +19 -3
  144. package/dist/native/rsc/shared/rsc-cache-key.js.map +1 -1
  145. package/dist/native/rsc/shims/headers.js +3 -4
  146. package/dist/native/rsc/shims/headers.js.map +1 -1
  147. package/dist/native/ssr/client/outlet-content-cache.js +17 -3
  148. package/dist/native/ssr/client/outlet-content-cache.js.map +1 -1
  149. package/dist/native/ssr/client/segment-outlet.js +3 -3
  150. package/dist/native/ssr/client/segment-outlet.js.map +1 -1
  151. package/dist/native/ssr/cookies/define-cookie.js +6 -2
  152. package/dist/native/ssr/cookies/define-cookie.js.map +1 -1
  153. package/dist/native/ssr/manifest.json +4 -0
  154. package/dist/native/ssr/search-params/define.js +4 -1
  155. package/dist/native/ssr/search-params/define.js.map +1 -1
  156. package/dist/native/ssr/server/als-registry.js +2 -1
  157. package/dist/native/ssr/server/als-registry.js.map +1 -1
  158. package/dist/native/ssr/server/client-state-tree.js +14 -9
  159. package/dist/native/ssr/server/client-state-tree.js.map +1 -1
  160. package/dist/native/ssr/server/cookie-context.js +12 -0
  161. package/dist/native/ssr/server/cookie-context.js.map +1 -1
  162. package/dist/native/ssr/server/flight-source.js +1 -0
  163. package/dist/native/ssr/server/flight-source.js.map +1 -1
  164. package/dist/native/ssr/server/framework-stack-frames.js +18 -0
  165. package/dist/native/ssr/server/framework-stack-frames.js.map +1 -0
  166. package/dist/native/ssr/server/request-context.js +10 -4
  167. package/dist/native/ssr/server/request-context.js.map +1 -1
  168. package/dist/native/ssr/server/rsc-cache-key-guard.js +5 -1
  169. package/dist/native/ssr/server/rsc-cache-key-guard.js.map +1 -1
  170. package/dist/native/ssr/server/segment-lifetime/key-digest.js +6 -0
  171. package/dist/native/ssr/server/segment-lifetime/key-digest.js.map +1 -0
  172. package/dist/native/ssr/server/segment-lifetime/read-rule.js +56 -0
  173. package/dist/native/ssr/server/segment-lifetime/read-rule.js.map +1 -0
  174. package/dist/native/ssr/shared/als-slots.js +2 -2
  175. package/dist/native/ssr/shared/als-slots.js.map +1 -1
  176. package/dist/native/ssr/shared/cookie-read-through.js +5 -0
  177. package/dist/native/ssr/shared/cookie-read-through.js.map +1 -0
  178. package/dist/native/ssr/shared/rsc-cache-key.js +19 -3
  179. package/dist/native/ssr/shared/rsc-cache-key.js.map +1 -1
  180. package/dist/native/ssr/shims/headers.js +3 -4
  181. package/dist/native/ssr/shims/headers.js.map +1 -1
  182. package/dist/plugins/callsite-jsx.d.ts +8 -1
  183. package/dist/plugins/callsite-jsx.d.ts.map +1 -1
  184. package/dist/plugins/entries.d.ts.map +1 -1
  185. package/dist/plugins/prerender-sugar.d.ts +9 -8
  186. package/dist/plugins/prerender-sugar.d.ts.map +1 -1
  187. package/dist/plugins/routing.d.ts.map +1 -1
  188. package/dist/routing/convention-lint.d.ts +11 -3
  189. package/dist/routing/convention-lint.d.ts.map +1 -1
  190. package/dist/routing/export-detect.d.ts +50 -23
  191. package/dist/routing/export-detect.d.ts.map +1 -1
  192. package/dist/routing/index.js +2 -2
  193. package/dist/routing/route-options-lint.d.ts +36 -0
  194. package/dist/routing/route-options-lint.d.ts.map +1 -0
  195. package/dist/routing/route-options.d.ts +55 -0
  196. package/dist/routing/route-options.d.ts.map +1 -0
  197. package/dist/routing/segment-keys.d.ts +35 -0
  198. package/dist/routing/segment-keys.d.ts.map +1 -1
  199. package/dist/search-params/index.js +5 -2
  200. package/dist/search-params/index.js.map +1 -1
  201. package/dist/server/als-registry.d.ts +23 -0
  202. package/dist/server/als-registry.d.ts.map +1 -1
  203. package/dist/server/client-state-tree.d.ts +10 -3
  204. package/dist/server/client-state-tree.d.ts.map +1 -1
  205. package/dist/server/cookie-context.d.ts +3 -0
  206. package/dist/server/cookie-context.d.ts.map +1 -1
  207. package/dist/server/flight-source.d.ts +4 -1
  208. package/dist/server/flight-source.d.ts.map +1 -1
  209. package/dist/server/framework-stack-frames.d.ts +23 -0
  210. package/dist/server/framework-stack-frames.d.ts.map +1 -0
  211. package/dist/server/index.d.ts +1 -0
  212. package/dist/server/index.d.ts.map +1 -1
  213. package/dist/server/index.js +2 -2
  214. package/dist/server/internal.js +105 -21
  215. package/dist/server/internal.js.map +1 -1
  216. package/dist/server/prebuilt/capture-routes.d.ts +1 -1
  217. package/dist/server/prebuilt-builder.d.ts.map +1 -1
  218. package/dist/server/request-context.d.ts +6 -1
  219. package/dist/server/request-context.d.ts.map +1 -1
  220. package/dist/server/route-element-builder.d.ts.map +1 -1
  221. package/dist/server/route-module-loader.d.ts +10 -2
  222. package/dist/server/route-module-loader.d.ts.map +1 -1
  223. package/dist/server/rsc-cache-key-guard.d.ts +3 -1
  224. package/dist/server/rsc-cache-key-guard.d.ts.map +1 -1
  225. package/dist/server/rsc-entry/index.d.ts.map +1 -1
  226. package/dist/server/rsc-entry/render-route.d.ts +10 -0
  227. package/dist/server/rsc-entry/render-route.d.ts.map +1 -1
  228. package/dist/server/rsc-entry/revalidate-renderer.d.ts +12 -0
  229. package/dist/server/rsc-entry/revalidate-renderer.d.ts.map +1 -1
  230. package/dist/server/segment-hash/outlet.d.ts +28 -0
  231. package/dist/server/segment-hash/outlet.d.ts.map +1 -1
  232. package/dist/server/segment-lifetime/document-outlet.d.ts +66 -0
  233. package/dist/server/segment-lifetime/document-outlet.d.ts.map +1 -0
  234. package/dist/server/segment-lifetime/key-digest.d.ts +46 -0
  235. package/dist/server/segment-lifetime/key-digest.d.ts.map +1 -0
  236. package/dist/server/segment-lifetime/read-rule.d.ts +43 -0
  237. package/dist/server/segment-lifetime/read-rule.d.ts.map +1 -0
  238. package/dist/server/segment-lifetime/read-scope.d.ts +39 -0
  239. package/dist/server/segment-lifetime/read-scope.d.ts.map +1 -0
  240. package/dist/server/segment-lifetime/segment-key.d.ts +60 -0
  241. package/dist/server/segment-lifetime/segment-key.d.ts.map +1 -0
  242. package/dist/server/segment-lifetime/slot-outlets.d.ts +81 -0
  243. package/dist/server/segment-lifetime/slot-outlets.d.ts.map +1 -0
  244. package/dist/server/slot-resolver.d.ts +6 -1
  245. package/dist/server/slot-resolver.d.ts.map +1 -1
  246. package/dist/server/slot-subtree-contain.d.ts +2 -6
  247. package/dist/server/slot-subtree-contain.d.ts.map +1 -1
  248. package/dist/server/subtree-walk.d.ts +56 -0
  249. package/dist/server/subtree-walk.d.ts.map +1 -0
  250. package/dist/server/types.d.ts +69 -0
  251. package/dist/server/types.d.ts.map +1 -1
  252. package/dist/shared/als-slots.d.ts +12 -2
  253. package/dist/shared/als-slots.d.ts.map +1 -1
  254. package/dist/shared/cookie-read-through.d.ts +18 -0
  255. package/dist/shared/cookie-read-through.d.ts.map +1 -0
  256. package/dist/shared/outlet-decision.d.ts +23 -4
  257. package/dist/shared/outlet-decision.d.ts.map +1 -1
  258. package/dist/shared/route-options-export.d.ts +13 -0
  259. package/dist/shared/route-options-export.d.ts.map +1 -0
  260. package/dist/shared/rsc-cache-key.d.ts +22 -0
  261. package/dist/shared/rsc-cache-key.d.ts.map +1 -1
  262. package/dist/shared/segment-info.d.ts +6 -0
  263. package/dist/shared/segment-info.d.ts.map +1 -1
  264. package/dist/shims/headers.d.ts.map +1 -1
  265. package/docs/api/30-api-server.mdx +29 -0
  266. package/docs/api/32-api-cache.mdx +10 -4
  267. package/docs/api/34-api-config.mdx +5 -0
  268. package/docs/learn/09-streaming.mdx +6 -2
  269. package/docs/learn/10-caching.mdx +10 -4
  270. package/package.json +1 -1
  271. package/src/cli-check.ts +11 -3
  272. package/src/client/navigation-commit.ts +11 -2
  273. package/src/client/outlet-content-cache.ts +40 -8
  274. package/src/client/router.ts +1 -0
  275. package/src/client/segment-outlet.tsx +10 -4
  276. package/src/config-types.ts +25 -0
  277. package/src/config-validation.ts +17 -0
  278. package/src/cookies/define-cookie.ts +5 -1
  279. package/src/index.ts +2 -1
  280. package/src/plugins/callsite-jsx.ts +104 -6
  281. package/src/plugins/entries.ts +3 -0
  282. package/src/plugins/prerender-sugar.ts +34 -18
  283. package/src/plugins/routing.ts +3 -1
  284. package/src/routing/convention-lint.ts +18 -7
  285. package/src/routing/export-detect.ts +14 -117
  286. package/src/routing/route-options-lint.ts +153 -0
  287. package/src/routing/route-options.ts +423 -0
  288. package/src/routing/segment-keys.ts +50 -0
  289. package/src/rsc-runtime/vendor-types.d.ts +4 -0
  290. package/src/search-params/define.ts +1 -1
  291. package/src/server/als-registry.ts +29 -0
  292. package/src/server/client-state-tree.ts +30 -16
  293. package/src/server/cookie-context.ts +17 -0
  294. package/src/server/flight-source.ts +7 -1
  295. package/src/server/framework-stack-frames.ts +44 -0
  296. package/src/server/index.ts +7 -0
  297. package/src/server/prebuilt/capture-routes.ts +1 -1
  298. package/src/server/prebuilt-builder.ts +30 -2
  299. package/src/server/request-context.ts +28 -4
  300. package/src/server/route-element-builder.ts +80 -5
  301. package/src/server/route-module-loader.ts +43 -10
  302. package/src/server/rsc-cache-key-guard.ts +17 -2
  303. package/src/server/rsc-entry/index.ts +16 -0
  304. package/src/server/rsc-entry/render-route.ts +19 -1
  305. package/src/server/rsc-entry/revalidate-renderer.ts +17 -1
  306. package/src/server/segment-hash/outlet.ts +62 -18
  307. package/src/server/segment-lifetime/document-outlet.ts +98 -0
  308. package/src/server/segment-lifetime/key-digest.ts +139 -0
  309. package/src/server/segment-lifetime/read-rule.ts +136 -0
  310. package/src/server/segment-lifetime/read-scope.ts +99 -0
  311. package/src/server/segment-lifetime/segment-key.ts +140 -0
  312. package/src/server/segment-lifetime/slot-outlets.ts +180 -0
  313. package/src/server/slot-resolver.ts +99 -56
  314. package/src/server/slot-subtree-contain.ts +35 -182
  315. package/src/server/subtree-walk.ts +316 -0
  316. package/src/server/types.ts +85 -0
  317. package/src/shared/als-slots.ts +19 -8
  318. package/src/shared/cookie-read-through.ts +18 -0
  319. package/src/shared/outlet-decision.ts +25 -4
  320. package/src/shared/route-options-export.ts +14 -0
  321. package/src/shared/rsc-cache-key.ts +41 -2
  322. package/src/shared/segment-info.ts +6 -0
  323. package/src/shims/headers.ts +5 -4
  324. package/dist/_chunks/actions-DIgnvDrG.js.map +0 -1
  325. package/dist/_chunks/als-slots-kbQrHTzm.js.map +0 -1
  326. package/dist/_chunks/chains-CSslTUdI.js +0 -1
  327. package/dist/_chunks/cli-check-C3QOAru7.js.map +0 -1
  328. package/dist/_chunks/convention-lint-BoVISNS6.js.map +0 -1
  329. package/dist/_chunks/dev-server-B8roKA3Q.js +0 -1
  330. package/dist/_chunks/dev-server-C5R6jx8Q.js.map +0 -1
  331. package/dist/_chunks/dist-C1Rjlo6s.js.map +0 -1
  332. package/dist/_chunks/error-boundary-DB51f9ih.js.map +0 -1
  333. package/dist/_chunks/scanner-C9Lrf77z.js.map +0 -1
@@ -27,115 +27,23 @@
27
27
  * still takes the slot's catch-all boundary. A thrown thenable — `use()` on a
28
28
  * pending promise — passes through untouched so Flight can suspend the task.
29
29
  *
30
- * Flight's `renderElement` does not only invoke plain functions: it unwraps
31
- * `memo` (renders `.type`), `forwardRef` (calls `.render`), and `lazy`
32
- * (runs `_init`, then renders what it resolved to). A server component behind
33
- * any of those is invoked all the same, so its deny would escape too. The walk
34
- * therefore resolves an element type the way Flight would — down to the
35
- * function Flight would call — and wraps that.
30
+ * The walk itself — memo, forwardRef and lazy unwrapping, promises, props —
31
+ * is `subtree-walk.ts`, shared with a 'document' segment's read scope.
36
32
  *
37
33
  * See design/02-rendering-pipeline.md §"Slot Access Failure = Graceful
38
34
  * Degradation", TIM-1450.
39
35
  */
40
36
 
41
- import { createElement, type ElementType, type ReactElement, type ReactNode } from 'react';
37
+ import { createElement, type ReactNode } from 'react';
42
38
 
43
- import { DenySignal } from './primitives.ts';
44
39
  import { isDenySignal } from './signal-identity.ts';
45
- import { isClientReference } from './utils/element-type.ts';
40
+ import {
41
+ isThenable,
42
+ rewriteSubtree,
43
+ type ServerComponent,
44
+ type SubtreeRule,
45
+ } from './subtree-walk.ts';
46
46
 
47
- // React 19 elements; the legacy tag is accepted so a stray pre-19 element in
48
- // a dependency's output is walked rather than skipped.
49
- const ELEMENT_TAGS = new Set<symbol>([
50
- Symbol.for('react.transitional.element'),
51
- Symbol.for('react.element'),
52
- ]);
53
-
54
- type ServerComponent = (props: Record<string, unknown>) => unknown;
55
-
56
- interface Thenable<T> {
57
- then(onFulfilled: (value: T) => unknown, onRejected?: (reason: unknown) => unknown): unknown;
58
- }
59
-
60
- /** What one walk carries: the fallback to substitute, and the one subtree it must not enter. */
61
- interface Containment {
62
- fallback: ReactNode;
63
- /**
64
- * An element the caller already owns and has contained on its own — a slot
65
- * layout's `children`, which the resolver built. Left untouched by identity
66
- * so the level below is not wrapped (and re-walked) a second time.
67
- */
68
- opaque: unknown;
69
- }
70
-
71
- function isThenable(value: unknown): value is Thenable<unknown> {
72
- return (
73
- typeof value === 'object' &&
74
- value !== null &&
75
- typeof (value as { then?: unknown }).then === 'function'
76
- );
77
- }
78
-
79
- function isElement(value: unknown): value is ReactElement {
80
- return (
81
- typeof value === 'object' &&
82
- value !== null &&
83
- ELEMENT_TAGS.has((value as { $$typeof?: symbol }).$$typeof as symbol)
84
- );
85
- }
86
-
87
- /** A server component Flight would invoke: a function that is neither a client reference nor a class. */
88
- function isServerComponent(type: unknown): type is ServerComponent {
89
- return (
90
- typeof type === 'function' &&
91
- !isClientReference(type) &&
92
- !(type as { prototype?: { isReactComponent?: unknown } }).prototype?.isReactComponent
93
- );
94
- }
95
-
96
- // The wrapper types Flight's renderElement unwraps before invoking a function.
97
- const MEMO_TAG = Symbol.for('react.memo');
98
- const FORWARD_REF_TAG = Symbol.for('react.forward_ref');
99
- const LAZY_TAG = Symbol.for('react.lazy');
100
-
101
- /** The shape React gives a `lazy()` result; `_init` is what Flight calls to resolve it. */
102
- interface LazyType {
103
- _payload: unknown;
104
- _init: (payload: unknown) => ElementType;
105
- }
106
-
107
- /**
108
- * The server component Flight would invoke for an element type, or undefined
109
- * when it would not invoke one (host tag, client reference, class, provider,
110
- * Suspense, and so on). Mirrors the unwrapping in Flight's `renderElement`:
111
- * a `memo` renders its `.type`, a `forwardRef` calls its `.render`, a `lazy`
112
- * resolves through `_init` and renders the result.
113
- */
114
- function serverComponentOf(type: unknown): ServerComponent | undefined {
115
- if (isServerComponent(type)) return type;
116
- if (typeof type !== 'object' || type === null) return undefined;
117
- const tag = (type as { $$typeof?: symbol }).$$typeof;
118
- if (tag === MEMO_TAG) return serverComponentOf((type as { type: unknown }).type);
119
- if (tag === FORWARD_REF_TAG) return serverComponentOf((type as { render: unknown }).render);
120
- if (tag === LAZY_TAG) {
121
- const lazy = type as LazyType;
122
- // Resolve as Flight does. Until the module has loaded, `_init` throws the
123
- // pending thenable; the wrapper lets any non-deny throw through, so Flight
124
- // suspends the task and retries it, and the next call returns the type.
125
- // That type becomes an element the wrapper walks like any other result,
126
- // so a server component (memo'd or not) behind the lazy is contained too.
127
- return (props) => createElement(lazy._init(lazy._payload), props);
128
- }
129
- return undefined;
130
- }
131
-
132
- function isPlainObject(value: unknown): value is Record<string, unknown> {
133
- if (typeof value !== 'object' || value === null) return false;
134
- const proto = Object.getPrototypeOf(value);
135
- return proto === Object.prototype || proto === null;
136
- }
137
-
138
- /** On a deny, the fallback takes the denying component's place; anything else propagates. */
139
47
  function denyToFallback(fallback: ReactNode): (error: unknown) => ReactNode {
140
48
  return (error) => {
141
49
  if (isDenySignal(error)) return fallback;
@@ -143,6 +51,28 @@ function denyToFallback(fallback: ReactNode): (error: unknown) => ReactNode {
143
51
  };
144
52
  }
145
53
 
54
+ /**
55
+ * The containment rule: each server component becomes a
56
+ * `ContainedSlotComponent`, a promise child that rejects with a deny becomes
57
+ * the fallback, and `opaque` — an element the caller already contained — is
58
+ * left alone.
59
+ */
60
+ function containment(fallback: ReactNode, opaque: unknown): SubtreeRule {
61
+ return {
62
+ wrap: (component, componentProps, key) =>
63
+ component === (ContainedSlotComponent as unknown)
64
+ ? undefined
65
+ : createElement(ContainedSlotComponent, {
66
+ component,
67
+ componentProps,
68
+ fallback,
69
+ ...(key !== null ? { key } : undefined),
70
+ }),
71
+ isOpaque: (node) => opaque !== undefined && node === opaque,
72
+ onRejected: denyToFallback(fallback),
73
+ };
74
+ }
75
+
146
76
  /**
147
77
  * Invokes a server component from a slot's subtree and contains its output.
148
78
  *
@@ -157,7 +87,7 @@ function ContainedSlotComponent(props: {
157
87
  fallback: ReactNode;
158
88
  }): ReactNode | Promise<ReactNode> {
159
89
  const { component: Component, componentProps, fallback } = props;
160
- const containment: Containment = { fallback, opaque: undefined };
90
+ const rule = containment(fallback, undefined);
161
91
  let result: unknown;
162
92
  try {
163
93
  result = Component(componentProps);
@@ -168,88 +98,11 @@ function ContainedSlotComponent(props: {
168
98
  // shape; what comes back for a component result is the result, rewritten.
169
99
  if (isThenable(result)) {
170
100
  return Promise.resolve(result).then(
171
- (value) => walk(value, containment, new WeakSet()) as ReactNode,
101
+ (value) => rewriteSubtree(value, rule) as ReactNode,
172
102
  denyToFallback(fallback)
173
103
  );
174
104
  }
175
- return walk(result, containment, new WeakSet()) as ReactNode;
176
- }
177
-
178
- /**
179
- * Rewrite `node`, returning the input itself when nothing beneath it needed
180
- * wrapping — so an unchanged subtree keeps its identity and Flight's own
181
- * object deduplication still applies to it.
182
- */
183
- function walk(node: unknown, c: Containment, seen: WeakSet<object>): unknown {
184
- if (typeof node !== 'object' || node === null) return node;
185
- if (node === c.opaque || seen.has(node)) return node;
186
- seen.add(node);
187
-
188
- if (isThenable(node)) {
189
- // A promise rendered as a child resolves to more tree; a rejection with a
190
- // deny is the slot denying, same as a component would.
191
- return node.then((value) => walk(value, c, seen), denyToFallback(c.fallback));
192
- }
193
-
194
- if (Array.isArray(node)) {
195
- let changed = false;
196
- const next = node.map((child) => {
197
- const walked = walk(child, c, seen);
198
- if (walked !== child) changed = true;
199
- return walked;
200
- });
201
- return changed ? next : node;
202
- }
203
-
204
- if (isElement(node)) {
205
- const { type, key, props } = node;
206
- const component = type === ContainedSlotComponent ? undefined : serverComponentOf(type);
207
- if (component) {
208
- const wrapped = {
209
- component,
210
- componentProps: props as Record<string, unknown>,
211
- fallback: c.fallback,
212
- ...(key !== null ? { key } : undefined),
213
- };
214
- return createElement(ContainedSlotComponent, wrapped);
215
- }
216
- // Host elements, fragments, Suspense, client references, providers, and
217
- // wrappers this walk already made: keep the type, contain whatever server
218
- // components ride in the props (children, `fallback`, render-prop-shaped
219
- // slots).
220
- const nextProps = walk(props, c, seen);
221
- if (nextProps === props) return node;
222
- // JSX compiles `<Flex><A /><B /></Flex>` to separate createElement
223
- // arguments that React does not key-validate, but the walk produces
224
- // `{ children: [A, B] }` inside props — an array that React treats as
225
- // dynamic and warns about missing keys. For 2+ children, spread them as
226
- // separate arguments to restore the JSX calling convention. For 0–1
227
- // children, pass the array as a single child argument to preserve the
228
- // array shape — spreading `[x]` would collapse it to a bare element,
229
- // breaking components that call `children.map()`.
230
- const { children, ...rest } = nextProps as Record<string, unknown>;
231
- const propsWithKey = key === null ? rest : { ...rest, key };
232
- if (Array.isArray(children) && children.length > 1) {
233
- return createElement(type, propsWithKey, ...(children as ReactNode[]));
234
- }
235
- if (children !== undefined) {
236
- return createElement(type, propsWithKey, children as ReactNode);
237
- }
238
- return createElement(type, propsWithKey);
239
- }
240
-
241
- if (isPlainObject(node)) {
242
- let changed = false;
243
- const next: Record<string, unknown> = {};
244
- for (const [name, value] of Object.entries(node)) {
245
- const walked = walk(value, c, seen);
246
- if (walked !== value) changed = true;
247
- next[name] = walked;
248
- }
249
- return changed ? next : node;
250
- }
251
-
252
- return node;
105
+ return rewriteSubtree(result, rule) as ReactNode;
253
106
  }
254
107
 
255
108
  /**
@@ -269,5 +122,5 @@ export function containSlotSubtree(
269
122
  fallback: ReactNode,
270
123
  opaque?: ReactNode
271
124
  ): ReactNode {
272
- return walk(tree, { fallback, opaque }, new WeakSet()) as ReactNode;
125
+ return rewriteSubtree(tree, containment(fallback, opaque)) as ReactNode;
273
126
  }
@@ -0,0 +1,316 @@
1
+ /**
2
+ * Rewrite the server components in a tree a server component returned.
3
+ *
4
+ * A server component's own call runs where timber calls it, but every server
5
+ * component in the tree it *returns* runs later, as its own Flight task, in
6
+ * Flight's context rather than the caller's: a `try` around the call does not
7
+ * see their throws, and an AsyncLocalStorage scope around it does not reach
8
+ * them. The only way to give them the caller's handling is to rewrite the
9
+ * tree before Flight renders it: each server-component element is replaced by
10
+ * one a rule builds, which calls the original and rewrites its output the
11
+ * same way, so the handling follows the tree however deep it renders.
12
+ *
13
+ * Two rules use it: slot deny containment (`slot-subtree-contain.ts`) and
14
+ * the read scope of a 'document' segment (`segment-lifetime/read-scope.ts`).
15
+ *
16
+ * Flight's `renderElement` does not only invoke plain functions: it unwraps
17
+ * `memo` (renders `.type`), `forwardRef` (calls `.render`), and `lazy` (runs
18
+ * `_init`, then renders what it resolved to). A server component behind any of
19
+ * those is invoked all the same, so the walk resolves an element type the way
20
+ * Flight would — down to the function Flight would call.
21
+ */
22
+
23
+ import { createElement, type ElementType, type ReactElement, type ReactNode } from 'react';
24
+
25
+ import { isClientReference } from './utils/element-type.ts';
26
+
27
+ const ELEMENT_TAGS = new Set<symbol>([
28
+ Symbol.for('react.transitional.element'),
29
+ Symbol.for('react.element'),
30
+ ]);
31
+
32
+ export type ServerComponent = (props: Record<string, unknown>) => unknown;
33
+
34
+ interface Thenable<T> {
35
+ then(onFulfilled: (value: T) => unknown, onRejected?: (reason: unknown) => unknown): unknown;
36
+ }
37
+
38
+ /** What one walk carries: the fallback to substitute, and the one subtree it must not enter. */
39
+ export function isThenable(value: unknown): value is Thenable<unknown> {
40
+ return (
41
+ typeof value === 'object' &&
42
+ value !== null &&
43
+ typeof (value as { then?: unknown }).then === 'function'
44
+ );
45
+ }
46
+
47
+ function isElement(value: unknown): value is ReactElement {
48
+ return (
49
+ typeof value === 'object' &&
50
+ value !== null &&
51
+ ELEMENT_TAGS.has((value as { $$typeof?: symbol }).$$typeof as symbol)
52
+ );
53
+ }
54
+
55
+ /** A server component Flight would invoke: a function that is neither a client reference nor a class. */
56
+ function isServerComponent(type: unknown): type is ServerComponent {
57
+ return (
58
+ typeof type === 'function' &&
59
+ !isClientReference(type) &&
60
+ !(type as { prototype?: { isReactComponent?: unknown } }).prototype?.isReactComponent
61
+ );
62
+ }
63
+
64
+ // The wrapper types Flight's renderElement unwraps before invoking a function.
65
+ const MEMO_TAG = Symbol.for('react.memo');
66
+ const FORWARD_REF_TAG = Symbol.for('react.forward_ref');
67
+ const LAZY_TAG = Symbol.for('react.lazy');
68
+
69
+ /** The shape React gives a `lazy()` result; `_init` is what Flight calls to resolve it. */
70
+ interface LazyType {
71
+ _payload: unknown;
72
+ _init: (payload: unknown) => ElementType;
73
+ }
74
+
75
+ /**
76
+ * The server component Flight would invoke for an element type, or undefined
77
+ * when it would not invoke one (host tag, client reference, class, provider,
78
+ * Suspense, and so on). Mirrors the unwrapping in Flight's `renderElement`:
79
+ * a `memo` renders its `.type`, a `forwardRef` calls its `.render`, a `lazy`
80
+ * resolves through `_init` and renders the result.
81
+ */
82
+ function serverComponentOf(type: unknown): ServerComponent | undefined {
83
+ if (isServerComponent(type)) return type;
84
+ if (typeof type !== 'object' || type === null) return undefined;
85
+ const tag = (type as { $$typeof?: symbol }).$$typeof;
86
+ if (tag === MEMO_TAG) return serverComponentOf((type as { type: unknown }).type);
87
+ if (tag === FORWARD_REF_TAG) return serverComponentOf((type as { render: unknown }).render);
88
+ if (tag === LAZY_TAG) {
89
+ const lazy = type as LazyType;
90
+ // Resolve as Flight does. Until the module has loaded, `_init` throws the
91
+ // pending thenable; the wrapper lets any non-deny throw through, so Flight
92
+ // suspends the task and retries it, and the next call returns the type.
93
+ // That type becomes an element the wrapper walks like any other result,
94
+ // so a server component (memo'd or not) behind the lazy is contained too.
95
+ return (props) => createElement(lazy._init(lazy._payload), props);
96
+ }
97
+ return undefined;
98
+ }
99
+
100
+ function isPlainObject(value: unknown): value is Record<string, unknown> {
101
+ if (typeof value !== 'object' || value === null) return false;
102
+ const proto = Object.getPrototypeOf(value);
103
+ return proto === Object.prototype || proto === null;
104
+ }
105
+
106
+ /** On a deny, the fallback takes the denying component's place; anything else propagates. */
107
+
108
+ function isRewritableIterable(value: object): value is Iterable<unknown> {
109
+ return (
110
+ typeof (value as { [Symbol.iterator]?: unknown })[Symbol.iterator] === 'function' &&
111
+ !ArrayBuffer.isView(value) &&
112
+ !(value instanceof ArrayBuffer) &&
113
+ !(typeof FormData !== 'undefined' && value instanceof FormData) &&
114
+ !isElement(value)
115
+ );
116
+ }
117
+
118
+ /** An async iterable Flight streams as one, not a `ReadableStream`, which it sends natively. */
119
+ function isAsyncIterable(value: object): value is AsyncIterable<unknown> {
120
+ return (
121
+ typeof (value as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] === 'function' &&
122
+ !(typeof ReadableStream !== 'undefined' && value instanceof ReadableStream)
123
+ );
124
+ }
125
+
126
+ /** How one use of the walk treats what it finds. */
127
+ export interface SubtreeRule {
128
+ /**
129
+ * The element to render in place of a server-component element, or
130
+ * undefined to keep the element and rewrite its props (a rule's own wrapper
131
+ * returns undefined, so a rewritten tree is not wrapped twice).
132
+ */
133
+ wrap(
134
+ component: ServerComponent,
135
+ props: Record<string, unknown>,
136
+ key: string | null
137
+ ): ReactElement | undefined;
138
+ /** A node to leave untouched, and not descend into. */
139
+ isOpaque(node: unknown): boolean;
140
+ /** Handles a rejection of a promise rendered as a child; rethrows by default. */
141
+ onRejected?: (reason: unknown) => unknown;
142
+ /**
143
+ * Runs work the walk defers past the component's return — advancing an
144
+ * async iterable it returned — in the rule's context. Default: as is.
145
+ */
146
+ runIn?: <T>(fn: () => T) => T;
147
+ }
148
+
149
+ /**
150
+ * Rewrite `node`, returning the input itself when nothing beneath it needed
151
+ * wrapping — so an unchanged subtree keeps its identity and Flight's own
152
+ * object deduplication still applies to it.
153
+ */
154
+ function walk(node: unknown, rule: SubtreeRule, seen: Seen): unknown {
155
+ if (typeof node !== 'object' || node === null) return node;
156
+ // A node reached again — one element rendered twice, a shared props object —
157
+ // gets the same rewrite as the first time, not the original: Flight renders
158
+ // every occurrence. While a node is still being rewritten its entry is the
159
+ // original, so a cycle back to it ends there.
160
+ if (seen.has(node)) return seen.get(node);
161
+ if (rule.isOpaque(node)) return node;
162
+ seen.set(node, node);
163
+ const rewritten = rewriteNode(node, rule, seen);
164
+ seen.set(node, rewritten);
165
+ return rewritten;
166
+ }
167
+
168
+ /** What each node visited in one walk was rewritten to. */
169
+ type Seen = WeakMap<object, unknown>;
170
+
171
+ function rewriteNode(node: object, rule: SubtreeRule, seen: Seen): unknown {
172
+ if (isThenable(node)) {
173
+ // A promise rendered as a child resolves to more tree.
174
+ return node.then((value) => walk(value, rule, seen), rule.onRejected);
175
+ }
176
+
177
+ if (Array.isArray(node)) {
178
+ let changed = false;
179
+ const next = node.map((child) => {
180
+ const walked = walk(child, rule, seen);
181
+ if (walked !== child) changed = true;
182
+ return walked;
183
+ });
184
+ return changed ? next : node;
185
+ }
186
+
187
+ // Every other collection that can carry elements — a Set, a Map, a
188
+ // generator, an async iterable — is rewritten too: React renders iterable
189
+ // children later like any child, and Flight renders the server elements in a
190
+ // Map or Set prop as it serializes it. A Set and a Map keep their type, which
191
+ // Flight serializes as such. Binary data, `FormData` and `ReadableStream`,
192
+ // which Flight sends as themselves and which hold no elements, are left alone.
193
+ if (node instanceof Set) {
194
+ let changed = false;
195
+ const next = new Set<unknown>();
196
+ for (const child of node) {
197
+ const walked = walk(child, rule, seen);
198
+ if (walked !== child) changed = true;
199
+ next.add(walked);
200
+ }
201
+ return changed ? next : node;
202
+ }
203
+ if (node instanceof Map) {
204
+ let changed = false;
205
+ const next = new Map<unknown, unknown>();
206
+ for (const [key, value] of node) {
207
+ const walkedKey = walk(key, rule, seen);
208
+ const walkedValue = walk(value, rule, seen);
209
+ if (walkedKey !== key || walkedValue !== value) changed = true;
210
+ next.set(walkedKey, walkedValue);
211
+ }
212
+ return changed ? next : node;
213
+ }
214
+ // A sync iterable is consumed now, inside the rule's context (the walk runs
215
+ // where the component returned): a generator's own body reads request
216
+ // inputs as it is advanced, and Flight would advance it later, elsewhere.
217
+ // React and Flight consume every child iterable whole, so nothing that
218
+ // would have been read lazily is lost.
219
+ if (isRewritableIterable(node)) {
220
+ let changed = false;
221
+ const next = Array.from(node, (child) => {
222
+ const walked = walk(child, rule, seen);
223
+ if (walked !== child) changed = true;
224
+ return walked;
225
+ });
226
+ // A re-iterable value that held nothing to rewrite (`URLSearchParams`) is
227
+ // returned as is, so Flight serializes it as before. A one-shot iterator
228
+ // was just consumed, so it is always replaced by one over what it held.
229
+ const oneShot = typeof (node as { next?: unknown }).next === 'function';
230
+ return changed || oneShot ? next[Symbol.iterator]() : node;
231
+ }
232
+ // An async iterable cannot be consumed now; each step is advanced, and its
233
+ // value rewritten, inside the rule's context instead.
234
+ if (isAsyncIterable(node)) {
235
+ const source = node;
236
+ const runIn = rule.runIn ?? ((fn) => fn());
237
+ return {
238
+ async *[Symbol.asyncIterator]() {
239
+ const iterator = runIn(() => source[Symbol.asyncIterator]());
240
+ for (;;) {
241
+ const step = await runIn(() => iterator.next());
242
+ // The return value travels too (Flight sends it in the close row).
243
+ if (step.done) return runIn(() => walk(step.value, rule, seen));
244
+ yield runIn(() => walk(step.value, rule, seen));
245
+ }
246
+ },
247
+ };
248
+ }
249
+
250
+ if (isElement(node)) {
251
+ const { type, key, props } = node;
252
+ const component = serverComponentOf(type);
253
+ const replaced = component && rule.wrap(component, props as Record<string, unknown>, key);
254
+ if (replaced) return replaced;
255
+ // Host elements, fragments, Suspense, client references, providers, and
256
+ // wrappers a rule already made: keep the type, rewrite whatever server
257
+ // components ride in the props (children, `fallback`, render-prop-shaped
258
+ // slots).
259
+ const nextProps = walk(props, rule, seen);
260
+ if (nextProps === props) return node;
261
+ // JSX compiles `<Flex><A /><B /></Flex>` to separate createElement
262
+ // arguments that React does not key-validate, but the walk produces
263
+ // `{ children: [A, B] }` inside props — an array that React treats as
264
+ // dynamic and warns about missing keys. For 2+ children, spread them as
265
+ // separate arguments to restore the JSX calling convention. For 0–1
266
+ // children, pass the array as a single child argument to preserve the
267
+ // array shape — spreading `[x]` would collapse it to a bare element,
268
+ // breaking components that call `children.map()`.
269
+ const { children, ...rest } = nextProps as Record<string, unknown>;
270
+ const propsWithKey = key === null ? rest : { ...rest, key };
271
+ if (Array.isArray(children) && children.length > 1) {
272
+ return createElement(type, propsWithKey, ...(children as ReactNode[]));
273
+ }
274
+ if (children !== undefined) {
275
+ return createElement(type, propsWithKey, children as ReactNode);
276
+ }
277
+ return createElement(type, propsWithKey);
278
+ }
279
+
280
+ if (isPlainObject(node)) {
281
+ let changed = false;
282
+ const next: Record<string, unknown> = {};
283
+ for (const [name, value] of Object.entries(node)) {
284
+ const walked = walk(value, rule, seen);
285
+ if (walked !== value) changed = true;
286
+ next[name] = walked;
287
+ }
288
+ return changed ? next : node;
289
+ }
290
+
291
+ return node;
292
+ }
293
+
294
+ /** Rewrite every server component in `tree` by `rule`. */
295
+ export function rewriteSubtree(tree: unknown, rule: SubtreeRule): unknown {
296
+ return walk(tree, rule, new WeakMap());
297
+ }
298
+
299
+ /**
300
+ * Call a server component and rewrite what it returns by `rule` — what a
301
+ * rule's wrapper component does. A synchronous throw leaves synchronously, so
302
+ * a `use()` that suspends is retried by Flight.
303
+ */
304
+ export function callAndRewrite(
305
+ component: ServerComponent,
306
+ props: Record<string, unknown>,
307
+ rule: SubtreeRule
308
+ ): ReactNode | Promise<ReactNode> {
309
+ const result = component(props);
310
+ // The walk is typed over `unknown` because it descends into props of any
311
+ // shape; what comes back for a component result is the result, rewritten.
312
+ if (isThenable(result)) {
313
+ return Promise.resolve(result).then((value) => rewriteSubtree(value, rule) as ReactNode);
314
+ }
315
+ return rewriteSubtree(result, rule) as ReactNode;
316
+ }
@@ -2,6 +2,8 @@
2
2
 
3
3
  import type { CoercedParams } from '../shared/param-value.ts';
4
4
  import type { EarlyHint } from './early-hints.ts';
5
+ import type { SearchParamsDefinition } from '../search-params/define.ts';
6
+ import type { ServerOnlyCookieDefinition } from '../cookies/define-cookie.ts';
5
7
 
6
8
  /**
7
9
  * A value that is safe to pass through `JSON.stringify` without data loss.
@@ -73,6 +75,89 @@ export interface RouteContext {
73
75
  // eslint-disable-next-line @typescript-eslint/no-empty-object-type, typescript/no-empty-interface
74
76
  export interface AccessContext {}
75
77
 
78
+ // ─── Route-module options ─────────────────────────────────────────────────
79
+ //
80
+ // `export const layoutOptions = { … } satisfies LayoutOptions` and
81
+ // `export const pageOptions = { … } satisfies PageOptions`.
82
+ // See design/53-segment-lifetime.md §"Route-module options".
83
+ //
84
+ // The objects are validated from source at build time
85
+ // (`routing/route-options.ts`), so they must be object literals whose values
86
+ // are literals (except a key's `searchParams` and `cookies`, which name
87
+ // definitions). In a .ts/.tsx/.js/.jsx route file, a spread, a computed key, a
88
+ // non-literal value or an unknown key fails the build (MDX pages are not read).
89
+ // Adding an option here without a validator there is a type error, and vice
90
+ // versa.
91
+
92
+ /**
93
+ * Prerender a page at build time. `true` is pure build time; an object adds a
94
+ * runtime lifetime (ISR) and implies `prerender: true`. Desugars to wrapping
95
+ * the page's default export in `cache.component(Page, { prerender: true, … })`.
96
+ * See design/45-cache-lifetimes.md §"Route-Level Static".
97
+ */
98
+ export type RoutePrerender = boolean | { ttl?: number; tags?: readonly string[] };
99
+
100
+ /**
101
+ * How long a segment's output lives. `'request'` (the default, unless the app
102
+ * sets `defaultLayoutLifetime` for its layouts) renders on every request. `'document'` renders on the document request and whenever its key
103
+ * changes or `router.refresh()` runs, and is skipped without rendering on
104
+ * every other client navigation. See design/53-segment-lifetime.md.
105
+ */
106
+ export type SegmentLifetime = 'request' | 'document';
107
+
108
+ /**
109
+ * The request inputs a `'document'` segment depends on — and the only ones it
110
+ * may read. Values are compared after parsing, through each definition's
111
+ * codec. See design/53-segment-lifetime.md §"Segment keys".
112
+ */
113
+ export interface SegmentKey {
114
+ /**
115
+ * Param names on the segment's path. Default: every param on the path.
116
+ * A name that is not on the path fails the build.
117
+ */
118
+ segmentParams?: readonly string[];
119
+ /** A search-params definition, often a `.pick()`. Default: none. */
120
+ searchParams?: SearchParamsDefinition<Record<string, unknown>>;
121
+ /** Cookie definitions (`defineCookie`). Default: none. */
122
+ cookies?: readonly ServerOnlyCookieDefinition<unknown>[];
123
+ }
124
+
125
+ /** Options for a `page.tsx`: `export const pageOptions = { … } satisfies PageOptions`. */
126
+ export interface PageOptions {
127
+ /** See `SegmentLifetime`. Default `'request'`. */
128
+ lifetime?: SegmentLifetime;
129
+ /** What a `'document'` page depends on. Only with `lifetime: 'document'`. */
130
+ key?: SegmentKey;
131
+ /** Overrides any ancestor layout's `prerender`. `false` opts out. */
132
+ prerender?: RoutePrerender;
133
+ /**
134
+ * Hold the SSR stream up to this many milliseconds so fast Suspense
135
+ * boundaries resolve inline. The route uses the maximum across its layouts
136
+ * and page. See design/05-streaming.md §"deferSuspenseFor".
137
+ */
138
+ deferSuspenseFor?: number;
139
+ }
140
+
141
+ /** Options for a `layout.tsx`: `export const layoutOptions = { … } satisfies LayoutOptions`. */
142
+ export interface LayoutOptions {
143
+ /** See `SegmentLifetime`. Default: the app's `defaultLayoutLifetime` (`'request'` unless set). */
144
+ lifetime?: SegmentLifetime;
145
+ /**
146
+ * What a `'document'` layout depends on. Only on a `'document'` layout: one
147
+ * that declares `lifetime: 'document'`, or declares no lifetime under a
148
+ * `'document'` `defaultLayoutLifetime`.
149
+ */
150
+ key?: SegmentKey;
151
+ /**
152
+ * Propagates to descendant pages that do not declare their own
153
+ * (most-specific wins). The layout itself is never cached: it renders with
154
+ * its real children. See design/45-cache-lifetimes.md §"Layout Propagation".
155
+ */
156
+ prerender?: RoutePrerender;
157
+ /** See `PageOptions.deferSuspenseFor`. */
158
+ deferSuspenseFor?: number;
159
+ }
160
+
76
161
  export interface Metadata {
77
162
  title?: string | { default?: string; template?: string; absolute?: string };
78
163
  description?: string;