@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
@@ -37,11 +37,15 @@ import loadCacheHandler from 'virtual:timber-cache-handler';
37
37
  import { loadCdnPurgeHandler } from 'virtual:timber-cache-handler';
38
38
  // @ts-expect-error — virtual module provided by timber-routing plugin
39
39
  import globalSchemaCodecs from 'virtual:timber-schema';
40
+ // The build's secret: the server-action encryption key, from which the
41
+ // 'document' key digests derive their own (design/53 §"The key digest").
42
+ import encryptionKeySource from 'virtual:vite-rsc/encryption-key';
40
43
 
41
44
  import { buildActionDispatcher } from './action-dispatcher.ts';
42
45
  import type { BodyLimitsConfig } from '../body-limits.ts';
43
46
  import type { DevHooks } from '../../dev-tools/dev-page-shell.ts';
44
47
  import type { BuildManifest } from '../build-manifest.ts';
48
+ import type { SegmentLifetime } from '../types.ts';
45
49
  import { resolveLogMode } from '../../dev-tools/logger.ts';
46
50
  import { sendEarlyHints103 } from '../early-hints-sender.ts';
47
51
  import { collectEarlyHintHeaders } from '../early-hints.ts';
@@ -66,6 +70,7 @@ import {
66
70
  type DevStoreClear,
67
71
  } from '../prebuilt/dev-store.ts';
68
72
  import { renderRoute } from './render-route.ts';
73
+ import { createKeyDigestSigner } from '../segment-lifetime/key-digest.ts';
69
74
  import { isDebug, isDevMode, setDebugFromConfig } from '../debug.ts';
70
75
  import { capturePrebuiltPayloads } from '../prebuilt-builder.ts';
71
76
  import { setPrebuiltPayloadSource } from '../prebuilt/payload-source.ts';
@@ -263,6 +268,13 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
263
268
  const clientJsDisabled = clientJsConfig?.disabled ?? false;
264
269
  const clientSegmentCache =
265
270
  ((runtimeConfig as Record<string, unknown>).clientSegmentCache as boolean) ?? false;
271
+ // Written by `plugins/entries.ts` as exactly 'request' or 'document'.
272
+ const defaultLayoutLifetime: SegmentLifetime =
273
+ (runtimeConfig as Record<string, unknown>).defaultLayoutLifetime === 'document'
274
+ ? 'document'
275
+ : 'request';
276
+ // One signer per server; it reads the secret on first use.
277
+ const keyDigestSigner = clientJsDisabled ? null : createKeyDigestSigner(encryptionKeySource);
266
278
  const clientBootstrap = buildClientScripts({
267
279
  ...runtimeConfig,
268
280
  clientJavascript: clientJsConfig ?? {
@@ -382,6 +394,8 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
382
394
  clientBootstrap,
383
395
  clientJsDisabled,
384
396
  clientSegmentCache,
397
+ keyDigestSigner,
398
+ defaultLayoutLifetime,
385
399
  renderDenyFallback,
386
400
  buildManifest: typedBuildManifest,
387
401
  renderTimeoutMs: (config as Record<string, unknown>).renderTimeoutMs as number,
@@ -485,6 +499,8 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
485
499
  matchRoute,
486
500
  coerceSegmentParams,
487
501
  buildManifest: buildManifest as BuildManifest,
502
+ keyDigestSigner,
503
+ defaultLayoutLifetime,
488
504
  }),
489
505
  }),
490
506
  };
@@ -35,6 +35,8 @@ import { parseClientStateTree } from '../client-state-tree.ts';
35
35
  import { isOutletType, type SegmentHashRender } from '../segment-hash/outlet.ts';
36
36
  import { createFromReadableStream } from '../vite-handoff-rsc.ts';
37
37
  import { createSegmentHashTap } from '../segment-hash/stream-tap.ts';
38
+ import type { KeyDigestSigner } from '../segment-lifetime/key-digest.ts';
39
+ import type { SegmentLifetime } from '../types.ts';
38
40
 
39
41
  import { handleApiRoute } from './api-handler.ts';
40
42
  import type { DenyFallbackRenderer } from './deny-fallback.ts';
