@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
@@ -12,6 +12,8 @@
12
12
  * smuggling primitive that the encoding contract closes.
13
13
  */
14
14
 
15
+ import { assertCookieRead, assertUnscopedRead } from './segment-lifetime/read-rule.ts';
16
+ import { COOKIE_READ_THROUGH, type CookieReadThrough } from '../shared/cookie-read-through.ts';
15
17
  import { requestContextAls, type RequestContextStore } from './als-registry.ts';
16
18
  import { isDebug } from './debug.ts';
17
19
  import {
@@ -76,19 +78,31 @@ export function getCookieJar(): RequestCookies {
76
78
  return {
77
79
  // Reads are noted (dev only) so a later write of the same cookie can
78
80
  // warn if React.cache may have memoized the old value (TIM-1529 D3).
81
+ // Inside a 'document' segment, only the cookies in its key (design/53).
79
82
  get(name: string): string | undefined {
83
+ assertCookieRead(name);
84
+ noteCookieReadForReactCache(name);
85
+ return map.get(name);
86
+ },
87
+ // A typed definition's read: allowed for a keyed cookie read through the
88
+ // key's own definition (shared/cookie-read-through.ts).
89
+ [COOKIE_READ_THROUGH](name: string, codec: unknown): string | undefined {
90
+ assertCookieRead(name, codec);
80
91
  noteCookieReadForReactCache(name);
81
92
  return map.get(name);
82
93
  },
83
94
  has(name: string): boolean {
95
+ assertCookieRead(name);
84
96
  noteCookieReadForReactCache(name);
85
97
  return map.has(name);
86
98
  },
87
99
  getAll(): Array<{ name: string; value: string }> {
100
+ assertUnscopedRead('every cookie');
88
101
  noteCookieReadForReactCache(ANY_COOKIE);
89
102
  return Array.from(map.entries()).map(([name, value]) => ({ name, value }));
90
103
  },
91
104
  get size(): number {
105
+ assertUnscopedRead('the number of cookies');
92
106
  noteCookieReadForReactCache(ANY_COOKIE);
93
107
  return map.size;
94
108
  },
@@ -234,6 +248,7 @@ export function getCookieJar(): RequestCookies {
234
248
  },
235
249
 
236
250
  toString(): string {
251
+ assertUnscopedRead('every cookie');
237
252
  noteCookieReadForReactCache(ANY_COOKIE);
238
253
  // Re-encode values when serializing as a Cookie header — the
239
254
  // RYW map holds decoded logical values, but a Cookie header has
@@ -317,6 +332,8 @@ export type CookieDeleteOptions = Omit<CookieOptions, 'maxAge' | 'expires'>;
317
332
  export interface RequestCookies {
318
333
  /** Get a cookie value by name. Returns undefined if not present. */
319
334
  get(name: string): string | undefined;
335
+ /** @internal A typed definition's read (`defineCookie().get()`). */
336
+ [COOKIE_READ_THROUGH]?: CookieReadThrough;
320
337
  /** Check if a cookie exists. */
321
338
  has(name: string): boolean;
322
339
  /** Get all cookies as an array of { name, value } pairs. */
@@ -22,6 +22,7 @@
22
22
  */
23
23
 
24
24
  import type { Readable } from 'node:stream';
25
+ import { isAppStackFrame } from './framework-stack-frames.ts';
25
26
  import { nodeStreamsPlatform } from './node-streams-platform.ts';
26
27
  import { releaseReason } from './render-utils.ts';
27
28
  import { withTimeout } from './render-timeout.ts';
@@ -126,6 +127,7 @@ export type WebFlightRenderer = (
126
127
  signal?: AbortSignal;
127
128
  temporaryReferences?: WeakMap<object, string>;
128
129
  identifierPrefix?: string;
130
+ filterStackFrame?: (url: string, functionName: string) => boolean;
129
131
  }
130
132
  ) => ReadableStream<Uint8Array>;
131
133
 
@@ -136,11 +138,13 @@ export type NodeFlightRenderer = (
136
138
  onError?: (error: unknown) => string | void;
137
139
  temporaryReferences?: WeakMap<object, string>;
138
140
  identifierPrefix?: string;
141
+ filterStackFrame?: (url: string, functionName: string) => boolean;
139
142
  }
140
143
  ) => import('./flight-source-node.ts').PipeableFlight;
141
144
 
142
145
  /**
143
- * Build `renderFlight()` from the platform's renderers. The Node renderer is
146
+ * Build `renderFlight()` from the platform's renderers. Every render filters
147
+ * timber's own frames out of its dev debug info (framework-stack-frames.ts). The Node renderer is
144
148
  * used whenever it was loaded (on Node it always is — see `rsc-runtime/rsc.ts`);
145
149
  * otherwise every render is a Web stream.
146
150
  *
@@ -162,6 +166,7 @@ export function createRenderFlight(
162
166
  onError: options.onError,
163
167
  temporaryReferences: options.temporaryReferences,
164
168
  identifierPrefix: options.identifierPrefix,
169
+ filterStackFrame: isAppStackFrame,
165
170
  }),
166
171
  {
167
172
  signal: options.signal,
@@ -177,6 +182,7 @@ export function createRenderFlight(
177
182
  signal: options.signal,
178
183
  temporaryReferences: options.temporaryReferences,
179
184
  identifierPrefix: options.identifierPrefix,
185
+ filterStackFrame: isAppStackFrame,
180
186
  });
181
187
  const timeoutMs = options.timeoutMs ?? defaultRenderTimeoutMs;
182
188
  return {
@@ -0,0 +1,44 @@
1
+ /**
2
+ * Which stack frames development Flight treats as the app's own.
3
+ *
4
+ * Dev Flight writes debug rows for the async work a server component awaited,
5
+ * awaited values included — but only for awaits made from app code, judged by
6
+ * the render's `filterStackFrame`. React's default counts everything outside
7
+ * `node_modules` as app code. Installed, timber sits in `node_modules`; run
8
+ * from source (this repo, its examples, a linked checkout) its own files would
9
+ * count as app code, and its internal awaits would be written into every dev
10
+ * payload. Segment captures make that a leak: a capture's reads await the
11
+ * segment's decoded content, so a skipped segment's content would be sent as
12
+ * the debug value of the read a decision chained through
13
+ * (design/52-segment-hash-dedupe.md §"Capture").
14
+ *
15
+ * Next.js passes its own `filterStackFrameDEV` for the same reason; its code
16
+ * is always in `node_modules`, so it filters by source map instead.
17
+ */
18
+
19
+ /**
20
+ * The directory of the framework package this module was loaded from — its
21
+ * `src/` or `dist/` parent. Null when the module URL does not show one (a
22
+ * bundled Worker), where the default filter is all there is.
23
+ */
24
+ function frameworkRoot(moduleUrl: string | undefined): string | null {
25
+ if (!moduleUrl) return null;
26
+ const path = stripFileScheme(moduleUrl);
27
+ const at = Math.max(path.lastIndexOf('/src/'), path.lastIndexOf('/dist/'));
28
+ return at > 0 ? path.slice(0, at + 1) : null;
29
+ }
30
+
31
+ function stripFileScheme(url: string): string {
32
+ return url.startsWith('file://') ? decodeURI(url.slice('file://'.length)) : url;
33
+ }
34
+
35
+ const FRAMEWORK_ROOT = frameworkRoot(import.meta.url);
36
+
37
+ /**
38
+ * `filterStackFrame` for every Flight render: React's default (no anonymous,
39
+ * `node:` or `node_modules` frames), and no frames from timber itself.
40
+ */
41
+ export function isAppStackFrame(url: string): boolean {
42
+ if (url === '' || url.startsWith('node:') || url.includes('node_modules')) return false;
43
+ return FRAMEWORK_ROOT === null || !stripFileScheme(url).startsWith(FRAMEWORK_ROOT);
44
+ }
@@ -8,6 +8,13 @@ export type { AccessContext } from './types.ts';
8
8
  export type { MiddlewareContext } from './types.ts';
9
9
  export type { RouteContext } from './types.ts';
10
10
  export type { Metadata, MetadataRoute, MetadataHandler, MetadataResult } from './types.ts';
11
+ export type {
12
+ LayoutOptions,
13
+ PageOptions,
14
+ RoutePrerender,
15
+ SegmentKey,
16
+ SegmentLifetime,
17
+ } from './types.ts';
11
18
 
12
19
  // Request Context — ALS-backed accessors (all sync)
13
20
  // Prefer defineSearchParams().get() and getSegmentParams(SEGMENT_PATH) for typed access.
@@ -73,7 +73,7 @@ export type ParamCombo = CoercedParams;
73
73
 
74
74
  /**
75
75
  * Resolve the param combos to capture for a route. Static routes have
76
- * exactly one combo (the empty record) — `export const prerender`-style
76
+ * exactly one combo (the empty record) — `pageOptions.prerender`-style
77
77
  * components on static pages need no enumerator. Dynamic routes require
78
78
  * `generateStaticSegmentParams` (design/44 §generateStaticSegmentParams);
79
79
  * without it every request renders live and the wrapper is a no-op.
@@ -212,6 +212,13 @@ export async function capturePrebuiltPayloads(
212
212
  // entries awaiting the param-independence decision after all combos.
213
213
  const pendingByComponent = new Map<string, { anyParamRead: boolean; entries: PendingEntry[] }>();
214
214
 
215
+ // Failed renders of components that no call site passes statically
216
+ // readable props to, so they were rendered with `{}` (see propsSets below).
217
+ // Such a render usually fails identically for every param combo — one log
218
+ // line per combo is noise, so the first is logged with a hint and the rest
219
+ // are counted (still recorded in summary.skipped) and reported once.
220
+ const emptyPropsFailures = new Map<string, number>();
221
+
215
222
  const skip = (issue: CaptureIssue) => {
216
223
  summary.skipped.push(issue);
217
224
  log(
@@ -348,8 +355,8 @@ export async function capturePrebuiltPayloads(
348
355
  // path (e.g., required prop access) and fail the build for a
349
356
  // shape no JSX call site actually uses.
350
357
  const capturedProps = options.callSiteProps?.[componentId];
351
- const propsSets: Record<string, unknown>[] =
352
- capturedProps && capturedProps.length > 0 ? [...capturedProps] : [{}];
358
+ const rendersEmptyProps = !capturedProps || capturedProps.length === 0;
359
+ const propsSets: Record<string, unknown>[] = rendersEmptyProps ? [{}] : [...capturedProps];
353
360
 
354
361
  let pending = pendingByComponent.get(componentId);
355
362
  if (!pending) {
@@ -423,6 +430,19 @@ export async function capturePrebuiltPayloads(
423
430
  if (outcome.failure instanceof BuildTimeContextError) {
424
431
  summary.hardErrors.push(issue);
425
432
  log(`[timber] BUILD ERROR: ${issue.message}`);
433
+ } else if (rendersEmptyProps) {
434
+ const failures = (emptyPropsFailures.get(componentId) ?? 0) + 1;
435
+ emptyPropsFailures.set(componentId, failures);
436
+ if (failures === 1) {
437
+ skip({
438
+ ...issue,
439
+ message:
440
+ `${issue.message} (rendered with empty props: no call site with statically ` +
441
+ `readable props was found — pass literals, not spreads or computed values)`,
442
+ });
443
+ } else {
444
+ summary.skipped.push(issue);
445
+ }
426
446
  } else {
427
447
  skip(issue);
428
448
  }
@@ -486,6 +506,14 @@ export async function capturePrebuiltPayloads(
486
506
  }
487
507
  }
488
508
 
509
+ for (const [componentId, failures] of emptyPropsFailures) {
510
+ if (failures < 2) continue;
511
+ log(
512
+ `[timber] cache.component skipped "${componentId}" for ${failures} param combos in all, ` +
513
+ `each rendered with empty props — those requests render live`
514
+ );
515
+ }
516
+
489
517
  // Emit remaining buffered entries — only param-independent components
490
518
  // still have entries here (param-dependent entries were emitted eagerly
491
519
  // above, TIM-1179). Collapse to one entry per props set (TIM-1175).
@@ -20,7 +20,11 @@ import {
20
20
  type ActionErrorForRender,
21
21
  type RequestContextStore,
22
22
  } from './als-registry.ts';
23
- import { _setGetSearchParamsFn, _setGetSegmentParamsFn } from '../shared/als-slots.ts';
23
+ import {
24
+ _setGetSearchParamsFn,
25
+ _setGetSegmentParamsFn,
26
+ type SearchParamsReader,
27
+ } from '../shared/als-slots.ts';
24
28
  import { appVisibleSearch } from '../shared/rsc-cache-key.ts';
25
29
  import {
26
30
  mergeSlotParams,
@@ -29,6 +33,11 @@ import {
29
33
  } from '../shared/slot-params.ts';
30
34
  import { isDebug } from './debug.ts';
31
35
  import { runWithReactCacheScope, type ReactCacheScope } from './react-cache-scope.ts';
36
+ import {
37
+ assertSearchParamsRead,
38
+ assertUnscopedRead,
39
+ scopedParams,
40
+ } from './segment-lifetime/read-rule.ts';
32
41
  import type { ReactFormState } from 'react-dom/client';
33
42
 
34
43
  // Re-export the ALS for framework-internal consumers that need direct access.
@@ -50,6 +59,9 @@ export function getHeaders(): ReadonlyHeaders {
50
59
  'It can only be used in middleware, access checks, server components, and server actions.'
51
60
  );
52
61
  }
62
+ // A 'document' segment may not depend on headers — nor on the pathname,
63
+ // which reaches a component only through one (design/53).
64
+ assertUnscopedRead('the request headers');
53
65
 
54
66
  return store.headers;
55
67
  }
@@ -71,8 +83,12 @@ export function getHeader(name: string): string | undefined {
71
83
  * Returns the current request's raw URLSearchParams.
72
84
  *
73
85
  * @internal — not part of the public API. Use `defineSearchParams().get()` instead.
86
+ *
87
+ * @param reader The definition the caller parses through (its fields, codecs
88
+ * and URL keys), checked against a 'document' segment's key. Omitted for a
89
+ * raw read.
74
90
  */
75
- export function getSearchParams(): URLSearchParams {
91
+ export function getSearchParams(reader?: SearchParamsReader): URLSearchParams {
76
92
  const store = requestContextAls.getStore();
77
93
  if (!store) {
78
94
  throw new Error(
@@ -80,6 +96,10 @@ export function getSearchParams(): URLSearchParams {
80
96
  'It can only be used in middleware, access checks, server components, and server actions.'
81
97
  );
82
98
  }
99
+ // A definition's `.get()` passes what it parses; a 'document' segment may
100
+ // read only fields its key reads the same way, and never the raw params.
101
+ if (reader) assertSearchParamsRead(reader);
102
+ else assertUnscopedRead('the raw search params');
83
103
 
84
104
  return store.searchParams;
85
105
  }
@@ -128,7 +148,8 @@ export function getSegmentParams(segmentPath?: string): CoercedParams {
128
148
  // client's useSegmentParams() also reads, so the two halves of one
129
149
  // documented API cannot drift (TIM-1285).
130
150
  const slotResolved = resolveSegmentParams(store.segmentParams, store.slotParams, segmentPath);
131
- if (slotResolved !== store.segmentParams) return slotResolved;
151
+ // Inside a 'document' segment, a param outside its key throws (design/53).
152
+ if (slotResolved !== store.segmentParams) return scopedParams(slotResolved);
132
153
 
133
154
  // Dev-mode validation: warn when the segment path expects dynamic
134
155
  // segments that don't exist on the actual matched segment. This catches
@@ -149,7 +170,7 @@ export function getSegmentParams(segmentPath?: string): CoercedParams {
149
170
  }
150
171
  }
151
172
 
152
- return store.segmentParams;
173
+ return scopedParams(store.segmentParams);
153
174
  }
154
175
 
155
176
  /**
@@ -318,6 +339,9 @@ function extractDynamicSegments(route: string): string[] {
318
339
  */
319
340
  export function getRequestSearchString(): string {
320
341
  const store = requestContextAls.getStore();
342
+ // A 'document' segment's redirect cannot carry search params outside its
343
+ // key (design/53): what it redirects to would freeze.
344
+ if (store) assertUnscopedRead('the raw search params');
321
345
  return store?.searchString ?? '';
322
346
  }
323
347
 
@@ -40,7 +40,13 @@ import {
40
40
  childrenOutletKey,
41
41
  computeSegmentKeys,
42
42
  computeSegmentTreePaths,
43
+ layoutOutletKey,
44
+ pageOutletKey,
43
45
  } from '../routing/segment-keys.ts';
46
+ import { documentOutletFor, pathParamNames } from './segment-lifetime/document-outlet.ts';
47
+ import { getSegmentParams } from './request-context.ts';
48
+ import { inReadScope, readScopeFor } from './segment-lifetime/read-scope.ts';
49
+ import type { ServerComponent } from './subtree-walk.ts';
44
50
  import { outletGate, type OutletSpec, type SegmentHashRender } from './segment-hash/outlet.ts';
45
51
  import { METADATA_OUTLET_PATH } from '../shared/outlet-decision.ts';
46
52
  import { setFirstDeniedSegmentIndex } from './deny-boundary.ts';
@@ -195,8 +201,19 @@ export async function buildRouteElement(
195
201
  // placed below each AccessGate — denied segments' metadata() never
196
202
  // executes because AccessGate prevents MetadataCollector from rendering.
197
203
  // No pre-render access pass needed. See TIM-1363.
198
- const { metadataSources, layoutComponents, PageComponent, deferSuspenseFor, accessFns } =
199
- await loadRouteModules(segments, req.url);
204
+ const {
205
+ metadataSources,
206
+ layoutComponents,
207
+ PageComponent: LoadedPage,
208
+ deferSuspenseFor,
209
+ accessFns,
210
+ documentLifetimes,
211
+ } = await loadRouteModules(segments, req.url, render.defaultLayoutLifetime);
212
+ // The coerced params every 'document' key on the main chain reads from —
213
+ // read only when a segment needs them.
214
+ const hasDocumentSegment =
215
+ documentLifetimes.page !== undefined || documentLifetimes.layouts.some(Boolean);
216
+ const mainParams = hasDocumentSegment ? getSegmentParams() : {};
200
217
  // An intercepted navigation renders a route its URL does not name. The
201
218
  // URL's whole access chain gates the tree, from its top, with the URL's
202
219
  // params; the segments both chains share get no gate of their own here, so
@@ -220,6 +237,20 @@ export async function buildRouteElement(
220
237
  // compares against. One derivation, so a slot cannot be keyed two ways.
221
238
  const segmentTreePaths = computeSegmentTreePaths(segments);
222
239
 
240
+ // A 'document' page runs in its read scope: a read outside its key throws
241
+ // (segment-lifetime/read-scope.ts). A client page never runs on the server.
242
+ const PageComponent =
243
+ documentLifetimes.page && !isClientReference(LoadedPage)
244
+ ? inReadScope(
245
+ LoadedPage as ServerComponent,
246
+ readScopeFor(
247
+ pageOutletKey(segmentTreePaths[segments.length - 1]),
248
+ documentLifetimes.page,
249
+ pathParamNames(segments, segments.length - 1)
250
+ )
251
+ )
252
+ : LoadedPage;
253
+
223
254
  // Build deny page fallback chains for each segment position.
224
255
  // When AccessGate or PageDenyBoundary catches a DenySignal, they render
225
256
  // the matching deny page in-tree instead of throwing into React Flight.
@@ -281,6 +312,28 @@ export async function buildRouteElement(
281
312
  element = h(TracedPage, {});
282
313
  }
283
314
 
315
+ // A 'document' page has an outlet of its own, so it can be skipped while
316
+ // the layouts above it and the metadata beside it are decided on their own
317
+ // (design/53-segment-lifetime.md §"Skipping"). Inside every access gate and
318
+ // error boundary of its segment, so access always runs.
319
+ let pageOutlet: OutletSpec | undefined;
320
+ if (documentLifetimes.page) {
321
+ const segmentPath = pageOutletKey(segmentTreePaths[leafIndex]);
322
+ pageOutlet = {
323
+ segmentPath,
324
+ content: element,
325
+ nested: [],
326
+ document: await documentOutletFor(
327
+ render,
328
+ segmentPath,
329
+ documentLifetimes.page,
330
+ pathParamNames(segments, leafIndex),
331
+ mainParams
332
+ ),
333
+ };
334
+ element = outletGate(pageOutlet, render);
335
+ }
336
+
284
337
  // Metadata is its own outlet, a SIBLING of the page rather than a wrapper.
285
338
  // React renders siblings concurrently — the page starts immediately while
286
339
  // MetadataHead awaits metadata promises. Float hoists the head elements to
@@ -310,7 +363,7 @@ export async function buildRouteElement(
310
363
  // the next outlet out will hold directly. A skipped outlet carries their
311
364
  // decisions, because the client's cached copy of it still holds the old
312
365
  // ones (segment-hash/outlet.ts).
313
- let unclaimedOutlets: OutletSpec[] = [metadataOutlet];
366
+ let unclaimedOutlets: OutletSpec[] = pageOutlet ? [metadataOutlet, pageOutlet] : [metadataOutlet];
314
367
 
315
368
  for (let i = segments.length - 1; i >= 0; i--) {
316
369
  const segment = segments[i];
@@ -351,6 +404,11 @@ export async function buildRouteElement(
351
404
  // See design/04-authorization.md §"Access Failure".
352
405
  if (layoutComponent) {
353
406
  const segmentId = segmentKeys[i];
407
+ // A 'document' layout's outlet is keyed by its tree path: its skip is
408
+ // identity-addressed, and segment ids collide across route groups
409
+ // (`layoutOutletKey`). A 'request' layout keeps its segment id.
410
+ const layoutLifetime = documentLifetimes.layouts[i];
411
+ const layoutOutletPath = layoutLifetime ? layoutOutletKey(segmentTreePaths[i]) : segmentId;
354
412
 
355
413
  // Everything this layout receives as `children` is one outlet, and the
356
414
  // layout's own outlet below is another: the layout's hash covers its
@@ -397,7 +455,13 @@ export async function buildRouteElement(
397
455
  // AccessGate and PageDenyBoundary). Without this, DenySignal
398
456
  // escapes to React Flight onError and triggers the re-render
399
457
  // fallback path. See TIM-668, design/04-authorization.md.
400
- const layoutComponentRef = layoutComponent;
458
+ // A 'document' layout runs in its read scope (segment-lifetime/read-scope.ts).
459
+ const layoutComponentRef = layoutLifetime
460
+ ? inReadScope(
461
+ layoutComponent as ServerComponent,
462
+ readScopeFor(layoutOutletPath, layoutLifetime, pathParamNames(segments, i))
463
+ )
464
+ : layoutComponent;
401
465
  const layoutDenyPages = denyPageChains.get(i);
402
466
  const TracedLayout = async (props: Record<string, unknown>) => {
403
467
  try {
@@ -442,7 +506,7 @@ export async function buildRouteElement(
442
506
  }
443
507
 
444
508
  const layoutOutlet: OutletSpec = {
445
- segmentPath: segmentId,
509
+ segmentPath: layoutOutletPath,
446
510
  content: h(clientComponents().SegmentProvider, {
447
511
  segments: segmentPath,
448
512
  segmentId,
@@ -450,6 +514,17 @@ export async function buildRouteElement(
450
514
  children: layoutElement,
451
515
  }),
452
516
  nested: [childrenOutlet, ...slots.outlets],
517
+ // The URL depth the layout's `SegmentProvider` publishes is part of
518
+ // its output: a key that leaves out a catch-all must still re-render
519
+ // the layout when the depth it reports changes.
520
+ document: await documentOutletFor(
521
+ render,
522
+ layoutOutletPath,
523
+ layoutLifetime,
524
+ pathParamNames(segments, i),
525
+ mainParams,
526
+ segmentPath.length
527
+ ),
453
528
  };
454
529
  element = outletGate(layoutOutlet, render);
455
530
  unclaimedOutlets = [layoutOutlet];
@@ -9,9 +9,15 @@
9
9
  */
10
10
 
11
11
  import type { ManifestSegmentNode } from './route-matcher.ts';
12
- import type { Metadata } from './types.ts';
12
+ import type { Metadata, SegmentLifetime } from './types.ts';
13
13
  import { loadModule } from './safe-load.ts';
14
+ import { ROUTE_OPTIONS_EXPORT } from '../shared/route-options-export.ts';
14
15
  import { NoPageComponentError, type LayoutComponentEntry } from './route-element-builder.ts';
16
+ import {
17
+ defaultLayoutLifetimeAt,
18
+ readDocumentLifetime,
19
+ type DocumentLifetime,
20
+ } from './segment-lifetime/segment-key.ts';
15
21
 
16
22
  /** Metadata export from a layout or page module, with its segment context. */
17
23
  export interface MetadataSource {
@@ -31,6 +37,8 @@ export interface LoadedRouteModules {
31
37
  PageComponent: (...args: unknown[]) => unknown;
32
38
  deferSuspenseFor: number;
33
39
  accessFns: Array<AccessFn>;
40
+ /** `'document'` lifetimes (design/53), by segment index for layouts. */
41
+ documentLifetimes: { layouts: Array<DocumentLifetime | undefined>; page?: DocumentLifetime };
34
42
  }
35
43
 
36
44
  /**
@@ -51,14 +59,23 @@ function rejectLegacyGenerateMetadata(mod: Record<string, unknown>, filePath: st
51
59
  }
52
60
 
53
61
  /**
54
- * Extract `deferSuspenseFor` from a module and return the maximum
55
- * of the current value and the module's value.
62
+ * Return the maximum of `current` and the module's `deferSuspenseFor`
63
+ * option — `layoutOptions.deferSuspenseFor` in a layout,
64
+ * `pageOptions.deferSuspenseFor` in a page (design/53 §"Route-module
65
+ * options"). The build validated the object it could read from source
66
+ * (`routing/route-options.ts`); this runtime read is what takes effect.
56
67
  */
57
- function extractDeferSuspenseFor(mod: Record<string, unknown>, current: number): number {
58
- if (typeof mod.deferSuspenseFor === 'number' && mod.deferSuspenseFor > current) {
59
- return mod.deferSuspenseFor;
68
+ function extractDeferSuspenseFor(
69
+ mod: Record<string, unknown>,
70
+ isPage: boolean,
71
+ current: number
72
+ ): number {
73
+ const options = mod[ROUTE_OPTIONS_EXPORT[isPage ? 'page' : 'layout']];
74
+ if (typeof options !== 'object' || options === null || !('deferSuspenseFor' in options)) {
75
+ return current;
60
76
  }
61
- return current;
77
+ const value = options.deferSuspenseFor;
78
+ return typeof value === 'number' && value > current ? value : current;
62
79
  }
63
80
 
64
81
  /**
@@ -83,7 +100,7 @@ function collectModuleExports(
83
100
  segmentIndex,
84
101
  });
85
102
  }
86
- return extractDeferSuspenseFor(mod, currentDefer);
103
+ return extractDeferSuspenseFor(mod, isPage, currentDefer);
87
104
  }
88
105
 
89
106
  /**
@@ -94,13 +111,16 @@ function collectModuleExports(
94
111
  */
95
112
  export async function loadRouteModules(
96
113
  segments: ManifestSegmentNode[],
97
- requestUrl: string
114
+ requestUrl: string,
115
+ /** The app's `defaultLayoutLifetime` (design/53 §"App-wide default"). */
116
+ defaultLayoutLifetime: SegmentLifetime
98
117
  ): Promise<LoadedRouteModules> {
99
118
  const metadataSources: MetadataSource[] = [];
100
119
  const layoutComponents: LayoutComponentEntry[] = [];
101
120
  const accessFns: Array<AccessFn> = [];
102
121
  let PageComponent: ((...args: unknown[]) => unknown) | null = null;
103
122
  let deferSuspenseFor = 0;
123
+ const documentLifetimes: LoadedRouteModules['documentLifetimes'] = { layouts: [] };
104
124
 
105
125
  for (let i = 0; i < segments.length; i++) {
106
126
  const segment = segments[i];
@@ -108,6 +128,11 @@ export async function loadRouteModules(
108
128
 
109
129
  if (segment.layout) {
110
130
  const mod = await loadModule(segment.layout);
131
+ documentLifetimes.layouts[i] = readDocumentLifetime(
132
+ mod,
133
+ 'layout',
134
+ defaultLayoutLifetimeAt(segments.slice(0, i + 1), defaultLayoutLifetime)
135
+ );
111
136
  if (mod.default) {
112
137
  layoutComponents.push({
113
138
  component: mod.default as (...args: unknown[]) => unknown,
@@ -129,6 +154,7 @@ export async function loadRouteModules(
129
154
  if (mod.default) {
130
155
  PageComponent = mod.default as (...args: unknown[]) => unknown;
131
156
  }
157
+ documentLifetimes.page = readDocumentLifetime(mod, 'page', 'request');
132
158
  deferSuspenseFor = collectModuleExports(
133
159
  mod,
134
160
  segment,
@@ -157,5 +183,12 @@ export async function loadRouteModules(
157
183
  );
158
184
  }
159
185
 
160
- return { metadataSources, layoutComponents, PageComponent, deferSuspenseFor, accessFns };
186
+ return {
187
+ metadataSources,
188
+ layoutComponents,
189
+ PageComponent,
190
+ deferSuspenseFor,
191
+ accessFns,
192
+ documentLifetimes,
193
+ };
161
194
  }
@@ -25,7 +25,12 @@
25
25
  * See design/19-client-navigation.md §"The `_rsc` cache key".
26
26
  */
27
27
 
28
- import { rscCacheKey, isRscCacheKeyShape, RSC_KEY_PARAM } from '../shared/rsc-cache-key.ts';
28
+ import {
29
+ rscCacheKey,
30
+ isRscCacheKeyShape,
31
+ RSC_KEY_PARAM,
32
+ stateTreeHasDocuments,
33
+ } from '../shared/rsc-cache-key.ts';
29
34
  import { isRscContentType } from '../shared/rsc-media-type.ts';
30
35
  import { preventResponseCaching } from './response-cache-policy.ts';
31
36
 
@@ -108,7 +113,9 @@ export function hardenRscPayloadResponse(response: Response): void {
108
113
  * harmless lets a CDN apply heuristic caching to a response that has none.
109
114
  *
110
115
  * The cost is that a mismatched request loses developer-chosen *browser*
111
- * caching too. That is a request no timber client ever makes.
116
+ * caching too. A mismatch is a request no timber client ever makes. A request
117
+ * carrying 'document' key digests is one every client holding such a segment
118
+ * makes; it is private, no-store by default anyway.
112
119
  *
113
120
  * Purge tags (`Surrogate-Key`, `Cache-Tag`) are deliberately left alone:
114
121
  * they address stored entries, and this response is not stored.
@@ -117,6 +124,14 @@ export function hardenRscPayloadResponse(response: Response): void {
117
124
  * headers at this point (see TIM-866).
118
125
  */
119
126
  export async function enforceRscCacheKey(req: Request, response: Response): Promise<void> {
127
+ // A request carrying 'document' key digests gets a response that depends
128
+ // on them — skips — while its `_rsc` key deliberately leaves them out
129
+ // (`stateTreeKeyValue`). Stored under that key, it would be served to a
130
+ // client that holds none of the skipped content. Same rule as a mismatch.
131
+ if (stateTreeHasDocuments(req.headers.get('X-Timber-State-Tree'))) {
132
+ preventResponseCaching(response.headers);
133
+ return;
134
+ }
120
135
  if (await hasValidRscCacheKey(req)) return;
121
136
  preventResponseCaching(response.headers);
122
137
  }