@timber-js/app 0.2.0-alpha.221 → 0.2.0-alpha.223

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 (380) hide show
  1. package/agent-skill.md +21 -5
  2. package/dist/_chunks/{actions-BDqn4Oxj.js → actions-7dTXYJfu.js} +53 -24
  3. package/dist/_chunks/actions-7dTXYJfu.js.map +1 -0
  4. package/dist/_chunks/{als-registry-BZqHCtq-.js → als-registry-DpygwCp0.js} +2 -3
  5. package/dist/_chunks/{als-registry-BZqHCtq-.js.map → als-registry-DpygwCp0.js.map} +1 -1
  6. package/dist/_chunks/{als-slots-BEEIPKYm.js → als-slots-kbQrHTzm.js} +2 -3
  7. package/dist/_chunks/{als-slots-BEEIPKYm.js.map → als-slots-kbQrHTzm.js.map} +1 -1
  8. package/dist/_chunks/{base-path-DaQrzbez.js → base-path-DDIx0FXe.js} +2 -3
  9. package/dist/_chunks/{base-path-DaQrzbez.js.map → base-path-DDIx0FXe.js.map} +1 -1
  10. package/dist/_chunks/{build-manifest-DWppEdLB.js → build-manifest-Y4jl7nwU.js} +2 -3
  11. package/dist/_chunks/{build-manifest-DWppEdLB.js.map → build-manifest-Y4jl7nwU.js.map} +1 -1
  12. package/dist/_chunks/{build-output-helper-RV_BRcF1.js → build-output-helper-B7wWGTfR.js} +14 -10
  13. package/dist/_chunks/build-output-helper-B7wWGTfR.js.map +1 -0
  14. package/dist/_chunks/{cache-api-GE4AOe2H.js → cache-api-TDZ4hlDc.js} +237 -37
  15. package/dist/_chunks/cache-api-TDZ4hlDc.js.map +1 -0
  16. package/dist/_chunks/{canonicalize-BAWkWiKK.js → canonicalize-CqK135BN.js} +29 -4
  17. package/dist/_chunks/{canonicalize-BAWkWiKK.js.map → canonicalize-CqK135BN.js.map} +1 -1
  18. package/dist/_chunks/chains-CwOr3Myj.js +1 -0
  19. package/dist/_chunks/{chains-e_Buf9vg.js → chains-Dgm3PrMe.js} +3 -4
  20. package/dist/_chunks/{chains-e_Buf9vg.js.map → chains-Dgm3PrMe.js.map} +1 -1
  21. package/dist/_chunks/{classify-2Yp3xJY1.js → classify--_kINHQV.js} +4 -5
  22. package/dist/_chunks/{classify-2Yp3xJY1.js.map → classify--_kINHQV.js.map} +1 -1
  23. package/dist/_chunks/{cli-check-DDwCkeDY.js → cli-check-Dv3f8d2j.js} +5 -6
  24. package/dist/_chunks/{cli-check-DDwCkeDY.js.map → cli-check-Dv3f8d2j.js.map} +1 -1
  25. package/dist/_chunks/{cli-context-_mPttGGY.js → cli-context-CbZp32SK.js} +3 -4
  26. package/dist/_chunks/{cli-context-_mPttGGY.js.map → cli-context-CbZp32SK.js.map} +1 -1
  27. package/dist/_chunks/cli-context-n5hmkdla.js +1 -0
  28. package/dist/_chunks/cli-dev-status-prPMLU8G.js +138 -0
  29. package/dist/_chunks/cli-dev-status-prPMLU8G.js.map +1 -0
  30. package/dist/_chunks/cli-init-BoXOYYil.js +196 -0
  31. package/dist/_chunks/cli-init-BoXOYYil.js.map +1 -0
  32. package/dist/_chunks/{cli-schema-sync-BdIebmk3.js → cli-schema-sync-DIPurq7X.js} +4 -5
  33. package/dist/_chunks/{cli-schema-sync-BdIebmk3.js.map → cli-schema-sync-DIPurq7X.js.map} +1 -1
  34. package/dist/_chunks/{cli-schema-sync-CLNfXQDK.js → cli-schema-sync-uq72EZmD.js} +1 -1
  35. package/dist/_chunks/{client-dep-entries-BOkpKjj1.js → client-dep-entries-CP7AkMCM.js} +4 -5
  36. package/dist/_chunks/{client-dep-entries-BOkpKjj1.js.map → client-dep-entries-CP7AkMCM.js.map} +1 -1
  37. package/dist/_chunks/{cloudflare-Byxl8FWP.js → cloudflare-B75X6u4O.js} +10 -13
  38. package/dist/_chunks/{cloudflare-Byxl8FWP.js.map → cloudflare-B75X6u4O.js.map} +1 -1
  39. package/dist/_chunks/{codec-registry-oOUxugz3.js → codec-registry-CPc6bjVl.js} +2 -3
  40. package/dist/_chunks/{codec-registry-oOUxugz3.js.map → codec-registry-CPc6bjVl.js.map} +1 -1
  41. package/dist/_chunks/{codegen-Bps1sLKJ.js → codegen-B9oWkWGf.js} +5 -8
  42. package/dist/_chunks/{codegen-Bps1sLKJ.js.map → codegen-B9oWkWGf.js.map} +1 -1
  43. package/dist/_chunks/{convention-lint-ByKJ6aqD.js → convention-lint-hZwz5wd4.js} +8 -11
  44. package/dist/_chunks/{convention-lint-ByKJ6aqD.js.map → convention-lint-hZwz5wd4.js.map} +1 -1
  45. package/dist/_chunks/dev-discovery-YnabkCKD.js +238 -0
  46. package/dist/_chunks/dev-discovery-YnabkCKD.js.map +1 -0
  47. package/dist/_chunks/{dev-server-DIy-SY-J.js → dev-server-C61GWpGg.js} +409 -51
  48. package/dist/_chunks/dev-server-C61GWpGg.js.map +1 -0
  49. package/dist/_chunks/dev-server-CBvvM7Lr.js +1 -0
  50. package/dist/_chunks/{dev-store-BOa304m_.js → dev-store-BvdqtHvK.js} +82 -38
  51. package/dist/_chunks/dev-store-BvdqtHvK.js.map +1 -0
  52. package/dist/_chunks/{dist-DtrJyBbw.js → dist-C1Rjlo6s.js} +3 -5
  53. package/dist/_chunks/{dist-DtrJyBbw.js.map → dist-C1Rjlo6s.js.map} +1 -1
  54. package/dist/_chunks/{error-boundary-Bc8QPZuq.js → error-boundary-DRQXGWCp.js} +20 -27
  55. package/dist/_chunks/{error-boundary-Bc8QPZuq.js.map → error-boundary-DRQXGWCp.js.map} +1 -1
  56. package/dist/_chunks/{fast-hash-C-tVYrLb.js → fast-hash-DddxkU5Y.js} +2 -3
  57. package/dist/_chunks/{fast-hash-C-tVYrLb.js.map → fast-hash-DddxkU5Y.js.map} +1 -1
  58. package/dist/_chunks/{flight-source-node-HptmGMT8.js → flight-source-node-0Tp6evlz.js} +6 -8
  59. package/dist/_chunks/flight-source-node-0Tp6evlz.js.map +1 -0
  60. package/dist/_chunks/{format-BKclgVbk.js → format-DuPOoXUP.js} +2 -3
  61. package/dist/_chunks/{format-BKclgVbk.js.map → format-DuPOoXUP.js.map} +1 -1
  62. package/dist/_chunks/{fs-identity-BRKuL215.js → fs-identity-BmQ_Agg-.js} +3 -5
  63. package/dist/_chunks/{fs-identity-BRKuL215.js.map → fs-identity-BmQ_Agg-.js.map} +1 -1
  64. package/dist/_chunks/global-context-DbxNWeBP.js +47 -0
  65. package/dist/_chunks/global-context-DbxNWeBP.js.map +1 -0
  66. package/dist/_chunks/{graph-cache-CYiUS2aS.js → graph-cache-B1LAg4t7.js} +5 -89
  67. package/dist/_chunks/graph-cache-B1LAg4t7.js.map +1 -0
  68. package/dist/_chunks/{href-validation-BIrxavIy.js → href-validation-CEZy1V-k.js} +4 -7
  69. package/dist/_chunks/{href-validation-BIrxavIy.js.map → href-validation-CEZy1V-k.js.map} +1 -1
  70. package/dist/_chunks/{json-lossy-check-C8zBY2uZ.js → json-lossy-check-DVkLUlfC.js} +3 -4
  71. package/dist/_chunks/{json-lossy-check-C8zBY2uZ.js.map → json-lossy-check-DVkLUlfC.js.map} +1 -1
  72. package/dist/_chunks/{live-graph-tSWrv8eH.js → live-graph-BcVjQ1Te.js} +6 -7
  73. package/dist/_chunks/{live-graph-tSWrv8eH.js.map → live-graph-BcVjQ1Te.js.map} +1 -1
  74. package/dist/_chunks/{logger-CbLdcy-W.js → logger-CWk44DLp.js} +97 -47
  75. package/dist/_chunks/logger-CWk44DLp.js.map +1 -0
  76. package/dist/_chunks/{metadata-routes-B3XJNyIH.js → metadata-routes-BL26HCDd.js} +2 -3
  77. package/dist/_chunks/{metadata-routes-B3XJNyIH.js.map → metadata-routes-BL26HCDd.js.map} +1 -1
  78. package/dist/_chunks/{navigation-root-BQfo1-kG.js → navigation-root-M3B2ZrdO.js} +6 -10
  79. package/dist/_chunks/{navigation-root-BQfo1-kG.js.map → navigation-root-M3B2ZrdO.js.map} +1 -1
  80. package/dist/_chunks/{node-response-rkQqcFGq.js → node-response-B9aviPDa.js} +43 -9
  81. package/dist/_chunks/node-response-B9aviPDa.js.map +1 -0
  82. package/dist/_chunks/{param-value-C8TNYchQ.js → param-value-DqlGfF57.js} +2 -3
  83. package/dist/_chunks/{param-value-C8TNYchQ.js.map → param-value-DqlGfF57.js.map} +1 -1
  84. package/dist/_chunks/{plugin-context-uDHFqHHJ.js → plugin-context-BfSRKJfz.js} +1 -1
  85. package/dist/_chunks/{plugin-context-DxMMvjUt.js → plugin-context-FCkaNLUB.js} +4 -6
  86. package/dist/_chunks/plugin-context-FCkaNLUB.js.map +1 -0
  87. package/dist/_chunks/{poison-rules-DoEhbqaY.js → poison-rules-Bmz-lCPi.js} +2 -3
  88. package/dist/_chunks/{poison-rules-DoEhbqaY.js.map → poison-rules-Bmz-lCPi.js.map} +1 -1
  89. package/dist/_chunks/{poison-scan-C4FgMxFl.js → poison-scan-DJYxZc_7.js} +4 -5
  90. package/dist/_chunks/{poison-scan-C4FgMxFl.js.map → poison-scan-DJYxZc_7.js.map} +1 -1
  91. package/dist/_chunks/{purge-store-WZaxu-3m.js → purge-store-8BqLAYZ1.js} +2 -3
  92. package/dist/_chunks/{purge-store-WZaxu-3m.js.map → purge-store-8BqLAYZ1.js.map} +1 -1
  93. package/dist/_chunks/{render-timeout-joFhz4KH.js → render-timeout-MrrqD1wd.js} +20 -4
  94. package/dist/_chunks/{render-timeout-joFhz4KH.js.map → render-timeout-MrrqD1wd.js.map} +1 -1
  95. package/dist/_chunks/{resolve-schema-CBR6Lm4i.js → resolve-schema-B-aCuTu3.js} +3 -4
  96. package/dist/_chunks/{resolve-schema-CBR6Lm4i.js.map → resolve-schema-B-aCuTu3.js.map} +1 -1
  97. package/dist/_chunks/{rsc-cache-key-ClUiXQnK.js → rsc-cache-key-D0cb0Gmc.js} +2 -3
  98. package/dist/_chunks/{rsc-cache-key-ClUiXQnK.js.map → rsc-cache-key-D0cb0Gmc.js.map} +1 -1
  99. package/dist/_chunks/{rsc-media-type-DDc7duTD.js → rsc-media-type-m8jz9u6_.js} +2 -3
  100. package/dist/_chunks/{rsc-media-type-DDc7duTD.js.map → rsc-media-type-m8jz9u6_.js.map} +1 -1
  101. package/dist/_chunks/{rsc-payload-path-dffcs4jp.js → rsc-payload-path-EphpDB-J.js} +2 -3
  102. package/dist/_chunks/{rsc-payload-path-dffcs4jp.js.map → rsc-payload-path-EphpDB-J.js.map} +1 -1
  103. package/dist/_chunks/{scan-BoP17W3w.js → scan-CyizcBiX.js} +2 -3
  104. package/dist/_chunks/{scan-BoP17W3w.js.map → scan-CyizcBiX.js.map} +1 -1
  105. package/dist/_chunks/{scanner-Cb3fSjAC.js → scanner-CJC-ScJU.js} +15 -23
  106. package/dist/_chunks/{scanner-Cb3fSjAC.js.map → scanner-CJC-ScJU.js.map} +1 -1
  107. package/dist/_chunks/{schema-bridge-C83xa9lT.js → schema-bridge-DyRs3cqy.js} +61 -25
  108. package/dist/_chunks/schema-bridge-DyRs3cqy.js.map +1 -0
  109. package/dist/_chunks/{segment-classify-C539Pa2O.js → segment-classify-Ho8jXWeC.js} +3 -5
  110. package/dist/_chunks/{segment-classify-C539Pa2O.js.map → segment-classify-Ho8jXWeC.js.map} +1 -1
  111. package/dist/_chunks/{segment-context-xtPUGfdq.js → segment-context-CYiGTi3K.js} +6 -12
  112. package/dist/_chunks/segment-context-CYiGTi3K.js.map +1 -0
  113. package/dist/_chunks/{segment-keys-D5hu1hz4.js → segment-keys-Y60KNc8C.js} +2 -3
  114. package/dist/_chunks/{segment-keys-D5hu1hz4.js.map → segment-keys-Y60KNc8C.js.map} +1 -1
  115. package/dist/_chunks/{singleflight-BeVMMKi0.js → singleflight-BChPMjwH.js} +2 -3
  116. package/dist/_chunks/{singleflight-BeVMMKi0.js.map → singleflight-BChPMjwH.js.map} +1 -1
  117. package/dist/_chunks/{sizeof-QPE5nd3u.js → sizeof-DG4W40lv.js} +3 -4
  118. package/dist/_chunks/{sizeof-QPE5nd3u.js.map → sizeof-DG4W40lv.js.map} +1 -1
  119. package/dist/_chunks/{ssr-data-nA3I70_n.js → ssr-data-9hPtcNOr.js} +3 -4
  120. package/dist/_chunks/{ssr-data-nA3I70_n.js.map → ssr-data-9hPtcNOr.js.map} +1 -1
  121. package/dist/_chunks/{state-BhNGPsdi.js → state-B-EBjeER.js} +2 -3
  122. package/dist/_chunks/{state-BhNGPsdi.js.map → state-B-EBjeER.js.map} +1 -1
  123. package/dist/_chunks/{status-page-marker-BRX9Ib-d.js → status-page-marker-XIQXlTOb.js} +8 -13
  124. package/dist/_chunks/{status-page-marker-BRX9Ib-d.js.map → status-page-marker-XIQXlTOb.js.map} +1 -1
  125. package/dist/_chunks/{tree-match-6yihorhk.js → tree-match-Bqdr9szG.js} +2 -3
  126. package/dist/_chunks/{tree-match-6yihorhk.js.map → tree-match-Bqdr9szG.js.map} +1 -1
  127. package/dist/_chunks/{use-query-states-I3JMng6J.js → use-query-states-pkDV-jSg.js} +4 -7
  128. package/dist/_chunks/{use-query-states-I3JMng6J.js.map → use-query-states-pkDV-jSg.js.map} +1 -1
  129. package/dist/_chunks/{walkers-qu8TpiLh.js → walkers-DIE203ir.js} +6 -8
  130. package/dist/_chunks/{walkers-qu8TpiLh.js.map → walkers-DIE203ir.js.map} +1 -1
  131. package/dist/_chunks/{write-file-atomic-D1qWqHb4.js → write-file-atomic-DW8m_Atv.js} +2 -3
  132. package/dist/_chunks/{write-file-atomic-D1qWqHb4.js.map → write-file-atomic-DW8m_Atv.js.map} +1 -1
  133. package/dist/adapters/build-output-helper.d.ts +10 -1
  134. package/dist/adapters/build-output-helper.d.ts.map +1 -1
  135. package/dist/adapters/cloudflare-dev.js +2 -3
  136. package/dist/adapters/cloudflare-kv-cache.js +3 -4
  137. package/dist/adapters/cloudflare.d.ts.map +1 -1
  138. package/dist/adapters/cloudflare.js +1 -1
  139. package/dist/adapters/nitro-presets.d.ts +6 -0
  140. package/dist/adapters/nitro-presets.d.ts.map +1 -1
  141. package/dist/adapters/nitro-preview.d.ts.map +1 -1
  142. package/dist/adapters/nitro.d.ts.map +1 -1
  143. package/dist/adapters/nitro.js +94 -57
  144. package/dist/adapters/nitro.js.map +1 -1
  145. package/dist/analyze/crawl-entry.js +7 -9
  146. package/dist/analyze/crawl-entry.js.map +1 -1
  147. package/dist/analyze/graph-command.d.ts.map +1 -1
  148. package/dist/analyze/graph-command.js +19 -105
  149. package/dist/analyze/graph-command.js.map +1 -1
  150. package/dist/cache/guarded-read.d.ts +29 -0
  151. package/dist/cache/guarded-read.d.ts.map +1 -0
  152. package/dist/cache/index.js +3 -3
  153. package/dist/cache/key-discipline.d.ts +61 -0
  154. package/dist/cache/key-discipline.d.ts.map +1 -0
  155. package/dist/cache/stores/cloudflare-kv.js +1 -2
  156. package/dist/cache/stores/memory.js +2 -3
  157. package/dist/cache/stores/redis.js +1 -2
  158. package/dist/cache/stores/vercel.js +1 -2
  159. package/dist/cache/timber-cache.d.ts +5 -1
  160. package/dist/cache/timber-cache.d.ts.map +1 -1
  161. package/dist/cdn/cloudflare-purge.js +1 -2
  162. package/dist/cdn/fastly-purge.js +1 -2
  163. package/dist/cdn/index.js +2 -3
  164. package/dist/cdn/workers-cache-purge.js +3 -5
  165. package/dist/cdn/workers-cache-purge.js.map +1 -1
  166. package/dist/cli-dev-status.d.ts +75 -0
  167. package/dist/cli-dev-status.d.ts.map +1 -0
  168. package/dist/cli-init.d.ts +72 -0
  169. package/dist/cli-init.d.ts.map +1 -0
  170. package/dist/cli.d.ts +4 -12
  171. package/dist/cli.d.ts.map +1 -1
  172. package/dist/cli.js +27 -54
  173. package/dist/cli.js.map +1 -1
  174. package/dist/client/error-boundary.d.ts.map +1 -1
  175. package/dist/client/error-boundary.js +1 -1
  176. package/dist/client/global-context.d.ts +21 -1
  177. package/dist/client/global-context.d.ts.map +1 -1
  178. package/dist/client/index.js +23 -44
  179. package/dist/client/index.js.map +1 -1
  180. package/dist/client/internal.js +13 -18
  181. package/dist/client/internal.js.map +1 -1
  182. package/dist/client/navigation-context.d.ts.map +1 -1
  183. package/dist/client/params-context.d.ts.map +1 -1
  184. package/dist/client/slot-context.d.ts +2 -2
  185. package/dist/client/slot-context.d.ts.map +1 -1
  186. package/dist/client/use-cookie.d.ts +18 -5
  187. package/dist/client/use-cookie.d.ts.map +1 -1
  188. package/dist/codec.js +2 -3
  189. package/dist/config-types.d.ts +22 -5
  190. package/dist/config-types.d.ts.map +1 -1
  191. package/dist/config-validation.d.ts.map +1 -1
  192. package/dist/cookies/define-cookie.d.ts.map +1 -1
  193. package/dist/cookies/index.js +40 -67
  194. package/dist/cookies/index.js.map +1 -1
  195. package/dist/cookies/json-cookie.d.ts +4 -4
  196. package/dist/index.js +266 -229
  197. package/dist/index.js.map +1 -1
  198. package/dist/params/index.js +3 -4
  199. package/dist/plugin-context.d.ts +7 -0
  200. package/dist/plugin-context.d.ts.map +1 -1
  201. package/dist/plugins/dev-discovery.d.ts +69 -5
  202. package/dist/plugins/dev-discovery.d.ts.map +1 -1
  203. package/dist/plugins/dev-hostname.d.ts +152 -0
  204. package/dist/plugins/dev-hostname.d.ts.map +1 -0
  205. package/dist/plugins/dev-server.d.ts +6 -2
  206. package/dist/plugins/dev-server.d.ts.map +1 -1
  207. package/dist/plugins/dev-store-clear.d.ts +83 -0
  208. package/dist/plugins/dev-store-clear.d.ts.map +1 -0
  209. package/dist/plugins/graph-endpoint.d.ts +4 -2
  210. package/dist/plugins/graph-endpoint.d.ts.map +1 -1
  211. package/dist/plugins/prebuilt.d.ts.map +1 -1
  212. package/dist/routing/index.js +4 -4
  213. package/dist/rsc-runtime/rsc.d.ts +2 -1
  214. package/dist/rsc-runtime/rsc.d.ts.map +1 -1
  215. package/dist/rsc-runtime/server-references.d.ts +8 -0
  216. package/dist/rsc-runtime/server-references.d.ts.map +1 -0
  217. package/dist/schema-bridge.d.ts +28 -19
  218. package/dist/schema-bridge.d.ts.map +1 -1
  219. package/dist/search-params/define.d.ts +1 -1
  220. package/dist/search-params/define.d.ts.map +1 -1
  221. package/dist/search-params/index.js +11 -14
  222. package/dist/search-params/index.js.map +1 -1
  223. package/dist/search-params/wrappers.d.ts +3 -3
  224. package/dist/server/access-gate.d.ts +12 -0
  225. package/dist/server/access-gate.d.ts.map +1 -1
  226. package/dist/server/canonicalize.d.ts +21 -0
  227. package/dist/server/canonicalize.d.ts.map +1 -1
  228. package/dist/server/cookie-context.d.ts +8 -1
  229. package/dist/server/cookie-context.d.ts.map +1 -1
  230. package/dist/server/flight-source-node.d.ts.map +1 -1
  231. package/dist/server/flight-source.d.ts.map +1 -1
  232. package/dist/server/index.d.ts +1 -1
  233. package/dist/server/index.d.ts.map +1 -1
  234. package/dist/server/index.js +8 -13
  235. package/dist/server/index.js.map +1 -1
  236. package/dist/server/interception-gates.d.ts +49 -0
  237. package/dist/server/interception-gates.d.ts.map +1 -0
  238. package/dist/server/internal.js +1080 -959
  239. package/dist/server/internal.js.map +1 -1
  240. package/dist/server/logger.d.ts +26 -0
  241. package/dist/server/logger.d.ts.map +1 -1
  242. package/dist/server/param-coercion.d.ts +8 -0
  243. package/dist/server/param-coercion.d.ts.map +1 -1
  244. package/dist/server/pipeline-interception.d.ts +34 -4
  245. package/dist/server/pipeline-interception.d.ts.map +1 -1
  246. package/dist/server/pipeline-metadata-route.d.ts +24 -0
  247. package/dist/server/pipeline-metadata-route.d.ts.map +1 -0
  248. package/dist/server/pipeline-metadata.d.ts +3 -2
  249. package/dist/server/pipeline-metadata.d.ts.map +1 -1
  250. package/dist/server/pipeline-phases.d.ts +9 -3
  251. package/dist/server/pipeline-phases.d.ts.map +1 -1
  252. package/dist/server/pipeline.d.ts +18 -0
  253. package/dist/server/pipeline.d.ts.map +1 -1
  254. package/dist/server/prebuilt/dev-store.d.ts +68 -22
  255. package/dist/server/prebuilt/dev-store.d.ts.map +1 -1
  256. package/dist/server/prebuilt/overlay.d.ts +17 -3
  257. package/dist/server/prebuilt/overlay.d.ts.map +1 -1
  258. package/dist/server/prebuilt-runtime.d.ts.map +1 -1
  259. package/dist/server/primitives.d.ts +13 -0
  260. package/dist/server/primitives.d.ts.map +1 -1
  261. package/dist/server/render-utils.d.ts +21 -0
  262. package/dist/server/render-utils.d.ts.map +1 -1
  263. package/dist/server/request-context.d.ts +14 -0
  264. package/dist/server/request-context.d.ts.map +1 -1
  265. package/dist/server/route-element-builder.d.ts.map +1 -1
  266. package/dist/server/route-handler.d.ts +7 -0
  267. package/dist/server/route-handler.d.ts.map +1 -1
  268. package/dist/server/route-matcher.d.ts +14 -3
  269. package/dist/server/route-matcher.d.ts.map +1 -1
  270. package/dist/server/rsc-entry/api-handler.d.ts.map +1 -1
  271. package/dist/server/rsc-entry/index.d.ts.map +1 -1
  272. package/dist/server/rsc-entry/rsc-stream.d.ts.map +1 -1
  273. package/dist/server/signal-identity.d.ts +6 -0
  274. package/dist/server/signal-identity.d.ts.map +1 -1
  275. package/dist/server/traced-access.d.ts +18 -0
  276. package/dist/server/traced-access.d.ts.map +1 -0
  277. package/dist/server/tracing.d.ts.map +1 -1
  278. package/dist/server/types.d.ts +5 -4
  279. package/dist/server/types.d.ts.map +1 -1
  280. package/dist/shims/font-google.js +1 -2
  281. package/dist/shims/font-local.js +1 -2
  282. package/dist/shims/headers.d.ts +11 -4
  283. package/dist/shims/headers.d.ts.map +1 -1
  284. package/docs/api/30-api-server.mdx +3 -1
  285. package/docs/api/32-api-cache.mdx +1 -1
  286. package/docs/api/33-api-search-params.mdx +3 -1
  287. package/docs/api/34-api-config.mdx +22 -0
  288. package/docs/api/36-cli.mdx +72 -6
  289. package/docs/learn/01-quick-start.mdx +1 -1
  290. package/docs/learn/06-typed-params.mdx +4 -4
  291. package/docs/learn/10-caching.mdx +26 -5
  292. package/llms.txt +1 -1
  293. package/package.json +12 -12
  294. package/src/adapters/build-output-helper.ts +26 -4
  295. package/src/adapters/cloudflare.ts +1 -0
  296. package/src/adapters/nitro-presets.ts +15 -0
  297. package/src/adapters/nitro-preview.ts +66 -34
  298. package/src/adapters/nitro.ts +14 -6
  299. package/src/analyze/graph-command.ts +25 -133
  300. package/src/cache/guarded-read.ts +44 -0
  301. package/src/cache/key-discipline.ts +218 -0
  302. package/src/cache/timber-cache.ts +46 -7
  303. package/src/cli-dev-status.ts +196 -0
  304. package/src/cli-init.ts +278 -0
  305. package/src/cli.ts +33 -79
  306. package/src/client/error-boundary.tsx +19 -2
  307. package/src/client/global-context.ts +42 -14
  308. package/src/client/navigation-context.ts +4 -11
  309. package/src/client/params-context.ts +5 -17
  310. package/src/client/segment-update-context.ts +1 -1
  311. package/src/client/slot-content-cache-context.ts +1 -1
  312. package/src/client/slot-context.ts +6 -17
  313. package/src/client/use-cookie.ts +33 -21
  314. package/src/config-types.ts +22 -5
  315. package/src/config-validation.ts +17 -0
  316. package/src/cookies/define-cookie.ts +10 -46
  317. package/src/cookies/json-cookie.ts +4 -4
  318. package/src/plugin-context.ts +7 -0
  319. package/src/plugins/dev-discovery.ts +216 -6
  320. package/src/plugins/dev-hostname.ts +322 -0
  321. package/src/plugins/dev-server.ts +130 -37
  322. package/src/plugins/dev-store-clear.ts +145 -0
  323. package/src/plugins/graph-endpoint.ts +15 -3
  324. package/src/plugins/prebuilt.ts +9 -0
  325. package/src/rsc-runtime/rsc.ts +7 -3
  326. package/src/rsc-runtime/server-references.ts +73 -0
  327. package/src/rsc-runtime/vendor-types.d.ts +17 -0
  328. package/src/schema-bridge.ts +93 -38
  329. package/src/search-params/define.ts +5 -6
  330. package/src/search-params/wrappers.ts +3 -3
  331. package/src/server/access-gate.tsx +32 -20
  332. package/src/server/action-handler.ts +58 -36
  333. package/src/server/canonicalize.ts +27 -0
  334. package/src/server/cookie-context.ts +11 -3
  335. package/src/server/flight-source-node.ts +5 -2
  336. package/src/server/flight-source.ts +4 -3
  337. package/src/server/index.ts +6 -1
  338. package/src/server/interception-gates.ts +94 -0
  339. package/src/server/logger.ts +32 -0
  340. package/src/server/param-coercion.ts +22 -0
  341. package/src/server/pipeline-interception.ts +64 -4
  342. package/src/server/pipeline-metadata-route.ts +242 -0
  343. package/src/server/pipeline-metadata.ts +7 -5
  344. package/src/server/pipeline-phases.ts +71 -131
  345. package/src/server/pipeline.ts +20 -2
  346. package/src/server/prebuilt/dev-store.ts +113 -34
  347. package/src/server/prebuilt/overlay.ts +32 -4
  348. package/src/server/prebuilt-runtime.ts +63 -45
  349. package/src/server/primitives.ts +14 -0
  350. package/src/server/render-utils.ts +25 -0
  351. package/src/server/request-context.ts +27 -3
  352. package/src/server/route-element-builder.ts +15 -2
  353. package/src/server/route-handler.ts +3 -2
  354. package/src/server/route-matcher.ts +48 -33
  355. package/src/server/rsc-entry/api-handler.ts +2 -33
  356. package/src/server/rsc-entry/index.ts +8 -3
  357. package/src/server/rsc-entry/rsc-stream.ts +7 -1
  358. package/src/server/signal-identity.ts +30 -12
  359. package/src/server/traced-access.ts +50 -0
  360. package/src/server/tracing.ts +18 -1
  361. package/src/server/types.ts +5 -4
  362. package/src/shims/headers.ts +12 -4
  363. package/dist/_chunks/actions-BDqn4Oxj.js.map +0 -1
  364. package/dist/_chunks/build-output-helper-RV_BRcF1.js.map +0 -1
  365. package/dist/_chunks/cache-api-GE4AOe2H.js.map +0 -1
  366. package/dist/_chunks/chains-CDK1AWZQ.js +0 -1
  367. package/dist/_chunks/cli-context-BJQB6rtF.js +0 -1
  368. package/dist/_chunks/dev-server-BiWNMBVU.js +0 -1
  369. package/dist/_chunks/dev-server-DIy-SY-J.js.map +0 -1
  370. package/dist/_chunks/dev-store-BOa304m_.js.map +0 -1
  371. package/dist/_chunks/flight-source-node-HptmGMT8.js.map +0 -1
  372. package/dist/_chunks/graph-cache-CYiUS2aS.js.map +0 -1
  373. package/dist/_chunks/logger-CbLdcy-W.js.map +0 -1
  374. package/dist/_chunks/node-response-rkQqcFGq.js.map +0 -1
  375. package/dist/_chunks/plugin-context-DxMMvjUt.js.map +0 -1
  376. package/dist/_chunks/schema-bridge-C83xa9lT.js.map +0 -1
  377. package/dist/_chunks/segment-context-xtPUGfdq.js.map +0 -1
  378. package/dist/server/prebuilt/key-discipline.d.ts +0 -52
  379. package/dist/server/prebuilt/key-discipline.d.ts.map +0 -1
  380. package/src/server/prebuilt/key-discipline.ts +0 -122