@@ -54,6 +56,14 @@ export interface RenderRouteDeps {
54
56
  clientBootstrap: ClientBootstrapConfig;
55
57
  clientJsDisabled: boolean;
56
58
  clientSegmentCache: boolean;
59
+ /**
60
+ * Issues and checks key digests for 'document' segments
61
+ * (design/53-segment-lifetime.md); null when client JavaScript is disabled,
62
+ * since no client router can hold a segment.
63
+ */
64
+ keyDigestSigner: KeyDigestSigner | null;
65
+ /** The app's `defaultLayoutLifetime` (design/53 §"App-wide default"). */
66
+ defaultLayoutLifetime: SegmentLifetime;
57
67
  renderDenyFallback: DenyFallbackRenderer;
58
68
  buildManifest: BuildManifest;
59
69
  /**
@@ -111,8 +121,16 @@ export async function renderRoute(
111
121
  // row through instead of reporting it a second time.
112
122
  const relayedDigests = new Set<string>();
113
123
  let mainOnError: ((error: unknown) => string | void) | null = null;
124
+ // Only a navigation carries the client's state; a document request renders
125
+ // every segment and the client records what it hydrates.
126
+ const clientState = isRscRequest(req) ? parseClientStateTree(req) : null;
127
+ const signer = clientJsDisabled ? null : deps.keyDigestSigner;
114
128
  const segmentHashRender: SegmentHashRender = {
115
- clientHashes: hashing && isRscRequest(req) ? (parseClientStateTree(req)?.hashes ?? null) : null,
129
+ clientHashes: hashing ? (clientState?.hashes ?? null) : null,
130
+ // 'document' segments are skipped when the client holds them under the
131
+ // current key — whether or not the app opted into hashing.
132
+ documents: signer ? { client: clientState?.documents ?? null, signer } : null,
133
+ defaultLayoutLifetime: deps.defaultLayoutLifetime,
116
134
  tap,
117
135
  captureTimeoutMs: deps.renderTimeoutMs,
118
136
  signal: req.signal,
@@ -48,6 +48,8 @@ import type { CoercedParams } from '../../shared/param-value.ts';
48
48
 
49
49
  import { runMiddlewareForAction } from './action-middleware-runner.ts';
50
50
  import { NO_SEGMENT_HASHING } from '../segment-hash/outlet.ts';
51
+ import type { KeyDigestSigner } from '../segment-lifetime/key-digest.ts';
52
+ import type { SegmentLifetime } from '../types.ts';
51
53
  import { RSC_CONTENT_TYPE } from '../../shared/rsc-media-type.ts';
52
54
 
53
55
  /** Result of validating a `revalidatePath()` argument. */
@@ -137,6 +139,16 @@ export interface RevalidateRendererDeps {
137
139
  matchRoute: RouteMatcher;
138
140
  coerceSegmentParams: CoerceSegmentParamsFn;
139
141
  buildManifest: BuildManifest;
142
+ /**
143
+ * Issues key digests for 'document' segments; null when client JavaScript
144
+ * is disabled. A revalidated tree renders every segment live (it carries no
145
+ * client claims), and issues digests from the cookies as the action left
146
+ * them, so the next navigation compares against what the browser now sends
147
+ * (design/53-segment-lifetime.md open question 4).
148
+ */
149
+ keyDigestSigner: KeyDigestSigner | null;
150
+ /** The app's `defaultLayoutLifetime` (design/53 §"App-wide default"). */
151
+ defaultLayoutLifetime: SegmentLifetime;
140
152
  }
141
153
 
142
154
  /**
@@ -338,7 +350,11 @@ export function createRevalidateRendererFactory(
338
350
  revalidateReq,
339
351
  match,
340
352
  undefined,
341
- NO_SEGMENT_HASHING,
353
+ {
354
+ ...NO_SEGMENT_HASHING,
355
+ documents: deps.keyDigestSigner ? { client: null, signer: deps.keyDigestSigner } : null,
356
+ defaultLayoutLifetime: deps.defaultLayoutLifetime,
357
+ },
342
358
  deps.buildManifest.metadataRouteHashes
343
359
  );
344
360
  return {
@@ -15,6 +15,12 @@
15
15
  * capture; a nested gate that denied rendered its deny page instead of the
16
16
  * hole, so its segment is never decided, never rendered, never sent.
17
17
  *
18
+ * A `'document'` segment (design/53-segment-lifetime.md) is decided before
19
+ * any of that, and never captured: when the client holds content rendered
20
+ * under the current key digest, the segment is skipped **without rendering**,
21
+ * and its nested outlets are decided as if it had rendered — lifetime does
22
+ * not cascade. Otherwise it is sent live with the digest it rendered under.
23
+ *
18
24
  * See design/52-segment-hash-dedupe.md §"Mechanism".
19
25
  */
20
26
 
@@ -24,12 +30,16 @@ import { clientComponents } from '../vite-handoff-rsc.ts';
24
30
  import { stripReferenceCacheTag } from './value-hash.ts';
25
31
  import { captureHoleMarker, captureSegment, type SegmentCapture } from './capture.ts';
26
32
  import type { SegmentHashTap } from './stream-tap.ts';
33
+ import type { DocumentKeys, DocumentOutlet } from '../segment-lifetime/document-outlet.ts';
34
+ import type { SegmentLifetime } from '../types.ts';
27
35
 
28
36
  /** One outlet in the element tree, and the outlets directly inside it. */
29
37
  export interface OutletSpec {
30
38
  segmentPath: string;
31
39
  content: ReactNode;
32
40
  nested: OutletSpec[];
41
+ /** Set on a `'document'` segment's outlet when the render can issue digests. */
42
+ document?: DocumentOutlet;
33
43
  }
34
44
 
35
45
  /** Per-request inputs to every gate in one render. */
@@ -49,6 +59,17 @@ export interface SegmentHashRender {
49
59
  */
50
60
  onCaptureError?: (error: unknown) => string | void;
51
61
  signal?: AbortSignal;
62
+ /**
63
+ * Key digests for `'document'` segments: the client's, and the signer that
64
+ * issues and checks them. Null when no client router can hold a segment.
65
+ */
66
+ documents: DocumentKeys | null;
67
+ /**
68
+ * The lifetime of a layout that declares none: the app's
69
+ * `defaultLayoutLifetime` (design/53 §"App-wide default"). Pages always
70
+ * default to `'request'`.
71
+ */
72
+ defaultLayoutLifetime: SegmentLifetime;
52
73
  }
53
74
 
54
75
  /** A render with dedupe off: every segment live, no hashes. */
@@ -56,6 +77,8 @@ export const NO_SEGMENT_HASHING: SegmentHashRender = {
56
77
  clientHashes: null,
57
78
  tap: null,
58
79
  captureTimeoutMs: 0,
80
+ documents: null,
81
+ defaultLayoutLifetime: 'request',
59
82
  };
60
83
 
61
84
  /**
@@ -95,30 +118,37 @@ export function outletGate(spec: OutletSpec, render: SegmentHashRender): ReactEl
95
118
  decision: decide(spec, render),
96
119
  });
97
120
  }
121
+ OUTLET_GATES.add(OutletGate);
98
122
  return createElement(OutletGate);
99
123
  }
100
124
 
101
- function decide(spec: OutletSpec, render: SegmentHashRender): OutletDecisionValue {
102
- const clientHash = render.clientHashes?.get(spec.segmentPath);
103
- if (clientHash === undefined) return live(spec, render, spec.content);
104
- return detached(compare(spec, render, clientHash));
105
- }
125
+ /** Every gate component `outletGate` made, so a subtree walk can stop at one. */
126
+ const OUTLET_GATES = new WeakSet<object>();
106
127
 
107
128
  /**
108
- * The decision as a promise of its own, created here and settled from the
109
- * capture's callback — not a link in the capture's promise chain.
110
- *
111
- * Development Flight follows the async chain of every promise it serializes
112
- * (async_hooks in the Node build, and each awaited promise's `_debugInfo`) and
113
- * writes what it finds as debug rows, awaited values included. The chain
114
- * through a capture ends at its decoded root, so a decision chained to it
115
- * would carry a skipped segment's content into the payload as debug info —
116
- * whenever the timing made those reads count as I/O.
129
+ * Whether `node` is an outlet gate element — the boundary of the segment
130
+ * whose content contains it. A walk over one segment's output (a
131
+ * 'document' segment's read scope) stops here: what renders inside belongs
132
+ * to the nested segment and its own rules.
117
133
  */
118
- function detached<T>(source: Promise<T>): Promise<T> {
119
- return new Promise<T>((resolve, reject) => {
120
- source.then(resolve, reject);
121
- });
134
+ export function isOutletGateElement(node: unknown): boolean {
135
+ if (typeof node !== 'object' || node === null || !('type' in node)) return false;
136
+ const type = (node as { type: unknown }).type;
137
+ return typeof type === 'function' && OUTLET_GATES.has(type);
138
+ }
139
+
140
+ function decide(spec: OutletSpec, render: SegmentHashRender): OutletDecisionValue {
141
+ if (spec.document) {
142
+ if ('held' in spec.document) return documentSkip(spec, render, spec.document.held);
143
+ return { children: spec.content, digest: spec.document.issued };
144
+ }
145
+ const clientHash = render.clientHashes?.get(spec.segmentPath);
146
+ if (clientHash === undefined) return live(spec, render, spec.content);
147
+ // Development Flight follows this decision's async chain into the capture's
148
+ // reads, whose awaited values include the decoded segment. It writes those
149
+ // as debug rows only for awaits in app code; every render filters timber's
150
+ // own frames out (framework-stack-frames.ts), so a skip sends nothing.
151
+ return compare(spec, render, clientHash);
122
152
  }
123
153
 
124
154
  function compare(
@@ -183,3 +213,17 @@ function skip(
183
213
  }
184
214
  return { skip: true, hash: capture.hash, outlets };
185
215
  }
216
+
217
+ /**
218
+ * A `'document'` skip: the segment is not rendered, so nothing says which
219
+ * nested outlets its content would hold — every one is decided. The client
220
+ * renders only those in its cached copy; a nested segment a layout body hid
221
+ * at load is still rendered and serialized here (its own `access.ts` still
222
+ * gates it), which is why a `'document'` layout body is not a data-hiding
223
+ * boundary (design/53 §"What stays frozen").
224
+ */
225
+ function documentSkip(spec: OutletSpec, render: SegmentHashRender, digest: string): OutletDecision {
226
+ const outlets: Record<string, OutletDecisionValue> = {};
227
+ for (const nested of spec.nested) outlets[nested.segmentPath] = decide(nested, render);
228
+ return { skip: true, digest, outlets };
229
+ }
@@ -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,136 @@
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
+
12
+ /** The read scope the current render runs in, if it is a `'document'` segment's. */
13
+ export function currentReadScope(): DocumentReadScope | undefined {
14
+ return documentReadScopeAls.getStore();
15
+ }
16
+
17
+ /** Which part of a key would allow a read, for the error's fix. */
18
+ type KeyPart = 'segmentParams' | 'searchParams' | 'cookies';
19
+
20
+ /**
21
+ * The error for a read outside the key. Names the segment, what was read, and
22
+ * the fix: add it to the key, or make the segment `'request'`.
23
+ */
24
+ export function readOutsideKey(scope: DocumentReadScope, what: string, part?: KeyPart): Error {
25
+ const fix = part
26
+ ? `Add it to key.${part}, or declare lifetime: 'request'.`
27
+ : "A 'document' segment cannot depend on it; declare lifetime: 'request'.";
28
+ return new Error(
29
+ `[timber] ${scope.segmentPath} is lifetime: 'document' (declared, or from defaultLayoutLifetime) ` +
30
+ `and read ${what}, which is not in its key. ` +
31
+ `${fix} The segment is skipped without rendering while its key is unchanged, so the read ` +
32
+ `would freeze at its first value. See design/53-segment-lifetime.md ` +
33
+ `§"What a 'document' segment may read".`
34
+ );
35
+ }
36
+
37
+ /** Throw if the current render may not read `what` at all (headers, raw search params). */
38
+ export function assertUnscopedRead(what: string): void {
39
+ const scope = currentReadScope();
40
+ if (scope) throw readOutsideKey(scope, what);
41
+ }
42
+
43
+ /**
44
+ * Throw if the current render reads search-param fields outside its key. A
45
+ * field is in the key only when the key's definition reads it through the
46
+ * same codec and URL key — a `.pick()` of the keyed definition, or the keyed
47
+ * definition itself. Another definition with a field of the same name may map
48
+ * it to another URL parameter or parse it differently.
49
+ */
50
+ export function assertSearchParamsRead(reader: SearchParamsReader): void {
51
+ const scope = currentReadScope();
52
+ if (!scope) return;
53
+ const outside = Object.keys(reader.codecs).filter((field) => {
54
+ const keyed = scope.searchParams.get(field);
55
+ return (
56
+ !keyed ||
57
+ keyed.codec !== reader.codecs[field] ||
58
+ keyed.urlKey !== (reader.urlKeys[field] ?? field)
59
+ );
60
+ });
61
+ if (outside.length > 0) {
62
+ throw readOutsideKey(scope, `the search params ${outside.join(', ')}`, 'searchParams');
63
+ }
64
+ }
65
+
66
+ /**
67
+ * Throw if the current render reads a cookie outside its key. A keyed cookie
68
+ * is in the key only as its definition parses it, so it may be read only
69
+ * through that definition (`codec` is the reader's); a raw read, or another
70
+ * definition of the same name, could see a difference the key does not.
71
+ */
72
+ export function assertCookieRead(name: string, codec?: unknown): void {
73
+ const scope = currentReadScope();
74
+ if (!scope) return;
75
+ if (!scope.cookies.has(name)) {
76
+ throw readOutsideKey(scope, `the cookie "${name}"`, 'cookies');
77
+ }
78
+ if (codec === undefined || scope.cookies.get(name) !== codec) {
79
+ throw readOutsideKey(
80
+ scope,
81
+ `the raw value of the cookie "${name}" (read it through the definition in its key)`,
82
+ 'cookies'
83
+ );
84
+ }
85
+ }
86
+
87
+ /**
88
+ * Property names that serializers and runtimes read on any object — Flight
89
+ * and `await` probe `then`, React `$$typeof`, JSON `toJSON`. No param can
90
+ * be named these in a way a reader means: they are never refused.
91
+ */
92
+ const OBJECT_PROBES: ReadonlySet<string> = new Set([
93
+ 'then',
94
+ 'toJSON',
95
+ '$$typeof',
96
+ 'constructor',
97
+ 'valueOf',
98
+ 'toString',
99
+ '__proto__',
100
+ ]);
101
+
102
+ /**
103
+ * The params a scoped render sees: reading one outside the key throws. Its
104
+ * own keys are only the params in the key, so spreading it, or passing it to
105
+ * a client component, carries exactly what the segment may depend on.
106
+ */
107
+ export function scopedParams<T extends CoercedParams>(params: T): T {
108
+ const scope = currentReadScope();
109
+ if (!scope) return params;
110
+ // Refused: every name the key leaves out — a param on the segment's path, a
111
+ // descendant's or a slot's, present in this request or not. Absence is a
112
+ // value too: a layout reading a child's param that this URL lacks would
113
+ // freeze `undefined` across the URLs that have it. Only the names runtimes
114
+ // probe on any object pass.
115
+ const refused = (name: string | symbol) =>
116
+ typeof name === 'string' && !scope.params.has(name) && !OBJECT_PROBES.has(name);
117
+ const allowed = (name: string | symbol) => !refused(name);
118
+ // Over a copy: the trap hides keys, which a frozen or non-configurable
119
+ // target would forbid, and the request's own record stays untouched.
120
+ const target = Object.assign(
121
+ Object.create(Object.getPrototypeOf(params) as object | null) as T,
122
+ params
123
+ );
124
+ return new Proxy(target, {
125
+ get(target, name, receiver) {
126
+ if (refused(name)) {
127
+ throw readOutsideKey(scope, `the segment param "${String(name)}"`, 'segmentParams');
128
+ }
129
+ return Reflect.get(target, name, receiver);
130
+ },
131
+ has: (target, name) => allowed(name) && Reflect.has(target, name),
132
+ ownKeys: (target) => Reflect.ownKeys(target).filter(allowed),
133
+ getOwnPropertyDescriptor: (target, name) =>
134
+ allowed(name) ? Reflect.getOwnPropertyDescriptor(target, name) : undefined,
135
+ });
136
+ }