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

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 (408) hide show
  1. package/dist/_chunks/{actions-DIgnvDrG.js → actions-BkwgRwCl.js} +146 -12
  2. package/dist/_chunks/actions-BkwgRwCl.js.map +1 -0
  3. package/dist/_chunks/{als-registry-PPYstxK0.js → als-registry-C-iwbtvI.js} +4 -3
  4. package/dist/_chunks/{als-registry-PPYstxK0.js.map → als-registry-C-iwbtvI.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-BGA7c5qJ.js} +5 -5
  8. package/dist/_chunks/{cache-api-uWQwuxWb.js.map → cache-api-BGA7c5qJ.js.map} +1 -1
  9. package/dist/_chunks/{chains-C7CExrUI.js → chains-Cuwwjv6T.js} +2 -2
  10. package/dist/_chunks/{chains-C7CExrUI.js.map → chains-Cuwwjv6T.js.map} +1 -1
  11. package/dist/_chunks/chains-LGjBHfSN.js +1 -0
  12. package/dist/_chunks/{classify-Cj9EeZoL.js → classify-Y8S9C0Na.js} +2 -2
  13. package/dist/_chunks/{classify-Cj9EeZoL.js.map → classify-Y8S9C0Na.js.map} +1 -1
  14. package/dist/_chunks/{cli-check-C3QOAru7.js → cli-check-KeE1QaIx.js} +7 -6
  15. package/dist/_chunks/cli-check-KeE1QaIx.js.map +1 -0
  16. package/dist/_chunks/{cli-schema-sync-DQUS_o3V.js → cli-schema-sync-DZEF31wd.js} +2 -2
  17. package/dist/_chunks/{cli-schema-sync-DQUS_o3V.js.map → cli-schema-sync-DZEF31wd.js.map} +1 -1
  18. package/dist/_chunks/{cli-schema-sync-BRxZz66D.js → cli-schema-sync-_y5O6MIg.js} +1 -1
  19. package/dist/_chunks/{client-dep-entries-ZETBdLgv.js → client-dep-entries-DpiwvoDi.js} +2 -2
  20. package/dist/_chunks/{client-dep-entries-ZETBdLgv.js.map → client-dep-entries-DpiwvoDi.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-0AEsPK2T.js} +378 -10
  24. package/dist/_chunks/convention-lint-0AEsPK2T.js.map +1 -0
  25. package/dist/_chunks/dev-server-CboXr8zX.js +1 -0
  26. package/dist/_chunks/{dev-server-C5R6jx8Q.js → dev-server-DYDr8KIc.js} +9 -3
  27. package/dist/_chunks/dev-server-DYDr8KIc.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-wuNvAJ4n.js} +11 -14
  31. package/dist/_chunks/error-boundary-wuNvAJ4n.js.map +1 -0
  32. package/dist/_chunks/{flight-source-node-D9cHBhjP.js → flight-source-node-KQsX_OhS.js} +4 -7
  33. package/dist/_chunks/flight-source-node-KQsX_OhS.js.map +1 -0
  34. package/dist/_chunks/{json-lossy-check-Y1GxqVX_.js → json-lossy-check-BVDALqMf.js} +2 -2
  35. package/dist/_chunks/{json-lossy-check-Y1GxqVX_.js.map → json-lossy-check-BVDALqMf.js.map} +1 -1
  36. package/dist/_chunks/key-headers-uIig1_mU.js +40 -0
  37. package/dist/_chunks/key-headers-uIig1_mU.js.map +1 -0
  38. package/dist/_chunks/{live-graph-BDQWvnMm.js → live-graph-VhzO7Ol9.js} +4 -4
  39. package/dist/_chunks/{live-graph-BDQWvnMm.js.map → live-graph-VhzO7Ol9.js.map} +1 -1
  40. package/dist/_chunks/{logger-DmRR9tmZ.js → logger-C4m8rfMy.js} +2 -2
  41. package/dist/_chunks/{logger-DmRR9tmZ.js.map → logger-C4m8rfMy.js.map} +1 -1
  42. package/dist/_chunks/metadata-routes-MXNjWOt5.js.map +1 -1
  43. package/dist/_chunks/{node-response-yp8zdyRp.js → node-response-8Vz29cGS.js} +2 -2
  44. package/dist/_chunks/{node-response-yp8zdyRp.js.map → node-response-8Vz29cGS.js.map} +1 -1
  45. package/dist/_chunks/{poison-scan-WQgUydF_.js → poison-scan-Dpl3ibG-.js} +2 -2
  46. package/dist/_chunks/{poison-scan-WQgUydF_.js.map → poison-scan-Dpl3ibG-.js.map} +1 -1
  47. package/dist/_chunks/{rsc-cache-key-D0cb0Gmc.js → rsc-cache-key-BGvUtMtN.js} +40 -4
  48. package/dist/_chunks/{rsc-cache-key-D0cb0Gmc.js.map → rsc-cache-key-BGvUtMtN.js.map} +1 -1
  49. package/dist/_chunks/{scanner-C9Lrf77z.js → scanner-CCEHN9Jg.js} +14 -81
  50. package/dist/_chunks/scanner-CCEHN9Jg.js.map +1 -0
  51. package/dist/_chunks/{sizeof-BISkSaU0.js → sizeof-CIF7fwSJ.js} +2 -2
  52. package/dist/_chunks/{sizeof-BISkSaU0.js.map → sizeof-CIF7fwSJ.js.map} +1 -1
  53. package/dist/_chunks/{walkers-Bxv4v7tX.js → walkers-BbotBhNG.js} +3 -3
  54. package/dist/_chunks/{walkers-Bxv4v7tX.js.map → walkers-BbotBhNG.js.map} +1 -1
  55. package/dist/adapters/cloudflare-dev.js +1 -1
  56. package/dist/adapters/cloudflare-kv-cache.js +2 -2
  57. package/dist/adapters/cloudflare.js +1 -1
  58. package/dist/analyze/crawl-entry.js +3 -3
  59. package/dist/analyze/graph-command.js +2 -2
  60. package/dist/cache/index.js +2 -2
  61. package/dist/cache/stores/memory.js +1 -1
  62. package/dist/cdn/workers-cache-purge.js +1 -1
  63. package/dist/cli-check.d.ts +3 -0
  64. package/dist/cli-check.d.ts.map +1 -1
  65. package/dist/cli.js +3 -3
  66. package/dist/client/browser-entry/router-init.d.ts +0 -1
  67. package/dist/client/browser-entry/router-init.d.ts.map +1 -1
  68. package/dist/client/error-boundary.js +1 -1
  69. package/dist/client/index.js +2 -2
  70. package/dist/client/index.js.map +1 -1
  71. package/dist/client/internal.js +4 -5
  72. package/dist/client/internal.js.map +1 -1
  73. package/dist/client/navigation-commit.d.ts +3 -5
  74. package/dist/client/navigation-commit.d.ts.map +1 -1
  75. package/dist/client/outlet-content-cache.d.ts +25 -30
  76. package/dist/client/outlet-content-cache.d.ts.map +1 -1
  77. package/dist/client/outlet-scope-context.d.ts +4 -4
  78. package/dist/client/outlet-scope-context.d.ts.map +1 -1
  79. package/dist/client/params-context.d.ts +1 -1
  80. package/dist/client/router-types.d.ts +3 -13
  81. package/dist/client/router-types.d.ts.map +1 -1
  82. package/dist/client/router.d.ts.map +1 -1
  83. package/dist/client/segment-cache.d.ts +2 -2
  84. package/dist/client/segment-outlet.d.ts +12 -13
  85. package/dist/client/segment-outlet.d.ts.map +1 -1
  86. package/dist/client/stale-segment.d.ts +2 -2
  87. package/dist/config-types.d.ts +22 -15
  88. package/dist/config-types.d.ts.map +1 -1
  89. package/dist/config-validation.d.ts.map +1 -1
  90. package/dist/cookies/define-cookie.d.ts.map +1 -1
  91. package/dist/cookies/index.js +5 -2
  92. package/dist/cookies/index.js.map +1 -1
  93. package/dist/index.d.ts +1 -0
  94. package/dist/index.d.ts.map +1 -1
  95. package/dist/index.js +109 -26
  96. package/dist/index.js.map +1 -1
  97. package/dist/native/rsc/cookies/define-cookie.js +6 -2
  98. package/dist/native/rsc/cookies/define-cookie.js.map +1 -1
  99. package/dist/native/rsc/manifest.json +12 -4
  100. package/dist/native/rsc/routing/segment-keys.js +11 -1
  101. package/dist/native/rsc/routing/segment-keys.js.map +1 -1
  102. package/dist/native/rsc/search-params/define.js +4 -1
  103. package/dist/native/rsc/search-params/define.js.map +1 -1
  104. package/dist/native/rsc/server/als-registry.js +2 -2
  105. package/dist/native/rsc/server/als-registry.js.map +1 -1
  106. package/dist/native/rsc/server/client-state-tree.js +13 -12
  107. package/dist/native/rsc/server/client-state-tree.js.map +1 -1
  108. package/dist/native/rsc/server/cookie-context.js +12 -0
  109. package/dist/native/rsc/server/cookie-context.js.map +1 -1
  110. package/dist/native/rsc/server/flight-source-node.js +2 -5
  111. package/dist/native/rsc/server/flight-source-node.js.map +1 -1
  112. package/dist/native/rsc/server/flight-source.js +8 -40
  113. package/dist/native/rsc/server/flight-source.js.map +1 -1
  114. package/dist/native/rsc/server/framework-stack-frames.js +18 -0
  115. package/dist/native/rsc/server/framework-stack-frames.js.map +1 -0
  116. package/dist/native/rsc/server/prebuilt-builder.js +15 -1
  117. package/dist/native/rsc/server/prebuilt-builder.js.map +1 -1
  118. package/dist/native/rsc/server/request-context.js +11 -5
  119. package/dist/native/rsc/server/request-context.js.map +1 -1
  120. package/dist/native/rsc/server/route-element-builder.js +29 -11
  121. package/dist/native/rsc/server/route-element-builder.js.map +1 -1
  122. package/dist/native/rsc/server/route-module-loader.js +14 -6
  123. package/dist/native/rsc/server/route-module-loader.js.map +1 -1
  124. package/dist/native/rsc/server/rsc-cache-key-guard.js +5 -1
  125. package/dist/native/rsc/server/rsc-cache-key-guard.js.map +1 -1
  126. package/dist/native/rsc/server/rsc-entry/render-route.js +10 -29
  127. package/dist/native/rsc/server/rsc-entry/render-route.js.map +1 -1
  128. package/dist/native/rsc/server/rsc-entry/revalidate-renderer.js +7 -2
  129. package/dist/native/rsc/server/rsc-entry/revalidate-renderer.js.map +1 -1
  130. package/dist/native/rsc/server/rsc-entry/rsc-stream.js +2 -5
  131. package/dist/native/rsc/server/rsc-entry/rsc-stream.js.map +1 -1
  132. package/dist/native/rsc/server/segment-lifetime/document-outlet.js +24 -0
  133. package/dist/native/rsc/server/segment-lifetime/document-outlet.js.map +1 -0
  134. package/dist/native/rsc/server/segment-lifetime/key-digest.js +74 -0
  135. package/dist/native/rsc/server/segment-lifetime/key-digest.js.map +1 -0
  136. package/dist/native/rsc/server/segment-lifetime/outlet-gate.js +44 -0
  137. package/dist/native/rsc/server/segment-lifetime/outlet-gate.js.map +1 -0
  138. package/dist/native/rsc/server/segment-lifetime/read-rule.js +78 -0
  139. package/dist/native/rsc/server/segment-lifetime/read-rule.js.map +1 -0
  140. package/dist/native/rsc/server/segment-lifetime/read-scope.js +41 -0
  141. package/dist/native/rsc/server/segment-lifetime/read-scope.js.map +1 -0
  142. package/dist/native/rsc/server/segment-lifetime/segment-key.js +64 -0
  143. package/dist/native/rsc/server/segment-lifetime/segment-key.js.map +1 -0
  144. package/dist/native/rsc/server/segment-lifetime/slot-outlets.js +72 -0
  145. package/dist/native/rsc/server/segment-lifetime/slot-outlets.js.map +1 -0
  146. package/dist/native/rsc/server/slot-resolver.js +51 -27
  147. package/dist/native/rsc/server/slot-resolver.js.map +1 -1
  148. package/dist/native/rsc/server/slot-subtree-contain.js +17 -89
  149. package/dist/native/rsc/server/slot-subtree-contain.js.map +1 -1
  150. package/dist/native/rsc/server/subtree-walk.js +140 -0
  151. package/dist/native/rsc/server/subtree-walk.js.map +1 -0
  152. package/dist/native/rsc/server/vite-handoff-rsc.js.map +1 -1
  153. package/dist/native/rsc/shared/als-slots.js +2 -2
  154. package/dist/native/rsc/shared/als-slots.js.map +1 -1
  155. package/dist/native/rsc/shared/cookie-read-through.js +5 -0
  156. package/dist/native/rsc/shared/cookie-read-through.js.map +1 -0
  157. package/dist/native/rsc/shared/key-headers.js +20 -0
  158. package/dist/native/rsc/shared/key-headers.js.map +1 -0
  159. package/dist/native/rsc/shared/outlet-decision.js.map +1 -1
  160. package/dist/native/rsc/shared/route-options-export.js +8 -0
  161. package/dist/native/rsc/shared/route-options-export.js.map +1 -0
  162. package/dist/native/rsc/shared/rsc-cache-key.js +19 -3
  163. package/dist/native/rsc/shared/rsc-cache-key.js.map +1 -1
  164. package/dist/native/rsc/shims/headers.js +3 -4
  165. package/dist/native/rsc/shims/headers.js.map +1 -1
  166. package/dist/native/ssr/client/outlet-content-cache.js +12 -18
  167. package/dist/native/ssr/client/outlet-content-cache.js.map +1 -1
  168. package/dist/native/ssr/client/outlet-scope-context.js.map +1 -1
  169. package/dist/native/ssr/client/segment-outlet.js +6 -19
  170. package/dist/native/ssr/client/segment-outlet.js.map +1 -1
  171. package/dist/native/ssr/cookies/define-cookie.js +6 -2
  172. package/dist/native/ssr/cookies/define-cookie.js.map +1 -1
  173. package/dist/native/ssr/manifest.json +5 -1
  174. package/dist/native/ssr/search-params/define.js +4 -1
  175. package/dist/native/ssr/search-params/define.js.map +1 -1
  176. package/dist/native/ssr/server/als-registry.js +2 -2
  177. package/dist/native/ssr/server/als-registry.js.map +1 -1
  178. package/dist/native/ssr/server/client-state-tree.js +13 -12
  179. package/dist/native/ssr/server/client-state-tree.js.map +1 -1
  180. package/dist/native/ssr/server/cookie-context.js +12 -0
  181. package/dist/native/ssr/server/cookie-context.js.map +1 -1
  182. package/dist/native/ssr/server/flight-source-node.js +2 -5
  183. package/dist/native/ssr/server/flight-source-node.js.map +1 -1
  184. package/dist/native/ssr/server/flight-source.js +1 -1
  185. package/dist/native/ssr/server/flight-source.js.map +1 -1
  186. package/dist/native/ssr/server/framework-stack-frames.js +18 -0
  187. package/dist/native/ssr/server/framework-stack-frames.js.map +1 -0
  188. package/dist/native/ssr/server/request-context.js +11 -5
  189. package/dist/native/ssr/server/request-context.js.map +1 -1
  190. package/dist/native/ssr/server/rsc-cache-key-guard.js +5 -1
  191. package/dist/native/ssr/server/rsc-cache-key-guard.js.map +1 -1
  192. package/dist/native/ssr/server/segment-lifetime/key-digest.js +6 -0
  193. package/dist/native/ssr/server/segment-lifetime/key-digest.js.map +1 -0
  194. package/dist/native/ssr/server/segment-lifetime/read-rule.js +78 -0
  195. package/dist/native/ssr/server/segment-lifetime/read-rule.js.map +1 -0
  196. package/dist/native/ssr/server/vite-handoff-rsc.js.map +1 -1
  197. package/dist/native/ssr/shared/als-slots.js +2 -2
  198. package/dist/native/ssr/shared/als-slots.js.map +1 -1
  199. package/dist/native/ssr/shared/cookie-read-through.js +5 -0
  200. package/dist/native/ssr/shared/cookie-read-through.js.map +1 -0
  201. package/dist/native/ssr/shared/key-headers.js +13 -0
  202. package/dist/native/ssr/shared/key-headers.js.map +1 -0
  203. package/dist/native/ssr/shared/rsc-cache-key.js +19 -3
  204. package/dist/native/ssr/shared/rsc-cache-key.js.map +1 -1
  205. package/dist/native/ssr/shims/headers.js +3 -4
  206. package/dist/native/ssr/shims/headers.js.map +1 -1
  207. package/dist/plugins/callsite-jsx.d.ts +8 -1
  208. package/dist/plugins/callsite-jsx.d.ts.map +1 -1
  209. package/dist/plugins/entries.d.ts.map +1 -1
  210. package/dist/plugins/prerender-sugar.d.ts +9 -8
  211. package/dist/plugins/prerender-sugar.d.ts.map +1 -1
  212. package/dist/plugins/routing.d.ts.map +1 -1
  213. package/dist/routing/convention-lint.d.ts +11 -3
  214. package/dist/routing/convention-lint.d.ts.map +1 -1
  215. package/dist/routing/export-detect.d.ts +50 -23
  216. package/dist/routing/export-detect.d.ts.map +1 -1
  217. package/dist/routing/index.js +2 -2
  218. package/dist/routing/route-options-lint.d.ts +36 -0
  219. package/dist/routing/route-options-lint.d.ts.map +1 -0
  220. package/dist/routing/route-options.d.ts +55 -0
  221. package/dist/routing/route-options.d.ts.map +1 -0
  222. package/dist/routing/segment-keys.d.ts +38 -4
  223. package/dist/routing/segment-keys.d.ts.map +1 -1
  224. package/dist/search-params/index.js +5 -2
  225. package/dist/search-params/index.js.map +1 -1
  226. package/dist/server/als-registry.d.ts +22 -13
  227. package/dist/server/als-registry.d.ts.map +1 -1
  228. package/dist/server/client-state-tree.d.ts +11 -10
  229. package/dist/server/client-state-tree.d.ts.map +1 -1
  230. package/dist/server/cookie-context.d.ts +3 -0
  231. package/dist/server/cookie-context.d.ts.map +1 -1
  232. package/dist/server/flight-source-node.d.ts +1 -6
  233. package/dist/server/flight-source-node.d.ts.map +1 -1
  234. package/dist/server/flight-source.d.ts +4 -28
  235. package/dist/server/flight-source.d.ts.map +1 -1
  236. package/dist/server/framework-stack-frames.d.ts +20 -0
  237. package/dist/server/framework-stack-frames.d.ts.map +1 -0
  238. package/dist/server/index.d.ts +1 -0
  239. package/dist/server/index.d.ts.map +1 -1
  240. package/dist/server/index.js +2 -2
  241. package/dist/server/internal.js +102 -28
  242. package/dist/server/internal.js.map +1 -1
  243. package/dist/server/prebuilt/capture-routes.d.ts +1 -1
  244. package/dist/server/prebuilt-builder.d.ts.map +1 -1
  245. package/dist/server/request-context.d.ts +6 -1
  246. package/dist/server/request-context.d.ts.map +1 -1
  247. package/dist/server/route-element-builder.d.ts +2 -2
  248. package/dist/server/route-element-builder.d.ts.map +1 -1
  249. package/dist/server/route-module-loader.d.ts +10 -2
  250. package/dist/server/route-module-loader.d.ts.map +1 -1
  251. package/dist/server/rsc-cache-key-guard.d.ts +3 -1
  252. package/dist/server/rsc-cache-key-guard.d.ts.map +1 -1
  253. package/dist/server/rsc-entry/helpers.d.ts +1 -1
  254. package/dist/server/rsc-entry/index.d.ts.map +1 -1
  255. package/dist/server/rsc-entry/render-route.d.ts +10 -1
  256. package/dist/server/rsc-entry/render-route.d.ts.map +1 -1
  257. package/dist/server/rsc-entry/revalidate-renderer.d.ts +12 -0
  258. package/dist/server/rsc-entry/revalidate-renderer.d.ts.map +1 -1
  259. package/dist/server/rsc-entry/rsc-stream.d.ts +2 -11
  260. package/dist/server/rsc-entry/rsc-stream.d.ts.map +1 -1
  261. package/dist/server/segment-lifetime/document-outlet.d.ts +66 -0
  262. package/dist/server/segment-lifetime/document-outlet.d.ts.map +1 -0
  263. package/dist/server/segment-lifetime/key-digest.d.ts +46 -0
  264. package/dist/server/segment-lifetime/key-digest.d.ts.map +1 -0
  265. package/dist/server/segment-lifetime/outlet-gate.d.ts +58 -0
  266. package/dist/server/segment-lifetime/outlet-gate.d.ts.map +1 -0
  267. package/dist/server/segment-lifetime/read-rule.d.ts +53 -0
  268. package/dist/server/segment-lifetime/read-rule.d.ts.map +1 -0
  269. package/dist/server/segment-lifetime/read-scope.d.ts +40 -0
  270. package/dist/server/segment-lifetime/read-scope.d.ts.map +1 -0
  271. package/dist/server/segment-lifetime/segment-key.d.ts +63 -0
  272. package/dist/server/segment-lifetime/segment-key.d.ts.map +1 -0
  273. package/dist/server/segment-lifetime/slot-outlets.d.ts +81 -0
  274. package/dist/server/segment-lifetime/slot-outlets.d.ts.map +1 -0
  275. package/dist/server/slot-resolver.d.ts +10 -5
  276. package/dist/server/slot-resolver.d.ts.map +1 -1
  277. package/dist/server/slot-subtree-contain.d.ts +2 -6
  278. package/dist/server/slot-subtree-contain.d.ts.map +1 -1
  279. package/dist/server/subtree-walk.d.ts +56 -0
  280. package/dist/server/subtree-walk.d.ts.map +1 -0
  281. package/dist/server/types.d.ts +75 -0
  282. package/dist/server/types.d.ts.map +1 -1
  283. package/dist/server/vite-handoff-rsc.d.ts +1 -10
  284. package/dist/server/vite-handoff-rsc.d.ts.map +1 -1
  285. package/dist/shared/als-slots.d.ts +12 -2
  286. package/dist/shared/als-slots.d.ts.map +1 -1
  287. package/dist/shared/cookie-read-through.d.ts +18 -0
  288. package/dist/shared/cookie-read-through.d.ts.map +1 -0
  289. package/dist/shared/key-headers.d.ts +13 -0
  290. package/dist/shared/key-headers.d.ts.map +1 -0
  291. package/dist/shared/outlet-decision.d.ts +16 -28
  292. package/dist/shared/outlet-decision.d.ts.map +1 -1
  293. package/dist/shared/payload-root.d.ts +1 -1
  294. package/dist/shared/route-options-export.d.ts +13 -0
  295. package/dist/shared/route-options-export.d.ts.map +1 -0
  296. package/dist/shared/rsc-cache-key.d.ts +22 -0
  297. package/dist/shared/rsc-cache-key.d.ts.map +1 -1
  298. package/dist/shared/segment-info.d.ts +7 -5
  299. package/dist/shared/segment-info.d.ts.map +1 -1
  300. package/dist/shims/headers.d.ts.map +1 -1
  301. package/docs/api/30-api-server.mdx +29 -0
  302. package/docs/api/32-api-cache.mdx +10 -4
  303. package/docs/api/34-api-config.mdx +5 -0
  304. package/docs/learn/09-streaming.mdx +6 -2
  305. package/docs/learn/10-caching.mdx +10 -4
  306. package/package.json +1 -1
  307. package/src/cli-check.ts +11 -3
  308. package/src/client/browser-entry/index.ts +0 -2
  309. package/src/client/browser-entry/router-init.ts +2 -4
  310. package/src/client/error-boundary.tsx +1 -1
  311. package/src/client/navigation-commit.ts +9 -14
  312. package/src/client/outlet-content-cache.ts +36 -42
  313. package/src/client/outlet-scope-context.ts +5 -5
  314. package/src/client/params-context.ts +1 -1
  315. package/src/client/router-types.ts +3 -14
  316. package/src/client/router.ts +1 -2
  317. package/src/client/rsc-fetch.ts +1 -1
  318. package/src/client/segment-cache.ts +2 -2
  319. package/src/client/segment-outlet.tsx +19 -45
  320. package/src/client/stale-segment.ts +2 -2
  321. package/src/config-types.ts +23 -15
  322. package/src/config-validation.ts +17 -1
  323. package/src/cookies/define-cookie.ts +5 -1
  324. package/src/index.ts +2 -1
  325. package/src/plugins/callsite-jsx.ts +104 -6
  326. package/src/plugins/entries.ts +3 -1
  327. package/src/plugins/prerender-sugar.ts +34 -18
  328. package/src/plugins/routing.ts +3 -1
  329. package/src/routing/convention-lint.ts +18 -7
  330. package/src/routing/export-detect.ts +14 -117
  331. package/src/routing/route-options-lint.ts +153 -0
  332. package/src/routing/route-options.ts +439 -0
  333. package/src/routing/scanner.ts +1 -1
  334. package/src/routing/segment-keys.ts +53 -4
  335. package/src/rsc-runtime/vendor-types.d.ts +5 -1
  336. package/src/search-params/define.ts +1 -1
  337. package/src/server/als-registry.ts +25 -17
  338. package/src/server/client-state-tree.ts +30 -27
  339. package/src/server/cookie-context.ts +17 -0
  340. package/src/server/flight-source-node.ts +1 -5
  341. package/src/server/flight-source.ts +8 -82
  342. package/src/server/framework-stack-frames.ts +41 -0
  343. package/src/server/index.ts +7 -0
  344. package/src/server/prebuilt/capture-routes.ts +1 -1
  345. package/src/server/prebuilt-builder.ts +30 -2
  346. package/src/server/request-context.ts +31 -6
  347. package/src/server/route-element-builder.ts +92 -18
  348. package/src/server/route-module-loader.ts +43 -10
  349. package/src/server/rsc-cache-key-guard.ts +17 -2
  350. package/src/server/rsc-entry/helpers.ts +1 -1
  351. package/src/server/rsc-entry/index.ts +16 -3
  352. package/src/server/rsc-entry/render-route.ts +22 -51
  353. package/src/server/rsc-entry/revalidate-renderer.ts +16 -2
  354. package/src/server/rsc-entry/rsc-stream.ts +3 -23
  355. package/src/server/segment-lifetime/document-outlet.ts +98 -0
  356. package/src/server/segment-lifetime/key-digest.ts +139 -0
  357. package/src/server/segment-lifetime/outlet-gate.ts +102 -0
  358. package/src/server/segment-lifetime/read-rule.ts +193 -0
  359. package/src/server/segment-lifetime/read-scope.ts +101 -0
  360. package/src/server/segment-lifetime/segment-key.ts +168 -0
  361. package/src/server/segment-lifetime/slot-outlets.ts +180 -0
  362. package/src/server/slot-resolver.ts +103 -60
  363. package/src/server/slot-subtree-contain.ts +35 -182
  364. package/src/server/subtree-walk.ts +316 -0
  365. package/src/server/types.ts +91 -0
  366. package/src/server/vite-handoff-rsc.ts +1 -12
  367. package/src/shared/als-slots.ts +19 -8
  368. package/src/shared/cookie-read-through.ts +18 -0
  369. package/src/shared/key-headers.ts +42 -0
  370. package/src/shared/outlet-decision.ts +16 -30
  371. package/src/shared/payload-root.ts +1 -1
  372. package/src/shared/route-options-export.ts +14 -0
  373. package/src/shared/rsc-cache-key.ts +41 -2
  374. package/src/shared/segment-info.ts +7 -5
  375. package/src/shims/headers.ts +5 -4
  376. package/dist/_chunks/actions-DIgnvDrG.js.map +0 -1
  377. package/dist/_chunks/als-slots-kbQrHTzm.js.map +0 -1
  378. package/dist/_chunks/chains-CSslTUdI.js +0 -1
  379. package/dist/_chunks/cli-check-C3QOAru7.js.map +0 -1
  380. package/dist/_chunks/convention-lint-BoVISNS6.js.map +0 -1
  381. package/dist/_chunks/dev-server-B8roKA3Q.js +0 -1
  382. package/dist/_chunks/dev-server-C5R6jx8Q.js.map +0 -1
  383. package/dist/_chunks/dist-C1Rjlo6s.js.map +0 -1
  384. package/dist/_chunks/error-boundary-DB51f9ih.js.map +0 -1
  385. package/dist/_chunks/flight-source-node-D9cHBhjP.js.map +0 -1
  386. package/dist/_chunks/scanner-C9Lrf77z.js.map +0 -1
  387. package/dist/native/rsc/server/segment-hash/capture.js +0 -107
  388. package/dist/native/rsc/server/segment-hash/capture.js.map +0 -1
  389. package/dist/native/rsc/server/segment-hash/outlet.js +0 -81
  390. package/dist/native/rsc/server/segment-hash/outlet.js.map +0 -1
  391. package/dist/native/rsc/server/segment-hash/stream-tap.js +0 -139
  392. package/dist/native/rsc/server/segment-hash/stream-tap.js.map +0 -1
  393. package/dist/native/rsc/server/segment-hash/value-hash.js +0 -171
  394. package/dist/native/rsc/server/segment-hash/value-hash.js.map +0 -1
  395. package/dist/native/ssr/server/segment-hash/value-hash.js +0 -162
  396. package/dist/native/ssr/server/segment-hash/value-hash.js.map +0 -1
  397. package/dist/server/segment-hash/capture.d.ts +0 -77
  398. package/dist/server/segment-hash/capture.d.ts.map +0 -1
  399. package/dist/server/segment-hash/outlet.d.ts +0 -65
  400. package/dist/server/segment-hash/outlet.d.ts.map +0 -1
  401. package/dist/server/segment-hash/stream-tap.d.ts +0 -49
  402. package/dist/server/segment-hash/stream-tap.d.ts.map +0 -1
  403. package/dist/server/segment-hash/value-hash.d.ts +0 -70
  404. package/dist/server/segment-hash/value-hash.d.ts.map +0 -1
  405. package/src/server/segment-hash/capture.ts +0 -232
  406. package/src/server/segment-hash/outlet.ts +0 -185
  407. package/src/server/segment-hash/stream-tap.ts +0 -244
  408. package/src/server/segment-hash/value-hash.ts +0 -338
