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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (264) hide show
  1. package/dist/_chunks/{actions-BCYVyoFl.js → actions-BkwgRwCl.js} +37 -9
  2. package/dist/_chunks/actions-BkwgRwCl.js.map +1 -0
  3. package/dist/_chunks/{als-registry-fabsRnPY.js → als-registry-C-iwbtvI.js} +1 -2
  4. package/dist/_chunks/{als-registry-fabsRnPY.js.map → als-registry-C-iwbtvI.js.map} +1 -1
  5. package/dist/_chunks/{cache-api-n5FL4wFs.js → cache-api-BGA7c5qJ.js} +5 -5
  6. package/dist/_chunks/{cache-api-n5FL4wFs.js.map → cache-api-BGA7c5qJ.js.map} +1 -1
  7. package/dist/_chunks/{chains-IswOWMnq.js → chains-Cuwwjv6T.js} +2 -2
  8. package/dist/_chunks/{chains-IswOWMnq.js.map → chains-Cuwwjv6T.js.map} +1 -1
  9. package/dist/_chunks/chains-LGjBHfSN.js +1 -0
  10. package/dist/_chunks/{classify-B08RCF6s.js → classify-Y8S9C0Na.js} +2 -2
  11. package/dist/_chunks/{classify-B08RCF6s.js.map → classify-Y8S9C0Na.js.map} +1 -1
  12. package/dist/_chunks/{cli-check-tpFb6pBU.js → cli-check-KeE1QaIx.js} +3 -3
  13. package/dist/_chunks/{cli-check-tpFb6pBU.js.map → cli-check-KeE1QaIx.js.map} +1 -1
  14. package/dist/_chunks/{cli-schema-sync-DRNJutey.js → cli-schema-sync-DZEF31wd.js} +2 -2
  15. package/dist/_chunks/{cli-schema-sync-DRNJutey.js.map → cli-schema-sync-DZEF31wd.js.map} +1 -1
  16. package/dist/_chunks/{cli-schema-sync-C0pXBtzG.js → cli-schema-sync-_y5O6MIg.js} +1 -1
  17. package/dist/_chunks/{client-dep-entries-Dw5Dvatr.js → client-dep-entries-DpiwvoDi.js} +2 -2
  18. package/dist/_chunks/{client-dep-entries-Dw5Dvatr.js.map → client-dep-entries-DpiwvoDi.js.map} +1 -1
  19. package/dist/_chunks/{convention-lint-BfC_dAhZ.js → convention-lint-0AEsPK2T.js} +19 -5
  20. package/dist/_chunks/convention-lint-0AEsPK2T.js.map +1 -0
  21. package/dist/_chunks/dev-server-CboXr8zX.js +1 -0
  22. package/dist/_chunks/{dev-server-3R6Bl9_R.js → dev-server-DYDr8KIc.js} +2 -3
  23. package/dist/_chunks/dev-server-DYDr8KIc.js.map +1 -0
  24. package/dist/_chunks/{error-boundary-Dfhxigko.js → error-boundary-wuNvAJ4n.js} +8 -15
  25. package/dist/_chunks/error-boundary-wuNvAJ4n.js.map +1 -0
  26. package/dist/_chunks/{flight-source-node-QOpWZATb.js → flight-source-node-KQsX_OhS.js} +4 -7
  27. package/dist/_chunks/flight-source-node-KQsX_OhS.js.map +1 -0
  28. package/dist/_chunks/{json-lossy-check-5KFcC1yt.js → json-lossy-check-BVDALqMf.js} +2 -2
  29. package/dist/_chunks/{json-lossy-check-5KFcC1yt.js.map → json-lossy-check-BVDALqMf.js.map} +1 -1
  30. package/dist/_chunks/key-headers-uIig1_mU.js +40 -0
  31. package/dist/_chunks/key-headers-uIig1_mU.js.map +1 -0
  32. package/dist/_chunks/{live-graph-D1dfVqoT.js → live-graph-VhzO7Ol9.js} +4 -4
  33. package/dist/_chunks/{live-graph-D1dfVqoT.js.map → live-graph-VhzO7Ol9.js.map} +1 -1
  34. package/dist/_chunks/{logger-BvGxPd1e.js → logger-C4m8rfMy.js} +2 -2
  35. package/dist/_chunks/{logger-BvGxPd1e.js.map → logger-C4m8rfMy.js.map} +1 -1
  36. package/dist/_chunks/metadata-routes-MXNjWOt5.js.map +1 -1
  37. package/dist/_chunks/{node-response-D5cfiyWP.js → node-response-8Vz29cGS.js} +2 -2
  38. package/dist/_chunks/{node-response-D5cfiyWP.js.map → node-response-8Vz29cGS.js.map} +1 -1
  39. package/dist/_chunks/{poison-scan-CX02ilxN.js → poison-scan-Dpl3ibG-.js} +2 -2
  40. package/dist/_chunks/{poison-scan-CX02ilxN.js.map → poison-scan-Dpl3ibG-.js.map} +1 -1
  41. package/dist/_chunks/{scanner-DneYxQoY.js → scanner-CCEHN9Jg.js} +2 -2
  42. package/dist/_chunks/{scanner-DneYxQoY.js.map → scanner-CCEHN9Jg.js.map} +1 -1
  43. package/dist/_chunks/{sizeof-BtQ3ErLf.js → sizeof-CIF7fwSJ.js} +2 -2
  44. package/dist/_chunks/{sizeof-BtQ3ErLf.js.map → sizeof-CIF7fwSJ.js.map} +1 -1
  45. package/dist/_chunks/{walkers-C9R2A4jN.js → walkers-BbotBhNG.js} +3 -3
  46. package/dist/_chunks/{walkers-C9R2A4jN.js.map → walkers-BbotBhNG.js.map} +1 -1
  47. package/dist/adapters/cloudflare-kv-cache.js +1 -1
  48. package/dist/analyze/crawl-entry.js +3 -3
  49. package/dist/analyze/graph-command.js +2 -2
  50. package/dist/cache/index.js +2 -2
  51. package/dist/cache/stores/memory.js +1 -1
  52. package/dist/cdn/workers-cache-purge.js +1 -1
  53. package/dist/cli.js +3 -3
  54. package/dist/client/browser-entry/router-init.d.ts +0 -1
  55. package/dist/client/browser-entry/router-init.d.ts.map +1 -1
  56. package/dist/client/error-boundary.js +1 -1
  57. package/dist/client/index.js +1 -1
  58. package/dist/client/index.js.map +1 -1
  59. package/dist/client/internal.js +3 -5
  60. package/dist/client/internal.js.map +1 -1
  61. package/dist/client/navigation-commit.d.ts +0 -7
  62. package/dist/client/navigation-commit.d.ts.map +1 -1
  63. package/dist/client/outlet-content-cache.d.ts +16 -42
  64. package/dist/client/outlet-content-cache.d.ts.map +1 -1
  65. package/dist/client/outlet-scope-context.d.ts +4 -4
  66. package/dist/client/outlet-scope-context.d.ts.map +1 -1
  67. package/dist/client/params-context.d.ts +1 -1
  68. package/dist/client/router-types.d.ts +3 -13
  69. package/dist/client/router-types.d.ts.map +1 -1
  70. package/dist/client/router.d.ts.map +1 -1
  71. package/dist/client/segment-cache.d.ts +2 -2
  72. package/dist/client/segment-outlet.d.ts +12 -15
  73. package/dist/client/segment-outlet.d.ts.map +1 -1
  74. package/dist/client/stale-segment.d.ts +2 -2
  75. package/dist/config-types.d.ts +0 -17
  76. package/dist/config-types.d.ts.map +1 -1
  77. package/dist/config-validation.d.ts.map +1 -1
  78. package/dist/index.js +7 -8
  79. package/dist/index.js.map +1 -1
  80. package/dist/native/rsc/manifest.json +2 -4
  81. package/dist/native/rsc/routing/segment-keys.js.map +1 -1
  82. package/dist/native/rsc/server/als-registry.js +1 -2
  83. package/dist/native/rsc/server/als-registry.js.map +1 -1
  84. package/dist/native/rsc/server/client-state-tree.js +1 -5
  85. package/dist/native/rsc/server/client-state-tree.js.map +1 -1
  86. package/dist/native/rsc/server/flight-source-node.js +2 -5
  87. package/dist/native/rsc/server/flight-source-node.js.map +1 -1
  88. package/dist/native/rsc/server/flight-source.js +6 -41
  89. package/dist/native/rsc/server/flight-source.js.map +1 -1
  90. package/dist/native/rsc/server/framework-stack-frames.js.map +1 -1
  91. package/dist/native/rsc/server/request-context.js +3 -3
  92. package/dist/native/rsc/server/request-context.js.map +1 -1
  93. package/dist/native/rsc/server/route-element-builder.js +5 -5
  94. package/dist/native/rsc/server/route-element-builder.js.map +1 -1
  95. package/dist/native/rsc/server/rsc-entry/render-route.js +4 -30
  96. package/dist/native/rsc/server/rsc-entry/render-route.js.map +1 -1
  97. package/dist/native/rsc/server/rsc-entry/revalidate-renderer.js +0 -2
  98. package/dist/native/rsc/server/rsc-entry/revalidate-renderer.js.map +1 -1
  99. package/dist/native/rsc/server/rsc-entry/rsc-stream.js +2 -5
  100. package/dist/native/rsc/server/rsc-entry/rsc-stream.js.map +1 -1
  101. package/dist/native/rsc/server/segment-lifetime/outlet-gate.js +44 -0
  102. package/dist/native/rsc/server/segment-lifetime/outlet-gate.js.map +1 -0
  103. package/dist/native/rsc/server/segment-lifetime/read-rule.js +25 -3
  104. package/dist/native/rsc/server/segment-lifetime/read-rule.js.map +1 -1
  105. package/dist/native/rsc/server/segment-lifetime/read-scope.js +3 -2
  106. package/dist/native/rsc/server/segment-lifetime/read-scope.js.map +1 -1
  107. package/dist/native/rsc/server/segment-lifetime/segment-key.js +17 -3
  108. package/dist/native/rsc/server/segment-lifetime/segment-key.js.map +1 -1
  109. package/dist/native/rsc/server/segment-lifetime/slot-outlets.js +4 -4
  110. package/dist/native/rsc/server/segment-lifetime/slot-outlets.js.map +1 -1
  111. package/dist/native/rsc/server/slot-resolver.js +3 -3
  112. package/dist/native/rsc/server/slot-resolver.js.map +1 -1
  113. package/dist/native/rsc/server/vite-handoff-rsc.js.map +1 -1
  114. package/dist/native/rsc/shared/key-headers.js +20 -0
  115. package/dist/native/rsc/shared/key-headers.js.map +1 -0
  116. package/dist/native/rsc/shared/outlet-decision.js.map +1 -1
  117. package/dist/native/ssr/client/outlet-content-cache.js +6 -26
  118. package/dist/native/ssr/client/outlet-content-cache.js.map +1 -1
  119. package/dist/native/ssr/client/outlet-scope-context.js.map +1 -1
  120. package/dist/native/ssr/client/segment-outlet.js +6 -19
  121. package/dist/native/ssr/client/segment-outlet.js.map +1 -1
  122. package/dist/native/ssr/manifest.json +1 -1
  123. package/dist/native/ssr/server/als-registry.js +0 -1
  124. package/dist/native/ssr/server/als-registry.js.map +1 -1
  125. package/dist/native/ssr/server/client-state-tree.js +1 -5
  126. package/dist/native/ssr/server/client-state-tree.js.map +1 -1
  127. package/dist/native/ssr/server/flight-source-node.js +2 -5
  128. package/dist/native/ssr/server/flight-source-node.js.map +1 -1
  129. package/dist/native/ssr/server/flight-source.js +0 -1
  130. package/dist/native/ssr/server/flight-source.js.map +1 -1
  131. package/dist/native/ssr/server/framework-stack-frames.js.map +1 -1
  132. package/dist/native/ssr/server/request-context.js +3 -3
  133. package/dist/native/ssr/server/request-context.js.map +1 -1
  134. package/dist/native/ssr/server/segment-lifetime/read-rule.js +25 -3
  135. package/dist/native/ssr/server/segment-lifetime/read-rule.js.map +1 -1
  136. package/dist/native/ssr/server/vite-handoff-rsc.js.map +1 -1
  137. package/dist/native/ssr/shared/key-headers.js +13 -0
  138. package/dist/native/ssr/shared/key-headers.js.map +1 -0
  139. package/dist/plugins/entries.d.ts.map +1 -1
  140. package/dist/routing/index.js +2 -2
  141. package/dist/routing/route-options.d.ts.map +1 -1
  142. package/dist/routing/segment-keys.d.ts +3 -4
  143. package/dist/routing/segment-keys.d.ts.map +1 -1
  144. package/dist/server/als-registry.d.ts +2 -16
  145. package/dist/server/als-registry.d.ts.map +1 -1
  146. package/dist/server/client-state-tree.d.ts +5 -11
  147. package/dist/server/client-state-tree.d.ts.map +1 -1
  148. package/dist/server/flight-source-node.d.ts +1 -6
  149. package/dist/server/flight-source-node.d.ts.map +1 -1
  150. package/dist/server/flight-source.d.ts +0 -27
  151. package/dist/server/flight-source.d.ts.map +1 -1
  152. package/dist/server/framework-stack-frames.d.ts +1 -4
  153. package/dist/server/framework-stack-frames.d.ts.map +1 -1
  154. package/dist/server/index.js +2 -2
  155. package/dist/server/internal.js +13 -23
  156. package/dist/server/internal.js.map +1 -1
  157. package/dist/server/request-context.d.ts.map +1 -1
  158. package/dist/server/route-element-builder.d.ts +2 -2
  159. package/dist/server/route-element-builder.d.ts.map +1 -1
  160. package/dist/server/rsc-entry/helpers.d.ts +1 -1
  161. package/dist/server/rsc-entry/index.d.ts.map +1 -1
  162. package/dist/server/rsc-entry/render-route.d.ts +0 -1
  163. package/dist/server/rsc-entry/render-route.d.ts.map +1 -1
  164. package/dist/server/rsc-entry/revalidate-renderer.d.ts.map +1 -1
  165. package/dist/server/rsc-entry/rsc-stream.d.ts +2 -11
  166. package/dist/server/rsc-entry/rsc-stream.d.ts.map +1 -1
  167. package/dist/server/segment-lifetime/outlet-gate.d.ts +58 -0
  168. package/dist/server/segment-lifetime/outlet-gate.d.ts.map +1 -0
  169. package/dist/server/segment-lifetime/read-rule.d.ts +13 -3
  170. package/dist/server/segment-lifetime/read-rule.d.ts.map +1 -1
  171. package/dist/server/segment-lifetime/read-scope.d.ts +2 -1
  172. package/dist/server/segment-lifetime/read-scope.d.ts.map +1 -1
  173. package/dist/server/segment-lifetime/segment-key.d.ts +3 -0
  174. package/dist/server/segment-lifetime/segment-key.d.ts.map +1 -1
  175. package/dist/server/segment-lifetime/slot-outlets.d.ts +2 -2
  176. package/dist/server/segment-lifetime/slot-outlets.d.ts.map +1 -1
  177. package/dist/server/slot-resolver.d.ts +5 -5
  178. package/dist/server/slot-resolver.d.ts.map +1 -1
  179. package/dist/server/types.d.ts +8 -2
  180. package/dist/server/types.d.ts.map +1 -1
  181. package/dist/server/vite-handoff-rsc.d.ts +1 -10
  182. package/dist/server/vite-handoff-rsc.d.ts.map +1 -1
  183. package/dist/shared/key-headers.d.ts +13 -0
  184. package/dist/shared/key-headers.d.ts.map +1 -0
  185. package/dist/shared/outlet-decision.d.ts +13 -44
  186. package/dist/shared/outlet-decision.d.ts.map +1 -1
  187. package/dist/shared/payload-root.d.ts +1 -1
  188. package/dist/shared/segment-info.d.ts +3 -7
  189. package/dist/shared/segment-info.d.ts.map +1 -1
  190. package/docs/api/30-api-server.mdx +1 -1
  191. package/package.json +1 -1
  192. package/src/client/browser-entry/index.ts +0 -2
  193. package/src/client/browser-entry/router-init.ts +2 -4
  194. package/src/client/error-boundary.tsx +1 -1
  195. package/src/client/navigation-commit.ts +4 -18
  196. package/src/client/outlet-content-cache.ts +24 -62
  197. package/src/client/outlet-scope-context.ts +5 -5
  198. package/src/client/params-context.ts +1 -1
  199. package/src/client/router-types.ts +3 -14
  200. package/src/client/router.ts +0 -2
  201. package/src/client/rsc-fetch.ts +1 -1
  202. package/src/client/segment-cache.ts +2 -2
  203. package/src/client/segment-outlet.tsx +19 -51
  204. package/src/client/stale-segment.ts +2 -2
  205. package/src/config-types.ts +0 -17
  206. package/src/config-validation.ts +0 -1
  207. package/src/plugins/entries.ts +0 -1
  208. package/src/routing/route-options.ts +20 -4
  209. package/src/routing/scanner.ts +1 -1
  210. package/src/routing/segment-keys.ts +3 -4
  211. package/src/rsc-runtime/vendor-types.d.ts +1 -1
  212. package/src/server/als-registry.ts +2 -23
  213. package/src/server/client-state-tree.ts +7 -18
  214. package/src/server/flight-source-node.ts +1 -5
  215. package/src/server/flight-source.ts +1 -81
  216. package/src/server/framework-stack-frames.ts +1 -4
  217. package/src/server/request-context.ts +6 -5
  218. package/src/server/route-element-builder.ts +13 -14
  219. package/src/server/rsc-entry/helpers.ts +1 -1
  220. package/src/server/rsc-entry/index.ts +0 -3
  221. package/src/server/rsc-entry/render-route.ts +7 -54
  222. package/src/server/rsc-entry/revalidate-renderer.ts +0 -2
  223. package/src/server/rsc-entry/rsc-stream.ts +3 -23
  224. package/src/server/segment-lifetime/outlet-gate.ts +102 -0
  225. package/src/server/segment-lifetime/read-rule.ts +63 -6
  226. package/src/server/segment-lifetime/read-scope.ts +4 -2
  227. package/src/server/segment-lifetime/segment-key.ts +31 -3
  228. package/src/server/segment-lifetime/slot-outlets.ts +5 -5
  229. package/src/server/slot-resolver.ts +8 -8
  230. package/src/server/types.ts +8 -2
  231. package/src/server/vite-handoff-rsc.ts +1 -12
  232. package/src/shared/key-headers.ts +42 -0
  233. package/src/shared/outlet-decision.ts +13 -48
  234. package/src/shared/payload-root.ts +1 -1
  235. package/src/shared/segment-info.ts +3 -7
  236. package/dist/_chunks/actions-BCYVyoFl.js.map +0 -1
  237. package/dist/_chunks/chains-DPZAMMav.js +0 -1
  238. package/dist/_chunks/convention-lint-BfC_dAhZ.js.map +0 -1
  239. package/dist/_chunks/dev-server-3DNTXQV-.js +0 -1
  240. package/dist/_chunks/dev-server-3R6Bl9_R.js.map +0 -1
  241. package/dist/_chunks/error-boundary-Dfhxigko.js.map +0 -1
  242. package/dist/_chunks/flight-source-node-QOpWZATb.js.map +0 -1
  243. package/dist/native/rsc/server/segment-hash/capture.js +0 -107
  244. package/dist/native/rsc/server/segment-hash/capture.js.map +0 -1
  245. package/dist/native/rsc/server/segment-hash/outlet.js +0 -101
  246. package/dist/native/rsc/server/segment-hash/outlet.js.map +0 -1
  247. package/dist/native/rsc/server/segment-hash/stream-tap.js +0 -139
  248. package/dist/native/rsc/server/segment-hash/stream-tap.js.map +0 -1
  249. package/dist/native/rsc/server/segment-hash/value-hash.js +0 -171
  250. package/dist/native/rsc/server/segment-hash/value-hash.js.map +0 -1
  251. package/dist/native/ssr/server/segment-hash/value-hash.js +0 -162
  252. package/dist/native/ssr/server/segment-hash/value-hash.js.map +0 -1
  253. package/dist/server/segment-hash/capture.d.ts +0 -77
  254. package/dist/server/segment-hash/capture.d.ts.map +0 -1
  255. package/dist/server/segment-hash/outlet.d.ts +0 -93
  256. package/dist/server/segment-hash/outlet.d.ts.map +0 -1
  257. package/dist/server/segment-hash/stream-tap.d.ts +0 -49
  258. package/dist/server/segment-hash/stream-tap.d.ts.map +0 -1
  259. package/dist/server/segment-hash/value-hash.d.ts +0 -70
  260. package/dist/server/segment-hash/value-hash.d.ts.map +0 -1
  261. package/src/server/segment-hash/capture.ts +0 -232
  262. package/src/server/segment-hash/outlet.ts +0 -229
  263. package/src/server/segment-hash/stream-tap.ts +0 -244
  264. package/src/server/segment-hash/value-hash.ts +0 -338
