@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
@@ -0,0 +1,423 @@
1
+ /**
2
+ * Route-module options: `export const layoutOptions = { … }` in a layout and
3
+ * `export const pageOptions = { … }` in a page, read from source.
4
+ *
5
+ * Design doc: design/53-segment-lifetime.md §"Route-module options".
6
+ *
7
+ * `prerender` is read here at build time, before any route module loads:
8
+ * `plugins/prerender-sugar.ts` decides from it which pages to wrap in
9
+ * `cache.component(...)`. Every other option is validated here and read at
10
+ * runtime from the loaded module (`deferSuspenseFor`, in
11
+ * `server/route-module-loader.ts`; `lifetime` and `key`, in
12
+ * `server/segment-lifetime/segment-key.ts`). A key's `searchParams` and
13
+ * `cookies` name definitions, so they are the one place a non-literal value is
14
+ * accepted; `segmentParams` is checked against the segment's path by
15
+ * `routing/route-options-lint.ts`. The whole object follows one rule so that
16
+ * every key is checkable: this reader accepts one spelling —
17
+ * `export const xOptions = { … }` of literal values, optionally behind
18
+ * `satisfies` / `as` — and reports the others it can see as problems.
19
+ * `routing/convention-lint.ts` turns problems into build errors:
20
+ *
21
+ * - a spread, a computed key, a getter or method, or a non-literal value
22
+ * - an unknown key (a misspelled `prerendr`)
23
+ * - `pageOptions` in a layout or `layoutOptions` in a page
24
+ * - options in a `'use client'` file, whose exports the server never sees
25
+ * - the removed floating exports, `export const prerender` and
26
+ * `export const deferSuspenseFor`
27
+ * - `let`, a destructured binding, a specifier or a named re-export
28
+ * (`export { pageOptions } from`, `export * as pageOptions from`)
29
+ *
30
+ * What it cannot see is not reported: `export * from` is not followed, a
31
+ * file that does not parse reads as having no options (the compiler reports
32
+ * it), and MDX pages are not read at all, so `prerender` in an MDX page does
33
+ * nothing and its `deferSuspenseFor` is unvalidated.
34
+ */
35
+
36
+ import { existsSync } from 'node:fs';
37
+ import type {
38
+ LayoutOptions,
39
+ PageOptions,
40
+ RoutePrerender,
41
+ SegmentKey,
42
+ SegmentLifetime,
43
+ } from '../server/types.ts';
44
+ import { patternBinds, TRANSPARENT_WRAPPERS, tryParse } from './export-detect.ts';
45
+ import { readFileCached } from './file-cache.ts';
46
+ import { ROUTE_OPTIONS_EXPORT, type RouteOptionsKind } from '../shared/route-options-export.ts';
47
+
48
+ const OPTIONS_TYPE = { layout: 'LayoutOptions', page: 'PageOptions' } as const;
49
+
50
+ /** Floating exports the options objects replaced (design/53). */
51
+ const REMOVED_EXPORTS = ['prerender', 'deferSuspenseFor'] as const;
52
+
53
+ export interface RouteOptionsRead {
54
+ /**
55
+ * The declared options. Undefined when the file declares none or when any
56
+ * problem was found — a half-read object is never acted on.
57
+ */
58
+ options: LayoutOptions | PageOptions | undefined;
59
+ /** One line per problem, each naming what to write instead. */
60
+ problems: string[];
61
+ }
62
+
63
+ // ─── AST access ────────────────────────────────────────────────────────────
64
+
65
+ /** An ESTree node as oxc's `parseAst` produces it, read field by field. */
66
+ type Node = { readonly type: string; readonly [field: string]: unknown };
67
+
68
+ function isNode(value: unknown): value is Node {
69
+ return (
70
+ typeof value === 'object' && value !== null && 'type' in value && typeof value.type === 'string'
71
+ );
72
+ }
73
+
74
+ function child(node: Node, field: string): Node | undefined {
75
+ const value = node[field];
76
+ return isNode(value) ? value : undefined;
77
+ }
78
+
79
+ function list(node: Node, field: string): unknown[] {
80
+ const value = node[field];
81
+ return Array.isArray(value) ? value : [];
82
+ }
83
+
84
+ /** Strip `satisfies T`, `as T`, `(x)` and friends, which compile away. */
85
+ function unwrap(node: Node): Node {
86
+ let current = node;
87
+ while (TRANSPARENT_WRAPPERS.has(current.type)) {
88
+ const inner = child(current, 'expression');
89
+ if (!inner) break;
90
+ current = inner;
91
+ }
92
+ return current;
93
+ }
94
+
95
+ /** An identifier's name or a string literal's value (`export { x as "y" }`). */
96
+ function nameOf(node: Node | undefined): string | undefined {
97
+ if (!node) return undefined;
98
+ if (typeof node.value === 'string') return node.value;
99
+ return typeof node.name === 'string' ? node.name : undefined;
100
+ }
101
+
102
+ /** A literal's value; a template literal with no `${}` counts as a string. */
103
+ function literal(node: Node): unknown {
104
+ const n = unwrap(node);
105
+ if (n.type === 'Literal') return n.value;
106
+ if (n.type !== 'TemplateLiteral' || list(n, 'expressions').length > 0) return undefined;
107
+ const [quasi] = list(n, 'quasis');
108
+ // A TemplateElement's `value` is `{ raw, cooked }`, not a node.
109
+ const parts = isNode(quasi) ? quasi.value : undefined;
110
+ const value =
111
+ typeof parts === 'object' && parts !== null && 'cooked' in parts ? parts.cooked : undefined;
112
+ return typeof value === 'string' ? value : undefined;
113
+ }
114
+
115
+ /** `key: undefined` — the same as leaving the key out, as the types allow. */
116
+ function isUndefined(node: Node): boolean {
117
+ const n = unwrap(node);
118
+ return n.type === 'Identifier' && n.name === 'undefined';
119
+ }
120
+
121
+ // ─── Value readers, one per option ────────────────────────────────────────
122
+
123
+ type Read<T> = { value: T } | { problem: string };
124
+
125
+ /** A numeric literal is never negative (`-1` is a unary expression), so finite is enough. */
126
+ function readNonNegativeNumber(node: Node, label: string): Read<number> {
127
+ const value = literal(node);
128
+ if (typeof value === 'number' && Number.isFinite(value)) return { value };
129
+ return { problem: `${label} must be a non-negative number literal.` };
130
+ }
131
+
132
+ function readPrerender(node: Node): Read<RoutePrerender> {
133
+ const value = literal(node);
134
+ if (typeof value === 'boolean') return { value };
135
+ const n = unwrap(node);
136
+ if (n.type !== 'ObjectExpression') {
137
+ return {
138
+ problem: 'prerender must be `true`, `false`, or an object literal `{ ttl?, tags? }`.',
139
+ };
140
+ }
141
+ const result: { ttl?: number; tags?: string[] } = {};
142
+ for (const entry of readProperties(n, 'prerender')) {
143
+ if ('problem' in entry) return entry;
144
+ if (entry.key === 'ttl') {
145
+ const ttl = readNonNegativeNumber(entry.value, 'prerender.ttl');
146
+ if ('problem' in ttl) return ttl;
147
+ result.ttl = ttl.value;
148
+ } else if (entry.key === 'tags') {
149
+ const tags = readStringArray(entry.value);
150
+ if (!tags) return { problem: 'prerender.tags must be an array of string literals.' };
151
+ result.tags = tags;
152
+ } else {
153
+ return { problem: `Unknown key "${entry.key}" in prerender. Allowed: ttl, tags.` };
154
+ }
155
+ }
156
+ return { value: result };
157
+ }
158
+
159
+ function readStringArray(node: Node): string[] | undefined {
160
+ const n = unwrap(node);
161
+ if (n.type !== 'ArrayExpression') return undefined;
162
+ const result: string[] = [];
163
+ for (const element of list(n, 'elements')) {
164
+ const value = isNode(element) ? literal(element) : undefined;
165
+ if (typeof value !== 'string') return undefined;
166
+ result.push(value);
167
+ }
168
+ return result;
169
+ }
170
+
171
+ /**
172
+ * One reader per option key. Typed against the public option types, so an
173
+ * option added to `PageOptions` / `LayoutOptions` without a reader here (or a
174
+ * reader without the option) fails typecheck — the two lists cannot drift.
175
+ */
176
+ type Readers<T> = {
177
+ [K in keyof Required<T>]: (
178
+ node: Node
179
+ ) => Read<NonNullable<T[K]> extends SegmentKey ? BuildTimeKey : NonNullable<T[K]>>;
180
+ };
181
+
182
+ const deferSuspenseFor = (node: Node) => readNonNegativeNumber(node, 'deferSuspenseFor');
183
+
184
+ const LIFETIMES: readonly SegmentLifetime[] = ['request', 'document'];
185
+
186
+ function readLifetime(node: Node): Read<SegmentLifetime> {
187
+ const value = literal(node);
188
+ const lifetime = LIFETIMES.find((l) => l === value);
189
+ if (lifetime) return { value: lifetime };
190
+ return { problem: "lifetime must be 'request' or 'document'." };
191
+ }
192
+
193
+ /**
194
+ * What the build can read of a segment key: the param names. `searchParams`
195
+ * and `cookies` name definitions — code the build cannot evaluate — so only
196
+ * their shape is checked here; their values take effect from the loaded
197
+ * module (`server/segment-lifetime/`). The route-options lint checks the
198
+ * param names against the segment's path.
199
+ */
200
+ type BuildTimeKey = Pick<SegmentKey, 'segmentParams'>;
201
+
202
+ /** A value written in place, which cannot be a definition imported or declared elsewhere. */
203
+ function isInlineValue(node: Node): boolean {
204
+ const type = unwrap(node).type;
205
+ return (
206
+ literal(node) !== undefined ||
207
+ type === 'ObjectExpression' ||
208
+ type === 'ArrayExpression' ||
209
+ type === 'Literal' ||
210
+ type === 'TemplateLiteral'
211
+ );
212
+ }
213
+
214
+ function readKey(node: Node): Read<BuildTimeKey> {
215
+ const n = unwrap(node);
216
+ if (n.type !== 'ObjectExpression') {
217
+ return {
218
+ problem: 'key must be an object literal `{ segmentParams?, searchParams?, cookies? }`.',
219
+ };
220
+ }
221
+ const result: BuildTimeKey = {};
222
+ for (const entry of readProperties(n, 'key')) {
223
+ if ('problem' in entry) return entry;
224
+ if (entry.key === 'segmentParams') {
225
+ const names = readStringArray(entry.value);
226
+ if (!names) return { problem: 'key.segmentParams must be an array of string literals.' };
227
+ result.segmentParams = names;
228
+ } else if (entry.key === 'searchParams') {
229
+ if (isInlineValue(entry.value)) {
230
+ return {
231
+ problem:
232
+ 'key.searchParams must name a search-params definition (`defineSearchParams`, or a `.pick()` of one).',
233
+ };
234
+ }
235
+ } else if (entry.key === 'cookies') {
236
+ const array = unwrap(entry.value);
237
+ const elements = list(array, 'elements');
238
+ const definitions = elements.every(
239
+ (e) => isNode(e) && e.type !== 'SpreadElement' && !isInlineValue(e)
240
+ );
241
+ if (array.type !== 'ArrayExpression' || !definitions) {
242
+ return {
243
+ problem: 'key.cookies must be an array literal of cookie definitions (`defineCookie`).',
244
+ };
245
+ }
246
+ } else {
247
+ return {
248
+ problem: `Unknown key "${entry.key}" in key. Allowed: segmentParams, searchParams, cookies.`,
249
+ };
250
+ }
251
+ }
252
+ return { value: result };
253
+ }
254
+
255
+ const READERS = {
256
+ layout: {
257
+ lifetime: readLifetime,
258
+ key: readKey,
259
+ prerender: readPrerender,
260
+ deferSuspenseFor,
261
+ } satisfies Readers<LayoutOptions>,
262
+ page: {
263
+ lifetime: readLifetime,
264
+ key: readKey,
265
+ prerender: readPrerender,
266
+ deferSuspenseFor,
267
+ } satisfies Readers<PageOptions>,
268
+ };
269
+
270
+ // ─── Object literal ───────────────────────────────────────────────────────
271
+
272
+ type Entry = { key: string; value: Node } | { problem: string };
273
+
274
+ /**
275
+ * The `key: value` entries of an object literal, or a problem per entry that
276
+ * has none. `key: undefined` entries are dropped: they mean "not set".
277
+ */
278
+ function readProperties(object: Node, label: string): Entry[] {
279
+ return list(object, 'properties').flatMap((prop): Entry[] => {
280
+ if (!isNode(prop) || prop.type === 'SpreadElement') {
281
+ return [{ problem: `${label} cannot use a spread; write every key in the literal.` }];
282
+ }
283
+ if (prop.computed === true) {
284
+ return [{ problem: `${label} cannot use a computed key; write the key name.` }];
285
+ }
286
+ const value = child(prop, 'value');
287
+ const key = nameOf(child(prop, 'key'));
288
+ if (prop.kind !== 'init' || prop.method === true || !value || key === undefined) {
289
+ return [{ problem: `${label} entries must be plain \`key: value\` pairs.` }];
290
+ }
291
+ return isUndefined(value) ? [] : [{ key, value }];
292
+ });
293
+ }
294
+
295
+ function readOptionsObject(init: Node, kind: RouteOptionsKind, problems: string[]) {
296
+ const name = ROUTE_OPTIONS_EXPORT[kind];
297
+ const object = unwrap(init);
298
+ if (object.type !== 'ObjectExpression') {
299
+ problems.push(`${name} must be an object literal: \`export const ${name} = { … }\`.`);
300
+ return undefined;
301
+ }
302
+ const readers: Record<string, (node: Node) => Read<unknown>> = READERS[kind];
303
+ const options: Record<string, unknown> = {};
304
+ for (const entry of readProperties(object, name)) {
305
+ if ('problem' in entry) {
306
+ problems.push(entry.problem);
307
+ continue;
308
+ }
309
+ const reader = Object.hasOwn(readers, entry.key) ? readers[entry.key] : undefined;
310
+ if (!reader) {
311
+ problems.push(
312
+ `Unknown key "${entry.key}" in ${name}. Allowed: ${Object.keys(readers).join(', ')}.`
313
+ );
314
+ continue;
315
+ }
316
+ const read = reader(entry.value);
317
+ if ('problem' in read) problems.push(read.problem);
318
+ else options[entry.key] = read.value;
319
+ }
320
+ return options;
321
+ }
322
+
323
+ // ─── File ─────────────────────────────────────────────────────────────────
324
+
325
+ const NONE: RouteOptionsRead = Object.freeze({ options: undefined, problems: [] });
326
+
327
+ /** Every name the reader reacts to; a file containing none of them is not parsed. */
328
+ const MENTIONS = /Options|prerender|deferSuspenseFor/;
329
+
330
+ /**
331
+ * Read a layout's `layoutOptions` or a page's `pageOptions` from source.
332
+ *
333
+ * A missing or unparseable file reads as no options and no problems: the
334
+ * compiler reports syntax errors, and guessing at a half-written file would
335
+ * misreport it. `.ts` files are parsed as TypeScript, not TSX, so an
336
+ * angle-bracket cast does not hide a file from this check.
337
+ */
338
+ export function readRouteOptions(filePath: string, kind: RouteOptionsKind): RouteOptionsRead {
339
+ if (!existsSync(filePath)) return NONE;
340
+ const source = readFileCached(filePath);
341
+ // Runs on every page and layout on each rescan; most declare nothing.
342
+ if (!MENTIONS.test(source)) return NONE;
343
+ const program = tryParse(source, /\.[mc]?ts$/.test(filePath) ? 'ts' : 'tsx');
344
+ if (!program) return NONE;
345
+
346
+ const own = ROUTE_OPTIONS_EXPORT[kind];
347
+ const otherKind: RouteOptionsKind = kind === 'page' ? 'layout' : 'page';
348
+ const other = ROUTE_OPTIONS_EXPORT[otherKind];
349
+ const problems: string[] = [];
350
+ let init: Node | undefined;
351
+
352
+ /** An export of a watched name in a form the build cannot read. */
353
+ const report = (name: string | undefined) => {
354
+ if (name === own) {
355
+ problems.push(
356
+ `${own} must be declared in this file as \`export const ${own} = { … } satisfies ${OPTIONS_TYPE[kind]}\`. ` +
357
+ '`let`, destructuring, `export { … }` and re-exports cannot be read at build time.'
358
+ );
359
+ } else if (name === other) {
360
+ problems.push(
361
+ `${other} configures a ${otherKind}; this file is a ${kind}. Use \`export const ${own}\`.`
362
+ );
363
+ } else if (name && (REMOVED_EXPORTS as readonly string[]).includes(name)) {
364
+ problems.push(
365
+ `\`export const ${name}\` was removed. Move it into the options object: ` +
366
+ `\`export const ${own} = { ${name}: … } satisfies ${OPTIONS_TYPE[kind]}\`.`
367
+ );
368
+ }
369
+ };
370
+ const watched = [own, other, ...REMOVED_EXPORTS];
371
+
372
+ for (const stmt of program.body) {
373
+ if (!isNode(stmt) || stmt.exportKind === 'type') continue;
374
+ // `export * as pageOptions from` names an export; bare `export * from` does not.
375
+ if (stmt.type === 'ExportAllDeclaration') report(nameOf(child(stmt, 'exported')));
376
+ if (stmt.type !== 'ExportNamedDeclaration') continue;
377
+ for (const spec of list(stmt, 'specifiers')) {
378
+ if (isNode(spec) && spec.exportKind !== 'type') report(nameOf(child(spec, 'exported')));
379
+ }
380
+ const decl = child(stmt, 'declaration');
381
+ if (!decl) continue;
382
+ if (decl.type !== 'VariableDeclaration') {
383
+ report(nameOf(child(decl, 'id'))); // function or class
384
+ continue;
385
+ }
386
+ for (const declarator of list(decl, 'declarations')) {
387
+ if (!isNode(declarator)) continue;
388
+ const id = child(declarator, 'id');
389
+ const value = child(declarator, 'init');
390
+ if (id?.type !== 'Identifier') {
391
+ for (const name of watched) if (patternBinds(id, name)) report(name);
392
+ } else if (id.name === own && decl.kind === 'const' && value) {
393
+ init = value;
394
+ } else {
395
+ report(nameOf(id));
396
+ }
397
+ }
398
+ }
399
+
400
+ if (init && isClientModule(program.body)) {
401
+ problems.push(
402
+ `A 'use client' ${kind} cannot declare ${own}: the server sees a client reference, ` +
403
+ `not the object. Move ${own} to a server ${kind} that renders the client component.`
404
+ );
405
+ }
406
+ const options = init ? readOptionsObject(init, kind, problems) : undefined;
407
+ return { options: problems.length === 0 ? options : undefined, problems };
408
+ }
409
+
410
+ /** Whether the module starts with a 'use client' directive. */
411
+ function isClientModule(body: readonly unknown[]): boolean {
412
+ for (const stmt of body) {
413
+ if (
414
+ !isNode(stmt) ||
415
+ stmt.type !== 'ExpressionStatement' ||
416
+ typeof stmt.directive !== 'string'
417
+ ) {
418
+ return false;
419
+ }
420
+ if (stmt.directive === 'use client') return true;
421
+ }
422
+ return false;
423
+ }
@@ -158,3 +158,53 @@ export function computeSlotKey(parentSegmentId: string, slotName: string): strin
158
158
  export function childrenOutletKey(segmentId: string): string {
159
159
  return computeSlotKey(segmentId, '@children');
160
160
  }