@@ -28,23 +28,12 @@
28
28
 
29
29
  'use client';
30
30
 
31
- import React, { type ReactNode } from 'react';
31
+ import { type ReactNode } from 'react';
32
+ import { createGlobalContext } from './global-context.ts';
32
33
 
33
34
  export type SlotValues = Record<string, ReactNode>;
34
35
 
35
- const CTX_KEY = Symbol.for('__timber_slot_ctx');
36
-
37
- function getOrCreateContext(): React.Context<SlotValues | null> {
38
- const existing = (globalThis as Record<symbol, unknown>)[CTX_KEY] as
39
- | React.Context<SlotValues | null>
40
- | undefined;
41
- if (existing !== undefined) return existing;
42
- if (typeof React.createContext === 'function') {
43
- const ctx = React.createContext<SlotValues | null>(null);
44
- (globalThis as Record<symbol, unknown>)[CTX_KEY] = ctx;
45
- return ctx;
46
- }
47
- return undefined as unknown as React.Context<SlotValues | null>;
48
- }
49
-
50
- export const SlotContext = getOrCreateContext();
36
+ export const SlotContext = createGlobalContext<SlotValues | null>(
37
+ Symbol.for('__timber_slot_ctx'),
38
+ null
39
+ );
@@ -35,6 +35,8 @@ export interface ClientCookieOptions {
35
35
  sameSite?: 'strict' | 'lax' | 'none';
36
36
  /** Only send over HTTPS. Default: true in production. */
37
37
  secure?: boolean;
38
+ /** Partitioned (CHIPS) — isolate cookie per top-level site. */
39
+ partitioned?: boolean;
38
40
  }