@@ -217,7 +217,7 @@ export const pageOptions = {
217
217
  | Option | Applies to | Meaning |
218
218
  | ------------------ | ------------ | ----------------------------------------------------------------------------------------------------------- |
219
219
  | `lifetime` | layout, page | `'request'` (default) or `'document'`: render once per loaded document and skip on client navigations until `key` changes ([Document lifetime](/docs/client-navigation#document-lifetime)). Slots included. |
220
- | `key` | layout, page | What a `'document'` segment depends on: `segmentParams` (names on its path; default all of them), `searchParams` (a definition), `cookies` (definitions). |
220
+ | `key` | layout, page | What a `'document'` segment depends on: `segmentParams` (names on its path; default all of them), `searchParams` (a definition), `cookies` (definitions), `headers` (header names). |
221
221
  | `prerender` | layout, page | Render at build time ([route-level sugar](/docs/api-cache#route-level-sugar)). Layouts cascade it to pages, slot pages included. |
222
222
  | `deferSuspenseFor` | layout, page | Hold the SSR stream up to N ms ([`deferSuspenseFor`](/docs/streaming#defersuspensefor)). Main route only, not parallel slots. |
223
223
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@timber-js/app",
3
- "version": "0.2.0-alpha.241",
3
+ "version": "0.2.0-alpha.242",
4
4
  "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
5
5
  "keywords": [
6
6
  "cloudflare-workers",
@@ -103,8 +103,6 @@ function bootstrap(runtimeConfig: typeof config, formState: ReactFormState | nul
103
103
  });
104
104
  const { router, navApiController, hydrate } = createTimberRouter({
105
105
  render: reactRoot.render,
106
- clientSegmentCache:
107
- ((runtimeConfig as Record<string, unknown>).clientSegmentCache as boolean) ?? false,
108
106
  });
109
107
 
110
108
  // Step 4: Make the page current and hydrate (no root without a payload)
@@ -36,7 +36,6 @@ export interface RouterInitOptions {
36
36
  * around `root.render`, and the `publish` it takes runs on React's commit.
37
37
  */
38
38
  render: NavigationRender;
39
- clientSegmentCache?: boolean;
40
39
  }
41
40
 
42
41
  export interface RouterInitResult {
@@ -82,12 +81,12 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
82
81
  */
83
82
  let displayed: { tree: unknown; params: ParamsSource; navState: NavigationState } | null = null;
84
83
 
85
- // The outlet content the client has committed, by segment path and hash.
84
+ // The 'document' content the client has committed, by segment path and digest.
86
85
  // Owned here so there is exactly one per router (never a module or
87
86
  // globalThis singleton — SegmentOutlet also executes during SSR, where a
88
87
  // process-wide record would be shared across requests). Read by
89
88
  // SegmentOutlet in render, written by it at commit only, and read by the
90
- // router for the hashes it advertises. See client/outlet-content-cache.ts.
89
+ // router for the digests it advertises. See client/outlet-content-cache.ts.
91
90
  const outletContentCache = new OutletContentCache();
92
91
 
93
92
  /**
@@ -237,7 +236,6 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
237
236
  };
238
237
 
239
238
  const deps: RouterDeps = {
240
- clientSegmentCache: options?.clientSegmentCache ?? false,
241
239
  outletContentCache,
242
240
  fetch: (url, init) => window.fetch(url, init),
243
241
  pushState: (data, unused, url) => {
@@ -154,7 +154,7 @@ let _pendingRedirectLocation: string | null = null;
154
154
  * Resets a boundary showing an error once a new navigation reaches it.
155
155
  *
156
156
  * Live content resets the boundary through new `children`. Content a skip
157
- * reuses (design/52) is the same element tree as before — the boundary sees
157
+ * reuses (design/53) is the same element tree as before — the boundary sees
158
158
  * the same `children` and would keep showing the old error, never mounting
159
159
  * the nested outlet that holds the new decision. What a skip does change is
160
160
  * the outlet scope: a new one for every decision. A scope other than the one
@@ -141,13 +141,6 @@ export function deriveNavigationState(url: string): NavigationState {
141
141
  export function createNavigationCommitter(deps: {
142
142
  segmentCache: SegmentCache;
143
143
  historyStack: HistoryStack;
144
- /** Read at call time — the router's `clientSegmentCache` opt-in. */
145
- clientSegmentCache: () => boolean | undefined;
146
- /**
147
- * The segment hashes the client holds content for, by outlet path
148
- * (`OutletContentCache.hashes()`). Empty outside a browser router.
149
- */
150
- outletHashes: () => Record<string, string>;
151
144
  /**
152
145
  * The key digests of the `'document'` segments the client holds content
153
146
  * for (`OutletContentCache.documents()`). Empty outside a browser router.
@@ -169,12 +162,9 @@ export function createNavigationCommitter(deps: {
169
162
  /**
170
163
  * The X-Timber-State-Tree to send with the next RSC request.
171
164
  *
172
- * Two different things travel on one header. `hashes` are the caching
173
- * opt-in — the segment hashes the client holds content for — and are
174
- * omitted unless `clientSegmentCache` is on (design/52). `documents` are
175
- * the key digests of 'document' segments (design/53), sent whenever the
176
- * client holds one.
177
- * `treePaths` is how the server learns which route is actually mounted,
165
+ * Two different things travel on one header. `documents` are the key
166
+ * digests of 'document' segments (design/53), sent whenever the client
167
+ * holds one. `treePaths` is how the server learns which route is actually mounted,
178
168
  * which stops being derivable from the address bar as soon as a modal is
179
169
  * open — so it crosses regardless (TIM-1282). Undefined when there is
180
170
  * nothing to say, so a no-op header never enters the `_rsc` cache key.
@@ -187,13 +177,9 @@ export function createNavigationCommitter(deps: {
187
177
  const tree: StateTree = {};
188
178
  const treePaths = segmentCache.treePaths();
189
179
  if (treePaths.length > 0) tree.treePaths = treePaths;
190
- if (deps.clientSegmentCache()) {
191
- const hashes = deps.outletHashes();
192
- if (Object.keys(hashes).length > 0) tree.hashes = hashes;
193
- }
194
180
  const documents = deps.outletDocuments();
195
181
  if (Object.keys(documents).length > 0) tree.documents = documents;
196
- return tree.treePaths || tree.hashes || tree.documents ? tree : undefined;
182
+ return tree.treePaths || tree.documents ? tree : undefined;
197
183
  },
198
184
 
199
185
  /**
@@ -1,16 +1,14 @@
1
1
  /**
2
- * The router-owned record of outlet content the client has *committed*, by
3
- * segment path and the hash the server advertised for it — or, for a
4
- * `'document'` segment (design/53-segment-lifetime.md), the key digest it
5
- * rendered under.
2
+ * The router-owned record of `'document'` segment content the client has
3
+ * *committed* (design/53-segment-lifetime.md), by segment path and the key
4
+ * digest it rendered under.
6
5
  *
7
- * A skipped outlet renders the content it holds under the skip's hash, so
8
- * the record is content-addressed: an outlet looks up `(path, hash)` or
9
- * `(path, digest)`, never
10
- * "whatever was last at this path". A stored payload replayed later, or a
11
- * prefetch consumed after the tree moved on, therefore either finds exactly
12
- * the content the server matched or finds nothing — never a newer or older
13
- * copy (design/52 §"The client checks before reusing").
6
+ * A skipped outlet renders the content it holds under the skip's digest, so
7
+ * an outlet looks up `(path, digest)`, never "whatever was last at this
8
+ * path". A stored payload replayed later, or a prefetch consumed after the
9
+ * tree moved on, therefore either finds exactly the content the server
10
+ * matched or finds nothing — never a newer or older copy. Only `'document'`
11
+ * content is recorded: nothing else is ever skipped.
14
12
  *
15
13
  * Ownership and write discipline (TIM-1423):
16
14
  *
@@ -21,10 +19,6 @@
21
19
  * - **Written only at commit.** `SegmentOutlet` records from a layout effect,
22
20
  * never during render, so a render React discards — a superseded
23
21
  * transition, a Suspense retry — records nothing.
24
- * - **A hash attaches to its own entry.** The hash arrives after the content
25
- * (it is computed from the rows that carried it), so the effect records the
26
- * content first and attaches the hash to that entry when it resolves. An
27
- * entry without a hash is never advertised.
28
22
  * - **`null` outside a router.** SSR renders no provider; the server never
29
23
  * sends a skip to a document request, and layout effects do not run there.
30
24
  *
@@ -38,9 +32,8 @@ import { createGlobalContext } from './global-context.ts';
38
32
 
39
33
  interface Entry {
40
34
  content: ReactNode;
41
- hash: string | null;
42
- /** A `'document'` segment's key digest, known when the content arrives. */
43
- digest: string | null;
35
+ /** The key digest the content rendered under. */
36
+ digest: string;
44
37
  }
45
38
 
46
39
  /**
@@ -52,9 +45,9 @@ const ENTRIES_PER_PATH = 3;
52
45
 
53
46
  /**
54
47
  * Paths kept, least recently committed evicted first. Bounds the memory the
55
- * cache pins (each entry holds a rendered subtree) and the `hashes` map the
56
- * router sends on every navigation, which must stay well inside a server's
57
- * header limits — the server ignores a map of more than 512 entries.
48
+ * cache pins (each entry holds a rendered subtree) and the `documents` map
49
+ * the router sends on every navigation, which must stay well inside a
50
+ * server's header limits — the server ignores a map of more than 512 entries.
58
51
  */
59
52
  const MAX_PATHS = 64;
60
53
 
@@ -62,13 +55,13 @@ export class OutletContentCache {
62
55
  private readonly byPath = new Map<string, Entry[]>();
63
56
 
64
57
  /**
65
- * Record content an outlet committed, with the key digest it rendered under
66
- * if it is a `'document'` segment. Returns the entry to attach its hash to.
58
+ * Record content an outlet committed. Only a `'document'` segment's
59
+ * content, which carries the key digest it rendered under, is kept.
67
60
  */
68
- record(segmentPath: string, content: ReactNode, digest?: string): Entry {
61
+ record(segmentPath: string, content: ReactNode, digest: string | undefined): void {
62
+ if (digest === undefined) return;
69
63
  const entries = this.byPath.get(segmentPath) ?? [];
70
- const entry: Entry = { content, hash: null, digest: digest ?? null };
71
- entries.unshift(entry);
64
+ entries.unshift({ content, digest });
72
65
  if (entries.length > ENTRIES_PER_PATH) entries.length = ENTRIES_PER_PATH;
73
66
  // Re-inserted, so the Map's order is least recently committed first.
74
67
  this.byPath.delete(segmentPath);
@@ -77,54 +70,23 @@ export class OutletContentCache {
77
70
  if (this.byPath.size <= MAX_PATHS) break;
78
71
  this.byPath.delete(path);
79
72
  }
80
- return entry;
81
73
  }
82
74
 
83
- /** Attach the server's hash for a recorded entry, if it is still held. */
84
- attachHash(segmentPath: string, entry: Entry, hash: string): void {
85
- const entries = this.byPath.get(segmentPath);
86
- if (!entries?.includes(entry)) return;
87
- // An identical earlier version is now redundant — keep the newest.
88
- const duplicate = entries.findIndex((e) => e !== entry && e.hash === hash);
89
- if (duplicate !== -1) entries.splice(duplicate, 1);
90
- entry.hash = hash;
91
- }
92
-
93
- /** The content committed under `hash` at `segmentPath`, if held. */
94
- lookup(segmentPath: string, hash: string): { content: ReactNode } | undefined {
95
- return this.byPath.get(segmentPath)?.find((e) => e.hash === hash);
96
- }
97
-
98
- /** The `'document'` content committed under `digest` at `segmentPath`, if held. */
99
- lookupDocument(segmentPath: string, digest: string): { content: ReactNode } | undefined {
75
+ /** The content committed under `digest` at `segmentPath`, if held. */
76
+ lookup(segmentPath: string, digest: string): { content: ReactNode } | undefined {
100
77
  return this.byPath.get(segmentPath)?.find((e) => e.digest === digest);
101
78
  }
102
79
 
103
- /**
104
- * What to advertise in `X-Timber-State-Tree`: per path, the hash of the
105
- * most recently committed content — only when it is known. A path whose
106
- * latest content has no hash yet advertises nothing, which means a resend.
107
- */
108
- hashes(): Record<string, string> {
109
- const out: Record<string, string> = {};
110
- for (const [path, entries] of this.byPath) {
111
- const latest = entries[0];
112
- if (latest?.hash) out[path] = latest.hash;
113
- }
114
- return out;
115
- }
116
-
117
80
  /**
118
81
  * What to advertise as `documents` in `X-Timber-State-Tree`: per path, the
119
- * key digest of the most recently committed content, when that content is
120
- * a `'document'` segment's. Sent on every navigation — it is not part of
121
- * the `clientSegmentCache` opt-in — and kept out of the `_rsc` key.
82
+ * key digest of the most recently committed content. Kept out of the
83
+ * `_rsc` key.
122
84
  */
123
85
  documents(): Record<string, string> {
124
86
  const out: Record<string, string> = {};
125
87
  for (const [path, entries] of this.byPath) {
126
88
  const latest = entries[0];
127
- if (latest?.digest) out[path] = latest.digest;
89
+ if (latest) out[path] = latest.digest;
128
90
  }
129
91
  return out;
130
92
  }
@@ -4,7 +4,7 @@
4
4
  *
5
5
  * A skipped outlet renders its cached content, and that content still holds
6
6
  * the nested `SegmentOutlet` elements from when it was committed — with
7
- * their old decisions. The skip carries the new ones (`SkipDecision.outlets`)
7
+ * their old decisions. The skip carries the new ones (`DocumentSkip.outlets`)
8
8
  * and provides them here, so each old outlet element renders its segment's
9
9
  * new decision in place: same element type, same position, so React keeps
10
10
  * every component's state below it.
@@ -14,12 +14,12 @@
14
14
  * segment was sent or skipped.
15
15
  *
16
16
  * Singleton across bundler-duplicated chunks via `createGlobalContext`.
17
- * See design/52-segment-hash-dedupe.md §"Wire format".
17
+ * See design/53-segment-lifetime.md §"Skipping".
18
18
  */
19
19
 
20
20
  'use client';
21
21
 
22
- import type { OutletDecisionValue } from '../shared/outlet-decision.ts';
22
+ import type { OutletDecision } from '../shared/outlet-decision.ts';
23
23
  import { createGlobalContext } from './global-context.ts';
24
24
 
25
25
  export interface OutletScope {
@@ -28,12 +28,12 @@ export interface OutletScope {
28
28
  * entry in `decisions` would render a stale decision, so it refuses to.
29
29
  */
30
30
  skipped: boolean;
31
- decisions: ReadonlyMap<string, OutletDecisionValue>;
31
+ decisions: ReadonlyMap<string, OutletDecision>;
32
32
  }
33
33
 
34
34
  export const LIVE_OUTLET_SCOPE: OutletScope = Object.freeze({
35
35
  skipped: false,
36
- decisions: new Map<string, OutletDecisionValue>(),
36
+ decisions: new Map<string, OutletDecision>(),
37
37
  });
38
38
 
39
39
  export const OutletScopeContext = createGlobalContext<OutletScope>(
@@ -19,7 +19,7 @@
19
19
  * to be there and it has to be alone: a segment the server skipped renders the
20
20
  * content the client cached for it, which carries no provider of its own, so a
21
21
  * provider *inside* the payload would never reach a reader in a skipped layout
22
- * (TIM-1297, design/52-segment-hash-dedupe.md).
22
+ * (TIM-1297, design/53-segment-lifetime.md).
23
23
  *
24
24
  * Ordering still holds without a bootstrap contract, for the same reason it
25
25
  * did when the provider was in the tree: a provider renders before its own
@@ -154,20 +154,9 @@ export interface RouterDeps {
154
154
  scrollToHash?: (hash: string) => boolean;
155
155
 
156
156
  /**
157
- * Whether the client segment cache is enabled. When false (the default),
158
- * the router advertises no segment hashes, so the server sends every
159
- * segment (design/52-segment-hash-dedupe.md).
160
- *
161
- * It does NOT gate the `treePaths` half of X-Timber-State-Tree. Those
162
- * describe the tree currently mounted, and interception scoping needs them
163
- * to open a modal on top of a modal — a routing behaviour, not a caching
164
- * optimization, so it must not depend on a performance opt-in (TIM-1282).
165
- */
166
- clientSegmentCache?: boolean;
167
-
168
- /**
169
- * The router's record of committed outlet content and its hashes — the
170
- * source of the hashes the router advertises. Absent outside a browser.
157
+ * The router's record of committed `'document'` content and its key
158
+ * digests — the source of the digests the router advertises. Absent
159
+ * outside a browser.
171
160
  */
172
161
  outletContentCache?: OutletContentCache;
173
162
  }
@@ -55,8 +55,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
55
55
  const { prepareNavigation, currentStateTree, committedSegmentInfo } = createNavigationCommitter({
56
56
  segmentCache,
57
57
  historyStack,
58
- clientSegmentCache: () => deps.clientSegmentCache,
59
- outletHashes: () => deps.outletContentCache?.hashes() ?? {},
60
58
  outletDocuments: () => deps.outletContentCache?.documents() ?? {},
61
59
  });
62
60
 
@@ -481,7 +481,7 @@ export async function fetchRscPayload(
481
481
  // Accept headers, so the route URL would return HTML.
482
482
  const staticTarget = staticMode ? toStaticRscUrl(url) : null;
483
483
  const fetchTarget = staticTarget ? staticTarget.url : url;
484
- // Static hosts resolve neither segment hashes nor intercepting routes,
484
+ // Static hosts resolve neither key digests nor intercepting routes,
485
485
  // so neither the state tree nor the source URL is sent — and neither may
486
486
  // fragment the cache key of a file that does not vary on them.
487
487
  const headers = staticMode
@@ -35,8 +35,8 @@ export interface PrefetchResult {
35
35
  * interception scoping (TIM-1282).
36
36
  *
37
37
  * Content reuse is not decided here. The outlet content cache holds what the
38
- * client can reuse, keyed by segment hash (client/outlet-content-cache.ts,
39
- * design/52-segment-hash-dedupe.md).
38
+ * client can reuse, keyed by key digest (client/outlet-content-cache.ts,
39
+ * design/53-segment-lifetime.md).
40
40
  *
41
41
  * Written only by a navigation's commit (`navigation-commit.ts`), so a
42
42
  * superseded navigation never describes the mounted tree (TIM-1301).
@@ -2,14 +2,13 @@
2
2
  * SegmentOutlet — the client boundary around one segment: a layout's own
3
3
  * chrome, a layout's `children`, a parallel slot, or the page's metadata.
4
4
  *
5
- * The server decides each outlet (server/segment-hash/outlet.ts):
5
+ * The server decides each outlet (server/segment-lifetime/outlet-gate.ts):
6
6
  *
7
7
  * - **Live** — the outlet renders the content it was sent, and once React
8
- * commits it, records it in the router's outlet content cache beside the
9
- * hash the server computed from the rows that carried it.
10
- * - **Skip** — the client already holds content with this hash (or, for a
11
- * `'document'` segment, rendered under this key digest — the server did
12
- * not render it at all). The outlet
8
+ * commits it, records it in the router's outlet content cache — beside its
9
+ * key digest when it is a `'document'` segment.
10
+ * - **Skip** — the client holds this `'document'` segment's content under
11
+ * the skip's key digest; the server did not render it at all. The outlet
13
12
  * renders the cached copy, and provides the nested outlets' new decisions
14
13
  * to the outlet elements inside that copy (client/outlet-scope-context.ts),
15
14
  * so each renders its segment's new decision in place.
@@ -24,18 +23,14 @@
24
23
  * what a later skip resolves to (TIM-1423).
25
24
  *
26
25
  * Security: performance only. The server runs every access.ts regardless, and
27
- * a skip whose hash the client does not hold leaves the SPA rather than show
26
+ * a skip whose digest the client does not hold leaves the SPA rather than show
28
27
  * other content. See design/13-security.md §"State tree manipulation".
29
28
  */
30
29
 
31
30
  'use client';
32
31
 
33
- import { createElement, use, useContext, useLayoutEffect, useMemo, type ReactNode } from 'react';
34
- import type {
35
- CaptureHole,
36
- OutletDecision,
37
- OutletDecisionValue,
38
- } from '../shared/outlet-decision.ts';
32
+ import { createElement, useContext, useLayoutEffect, useMemo, type ReactNode } from 'react';
33
+ import type { OutletDecision } from '../shared/outlet-decision.ts';
39
34
  import { OutletContentCacheContext } from './outlet-content-cache.ts';
40
35
  import { LIVE_OUTLET_SCOPE, OutletScopeContext, type OutletScope } from './outlet-scope-context.ts';
41
36
  import { staleSegmentError } from './stale-segment.ts';
@@ -43,23 +38,13 @@ import { staleSegmentError } from './stale-segment.ts';
43
38
  export interface SegmentOutletProps {
44
39
  /**
45
40
  * The outlet's key: a segment id (`/`, `/(marketing)`), a slot key
46
- * (`/@sidebar`), a layout's children (`/dashboard/@children`), or the
47
- * metadata outlet.
41
+ * (`/@sidebar`), a layout's children (`/dashboard/@children`), a
42
+ * `'document'` segment's tree-path key (`/#layout`), or the metadata
43
+ * outlet.
48
44
  */
49
45
  segmentPath: string;
50
- /**
51
- * What the server decided for this segment. Absent only on the bare holes
52
- * a capture render emits, which never reach the client.
53
- */
54
- decision?: OutletDecisionValue | CaptureHole;
55
- }
56
-
57
- function isCaptureHole(value: OutletDecisionValue | CaptureHole): value is CaptureHole {
58
- return 'captureHole' in value;
59
- }
60
-
61
- function isThenable(value: OutletDecisionValue): value is PromiseLike<OutletDecision> {
62
- return typeof (value as PromiseLike<OutletDecision>).then === 'function';
46
+ /** What the server decided for this segment. */
47
+ decision: OutletDecision;
63
48
  }
64
49
 
65
50
  export function SegmentOutlet({ segmentPath, decision }: SegmentOutletProps): ReactNode {
@@ -68,17 +53,10 @@ export function SegmentOutlet({ segmentPath, decision }: SegmentOutletProps): Re
68
53
 
69
54
  // Inside a skipped segment's cached content this element is from an
70
55
  // earlier render; the skip handed down this segment's new decision.
71
- const value = scope.skipped ? scope.decisions.get(segmentPath) : decision;
72
- // A capture's hole marker is replaced before anything is sent; one that got
73
- // through is a decision the client does not have.
74
- if (value === undefined || isCaptureHole(value)) throw staleSegmentError(segmentPath);
75
- const resolved = isThenable(value) ? use(value) : value;
56
+ const resolved = scope.skipped ? scope.decisions.get(segmentPath) : decision;
57
+ if (resolved === undefined) throw staleSegmentError(segmentPath);
76
58
 
77
- const cached = !resolved.skip
78
- ? undefined
79
- : resolved.digest !== undefined
80
- ? cache?.lookupDocument(segmentPath, resolved.digest)
81
- : cache?.lookup(segmentPath, resolved.hash);
59
+ const cached = resolved.skip ? cache?.lookup(segmentPath, resolved.digest) : undefined;
82
60
  if (resolved.skip && !cached) throw staleSegmentError(segmentPath);
83
61
  const content: ReactNode = resolved.skip ? cached!.content : resolved.children;
84
62
  const childScope = useMemo<OutletScope>(
@@ -89,21 +67,11 @@ export function SegmentOutlet({ segmentPath, decision }: SegmentOutletProps): Re
89
67
  [resolved]
90
68
  );
91
69
 
92
- // Commit-time write: live content is recorded once React commits it, and
93
- // its hash attached when the server's arrives.
70
+ // Commit-time write: live content is recorded once React commits it.
94
71
  useLayoutEffect(() => {
95
72
  if (cache === null) return;
96
- if (resolved.skip) {
97
- cache.touch(segmentPath, content);
98
- return;
99
- }
100
- const entry = cache.record(segmentPath, content, resolved.digest);
101
- resolved.hash?.then(
102
- (hash) => {
103
- if (hash) cache.attachHash(segmentPath, entry, hash);
104
- },
105
- () => {}
106
- );
73
+ if (resolved.skip) cache.touch(segmentPath, content);
74
+ else cache.record(segmentPath, content, resolved.digest);
107
75
  }, [resolved, cache, segmentPath, content]);
108
76
 
109
77
  return createElement(OutletScopeContext.Provider, { value: childScope }, content);
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * The error a `SegmentOutlet` throws when it cannot render what the server
3
- * decided — a skip whose content the client no longer holds under that hash,
3
+ * decided — a skip whose content the client no longer holds under that digest,
4
4
  * or an outlet inside a skipped segment that received no new decision.
5
5
  *
6
6
  * Either means the client's record moved on between the request and the
@@ -8,7 +8,7 @@
8
8
  * evicted). Rendering anything else would show content the server did not
9
9
  * produce, so the error passes every boundary to the terminal, which fetches
10
10
  * the page again (`recoverFromStaleSegment`) — and leaves the SPA only if
11
- * that misses too (design/52 §"The client checks before reusing").
11
+ * that misses too (design/53-segment-lifetime.md §"Skipping").
12
12
  */
13
13
 
14
14
  export interface StaleSegmentDigest {
@@ -328,23 +328,6 @@ export interface TimberUserConfig {
328
328
  * ```
329
329
  */
330
330
  buildDir?: string;
331
- /**
332
- * Skip unchanged segments on client navigation (segment hash dedupe).
333
- *
334
- * When enabled, every live segment the server sends carries a hash of its
335
- * output, and the router advertises the hashes of the content it holds in
336
- * `X-Timber-State-Tree`. The server still renders every segment; one whose
337
- * output hashes the same as the client's copy is sent as a skip, and the
338
- * client keeps its copy. Every segment renders once either way.
339
- *
340
- * When disabled (the default), every navigation gets a full RSC payload.
341
- *
342
- * This is a performance optimization only — not a security boundary.
343
- * The server always runs all `access.ts` files regardless.
344
- *
345
- * See design/52-segment-hash-dedupe.md
346
- */
347
- clientSegmentCache?: boolean;
348
331
  /**
349
332
  * The lifetime of every layout that does not declare one, slot layouts
350
333
  * included. Pages are unaffected, and a layout's own
@@ -56,7 +56,6 @@ const KNOWN_CONFIG_KEYS = {
56
56
  sitemap: true,
57
57
  buildDir: true,
58
58
  cache: true,
59
- clientSegmentCache: true,
60
59
  defaultLayoutLifetime: true,
61
60
  topLoader: true,
62
61
  budget: true,
@@ -164,7 +164,6 @@ function generateConfigModule(ctx: PluginContext): string {
164
164
  // Per-build deployment ID for version skew detection (TIM-446).
165
165
  // Null in dev mode — HMR handles code updates without full reloads.
166
166
  deploymentId: ctx.deploymentId ?? null,
167
- clientSegmentCache: ctx.config.clientSegmentCache ?? false,
168
167
  // Read by the RSC entry only: the lifetime of a layout that declares none
169
168
  // (design/53 §"App-wide default").
170
169
  defaultLayoutLifetime: ctx.config.defaultLayoutLifetime === 'document' ? 'document' : 'request',
@@ -33,6 +33,7 @@
33
33
  * nothing and its `deferSuspenseFor` is unvalidated.
34
34
  */
35
35
 
36
+ import { headerKeyProblem } from '../shared/key-headers.ts';
36
37
  import { existsSync } from 'node:fs';
37
38
  import type {
38
39
  LayoutOptions,
@@ -191,13 +192,23 @@ function readLifetime(node: Node): Read<SegmentLifetime> {
191
192
  }
192
193
 
193
194
  /**
194
- * What the build can read of a segment key: the param names. `searchParams`
195
+ * What the build can read of a segment key: the param and header names. `searchParams`
195
196
  * and `cookies` name definitions — code the build cannot evaluate — so only
196
197
  * their shape is checked here; their values take effect from the loaded
197
198
  * module (`server/segment-lifetime/`). The route-options lint checks the
198
199
  * param names against the segment's path.
199
200
  */
200
- type BuildTimeKey = Pick<SegmentKey, 'segmentParams'>;
201
+ type BuildTimeKey = Pick<SegmentKey, 'segmentParams' | 'headers'>;
202
+
203
+ function readHeaderNames(node: Node): Read<string[]> {
204
+ const names = readStringArray(node);
205
+ if (!names) return { problem: 'key.headers must be an array of header-name string literals.' };
206
+ for (const name of names) {
207
+ const problem = headerKeyProblem(name);
208
+ if (problem) return { problem };
209
+ }
210
+ return { value: names };
211
+ }
201
212
 
202
213
  /** A value written in place, which cannot be a definition imported or declared elsewhere. */
203
214
  function isInlineValue(node: Node): boolean {
@@ -215,7 +226,8 @@ function readKey(node: Node): Read<BuildTimeKey> {
215
226
  const n = unwrap(node);
216
227
  if (n.type !== 'ObjectExpression') {
217
228
  return {
218
- problem: 'key must be an object literal `{ segmentParams?, searchParams?, cookies? }`.',
229
+ problem:
230
+ 'key must be an object literal `{ segmentParams?, searchParams?, cookies?, headers? }`.',
219
231
  };
220
232
  }
221
233
  const result: BuildTimeKey = {};
@@ -243,9 +255,13 @@ function readKey(node: Node): Read<BuildTimeKey> {
243
255
  problem: 'key.cookies must be an array literal of cookie definitions (`defineCookie`).',
244
256
  };
245
257
  }
258
+ } else if (entry.key === 'headers') {
259
+ const headers = readHeaderNames(entry.value);
260
+ if ('problem' in headers) return headers;
261
+ result.headers = headers.value;
246
262
  } else {
247
263
  return {
248
- problem: `Unknown key "${entry.key}" in key. Allowed: segmentParams, searchParams, cookies.`,
264
+ problem: `Unknown key "${entry.key}" in key. Allowed: segmentParams, searchParams, cookies, headers.`,
249
265
  };
250
266
  }
251
267
  }
@@ -369,7 +369,7 @@ function scanChildren(dirPath: string, parentNode: SegmentNode, extSet: Set<stri
369
369
  // `@children` is the implicit slot a layout's `children` prop fills, and
370
370
  // the key of the outlet that carries it (`childrenOutletKey`). A slot
371
371
  // directory by that name would claim the same outlet and be rendered in
372
- // place of the children (design/52-segment-hash-dedupe.md).
372
+ // place of the children.
373
373
  if (entry === '@children') {
374
374
  throw new Error(
375
375
  `Build error: "@children" is reserved and cannot be a slot directory.\n` +
@@ -150,10 +150,9 @@ export function computeSlotKey(parentSegmentId: string, slotName: string): strin
150
150
  * The outlet key of a layout's `children`. A layout's own outlet covers its
151
151
  * chrome; everything it receives as `children` — this segment's boundaries
152
152
  * and metadata collectors, the next segment's access gate, the page — is a
153
- * separate outlet, so an unchanged layout
154
- * dedupes while what is under it changes. Keyed as the implicit `children`
155
- * slot; the route scanner rejects an `@children` directory.
156
- * See design/52-segment-hash-dedupe.md §"The unit is the segment's own output".
153
+ * separate outlet, so a skipped 'document' layout never freezes what is under
154
+ * it. Keyed as the implicit `children` slot; the route scanner rejects an
155
+ * `@children` directory. See design/53-segment-lifetime.md §"Skipping".
157
156
  */
158
157
  export function childrenOutletKey(segmentId: string): string {
159
158
  return computeSlotKey(segmentId, '@children');
@@ -75,7 +75,7 @@ declare module '@vitejs/plugin-rsc/vendor/react-server-dom/server.edge' {
75
75
  exportName: string | null
76
76
  ): T;
77
77
 
78
- // Tests render real client references (segment-hash tests) the way the
78
+ // Tests render real client references the way the
79
79
  // use-client transform registers them.
80
80
  export function registerClientReference<T>(
81
81
  proxyImplementation: T,