@@ -0,0 +1,98 @@
1
+ /**
2
+ * The per-request decision input for a `'document'` segment's outlet: either
3
+ * the client holds content rendered under the current key (skip, without
4
+ * rendering), or the server issues a new digest for content it sends.
5
+ *
6
+ * Decided before the element tree is rendered, while the builder is still
7
+ * async, so the outlet gate decides synchronously and a skipped segment's
8
+ * component is never called (design/53-segment-lifetime.md §"Skipping").
9
+ */
10
+
11
+ import type { CoercedParams } from '../../shared/param-value.ts';
12
+ import type { KeyDigestSigner } from './key-digest.ts';
13
+ import { readKeyValues, type DocumentLifetime } from './segment-key.ts';
14
+
15
+ /** What one render knows about `'document'` keys. */
16
+ export interface DocumentKeys {
17
+ /**
18
+ * The digests the client advertised (`X-Timber-State-Tree` `documents`), by
19
+ * outlet path. Null when no request can skip: a document request, an
20
+ * action's revalidated render, `router.refresh()`.
21
+ */
22
+ client: ReadonlyMap<string, string> | null;
23
+ signer: KeyDigestSigner;
24
+ }
25
+
26
+ /** A `'document'` outlet's decision input. */
27
+ export type DocumentOutlet =
28
+ /** The client's digest verified against this request's key values. */
29
+ | { held: string }
30
+ /** The digest this render issues for the content it sends. */
31
+ | { issued: string };
32
+
33
+ /**
34
+ * Decide a `'document'` outlet from the client's claim and this request's key
35
+ * values. Undefined when the render has no signer (client JavaScript is
36
+ * disabled, so no client can hold anything): the segment renders as a plain
37
+ * live outlet.
38
+ *
39
+ * A claim that does not verify — forged, from another segment, issued under
40
+ * other key values, or from another build — is treated as no claim. A claim
41
+ * that verifies but names content the client no longer holds is caught by
42
+ * the client (`stale-segment`), so a claim is never trusted for correctness.
43
+ */
44
+ export async function prepareDocumentOutlet(
45
+ keys: DocumentKeys | null,
46
+ segmentPath: string,
47
+ values: string
48
+ ): Promise<DocumentOutlet | undefined> {
49
+ if (!keys) return undefined;
50
+ const claimed = keys.client?.get(segmentPath);
51
+ if (claimed !== undefined && (await keys.signer.verify(claimed, segmentPath, values))) {
52
+ return { held: claimed };
53
+ }
54
+ return { issued: await keys.signer.issue(segmentPath, values) };
55
+ }
56
+
57
+ /**
58
+ * The decision input for one segment's outlet: undefined unless the segment
59
+ * is `'document'` and the render can issue digests.
60
+ */
61
+ export async function documentOutletFor(
62
+ render: { documents: DocumentKeys | null },
63
+ segmentPath: string,
64
+ lifetime: DocumentLifetime | undefined,
65
+ pathParams: readonly string[],
66
+ params: CoercedParams,
67
+ /**
68
+ * The URL depth a layout publishes to `useSelectedLayoutSegment(s)`, which
69
+ * sits inside its outlet: when it changes, so does the layout's output,
70
+ * whatever the key says.
71
+ */
72
+ urlDepth?: number
73
+ ): Promise<DocumentOutlet | undefined> {
74
+ if (!lifetime || !render.documents) return undefined;
75
+ const keyValues = readKeyValues(lifetime, pathParams, params);
76
+ return prepareDocumentOutlet(
77
+ render.documents,
78
+ segmentPath,
79
+ urlDepth === undefined ? keyValues : JSON.stringify([keyValues, urlDepth])
80
+ );
81
+ }
82
+
83
+ /**
84
+ * Every param named on the path down to `segments[index]`, outermost first —
85
+ * the default `segmentParams` of a key. A segment can read every param above
86
+ * it, so a new value for any of them must re-render it.
87
+ */
88
+ export function pathParamNames(
89
+ segments: ReadonlyArray<{ paramName?: string }>,
90
+ index: number
91
+ ): string[] {
92
+ const names: string[] = [];
93
+ for (let i = 0; i <= index; i++) {
94
+ const name = segments[i]?.paramName;
95
+ if (name) names.push(name);
96
+ }
97
+ return names;
98
+ }
@@ -0,0 +1,139 @@
1
+ /**
2
+ * The key digest of a `'document'` segment — a keyed, per-render token over
3
+ * the parsed values of the request inputs in its key.
4
+ *
5
+ * Works like an ETag the server can check without storing anything: when a
6
+ * `'document'` segment renders, the server issues a token over its key values
7
+ * and the client stores it beside the content. On the next navigation the
8
+ * client sends it back (`X-Timber-State-Tree` `documents`), the server
9
+ * recomputes the MAC from that request's values, and skips the segment when
10
+ * they match (design/53-segment-lifetime.md §"The key digest").
11
+ *
12
+ * A token is `<nonce>.<mac>`, where
13
+ * `mac = HMAC-SHA256(key, nonce ‖ segmentPath ‖ values)` truncated to 128 bits:
14
+ *
15
+ * - **Keyed.** The key is derived from the build's secret (the server-action
16
+ * encryption key, `TIMBER_ACTIONS_ENCRYPTION_KEY` or plugin-rsc's per-build
17
+ * key) with HKDF under a label of its own, so the two uses never share key
18
+ * material. Without it a token cannot be reversed, and a guessed cookie value
19
+ * cannot be tested against it — a plain hash of a low-entropy value (a role,
20
+ * a short id) could be brute-forced.
21
+ * - **Fresh per render.** Every token carries its own random nonce, so the
22
+ * same session cookie yields a different token on every render and tokens
23
+ * cannot link visits. The nonce travels inside the token, so neither side
24
+ * keeps any nonce state.
25
+ * - **Bound to its segment.** The segment path is MACed with the values, so a
26
+ * token cannot be replayed at another segment with the same key values.
27
+ *
28
+ * Tokens never enter a URL: they are excluded from the `_rsc` cache key
29
+ * (`shared/rsc-cache-key.ts`).
30
+ */
31
+
32
+ /** base64url characters in 16 bytes, unpadded. */
33
+ const PART_LENGTH = 22;
34
+ const PART_BYTES = 16;
35
+
36
+ /** The shape of a token; anything else the client sends is dropped. */
37
+ export const KEY_DIGEST_SHAPE = new RegExp(
38
+ `^[A-Za-z0-9_-]{${PART_LENGTH}}\\.[A-Za-z0-9_-]{${PART_LENGTH}}$`
39
+ );
40
+
41
+ /** HKDF `info` for this use of the build secret. Versioned with the token format. */
42
+ const HKDF_INFO = 'timber segment key digest v1';
43
+
44
+ /** Issues and checks key digests. One per server, shared by every request. */
45
+ export interface KeyDigestSigner {
46
+ /** A new token for a segment rendered with these key values. */
47
+ issue(segmentPath: string, values: string): Promise<string>;
48
+ /** Whether `token` was issued for this segment with these key values. */
49
+ verify(token: string, segmentPath: string, values: string): Promise<boolean>;
50
+ }
51
+
52
+ /**
53
+ * A signer over a base64-encoded secret of at least 32 bytes. The source is
54
+ * read once, on first use, so an entry that reads it from a lazily loaded
55
+ * module pays nothing until a `'document'` segment renders.
56
+ */
57
+ export function createKeyDigestSigner(
58
+ secretSource: () => string | Promise<string>
59
+ ): KeyDigestSigner {
60
+ let keyPromise: Promise<CryptoKey> | undefined;
61
+ const macKey = (): Promise<CryptoKey> => {
62
+ // A failed load is not kept: the next render retries it, rather than every
63
+ // 'document' segment failing until the process restarts.
64
+ keyPromise ??= Promise.resolve(secretSource()).then(async (secret) => {
65
+ const material = await crypto.subtle.importKey('raw', base64ToBytes(secret), 'HKDF', false, [
66
+ 'deriveKey',
67
+ ]);
68
+ return crypto.subtle.deriveKey(
69
+ {
70
+ name: 'HKDF',
71
+ hash: 'SHA-256',
72
+ salt: new Uint8Array(0),
73
+ info: new TextEncoder().encode(HKDF_INFO),
74
+ },
75
+ material,
76
+ { name: 'HMAC', hash: 'SHA-256', length: 256 },
77
+ false,
78
+ ['sign']
79
+ );
80
+ });
81
+ keyPromise.catch(() => {
82
+ keyPromise = undefined;
83
+ });
84
+ return keyPromise;
85
+ };
86
+
87
+ async function mac(nonce: Uint8Array, segmentPath: string, values: string): Promise<Uint8Array> {
88
+ // Length-prefixed by JSON: no segment path or value can be mistaken for
89
+ // the boundary between the two.
90
+ const message = new TextEncoder().encode(JSON.stringify([segmentPath, values]));
91
+ const input = new Uint8Array(nonce.byteLength + message.byteLength);
92
+ input.set(nonce, 0);
93
+ input.set(message, nonce.byteLength);
94
+ const signature = await crypto.subtle.sign('HMAC', await macKey(), input);
95
+ return new Uint8Array(signature, 0, PART_BYTES);
96
+ }
97
+
98
+ return {
99
+ async issue(segmentPath, values) {
100
+ const nonce = crypto.getRandomValues(new Uint8Array(PART_BYTES));
101
+ const tag = await mac(nonce, segmentPath, values);
102
+ return `${bytesToBase64Url(nonce)}.${bytesToBase64Url(tag)}`;
103
+ },
104
+ async verify(token, segmentPath, values) {
105
+ if (!KEY_DIGEST_SHAPE.test(token)) return false;
106
+ const [noncePart, tagPart] = token.split('.');
107
+ const nonce = base64UrlToBytes(noncePart);
108
+ const claimed = base64UrlToBytes(tagPart);
109
+ if (nonce.byteLength !== PART_BYTES || claimed.byteLength !== PART_BYTES) return false;
110
+ return constantTimeEqual(await mac(nonce, segmentPath, values), claimed);
111
+ },
112
+ };
113
+ }
114
+
115
+ /** Compare without an early exit, so timing does not reveal a matching prefix. */
116
+ function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {
117
+ if (a.byteLength !== b.byteLength) return false;
118
+ let diff = 0;
119
+ for (let i = 0; i < a.byteLength; i++) diff |= a[i] ^ b[i];
120
+ return diff === 0;
121
+ }
122
+
123
+ function base64ToBytes(base64: string): Uint8Array<ArrayBuffer> {
124
+ const binary = atob(base64);
125
+ const bytes = new Uint8Array(binary.length);
126
+ for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
127
+ return bytes;
128
+ }
129
+
130
+ function base64UrlToBytes(value: string): Uint8Array {
131
+ const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
132
+ return base64ToBytes(base64 + '='.repeat((4 - (base64.length % 4)) % 4));
133
+ }
134
+
135
+ function bytesToBase64Url(bytes: Uint8Array): string {
136
+ let binary = '';
137
+ for (const byte of bytes) binary += String.fromCharCode(byte);
138
+ return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
139
+ }
@@ -0,0 +1,102 @@
1
+ /**
2
+ * The outlet gate: renders one segment as a `SegmentOutlet` whose decision is
3
+ * either its live content or a skip.
4
+ *
5
+ * Only a `'document'` segment (design/53-segment-lifetime.md) is ever
6
+ * skipped. Its decision is made before the tree renders
7
+ * (`document-outlet.ts`): when the client holds content rendered under the
8
+ * current key digest, the segment is skipped **without rendering**, and its
9
+ * nested outlets are decided as if it had rendered — lifetime does not
10
+ * cascade. Otherwise it is sent live with the digest it rendered under. Every
11
+ * other segment is sent live. Access runs for every segment either way.
12
+ *
13
+ * See design/53-segment-lifetime.md §"Skipping".
14
+ */
15
+
16
+ import { createElement, type ReactElement, type ReactNode } from 'react';
17
+ import type { OutletDecision } from '../../shared/outlet-decision.ts';
18
+ import { clientComponents } from '../vite-handoff-rsc.ts';
19
+ import type { DocumentKeys, DocumentOutlet } from './document-outlet.ts';
20
+ import type { SegmentLifetime } from '../types.ts';
21
+
22
+ /** One outlet in the element tree, and the outlets directly inside it. */
23
+ export interface OutletSpec {
24
+ segmentPath: string;
25
+ content: ReactNode;
26
+ nested: OutletSpec[];
27
+ /** Set on a `'document'` segment's outlet when the render can issue digests. */
28
+ document?: DocumentOutlet;
29
+ }
30
+
31
+ /** Per-request inputs to every gate in one render. */
32
+ export interface SegmentRender {
33
+ /**
34
+ * Key digests for `'document'` segments: the client's, and the signer that
35
+ * issues and checks them. Null when no client router can hold a segment.
36
+ */
37
+ documents: DocumentKeys | null;
38
+ /**
39
+ * The lifetime of a layout that declares none: the app's
40
+ * `defaultLayoutLifetime` (design/53 §"App-wide default"). Pages always
41
+ * default to `'request'`.
42
+ */
43
+ defaultLayoutLifetime: SegmentLifetime;
44
+ }
45
+
46
+ /** A render with no client router to hold segments: every outlet live. */
47
+ export const LIVE_ONLY_RENDER: SegmentRender = {
48
+ documents: null,
49
+ defaultLayoutLifetime: 'request',
50
+ };
51
+
52
+ /**
53
+ * The element for an outlet: a server component that decides when it renders
54
+ * — after every access gate above it.
55
+ *
56
+ * A closure with no props rather than a component taking `{ spec }`:
57
+ * dev Flight serializes a server component's props as debug info, and these
58
+ * would repeat the whole subtree in every dev payload.
59
+ */
60
+ export function outletGate(spec: OutletSpec): ReactElement {
61
+ function OutletGate(): ReactElement {
62
+ const { SegmentOutlet } = clientComponents();
63
+ return createElement(SegmentOutlet, { segmentPath: spec.segmentPath, decision: decide(spec) });
64
+ }
65
+ OUTLET_GATES.add(OutletGate);
66
+ return createElement(OutletGate);
67
+ }
68
+
69
+ /** Every gate component `outletGate` made, so a subtree walk can stop at one. */
70
+ const OUTLET_GATES = new WeakSet<object>();
71
+
72
+ /**
73
+ * Whether `node` is an outlet gate element — the boundary of the segment
74
+ * whose content contains it. A walk over one segment's output (a
75
+ * 'document' segment's read scope) stops here: what renders inside belongs
76
+ * to the nested segment and its own rules.
77
+ */
78
+ export function isOutletGateElement(node: unknown): boolean {
79
+ if (typeof node !== 'object' || node === null || !('type' in node)) return false;
80
+ const type = (node as { type: unknown }).type;
81
+ return typeof type === 'function' && OUTLET_GATES.has(type);
82
+ }
83
+
84
+ function decide(spec: OutletSpec): OutletDecision {
85
+ if (!spec.document) return { children: spec.content };
86
+ if ('issued' in spec.document) return { children: spec.content, digest: spec.document.issued };
87
+ return documentSkip(spec, spec.document.held);
88
+ }
89
+
90
+ /**
91
+ * A `'document'` skip: the segment is not rendered, so nothing says which
92
+ * nested outlets its content would hold — every one is decided. The client
93
+ * renders only those in its cached copy; a nested segment a layout body hid
94
+ * at load is still rendered and serialized here (its own `access.ts` still
95
+ * gates it), which is why a `'document'` layout body is not a data-hiding
96
+ * boundary (design/53 §"What stays frozen").
97
+ */
98
+ function documentSkip(spec: OutletSpec, digest: string): OutletDecision {
99
+ const outlets: Record<string, OutletDecision> = {};
100
+ for (const nested of spec.nested) outlets[nested.segmentPath] = decide(nested);
101
+ return { skip: true, digest, outlets };
102
+ }
@@ -0,0 +1,193 @@
1
+ /**
2
+ * The checks every request-input accessor runs inside a `'document'`
3
+ * segment's read scope (`read-scope.ts`, design/53-segment-lifetime.md §"What
4
+ * a 'document' segment may read"). No React and no render machinery: the
5
+ * accessors in `request-context.ts` and `cookie-context.ts` import this.
6
+ */
7
+
8
+ import { documentReadScopeAls, type DocumentReadScope } from '../als-registry.ts';
9
+ import type { CoercedParams } from '../../shared/param-value.ts';
10
+ import type { SearchParamsReader } from '../../shared/als-slots.ts';
11
+ import type { ReadonlyHeaders } from '../request-context.ts';
12
+ import { isUnkeyableHeader } from '../../shared/key-headers.ts';
13
+
14
+ /** The read scope the current render runs in, if it is a `'document'` segment's. */
15
+ export function currentReadScope(): DocumentReadScope | undefined {
16
+ return documentReadScopeAls.getStore();
17
+ }
18
+
19
+ /** Which part of a key would allow a read, for the error's fix. */
20
+ type KeyPart = 'segmentParams' | 'searchParams' | 'cookies' | 'headers';
21
+
22
+ /**
23
+ * The error for a read outside the key. Names the segment, what was read, and
24
+ * the fix: add it to the key, or make the segment `'request'`.
25
+ */
26
+ export function readOutsideKey(
27
+ scope: DocumentReadScope,
28
+ what: string,
29
+ part?: KeyPart,
30
+ /** Overrides the fix when adding the read to the key is not possible. */
31
+ fixOverride?: string
32
+ ): Error {
33
+ const fix =
34
+ fixOverride ??
35
+ (part
36
+ ? `Add it to key.${part}, or declare lifetime: 'request'.`
37
+ : "A 'document' segment cannot depend on it; declare lifetime: 'request'.");
38
+ return new Error(
39
+ `[timber] ${scope.segmentPath} is lifetime: 'document' (declared, or from defaultLayoutLifetime) ` +
40
+ `and read ${what}, which is not in its key. ` +
41
+ `${fix} The segment is skipped without rendering while its key is unchanged, so the read ` +
42
+ `would freeze at its first value. See design/53-segment-lifetime.md ` +
43
+ `§"What a 'document' segment may read".`
44
+ );
45
+ }
46
+
47
+ /**
48
+ * The request headers as a `'document'` segment may read them: `get` and
49
+ * `has` of a header in its key. Any other name throws, and so does reading
50
+ * them all (iteration, `entries`, `forEach`), which could see headers the
51
+ * key leaves out — the pathname among them.
52
+ */
53
+ export function keyedHeaders(headers: ReadonlyHeaders, scope: DocumentReadScope): ReadonlyHeaders {
54
+ const keyed = (name: string): string => {
55
+ if (scope.headers.has(name.toLowerCase())) return name;
56
+ const what = `the header "${name}"`;
57
+ if (name.toLowerCase() === 'cookie') {
58
+ throw readOutsideKey(
59
+ scope,
60
+ what,
61
+ 'cookies',
62
+ 'Read cookies through a cookie definition in key.cookies.'
63
+ );
64
+ }
65
+ if (isUnkeyableHeader(name)) {
66
+ throw readOutsideKey(
67
+ scope,
68
+ what,
69
+ undefined,
70
+ "A key may not name a credential; declare lifetime: 'request'."
71
+ );
72
+ }
73
+ throw readOutsideKey(scope, what, 'headers');
74
+ };
75
+ const all = (): never => {
76
+ throw readOutsideKey(
77
+ scope,
78
+ 'every request header',
79
+ undefined,
80
+ "Read each header you need with getHeaders().get(name) and add it to key.headers, or declare lifetime: 'request'."
81
+ );
82
+ };
83
+ return {
84
+ get: (name) => headers.get(keyed(name)),
85
+ has: (name) => headers.has(keyed(name)),
86
+ entries: all,
87
+ keys: all,
88
+ values: all,
89
+ forEach: all,
90
+ [Symbol.iterator]: all,
91
+ };
92
+ }
93
+
94
+ /** Throw if the current render may not read `what` at all (raw search params). */
95
+ export function assertUnscopedRead(what: string): void {
96
+ const scope = currentReadScope();
97
+ if (scope) throw readOutsideKey(scope, what);
98
+ }
99
+
100
+ /**
101
+ * Throw if the current render reads search-param fields outside its key. A
102
+ * field is in the key only when the key's definition reads it through the
103
+ * same codec and URL key — a `.pick()` of the keyed definition, or the keyed
104
+ * definition itself. Another definition with a field of the same name may map
105
+ * it to another URL parameter or parse it differently.
106
+ */
107
+ export function assertSearchParamsRead(reader: SearchParamsReader): void {
108
+ const scope = currentReadScope();
109
+ if (!scope) return;
110
+ const outside = Object.keys(reader.codecs).filter((field) => {
111
+ const keyed = scope.searchParams.get(field);
112
+ return (
113
+ !keyed ||
114
+ keyed.codec !== reader.codecs[field] ||
115
+ keyed.urlKey !== (reader.urlKeys[field] ?? field)
116
+ );
117
+ });
118
+ if (outside.length > 0) {
119
+ throw readOutsideKey(scope, `the search params ${outside.join(', ')}`, 'searchParams');
120
+ }
121
+ }
122
+
123
+ /**
124
+ * Throw if the current render reads a cookie outside its key. A keyed cookie
125
+ * is in the key only as its definition parses it, so it may be read only
126
+ * through that definition (`codec` is the reader's); a raw read, or another
127
+ * definition of the same name, could see a difference the key does not.
128
+ */
129
+ export function assertCookieRead(name: string, codec?: unknown): void {
130
+ const scope = currentReadScope();
131
+ if (!scope) return;
132
+ if (!scope.cookies.has(name)) {
133
+ throw readOutsideKey(scope, `the cookie "${name}"`, 'cookies');
134
+ }
135
+ if (codec === undefined || scope.cookies.get(name) !== codec) {
136
+ throw readOutsideKey(
137
+ scope,
138
+ `the raw value of the cookie "${name}" (read it through the definition in its key)`,
139
+ 'cookies'
140
+ );
141
+ }
142
+ }
143
+
144
+ /**
145
+ * Property names that serializers and runtimes read on any object — Flight
146
+ * and `await` probe `then`, React `$$typeof`, JSON `toJSON`. No param can
147
+ * be named these in a way a reader means: they are never refused.
148
+ */
149
+ const OBJECT_PROBES: ReadonlySet<string> = new Set([
150
+ 'then',
151
+ 'toJSON',
152
+ '$$typeof',
153
+ 'constructor',
154
+ 'valueOf',
155
+ 'toString',
156
+ '__proto__',
157
+ ]);
158
+
159
+ /**
160
+ * The params a scoped render sees: reading one outside the key throws. Its
161
+ * own keys are only the params in the key, so spreading it, or passing it to
162
+ * a client component, carries exactly what the segment may depend on.
163
+ */
164
+ export function scopedParams<T extends CoercedParams>(params: T): T {
165
+ const scope = currentReadScope();
166
+ if (!scope) return params;
167
+ // Refused: every name the key leaves out — a param on the segment's path, a
168
+ // descendant's or a slot's, present in this request or not. Absence is a
169
+ // value too: a layout reading a child's param that this URL lacks would
170
+ // freeze `undefined` across the URLs that have it. Only the names runtimes
171
+ // probe on any object pass.
172
+ const refused = (name: string | symbol) =>
173
+ typeof name === 'string' && !scope.params.has(name) && !OBJECT_PROBES.has(name);
174
+ const allowed = (name: string | symbol) => !refused(name);
175
+ // Over a copy: the trap hides keys, which a frozen or non-configurable
176
+ // target would forbid, and the request's own record stays untouched.
177
+ const target = Object.assign(
178
+ Object.create(Object.getPrototypeOf(params) as object | null) as T,
179
+ params
180
+ );
181
+ return new Proxy(target, {
182
+ get(target, name, receiver) {
183
+ if (refused(name)) {
184
+ throw readOutsideKey(scope, `the segment param "${String(name)}"`, 'segmentParams');
185
+ }
186
+ return Reflect.get(target, name, receiver);
187
+ },
188
+ has: (target, name) => allowed(name) && Reflect.has(target, name),
189
+ ownKeys: (target) => Reflect.ownKeys(target).filter(allowed),
190
+ getOwnPropertyDescriptor: (target, name) =>
191
+ allowed(name) ? Reflect.getOwnPropertyDescriptor(target, name) : undefined,
192
+ });
193
+ }
@@ -0,0 +1,101 @@
1
+ /**
2
+ * The read rule of a `'document'` segment: it may read the request inputs in
3
+ * its key, and nothing else from the request (design/53-segment-lifetime.md
4
+ * §"What a 'document' segment may read").
5
+ *
6
+ * A `'document'` segment is skipped without rendering whenever its key is
7
+ * unchanged, so anything else it read would freeze silently at its load-time
8
+ * value. The rule makes that a thrown error instead, in every environment:
9
+ *
10
+ * - `getSegmentParams()` returns a view that throws on a param outside the key;
11
+ * - a search-params definition's `.get()` throws unless every field it reads is
12
+ * in the key's definition, and the raw search params throw;
13
+ * - the cookie jar throws on a cookie outside the key, and on `getAll()`;
14
+ * - `getHeaders()` reads only the headers in the key; any other header, and
15
+ * iterating them all, throws — and with that the pathname, which no timber
16
+ * API exposes to a component except through a header.
17
+ *
18
+ * **Reach.** The scope is an AsyncLocalStorage scope around the segment's
19
+ * component, so it covers the component and everything it calls or awaits.
20
+ * That alone would not reach the server components it *returns*: Flight
21
+ * renders those later, as tasks of its own, outside the scope. So the
22
+ * returned tree is rewritten (`subtree-walk.ts`) and each server component in
23
+ * it runs inside the scope too, down to the nested outlets — a layout's
24
+ * `children` and slots, which are other segments with their own rules.
25
+ *
26
+ * Not covered: values computed outside this render and handed to it — a
27
+ * `timber.cache` entry an earlier request filled, or a module-level value. The
28
+ * accessors' checks are `read-rule.ts`.
29
+ */
30
+
31
+ import { createElement, type ReactNode } from 'react';
32
+
33
+ import { documentReadScopeAls, type DocumentReadScope } from '../als-registry.ts';
34
+ import { isOutletGateElement } from './outlet-gate.ts';
35
+ import { callAndRewrite, type ServerComponent, type SubtreeRule } from '../subtree-walk.ts';
36
+ import type { DocumentLifetime } from './segment-key.ts';
37
+
38
+ /** The read scope of one `'document'` segment. */
39
+ export function readScopeFor(
40
+ segmentPath: string,
41
+ lifetime: DocumentLifetime,
42
+ pathParams: readonly string[]
43
+ ): DocumentReadScope {
44
+ const { key } = lifetime;
45
+ return {
46
+ segmentPath,
47
+ params: new Set(key.segmentParams ?? pathParams),
48
+ searchParams: new Map(
49
+ Object.entries(key.searchParams?.codecs ?? {}).map(([field, codec]) => [
50
+ field,
51
+ { codec, urlKey: key.searchParams?.urlKeys[field] ?? field },
52
+ ])
53
+ ),
54
+ cookies: new Map((key.cookies ?? []).map((cookie) => [cookie.name, cookie.codec])),
55
+ headers: new Set((key.headers ?? []).map((name) => name.toLowerCase())),
56
+ };
57
+ }
58
+
59
+ /**
60
+ * The segment's component, run inside its read scope with every server
61
+ * component it returns rewritten to run there too.
62
+ */
63
+ export function inReadScope(component: ServerComponent, scope: DocumentReadScope): ServerComponent {
64
+ const rule = scopeRule(scope);
65
+ return (props) => documentReadScopeAls.run(scope, () => callAndRewrite(component, props, rule));
66
+ }
67
+
68
+ /**
69
+ * Runs one server component from a scoped tree inside the scope. Declared at
70
+ * module scope and given the component as a prop, so its identity is stable
71
+ * across renders; `component` and `scope` are consumed here and never reach
72
+ * the Flight stream.
73
+ */
74
+ function ScopedServerComponent(props: {
75
+ component: ServerComponent;
76
+ componentProps: Record<string, unknown>;
77
+ scope: DocumentReadScope;
78
+ }): ReactNode | Promise<ReactNode> {
79
+ const { component, componentProps, scope } = props;
80
+ return documentReadScopeAls.run(scope, () =>
81
+ callAndRewrite(component, componentProps, scopeRule(scope))
82
+ );
83
+ }
84
+
85
+ function scopeRule(scope: DocumentReadScope): SubtreeRule {
86
+ return {
87
+ wrap: (component, componentProps, key) =>
88
+ component === (ScopedServerComponent as unknown)
89
+ ? undefined
90
+ : createElement(ScopedServerComponent, {
91
+ component,
92
+ componentProps,
93
+ scope,
94
+ ...(key !== null ? { key } : undefined),
95
+ }),
96
+ // A nested outlet is another segment: its own lifetime decides what it reads.
97
+ isOpaque: isOutletGateElement,
98
+ // An async iterable it returned reads, as it is advanced, inside the scope.
99
+ runIn: (fn) => documentReadScopeAls.run(scope, fn),
100
+ };
101
+ }