39
41
 
40
42
  export type CookieSetter = (value: string, options?: ClientCookieOptions) => void;
@@ -67,7 +69,10 @@ export function serializeOptions(options?: ClientCookieOptions): string {
67
69
  maxAge: options.maxAge,
68
70
  expires: options.expires,
69
71
  sameSite,
70
- secure: options.secure,
72
+ // Browsers reject SameSite=None and Partitioned without Secure, so a
73
+ // write that omits it silently does nothing — imply it (TIM-1606).
74
+ secure: options.secure ?? (sameSite === 'none' || options.partitioned ? true : undefined),
75
+ partitioned: options.partitioned,
71
76
  });
72
77
  // Strip everything up to and including the first "; "
73
78
  const idx = full.indexOf('; ');
@@ -83,13 +88,33 @@ function notify(name: string): void {
83
88
  }
84
89
 
85
90
  /**
86
- * Notify useCookie subscribers that a cookie value changed.
87
- * Called by defineCookie's imperative client .set()/.delete() methods
88
- * so mounted useCookie() consumers re-render.
91
+ * Write a cookie via document.cookie and notify useCookie subscribers.
89
92
  *
90
- * @internal — framework use only
93
+ * Auto-encode mirrors the server's `cookies().set()` contract: values are
94
+ * URL-encoded on write, URL-decoded on read, so the logical bytes
95
+ * round-trip losslessly. See design/29-cookies.md §"Encoding Contract".
96
+ *
97
+ * @internal — shared by useCookie() and defineCookie's client methods
98
+ */
99
+ export function writeClientCookie(
100
+ name: string,
101
+ value: string,
102
+ options?: ClientCookieOptions
103
+ ): void {
104
+ document.cookie = `${name}=${encodeURIComponent(value)}${serializeOptions(options)}`;
105
+ notify(name);
106
+ }
107
+
108
+ /**
109
+ * Delete a cookie via document.cookie and notify useCookie subscribers.
110
+ *
111
+ * Keeps every attribute but the lifetime: a partitioned cookie is only
112
+ * removed by a deletion that is also `Partitioned` (TIM-1606).
113
+ *
114
+ * @internal — shared by useCookie() and defineCookie's client methods
91
115
  */