161
+
162
+ /**
163
+ * The outlet keys of `'document'` segments (design/53-segment-lifetime.md
164
+ * §"Skipping"), by the segment's **tree path** — its directory path, route
165
+ * groups and `@slot` directories included. A `'document'` skip is
166
+ * identity-addressed (the client renders what it holds at this key, under a
167
+ * digest bound to it), so the key must name one segment. Segment ids
168
+ * (`computeSegmentKeys`) do not: `(landing)/feed` and `(browse)/feed` both
169
+ * key as `/feed`, which a content-addressed hash skip survives and a digest
170
+ * skip would not.
171
+ *
172
+ * `#` starts a URL fragment, so no routable segment is named with it — the
173
+ * same reason the metadata outlet is `#metadata`. A `'document'` layout's
174
+ * `children` outlet is `childrenOutletKey` of its layout key in a slot; on the
175
+ * main chain it keeps `childrenOutletKey(segmentId)`.
176
+ */
177
+ export function pageOutletKey(treePath: string): string {
178
+ return `${treePath === '/' ? '' : treePath}/#page`;
179
+ }
180
+
181
+ /** See `pageOutletKey`. */
182
+ export function layoutOutletKey(treePath: string): string {
183
+ return `${treePath === '/' ? '' : treePath}/#layout`;
184
+ }
185
+
186
+ /**
187
+ * The full tree path of a slot's matched chain (or a prefix of it) — the key
188
+ * the ALS slot params map, the generated `getSegmentParams` overloads and a
189
+ * slot's `'document'` outlets all use.
190
+ *
191
+ * Built from the parent's tree path plus each chain node's directory name,
192
+ * so an intercepting node contributes its marker
193
+ * (`/gallery/@modal/(.)photo/[id]`) and a route group contributes its
194
+ * parentheses.
195
+ *
196
+ * One definition for the render path, the eager access path and the outlet
197
+ * keys: they key the same things, and a divergence would silently strand one
198
+ * of them.
199
+ */
200
+ export function slotChainTreePath(
201
+ chain: ReadonlyArray<{ segmentName?: string }>,
202
+ parentTreePath: string
203
+ ): string {
204
+ const slotSuffix = chain
205
+ .map((s) => s.segmentName)
206
+ .filter(Boolean)
207
+ .join('/');
208
+ const prefix = parentTreePath === '/' ? '' : parentTreePath;
209
+ return `${prefix}/${slotSuffix}`;
210
+ }
@@ -24,6 +24,7 @@ declare module '@vitejs/plugin-rsc/vendor/react-server-dom/server.node' {
24
24
  onError?: (error: unknown) => string | void;
25
25
  identifierPrefix?: string;
26
26
  temporaryReferences?: unknown;
27
+ filterStackFrame?: (url: string, functionName: string) => boolean;
27
28
  debugChannel?: import('node:stream').Readable | import('node:stream').Writable;
28
29
  }