92
- export function notifyCookieChange(name: string): void {
116
+ export function deleteClientCookie(name: string, options?: ClientCookieOptions): void {
117
+ document.cookie = `${name}=${serializeOptions({ ...options, maxAge: 0, expires: new Date(0) })}`;
93
118
  notify(name);
94
119
  }
95
120
 
@@ -152,23 +177,10 @@ export function useCookie(
152
177
  ` '@timber-js/app/cookies' and call its useCookie() hook instead.`
153
178
  );
154
179
  }
155
- const merged = { ...defaultOptions, ...options };
156
- // Auto-encode mirrors the server's `cookies().set()` contract:
157
- // values are URL-encoded on write, URL-decoded on read, so the
158
- // logical bytes round-trip losslessly. See design/29-cookies.md
159
- // §"Encoding Contract".
160
- document.cookie = `${name}=${encodeURIComponent(newValue)}${serializeOptions(merged)}`;
161
- notify(name);
180
+ writeClientCookie(name, newValue, { ...defaultOptions, ...options });
162
181
  };
163
182
 
164
- const deleteCookie = (): void => {
165
- const path = defaultOptions?.path ?? '/';
166
- const domain = defaultOptions?.domain;
167
- let cookieStr = `${name}=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=${path}`;
168
- if (domain) cookieStr += `; Domain=${domain}`;
169
- document.cookie = cookieStr;
170
- notify(name);
171
- };
183
+ const deleteCookie = (): void => deleteClientCookie(name, defaultOptions);
172
184
 
173
185
  return [value, setCookie, deleteCookie];
174
186
  }
@@ -124,6 +124,22 @@ export interface TimberUserConfig {
124
124
  dev?: {
125
125
  /** Threshold in ms to highlight slow phases in dev logging output. Default: 200. */
126
126
  slowPhaseMs?: number;
127
+ /**
128
+ * Hostname the dev server prints and opens, as `<hostname>.localhost`.
129
+ * Each app gets its own name, and so its own cookie jar: cookies are not
130
+ * scoped by port, so apps sharing `localhost` overwrite each other's.
131
+ *
132
+ * Default: derived from package.json `name` (`@acme/web` →
133
+ * `web.acme.localhost`), else the app directory's name. Placeholder
134
+ * names (`my-timber-app`, `my-app`, `app`) fall through to the directory.
135
+ * Under `server.https` the name is used only when the certificate covers
136
+ * it. Set a name
137
+ * (`"blog"` or `"blog.localhost"`) to choose it, or `false` to keep
138
+ * plain `localhost`. `localhost:<port>` keeps working either way.
139
+ *
140
+ * See design/21-dev-server.md §"Dev Hostnames".
141
+ */
142
+ hostname?: string | false;
127
143
  };
128
144
  /**
129
145
  * Control Server-Timing header output.
@@ -292,13 +308,14 @@ export interface TimberUserConfig {
292
308
  */
293
309
  cache?: {
294
310
  /**
295
- * Promote the runtime-tier cache.component key-discipline warning to a
296
- * hard error. When true, a cached component that reads request context
297
- * (cookies, headers, searchParams) during a capture render throws
298
- * instead of logging — the tainted payload is never cached.
311
+ * Promote the key-discipline warning to a hard error. When true, a
312
+ * runtime-tier cache.component that reads request context (cookies,
313
+ * headers, searchParams) during a capture render, or a cache.data fn
314
+ * that reads it (or segment params) while computing its value, throws instead of logging —
315
+ * the tainted result is never cached.
299
316
  *
300
317
  * Default: false (structured error-level diagnostic, rate-limited per
301
- * component). Recommended true for any app serving authenticated content.
318
+ * callsite). Recommended true for any app serving authenticated content.
302
319
  *
303
320
  * See design/45-cache-lifetimes.md §Enforcement.
304
321
  */
@@ -10,6 +10,7 @@
10
10
 
11
11
  import { createRequire } from 'node:module';
12
12
  import type { TimberUserConfig } from './config-types.ts';
13
+ import { devHostnameError } from './plugins/dev-hostname.ts';
13
14
  import { DEFAULT_RENDER_TIMEOUT_MS, RENDER_TIMEOUT_CEILING_MS } from './server/render-timeout.ts';
14
15
 
15
16
  // ─── Types ──────────────────────────────────────────────────────────────────
@@ -185,6 +186,22 @@ export function validateConfig(config: TimberUserConfig): ConfigError[] {
185
186
  }
186
187
  }
187
188
 
189
+ // dev.hostname — not fatal: it is dev-only, so a typo must not fail
190
+ // `timber build`. Dev startup still refuses it (deriveDevHostname throws).
191
+ if (config.dev?.hostname !== undefined) {
192
+ const problem = devHostnameError(config.dev.hostname);
193
+ if (problem) {
194
+ errors.push({
195
+ field: 'dev.hostname',
196
+ message: `dev.hostname ${problem}`,
197
+ value: config.dev.hostname,
198
+ suggestion:
199
+ 'Use DNS labels separated by dots, e.g. dev: { hostname: "blog" } for blog.localhost, ' +
200
+ 'or false to keep plain localhost.',
201
+ });
202
+ }
203
+ }
204
+
188
205
  // sitemap
189
206
  if (config.sitemap != null && typeof config.sitemap === 'object') {
190
207
  if (config.sitemap.enabled && !config.sitemap.baseUrl) {
@@ -81,7 +81,7 @@ export interface CookieDefinition<T> extends ServerOnlyCookieDefinition<T> {
81
81
  // by trying getCookieJar() — if it throws the stub error, we fall through
82
82
  // to the client path.
83
83
  //
84
- // Client: useCookie, getCookieValue, notifyCookieChange
84
+ // Client: useCookie, getCookieValue, writeClientCookie, deleteClientCookie
85
85
  // are imported from use-cookie.ts. These are safe in all environments (no
86
86
  // node:async_hooks dependency).
87
87
  //
@@ -90,8 +90,9 @@ export interface CookieDefinition<T> extends ServerOnlyCookieDefinition<T> {
90
90
  import { getCookieJar } from '@timber-js/app/server';
91
91
  import {
92
92
  useCookie as useRawCookie,
93
- notifyCookieChange,
94
93
  getCookieValue,
94
+ writeClientCookie,
95
+ deleteClientCookie,
95
96
  } from '../client/use-cookie.ts';
96
97
 
97
98
  // ─── Environment Detection ────────────────────────────────────────────────
@@ -117,33 +118,6 @@ function tryGetServerCookieJar(): ReturnType<typeof getCookieJar> | null {
117
118
  }
118
119
  }
119
120
 
120
- // ─── Client Cookie Helpers ────────────────────────────────────────────────
121
-
122
- /** Write a cookie via document.cookie and notify useCookie subscribers. */
123
- function setClientCookie(name: string, value: string, options?: ClientCookieOptions): void {
124
- const parts: string[] = [`${name}=${encodeURIComponent(value)}`];
125
- const path = options?.path ?? '/';
126
- parts.push(`Path=${path}`);
127
- if (options?.domain) parts.push(`Domain=${options.domain}`);
128
- if (options?.maxAge !== undefined) parts.push(`Max-Age=${options.maxAge}`);
129
- if (options?.expires) parts.push(`Expires=${options.expires.toUTCString()}`);
130
- const sameSite = options?.sameSite ?? 'lax';
131
- parts.push(`SameSite=${sameSite.charAt(0).toUpperCase()}${sameSite.slice(1)}`);
132
- if (options?.secure) parts.push('Secure');
133
- document.cookie = parts.join('; ');
134
- notifyCookieChange(name);
135
- }
136
-
137
- /** Delete a cookie via document.cookie and notify useCookie subscribers. */
138
- function deleteClientCookie(name: string, options?: ClientCookieOptions): void {
139
- const path = options?.path ?? '/';
140
- const domain = options?.domain;
141
- let cookieStr = `${name}=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=${path}`;
142
- if (domain) cookieStr += `; Domain=${domain}`;
143
- document.cookie = cookieStr;
144
- notifyCookieChange(name);
145
- }
146
-
147
121
  // ─── Standard Schema Auto-Detection ───────────────────────────────────────
148
122
 
149
123
  function resolveCodec<T>(codecOrSchema: CookieCodec<T> | StandardSchemaV1<T>): CookieCodec<T> {
@@ -196,14 +170,10 @@ export function defineCookie<T, HttpOnly extends boolean = true>(
196
170
  const isHttpOnly = options.httpOnly !== false; // default true
197
171
 
198
172
  function getClientOpts(): ClientCookieOptions {
199
- return {
200
- path: resolvedOptions.path,
201
- domain: resolvedOptions.domain,
202
- maxAge: resolvedOptions.maxAge,
203
- expires: resolvedOptions.expires,
204
- sameSite: resolvedOptions.sameSite,
205
- secure: resolvedOptions.secure,
206
- };
173
+ // httpOnly is the one attribute document.cookie cannot write.
174
+ const { httpOnly: _httpOnly, ...clientOpts } = resolvedOptions;
175
+ void _httpOnly;
176
+ return clientOpts;
207
177
  }
208
178
 
209
179
  const base: ServerOnlyCookieDefinition<T> = {
@@ -232,10 +202,7 @@ export function defineCookie<T, HttpOnly extends boolean = true>(
232
202
  if (serverJar) {
233
203
  const serialized = codec.serialize(value);
234
204
  if (serialized === null) {
235
- serverJar.delete(name, {
236
- path: resolvedOptions.path,
237
- domain: resolvedOptions.domain,
238
- });
205
+ serverJar.delete(name, resolvedOptions);
239
206
  } else {
240
207
  serverJar.set(name, serialized, resolvedOptions);
241
208
  }
@@ -252,17 +219,14 @@ export function defineCookie<T, HttpOnly extends boolean = true>(
252
219
  if (serialized === null) {
253
220
  deleteClientCookie(name, getClientOpts());
254
221
  } else {
255
- setClientCookie(name, serialized, getClientOpts());
222
+ writeClientCookie(name, serialized, getClientOpts());
256
223
  }
257
224
  },
258
225
 
259
226
  delete(): void {
260
227
  const serverJar = tryGetServerCookieJar();
261
228
  if (serverJar) {
262
- serverJar.delete(name, {
263
- path: resolvedOptions.path,
264
- domain: resolvedOptions.domain,
265
- });
229
+ serverJar.delete(name, resolvedOptions);
266
230
  return;
267
231
  }
268
232
  // Client path
@@ -6,12 +6,12 @@
6
6
  * `JSON.parse` on parse. The framework handles the URL encoding /
7
7
  * decoding around it (see design/29-cookies.md §"Encoding Contract"):
8
8
  *
9
- * defineCookie.setCookie(value)
9
+ * defineCookie().set(value)
10
10
  * → codec.serialize: JSON.stringify → '{"a":1}'
11
- * → cookies().set: encodeURIComponent → '%7B%22a%22%3A1%7D'
11
+ * → getCookieJar().set: encodeURIComponent → '%7B%22a%22%3A1%7D'
12
12
  * → wire: Set-Cookie: prefs=%7B%22a%22%3A1%7D
13
13
  *
14
- * defineCookie.getCookie()
14
+ * defineCookie().get()
15
15
  * → wire: Cookie: prefs=%7B%22a%22%3A1%7D
16
16
  * → parseCookieHeader: decodeURIComponent → '{"a":1}'
17
17
  * → codec.parse: JSON.parse → { a: 1 }
@@ -36,7 +36,7 @@
36
36
  * maxAge: 60 * 60 * 24 * 365,
37
37
  * });
38
38
  *
39
- * await prefsCookie.setCookie({ lang: 'fr', fontSize: 18 });
39
+ * prefsCookie.set({ lang: 'fr', fontSize: 18 });
40
40
  * ```
41
41
  */
42
42
 
@@ -167,6 +167,13 @@ export interface PluginContext {
167
167
  * RSC generateBundle alongside routePrebuiltComponents.
168
168
  */
169
169
  prebuiltLazyChunks?: Map<string, string>;
170
+ /**
171
+ * Dev only: RSC module ID → the cache.component IDs its last transform
172
+ * declared. Written by timber-prebuilt's transform, read by
173
+ * timber-dev-server to scope a dev store clear to the components a saved
174
+ * module could have changed (plugins/dev-store-clear.ts, TIM-1599).
175
+ */
176
+ devPrebuiltComponentIds?: Map<string, string[]>;
170
177
  /**
171
178
  * Content-keyed AST parse memo shared across cache/prebuilt/prerender-sugar
172
179
  * transforms. Collapses both cross-plugin and cross-environment duplicate
@@ -1,10 +1,11 @@
1
1
  /**
2
2
  * Dev-server discovery records — `.timber/dev/<pid>-<port>-<token>.json`.
3
3
  *
4
- * On startup each dev server writes `{ port, pid, host, protocol }` to its own record
5
- * file under the app's `.timber/dev/` so the `timber graph` CLI and the
6
- * VS Code extension can discover a running dev server for the
7
- * live-graph fast path.
4
+ * On startup each dev server writes `{ url, port, pid, host, protocol }` to its own record
5
+ * file under the app's `.timber/dev/` so `timber dev status`, the
6
+ * `timber graph` CLI, and the VS Code extension can discover a running
7
+ * dev server. `timber dev status` is the public, agent-facing consumer;
8
+ * the records themselves are not.
8
9
  *
9
10
  * One record file per server, one writer per file. This is what makes
10
11
  * multi-server roots (Vite auto-increments the port across processes;
@@ -29,12 +30,29 @@ import type { Server } from 'node:net';
29
30
  import { Server as TlsServer } from 'node:tls';
30
31
  import { randomUUID } from 'node:crypto';
31
32
  import { mkdirSync, writeFileSync, rmSync, readFileSync, readdirSync } from 'node:fs';
32
- import { join } from 'node:path';
33
+ import { dirname, join } from 'node:path';
34
+ import { request as httpRequest, type ClientRequest } from 'node:http';
35
+ import { request as httpsRequest } from 'node:https';
36
+ import type { AdvertisedUrls } from './dev-hostname.ts';
33
37
 
34
38
  /** Relative path of the discovery directory within the project root. */
35
39
  export const DEV_DISCOVERY_DIR = join('.timber', 'dev');
36
40
 
37
41
  export interface DevRecord {
42
+ /**
43
+ * The URL the server printed and opened — Vite's `resolvedUrls` pick,
44
+ * with the app's dev hostname applied (`http://blog.localhost:3000/`,
45
+ * see plugins/dev-hostname.ts). What `timber dev status` reports. Taken
46
+ * from Vite rather than rebuilt from `host`, so the two cannot disagree.
47
+ */
48
+ url: string;
49
+ /**
50
+ * The same server for non-browser HTTP clients: `url` at plain
51
+ * `localhost` when that resolves and verifies (see `loopbackUrl` in
52
+ * plugins/dev-hostname.ts). Computed by the server, which alone knows its
53
+ * TLS certificate.
54
+ */
55
+ loopbackUrl: string;
38
56
  port: number;
39
57
  pid: number;
40
58
  /**
@@ -133,12 +151,28 @@ function sweepDeadRecords(dir: string): void {
133
151
  }
134
152
  }
135
153
 
154
+ /**
155
+ * The directory whose `.timber/dev/` holds a server's record: the Vite
156
+ * config file's directory, falling back to the resolved root for an inline
157
+ * (`configFile: false`) server. Every consumer — `timber dev status`,
158
+ * `timber graph`, the VS Code extension — locates an app by its config or
159
+ * package directory without evaluating Vite, so the record goes where they
160
+ * look rather than under a `root` the config may move elsewhere.
161
+ */
162
+ export function devRecordRoot(root: string, configFile: string | false | undefined): string {
163
+ return typeof configFile === 'string' ? dirname(configFile) : root;
164
+ }
165
+
136
166
  /**
137
167
  * Register discovery-record lifecycle handlers on the dev server's HTTP
138
168
  * server. Writes `.timber/dev/<pid>-<port>-<token>.json` once the server is
139
169
  * listening (the bound port is only known then) and removes exactly
140
170
  * that record on clean shutdown.
141
171
  *
172
+ * `urls` is read when the server starts listening: the URLs to advertise
173
+ * (`advertisedUrls`). With none, nothing is written — a record no one can
174
+ * open is not worth advertising.
175
+ *
142
176
  * All filesystem work is best-effort: a failure to write or remove a
143
177
  * record must never break the dev server. `httpServer` is null in
144
178
  * middleware mode — no port exists, so there is nothing to advertise.
@@ -148,6 +182,7 @@ function sweepDeadRecords(dir: string): void {
148
182
  export function registerDevDiscovery(
149
183
  httpServer: Server | null,
150
184
  root: string,
185
+ urls: () => AdvertisedUrls | undefined,
151
186
  config?: {
152
187
  configFile?: string | false;
153
188
  base?: string;
@@ -164,16 +199,20 @@ export function registerDevDiscovery(
164
199
  ): void {
165
200
  if (!httpServer) return;
166
201
 
167
- const dir = join(root, DEV_DISCOVERY_DIR);
202
+ const dir = join(devRecordRoot(root, config?.configFile), DEV_DISCOVERY_DIR);
168
203
  let recordPath: string | null = null;
169
204
 
170
205
  httpServer.on('listening', () => {
171
206
  const address = httpServer.address();
172
207
  // Unix-socket listeners have a string address — no port to advertise.
173
208
  if (address === null || typeof address === 'string') return;
209
+ const advertised = urls();
210
+ if (advertised === undefined) return;
174
211
  const hmrOpts = typeof config?.server?.hmr === 'object' ? config.server.hmr : undefined;
175
212
  const wsOpts = typeof config?.server?.ws === 'object' ? config.server.ws : undefined;
176
213
  const record: DevRecord = {
214
+ url: advertised.url,
215
+ loopbackUrl: advertised.loopbackUrl,
177
216
  port: address.port,
178
217
  pid: process.pid,
179
218
  host: address.address,
@@ -216,3 +255,174 @@ export function registerDevDiscovery(
216
255
  }
217
256
  });
218
257
  }
258
+
259
+ // ─── Reading records ─────────────────────────────────────────────────────────
260
+ //
261
+ // The consumer side of the same contract, for the CLI: `timber graph` and
262
+ // `timber dev status` only see validated `DevRecord`s. The VS Code extension
263
+ // (packages/timber-vscode/src/graph-client.ts) is a separate package with its
264
+ // own reader of the same format; a format change must update both.
265
+
266
+ /**
267
+ * `GET /__timber/status` — the dev server's identity probe. Answers
268
+ * `{ pid }` with the serving process's pid, so a consumer can confirm the
269
+ * server on a record's port is the one that wrote the record (a crashed
270
+ * server's port may since have been taken by another process).
271
+ */
272
+ export const STATUS_ENDPOINT_PATH = '/__timber/status';
273
+
274
+ /** Probe deadline: discovery must never hold a CLI hostage. */
275
+ export const DEV_PROBE_TIMEOUT_MS = 2_000;
276
+
277
+ /** Max probe response body (16 MB — matches the crawl child). */
278
+ const PROBE_MAX_BODY_BYTES = 16 * 1024 * 1024;
279
+
280
+ function isValidRecord(record: Partial<DevRecord>): record is DevRecord {
281
+ return (
282
+ typeof record.url === 'string' &&
283
+ typeof record.loopbackUrl === 'string' &&
284
+ typeof record.port === 'number' &&
285
+ Number.isInteger(record.port) &&
286
+ record.port >= 1 &&
287
+ record.port <= 65535 &&
288
+ typeof record.pid === 'number' &&
289
+ Number.isInteger(record.pid) &&
290
+ record.pid >= 1 &&
291
+ typeof record.host === 'string' &&
292
+ (record.protocol === 'http' || record.protocol === 'https')
293
+ );
294
+ }
295
+
296
+ /**
297
+ * Records under `<root>/.timber/dev/` that are well-formed and name a live
298
+ * pid. These are candidates, not proof: the caller still has to probe the
299
+ * endpoint (`readLiveDevRecords`, or `timber graph`'s own graph request,
300
+ * which doubles as its probe). A missing directory or unreadable record is
301
+ * absence, never an error.
302
+ */
303
+ export function readDevRecords(root: string): DevRecord[] {
304
+ const dir = join(root, DEV_DISCOVERY_DIR);
305
+ let entries: string[];
306
+ try {
307
+ entries = readdirSync(dir);
308
+ } catch {
309
+ return [];
310
+ }
311
+ const records: DevRecord[] = [];
312
+ for (const entry of entries) {
313
+ if (!entry.endsWith('.json')) continue;
314
+ let record: Partial<DevRecord>;
315
+ try {
316
+ record = JSON.parse(readFileSync(join(dir, entry), 'utf8')) as Partial<DevRecord>;
317
+ } catch {
318
+ continue;
319
+ }
320
+ if (isValidRecord(record) && isPidAlive(record.pid)) records.push(record);
321
+ }
322
+ return records;
323
+ }
324
+
325
+ /**
326
+ * Records whose server answers the status probe with the record's own pid —
327
+ * the full "pid alive AND probe succeeds" validation. Probes run in
328
+ * parallel, each under `DEV_PROBE_TIMEOUT_MS`.
329
+ */
330
+ export async function readLiveDevRecords(root: string): Promise<DevRecord[]> {
331
+ const candidates = readDevRecords(root);
332
+ const answers = await Promise.all(
333
+ candidates.map((record) => probeDevServer(record, STATUS_ENDPOINT_PATH, DEV_PROBE_TIMEOUT_MS))
334
+ );
335
+ return candidates.filter((record, i) => {
336
+ const answer = answers[i];
337
+ return typeof answer === 'object' && answer !== null && 'pid' in answer
338
+ ? answer.pid === record.pid
339
+ : false;
340
+ });
341
+ }
342
+
343
+ /**
344
+ * Wildcard binds (`0.0.0.0`, `::`) are reached through loopback; a server
345
+ * bound to one specific interface is reached only through that address.
346
+ */
347
+ function connectHost(host: string): string {
348
+ return host === '0.0.0.0' || host === '::' || host === '' ? '127.0.0.1' : host;
349
+ }
350
+
351
+ /**
352
+ * HTTP(S) GET against a record's server with a wall-clock deadline and a
353
+ * response-size limit, returning the parsed JSON body or null on any failure
354
+ * (non-200, bad JSON, timeout, connection error). Uses node:http/https
355
+ * directly — `fetch` silently strips the Host header, which the endpoint's
356
+ * DNS-rebinding defense needs to see as a localhost form.
357
+ *
358
+ * The wall-clock timer covers both connection and body streaming — node's
359
+ * `timeout` option is an INACTIVITY timeout that resets on every chunk, so a
360
+ * slow-drip response would never fire it.
361
+ */
362
+ export function probeDevServer(
363
+ record: DevRecord,
364
+ path: string,
365
+ timeoutMs: number
366
+ ): Promise<unknown> {
367
+ return new Promise((resolve) => {
368
+ let settled = false;
369
+ let req: ClientRequest | undefined;
370
+ const done = (value: unknown) => {
371
+ if (settled) return;
372
+ settled = true;
373
+ clearTimeout(wallClock);
374
+ resolve(value);
375
+ };
376
+ const wallClock = setTimeout(() => {
377
+ req?.destroy();
378
+ done(null);
379
+ }, timeoutMs);
380
+
381
+ const doRequest = record.protocol === 'https' ? httpsRequest : httpRequest;
382
+ try {
383
+ req = doRequest(
384
+ {
385
+ hostname: connectHost(record.host),
386
+ port: record.port,
387
+ path,
388
+ method: 'GET',
389
+ // Self-signed certs are normal for dev servers.
390
+ rejectUnauthorized: false,
391
+ },
392
+ (res) => {
393
+ if (res.statusCode !== 200) {
394
+ req?.destroy();
395
+ done(null);
396
+ return;
397
+ }
398
+ const chunks: Buffer[] = [];
399
+ let totalBytes = 0;
400
+ res.on('data', (chunk: Buffer) => {
401
+ totalBytes += chunk.length;
402
+ if (totalBytes > PROBE_MAX_BODY_BYTES) {
403
+ req?.destroy();
404
+ done(null);
405
+ return;
406
+ }
407
+ chunks.push(chunk);
408
+ });
409
+ res.on('end', () => {
410
+ try {
411
+ done(JSON.parse(Buffer.concat(chunks).toString('utf8')));
412
+ } catch {
413
+ done(null);
414
+ }
415
+ });
416
+ res.on('error', () => done(null));
417
+ }
418
+ );
419
+ } catch {
420
+ // http.request throws synchronously on malformed hostnames
421
+ // (ERR_INVALID_CHAR) or other invalid options — treat as absent.
422
+ done(null);
423
+ return;
424
+ }
425
+ req.on('error', () => done(null));
426
+ req.end();
427
+ });
428
+ }