29
30
  ): { pipe<T extends NodeJS.WritableStream>(destination: T): T; abort(reason?: unknown): void };
@@ -52,6 +53,9 @@ declare module '@vitejs/plugin-rsc/vendor/react-server-dom/server.edge' {
52
53
  signal?: AbortSignal;
53
54
  onError?: (error: unknown) => string | void;
54
55
  onPostpone?: (reason: string) => void;
56
+ temporaryReferences?: unknown;
57
+ identifierPrefix?: string;
58
+ filterStackFrame?: (url: string, functionName: string) => boolean;
55
59
  }
56
60
  ): ReadableStream<Uint8Array>;
57
61
 
@@ -676,7 +676,7 @@ function buildDefinition<T extends Record<string, unknown>>(
676
676
  'Use searchParams.useQueryStates() on the client.'
677
677
  );
678
678
  }
679
- const raw = getSearchParamsFromAls();
679
+ const raw = getSearchParamsFromAls({ codecs: codecMap, urlKeys });
680
680
  return parseSync(raw);
681
681
  }
682
682
 
@@ -362,3 +362,32 @@ export interface SegmentCaptureStore {
362
362
  export const segmentCaptureAls = getOrCreateAls<SegmentCaptureStore>(
363
363
  Symbol.for('timber:segment-capture-als')
364
364
  );
365
+
366
+ // ─── 'document' segment read scope ────────────────────────────────────────
367
+ // Used by: segment-lifetime/read-scope.ts (set), request-context.ts and
368
+ // cookie-context.ts (checked by every request-input accessor).
369
+ // Design doc: design/53-segment-lifetime.md §"What a 'document' segment may read"
370
+
371
+ /** The request inputs a `'document'` segment's render may read: its key. */
372
+ export interface DocumentReadScope {
373
+ /** The segment's outlet path, for error messages. */
374
+ segmentPath: string;
375
+ /** Segment param names in the key. */
376
+ params: ReadonlySet<string>;
377
+ /**
378
+ * The fields of the key's search-params definition, each with the codec and
379
+ * URL key it is read through — a field of another definition matches only
380
+ * when both are the same.
381
+ */
382
+ searchParams: ReadonlyMap<string, { codec: unknown; urlKey: string }>;
383
+ /**
384
+ * The key's cookies, by name, with the codec of the definition the key
385
+ * holds: a keyed cookie may be read only through that definition.
386
+ */
387
+ cookies: ReadonlyMap<string, unknown>;
388
+ }
389
+
390
+ /** @internal — run and read via segment-lifetime/read-scope.ts */
391
+ export const documentReadScopeAls = getOrCreateAls<DocumentReadScope>(
392
+ Symbol.for('timber:document-read-scope-als')
393
+ );
@@ -1,38 +1,46 @@
1
1
  /**
2
2
  * Parsing of the client's `X-Timber-State-Tree` request header.
3
3
  *
4
- * The header carries two unrelated things:
4
+ * The header carries three unrelated things:
5
5
  *
6
6
  * - `hashes` — the segment hashes the client holds content for, by outlet
7
7
  * path. The outlet gates compare them with a capture of each segment and
8
8
  * skip the ones that match (design/52-segment-hash-dedupe.md). Read only
9
9
  * when the app opted into `clientSegmentCache`.
10
+ * - `documents` — the key digests of the `'document'` segments the client
11
+ * holds content for, by outlet path. An outlet gate skips a `'document'`
12
+ * segment without rendering it when the digest verifies against this
13
+ * request's key values (design/53-segment-lifetime.md). Always read on a
14
+ * navigation; excluded from the `_rsc` cache key.
10
15
  * - `treePaths` — the `app/` directory paths of the segments mounted right
11
16
  * now, for interception scoping (design/07-routing.md §"Intercepting
12
17
  * Routes", TIM-1282).
13
18
  *
14
- * Neither is a security input. A forged hash can only make the server send a
15
- * skip for content the client claims to hold; the client checks every skip
19
+ * None is a security input. A forged hash or digest can only make the server
20
+ * send a skip for content the client claims to hold; the client checks every skip
16
21
  * against the hash of what it actually holds, and every `access.ts` runs
17
22
  * regardless. See design/13-security.md §"State tree manipulation".
18
23
  */
19
24
 
20
25
  import { SEGMENT_HASH_LENGTH } from './segment-hash/value-hash.ts';
26
+ import { KEY_DIGEST_SHAPE } from './segment-lifetime/key-digest.ts';
21
27
  import { swallow } from './logger.ts';
22
28
 
23
29
  /** The parsed header. */
24
30
  export interface ClientStateTree {
25
31
  /** Segment hashes by outlet path, or null when none were sent. */
26
32
  hashes: ReadonlyMap<string, string> | null;
33
+ /** `'document'` key digests by outlet path, or null when none were sent. */
34
+ documents: ReadonlyMap<string, string> | null;
27
35
  /** Directory paths of the mounted segments, or null when none were sent. */
28
36
  treePaths: ReadonlySet<string> | null;
29
37
  }
30
38
 
31
39
  /**
32
- * More hashes than any route renders outlets. A header past it is not a
40
+ * More entries than any route renders outlets. A map past it is not a
33
41
  * client's: it is ignored rather than walked.
34
42
  */
35
- const MAX_HASHES = 512;
43
+ const MAX_ENTRIES = 512;
36
44
 
37
45
  const HASH_SHAPE = new RegExp(`^[A-Za-z0-9_-]{${SEGMENT_HASH_LENGTH}}$`);
38
46
 
@@ -44,7 +52,7 @@ export function parseClientStateTree(req: Request): ClientStateTree | null {
44
52
  const header = req.headers.get('X-Timber-State-Tree');
45
53
  if (!header) return null;
46
54
 
47
- let parsed: { hashes?: unknown; treePaths?: unknown };
55
+ let parsed: { hashes?: unknown; documents?: unknown; treePaths?: unknown };
48
56
  try {
49
57
  parsed = JSON.parse(header) as typeof parsed;
50
58
  } catch (err) {
@@ -53,23 +61,29 @@ export function parseClientStateTree(req: Request): ClientStateTree | null {
53
61
  }
54
62
  if (!parsed || typeof parsed !== 'object') return null;
55
63
 
56
- const hashes = new Map<string, string>();
57
- if (parsed.hashes && typeof parsed.hashes === 'object' && !Array.isArray(parsed.hashes)) {
58
- const entries = Object.entries(parsed.hashes as Record<string, unknown>);
59
- if (entries.length <= MAX_HASHES) {
60
- for (const [path, hash] of entries) {
61
- if (typeof hash === 'string' && HASH_SHAPE.test(hash)) hashes.set(path, hash);
62
- }
63
- }
64
- }
64
+ const hashes = readTokenMap(parsed.hashes, HASH_SHAPE);
65
+ const documents = readTokenMap(parsed.documents, KEY_DIGEST_SHAPE);
65
66
 
66
67
  const treePaths = Array.isArray(parsed.treePaths)
67
68
  ? new Set(parsed.treePaths.filter((p): p is string => typeof p === 'string'))
68
69
  : new Set<string>();
69
70
 
70
- if (hashes.size === 0 && treePaths.size === 0) return null;
71
+ if (hashes.size === 0 && documents.size === 0 && treePaths.size === 0) return null;
71
72
  return {
72
73
  hashes: hashes.size > 0 ? hashes : null,
74
+ documents: documents.size > 0 ? documents : null,
73
75
  treePaths: treePaths.size > 0 ? treePaths : null,
74
76
  };
75
77
  }
78
+
79
+ /** A `{ [outletPath]: token }` map, keeping only tokens of the expected shape. */
80
+ function readTokenMap(value: unknown, shape: RegExp): Map<string, string> {
81
+ const map = new Map<string, string>();
82
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return map;
83
+ const entries = Object.entries(value as Record<string, unknown>);
84
+ if (entries.length > MAX_ENTRIES) return map;
85
+ for (const [path, token] of entries) {
86
+ if (typeof token === 'string' && shape.test(token)) map.set(path, token);
87
+ }
88
+ return map;
89
+ }