@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
@@ -0,0 +1,145 @@
1
+ /**
2
+ * Clear the cache.component dev store on every dev-server watcher event
3
+ * (TIM-1588, server/prebuilt/dev-store.ts) — and once more shortly after.
4
+ *
5
+ * A clear is scoped when the RSC module graph can say what a save changed
6
+ * (TIM-1599). A `change` to a file the graph knows as a module can only have
7
+ * changed the output of the modules that import it, transitively, so only
8
+ * the components declared in those modules (and in the file itself) are
9
+ * dropped. Element props need no tracking: non-slot element props make a
10
+ * render unkeyable, and slot content is composed live (design/45 §Cache Key,
11
+ * §Slot Components). Nested cache.component children are baked flat into
12
+ * their parent, whose module imports them, so the walk reaches the parent.
13
+ *
14
+ * The graph also holds file-only entries: files a plugin declared with
15
+ * `addWatchFile`. Tailwind's plugin declares every file its scanner finds,
16
+ * markdown and JSON included, as a dependency of the stylesheet. A file-only
17
+ * entry says what watches the file, never what reads it with fs, so a file
18
+ * with no module node clears everything. When the walk meets one on its way
19
+ * up (a module Tailwind also scans), it goes through it to the stylesheet's
20
+ * importers, which costs extra re-renders of components declared up that
21
+ * chain and never a stale one.
22
+ *
23
+ * Everything else clears every component: a file the graph does not know as
24
+ * a module (markdown or JSON read with fs), and an add or a delete (a glob
25
+ * or a route scan may pick it up). The decision is graph membership, never
26
+ * the file's extension. Not covered: a module loaded by a variable dynamic
27
+ * `import()` that Vite cannot analyze has no importer edge, and a component
28
+ * that reads a project module with fs is not that module's importer. A hard
29
+ * reload covers both.
30
+ *
31
+ * Vite's watcher (chokidar) throttles `change`: once it emits one for a
32
+ * path, it DROPS every further `change` for that path for 50ms, and never
33
+ * emits a trailing event for them. So a save is invisible when it lands
34
+ * inside that window, which is easy to hit: save a file, the next request
35
+ * renders and stores it in a few milliseconds, save again (an editor that
36
+ * writes twice, a script that rewrites a file the page reads with fs).
37
+ * The store keeps the first save's render until some later, unrelated
38
+ * save. Before the store, a dropped event cost nothing: a file read with
39
+ * fs was read again on every request.
40
+ *
41
+ * The trailing clear lands after that window closes, so it follows any
42
+ * write whose event was dropped. A dropped event is always for a path the
43
+ * burst already reported, so the trailing clear covers every path seen in
44
+ * the burst, and resolves them against the graph again when it fires: a
45
+ * request between the saves may have re-transformed a module and given its
46
+ * call sites new IDs. A render of a covered component that started before
47
+ * it cannot store (the clear records an invalidation of it), and a render
48
+ * after it reads the file as written. Debounced, so a burst of saves gets
49
+ * one trailing clear, after the last of them. The cost is at most one
50
+ * extra re-render per save, in dev only.
51
+ */
52
+
53
+ /** chokidar's per-path `change` throttle (`_throttle(EV_CHANGE, path, 50)`). */
54
+ const WATCHER_CHANGE_THROTTLE_MS = 50;
55
+
56
+ /**
57
+ * Comfortably past the throttle window. Both are timers started in the same
58
+ * synchronous emit, so this one always fires after the throttle has expired,
59
+ * however late the event loop runs them.
60
+ */
61
+ const TRAILING_CLEAR_DELAY_MS = WATCHER_CHANGE_THROTTLE_MS * 2;
62
+
63
+ /** The part of Vite's `FSWatcher` this needs. */
64
+ interface WatcherEvents {
65
+ on(event: 'all', listener: (event: string, path: string) => void): unknown;
66
+ }
67
+
68
+ /**
69
+ * What a clear covers: the paths changed in place, or null for anything
70
+ * else (an add, a delete, a directory event), which clears everything.
71
+ */
72
+ export type ChangedPaths = ReadonlySet<string> | null;
73
+
74
+ export function clearDevStoreOnWatcherEvents(
75
+ watcher: WatcherEvents,
76
+ clear: (changed: ChangedPaths) => void
77
+ ): void {
78
+ let trailing: ReturnType<typeof setTimeout> | undefined;
79
+ // Every path the burst reported, or null once anything cleared everything.
80
+ let burst: Set<string> | null = new Set();
81
+ watcher.on('all', (event, path) => {
82
+ const changed = event === 'change' ? new Set([path]) : null;
83
+ clear(changed);
84
+ if (changed === null) burst = null;
85
+ else burst?.add(path);
86
+ clearTimeout(trailing);
87
+ trailing = setTimeout(() => {
88
+ const covered = burst;
89
+ burst = new Set();
90
+ clear(covered);
91
+ }, TRAILING_CLEAR_DELAY_MS);
92
+ // Never the reason the dev process stays alive.
93
+ trailing.unref?.();
94
+ });
95
+ }
96
+
97
+ /** The part of Vite's `EnvironmentModuleNode` the walk reads. */
98
+ export interface GraphModule {
99
+ /** Null for a file-only entry (`addWatchFile`), which declares nothing. */
100
+ id: string | null;
101
+ importers: Set<GraphModule>;
102
+ }
103
+
104
+ /** The part of Vite's `EnvironmentModuleGraph` the walk reads. */
105
+ export interface ModuleGraphView {
106
+ getModulesByFile(file: string): Set<GraphModule> | undefined;
107
+ }
108
+
109
+ /**
110
+ * The cache.component IDs whose output the changed paths could have
111
+ * changed: those declared in each changed module and its transitive
112
+ * importers. Null means every component — a path the graph does not know.
113
+ *
114
+ * `componentIds` maps a module ID to the IDs its last transform declared
115
+ * (`PluginContext.devPrebuiltComponentIds`). `toGraphPath` puts a watcher
116
+ * path in the graph's path space (symlinks resolved, `/` separators).
117
+ */
118
+ export function componentsChangedBy(
119
+ changed: ChangedPaths,
120
+ graph: ModuleGraphView,
121
+ componentIds: ReadonlyMap<string, readonly string[]>,
122
+ toGraphPath: (path: string) => string
123
+ ): string[] | null {
124
+ if (changed === null) return null;
125
+ const affected = new Set<string>();
126
+ const visited = new Set<GraphModule>();
127
+ const pending: GraphModule[] = [];
128
+ for (const path of changed) {
129
+ const nodes = [...(graph.getModulesByFile(toGraphPath(path)) ?? [])];
130
+ // Known as a module, or not at all: a file that only a plugin watches
131
+ // may also be read with fs, by any component.
132
+ if (!nodes.some((node) => node.id !== null)) return null;
133
+ pending.push(...nodes);
134
+ }
135
+ while (pending.length > 0) {
136
+ const module = pending.pop()!;
137
+ if (visited.has(module)) continue;
138
+ visited.add(module);
139
+ if (module.id !== null) {
140
+ for (const id of componentIds.get(module.id) ?? []) affected.add(id);
141
+ }
142
+ pending.push(...module.importers);
143
+ }
144
+ return [...affected];
145
+ }
@@ -1,5 +1,6 @@
1
1
  /**
2
- * graph-endpoint — `GET /__timber/graph` on the dev server.
2
+ * graph-endpoint — `GET /__timber/graph` (and the `GET /__timber/status`
3
+ * identity probe) on the dev server.
3
4
  *
4
5
  * The fast path of design/47: when a dev server runs, the env module
5
6
  * graphs are already resident and classification is a lookup. Serves
@@ -38,6 +39,7 @@ import { isAbsolute, join, relative, resolve } from 'node:path';
38
39
  import type { PluginContext } from '../plugin-context.ts';
39
40
  import { buildSourceExtensions, isScannableSourceFile } from '../analyze/scan.ts';
40
41
  import { GRAPH_JSON_VERSION } from '../analyze/graph-cache.ts';
42
+ import { STATUS_ENDPOINT_PATH } from './dev-discovery.ts';
41
43
 
42
44
  export const GRAPH_ENDPOINT_PATH = '/__timber/graph';
43
45
 
@@ -159,7 +161,8 @@ function reflectCors(res: ServerResponse, origin: string | undefined): void {
159
161
  }
160
162
 
161
163
  /**
162
- * Create the Connect middleware handling GET /__timber/graph.
164
+ * Create the Connect middleware handling GET /__timber/graph and the
165
+ * GET /__timber/status identity probe.
163
166
  *
164
167
  * Query surface: `?file=<path>` (absolute or project-root-relative) or
165
168
  * `?all=1`. Anything else is a 400 — fail loudly, like the CLI.
@@ -175,7 +178,8 @@ export function createGraphEndpointMiddleware(server: ViteDevServer, ctx: Plugin
175
178
  return;
176
179
  }
177
180
  const url = new URL(rawUrl, 'http://placeholder.invalid');
178
- if (url.pathname !== GRAPH_ENDPOINT_PATH) {
181
+ const isStatus = url.pathname === STATUS_ENDPOINT_PATH;
182
+ if (!isStatus && url.pathname !== GRAPH_ENDPOINT_PATH) {
179
183
  sendJson(res, 404, { error: `unknown /__timber/ endpoint: ${url.pathname}` });
180
184
  return;
181
185
  }
@@ -205,6 +209,14 @@ export function createGraphEndpointMiddleware(server: ViteDevServer, ctx: Plugin
205
209
  // consumers can actually READ the response.
206
210
  reflectCors(res, origin);
207
211
 
212
+ // Identity probe for `timber dev status` (dev-discovery.ts): the pid
213
+ // lets the CLI confirm this is the server that wrote the record, not
214
+ // a different process that took a crashed server's port.
215
+ if (isStatus) {
216
+ sendJson(res, 200, { pid: process.pid });
217
+ return;
218
+ }
219
+
208
220
  try {
209
221
  // Lazy import: the analyze pipeline (oxc parse, chains) loads on
210
222
  // first query, not on every dev-server boot.
@@ -420,6 +420,14 @@ export function timberPrebuilt(ctx: PluginContext): Plugin & { api: PrebuiltBuil
420
420
  moduleComponents.delete(id);
421
421
  bindingNames.delete(id);
422
422
  }
423
+ // Dev: the same, for the dev store's scoped clears. A save reaches the
424
+ // watcher before the module is transformed again, so the clear for a
425
+ // save drops the IDs the module declared before it.
426
+ const devIds =
427
+ ctx.dev && this?.environment?.name === 'rsc'
428
+ ? (ctx.devPrebuiltComponentIds ??= new Map())
429
+ : null;
430
+ devIds?.delete(id);
423
431
  if (!code.includes('@timber-js/app/cache') && !code.includes('timber/cache')) return;
424
432
  // Skip node_modules (don't transform third-party code)
425
433
  if (id.includes('node_modules')) return;
@@ -468,6 +476,7 @@ export function timberPrebuilt(ctx: PluginContext): Plugin & { api: PrebuiltBuil
468
476
  // Only prerender-capable call sites feed the capture attribution —
469
477
  // runtime-tier components (ttl/tags only) must do no build work.
470
478
  if (!ctx.dev && mayPrerender(call)) componentIds.push(componentId);
479
+ if (devIds) devIds.set(id, [...(devIds.get(id) ?? []), componentId]);
471
480
 
472
481
  s.overwrite(call.callee.start, call.callee.end, '__prebuilt');
473
482
  s.appendLeft(call.arguments[0].start, `${JSON.stringify(componentId)}, `);
@@ -10,8 +10,9 @@
10
10
  * touches the RSC runtime.
11
11
  *
12
12
  * Keep this as thin pass-through re-exports — the value is the single choke
13
- * point, not abstraction. The exception is `renderFlight`, the only way to
14
- * render Flight (render-flight.ts). Bound-args encryption is plugin-rsc's
13
+ * point, not abstraction. The exceptions are `renderFlight`, the only way to
14
+ * render Flight (render-flight.ts), and `loadServerAction`, which tells an
15
+ * unknown reference from a broken module (server-references.ts). Bound-args encryption is plugin-rsc's
15
16
  * injected runtime, resolved to encryption-runtime.ts so it renders through
16
17
  * `renderFlight` too.
17
18
  */
@@ -21,8 +22,11 @@ import { scopeReferenceCacheToGeneration } from './dev-reference-cache.ts';
21
22
  // The only way to render Flight; see render-flight.ts.
22
23
  export { renderFlight } from './render-flight.ts';
23
24
 
25
+ // Resolves an unknown reference to undefined instead of rejecting, so a
26
+ // rejection means a real module failed to load; see server-references.ts.
27
+ export { loadServerAction } from './server-references.ts';
28
+
24
29
  export {
25
- loadServerAction,
26
30
  decodeReply,
27
31
  decodeAction,
28
32
  // No-JS action result → the `useActionState` hook that submitted it
@@ -0,0 +1,73 @@
1
+ /// <reference types="vite/client" />
2
+ /// <reference types="@vitejs/plugin-rsc/types" />
3
+ // Declares the server-reference virtual for projects that typecheck this
4
+ // file without the package tsconfig (the website).
5
+ /// <reference path="./vendor-types.d.ts" />
6
+
7
+ /**
8
+ * Load a server action by reference ID, telling a reference that does not
9
+ * exist apart from a module that fails to load (TIM-1601).
10
+ *
11
+ * plugin-rsc's `loadServerAction` rejects the same way for both: an unknown
12
+ * module ID throws from its reference lookup, and a real `'use server'`
13
+ * module that fails to import throws from the import. The first is a client
14
+ * error, the second a server fault, and the error message is the only thing
15
+ * that differs. So the lookup is asked first, through the same table
16
+ * plugin-rsc's loader reads, and an unknown module resolves to `undefined`:
17
+ * what plugin-rsc already resolves for an unknown export of a known module.
18
+ * A rejection from the load itself is then a real failure.
19
+ */
20
+
21
+ import { loadServerAction as loadServerReference } from '@vitejs/plugin-rsc/rsc';
22
+ import serverReferences from 'virtual:vite-rsc/server-references';
23
+
24
+ /**
25
+ * Whether plugin-rsc knows `moduleId` as a `'use server'` module.
26
+ *
27
+ * - Build: the keys of `virtual:vite-rsc/server-references`, the table
28
+ * plugin-rsc's build loader indexes. Own keys only: the table is a plain
29
+ * object, so `constructor` would otherwise be found on its prototype.
30
+ * - Dev: plugin-rsc's reference-validation virtual, which its dev loader
31
+ * imports before the module itself, and which fails for a module ID it has
32
+ * no server-reference metadata for (after transforming the file once, so a
33
+ * module no render has reached yet is still found). plugin-rsc swallows
34
+ * the transform's own error, so a module that fails to transform in the
35
+ * RSC environment (a syntax error, a non-async export) counts as unknown
36
+ * here too, and is answered with a 400 and a warning. When an RSC render
37
+ * imports the module, that render reports the error. When only a client
38
+ * component imports it, nothing does until the production build fails on
39
+ * it. Any other rejection of this import (the environment closing during a
40
+ * restart) is likewise read as unknown. These cases are dev-only: a build
41
+ * never contains a module that failed to transform.
42
+ */
43
+ async function isServerReferenceModule(moduleId: string): Promise<boolean> {
44
+ if (import.meta.env.__vite_rsc_build__) {
45
+ return Object.hasOwn(serverReferences, moduleId);
46
+ }
47
+ try {
48
+ // The ID plugin-rsc's dev loader imports (`toReferenceValidationVirtual`
49
+ // in its plugins/shared.ts), which it does not export.
50
+ await import(
51
+ /* @vite-ignore */
52
+ '/@id/__x00__virtual:vite-rsc/reference-validation?type=server&id=' +
53
+ encodeURIComponent(moduleId) +
54
+ '&lang.js'
55
+ );
56
+ return true;
57
+ } catch {
58
+ return false;
59
+ }
60
+ }
61
+
62
+ /**
63
+ * The export `id` (`<module>#<export>`) names, or `undefined` when the module
64
+ * or the export does not exist. Rejects only when a known module fails to
65
+ * load. The value is not checked: the caller decides whether it is a server
66
+ * function.
67
+ */
68
+ export async function loadServerAction(id: string): Promise<unknown> {
69
+ // Split at `#` as plugin-rsc's `loadServerAction` does.
70
+ const [moduleId] = id.split('#');
71
+ if (!(await isServerReferenceModule(moduleId))) return undefined;
72
+ return loadServerReference(id);
73
+ }
@@ -5,6 +5,15 @@ declare module 'virtual:vite-rsc/encryption-key' {
5
5
  export default encryptionKey;
6
6
  }
7
7
 
8
+ // plugin-rsc's server-reference table (its `vite-rsc/server-references`
9
+ // virtual): reference key → module loader in a build, read by
10
+ // server-references.ts. In dev the virtual exports nothing, so this is
11
+ // undefined there and is read only behind `__vite_rsc_build__`.
12
+ declare module 'virtual:vite-rsc/server-references' {
13
+ const serverReferences: Record<string, () => Promise<Record<string, unknown>>>;
14
+ export default serverReferences;
15
+ }
16
+
8
17
  // src renders through plugin-rsc's wrappers (rsc-runtime/rsc.ts); tests stand
9
18
  // in the vendored servers for them, with an empty client manifest.
10
19
  declare module '@vitejs/plugin-rsc/vendor/react-server-dom/server.node' {
@@ -53,6 +62,14 @@ declare module '@vitejs/plugin-rsc/vendor/react-server-dom/server.edge' {
53
62
  manifest: unknown,
54
63
  options?: { temporaryReferences?: unknown; arraySizeLimit?: number }
55
64
  ): Promise<unknown[]>;
65
+
66
+ // Tests stub `loadServerAction` with functions registered the way the
67
+ // use-server transform registers a module's exports.
68
+ export function registerServerReference<T extends Function>(
69
+ reference: T,
70
+ id: string,
71
+ exportName: string | null
72
+ ): T;
56
73
  }
57
74
 
58
75
  // src decodes through plugin-rsc's wrappers; tests decode a Flight response
@@ -12,9 +12,10 @@
12
12
  *
13
13
  * One parse loop, four candidate orders. Which shapes a bridge offers, and
14
14
  * in what order, is the ONLY thing that differs — see §"Shape tolerance"
15
- * below and in design/23-search-params.md. `serialize` is deliberately NOT
16
- * shared: `null` means "omit the key" for a search param and "delete the
17
- * cookie" for a cookie, so unifying it silently changed what
15
+ * below and in design/23-search-params.md. `serialize` is shared only by
16
+ * the two search-param bridges (`serializeSearchValue`), never with the
17
+ * cookie bridge: `null` means "omit the key" for a search param and
18
+ * "delete the cookie" for a cookie, so unifying it silently changed what
18
19
  * `cookie.set([])` did (TIM-1352).
19
20
  *
20
21
  * These are re-exported from @timber-js/app/search-params, @timber-js/app/segment-params,
@@ -132,22 +133,24 @@ export function fromParamSchema<T>(fieldName: string, schema: StandardSchemaV1<T
132
133
  *
133
134
  * @param fieldName - used in error messages
134
135
  * @param value - the codec or schema to resolve
136
+ * Search params don't come through here: `defineSearchParams` wraps
137
+ * schemas with `fromSchema`, whose `serialize` may return `string[]`.
138
+ *
139
+ * @param fieldName - used in error messages
140
+ * @param value - the codec or schema to resolve
135
141
  * @param mode - 'param' uses fromParamSchema (throws on parse failure),
136
- * 'search' uses fromSchema (falls back to default on failure,
137
- * tolerant of the repeated-key array shape),
138
- * 'cookie' uses fromCookieSchema (same, minus the array shape,
139
- * which a cookie value cannot have)
142
+ * 'cookie' uses fromCookieSchema (falls back to default on
143
+ * failure; scalar shape only, since a cookie has no array shape)
140
144
  */
141
145
  export function resolveCodecOrSchema(
142
146
  fieldName: string,
143
147
  value: unknown,
144
- mode: 'param' | 'search' | 'cookie' = 'search'
148
+ mode: 'param' | 'cookie'
145
149
  ): Codec<unknown> {
146
150
  if (isCodec(value)) return value;
147
151
  if (isStandardSchema(value)) {
148
152
  if (mode === 'param') return fromParamSchema(fieldName, value);
149
- if (mode === 'cookie') return fromCookieSchema(value) as Codec<unknown>;
150
- return fromSchema(value) as Codec<unknown>;
153
+ return fromCookieSchema(value) as Codec<unknown>;
151
154
  }
152
155
  throw new Error(
153
156
  `[timber] Field '${fieldName}' is not a valid codec or Standard Schema. ` +
@@ -272,10 +275,9 @@ function parseThroughSchema<T>(
272
275
  * schema should have a `.default()` call). If that also fails, returns
273
276
  * `undefined`.
274
277
  *
275
- * Serialize: `String()` for primitives, `null` for null/undefined. Note
276
- * that `String(['a','b'])` is `'a,b'` — the same string `fromArraySchema`
277
- * writes — so a bare array schema round-trips exactly as design/09
278
- * §"Array params" describes.
278
+ * Serialize: `String()` for primitives, `null` for null/undefined. An
279
+ * array is written in whichever encoding the schema reads back as the same
280
+ * array — see `serializeArrayForSchema`.
279
281
  *
280
282
  * This is the SEARCH-PARAM bridge. Cookies use `fromCookieSchema`; a
281
283
  * cookie has no array shape (see below).
@@ -287,19 +289,86 @@ function parseThroughSchema<T>(
287
289
  * const tagsCodec = fromSchema(z.array(z.string()).default([]))
288
290
  * ```
289
291
  */
290
- export function fromSchema<T>(schema: StandardSchemaV1<T>): Codec<T> {
292
+ export function fromSchema<T>(schema: StandardSchemaV1<T>): SearchValueCodec<T> {
291
293
  return {
292
294
  parse: (value: string | string[] | undefined): T =>
293
295
  parseThroughSchema(schema, scalarFirst, value),
294
- serialize(value: T): string | null {
295
- if (value === null || value === undefined) {
296
- return null;
297
- }
298
- return String(value);
299
- },
296
+ serialize: (value: T): string | string[] | null =>
297
+ Array.isArray(value) ? serializeArrayForSchema(schema, value) : serializeSearchValue(value),
300
298
  };
301
299
  }
302
300
 
301
+ /**
302
+ * An array value has two URL encodings, and the schema alone decides which
303
+ * one reads back. `z.array(z.string())` reads repeated keys
304
+ * (`?tags=a&tags=b`); the comma idiom, `z.string().transform(v =>
305
+ * v.split(','))`, reads ONE key (`?tags=a,b`) and takes only the first of
306
+ * repeated keys. Writing the wrong one is silent data corruption: joining
307
+ * for an array schema reads back as the single element `'a,b'`, and
308
+ * repeating for the comma idiom reads back as `['a']`.
309
+ *
310
+ * Standard Schema exposes no input type at runtime, so ask the schema:
311
+ * parse the preferred encoding exactly as a request would deliver it, and
312
+ * keep it if the same array comes back. Otherwise write the joined string,
313
+ * which is what the comma idiom reads.
314
+ *
315
+ * An empty array prefers omitting the key, which reads back as `[]` for
316
+ * `z.array(z.string()).default([])`. A comma schema whose absent value is
317
+ * a non-empty default (`.catch(['all'])`) instead needs `tags=`, which its
318
+ * transform turns into `[]` — omitting would read back as `['all']`.
319
+ */
320
+ function serializeArrayForSchema<T>(
321
+ schema: StandardSchemaV1<T>,
322
+ value: unknown[]
323
+ ): string | string[] | null {
324
+ const preferred = value.length === 0 ? null : value.map(String);
325
+ return readsBack(schema, preferred, value) ? preferred : String(value);
326
+ }
327
+
328
+ /** Does `encoded`, delivered as a request would, parse back to `value`? */
329
+ function readsBack<T>(
330
+ schema: StandardSchemaV1<T>,
331
+ encoded: string[] | null,
332
+ value: unknown[]
333
+ ): boolean {
334
+ // An omitted key arrives as undefined; URLSearchParams.getAll() yields
335
+ // one value as a plain string.
336
+ const delivered = encoded === null ? undefined : encoded.length === 1 ? encoded[0] : encoded;
337
+ let readBack: unknown;
338
+ try {
339
+ readBack = parseThroughSchema(schema, scalarFirst, delivered);
340
+ } catch {
341
+ // The schema refuses this URL outright, so it is not the encoding.
342
+ return false;
343
+ }
344
+ return (
345
+ Array.isArray(readBack) &&
346
+ readBack.length === value.length &&
347
+ readBack.every((item, i) => String(item) === String(value[i]))
348
+ );
349
+ }
350
+
351
+ /**
352
+ * The codec shape both search-param bridges return. Structurally a
353
+ * `SearchParamCodec<T>` (search-params/define.ts), declared here because
354
+ * define.ts imports this module.
355
+ */
356
+ interface SearchValueCodec<T> {
357
+ parse(value: string | string[] | undefined): T;
358
+ serialize(value: T): string | string[] | null;
359
+ }
360
+
361
+ /**
362
+ * Search-param serialize for `fromSchema` and `fromArraySchema`. An array
363
+ * becomes `string[]` so it is written as repeated keys (TIM-1353); an empty
364
+ * array omits the key.
365
+ */
366
+ function serializeSearchValue(value: unknown): string | string[] | null {
367
+ if (value === null || value === undefined) return null;
368
+ if (Array.isArray(value)) return value.length === 0 ? null : value.map(String);
369
+ return String(value);
370
+ }
371
+
303
372
  // ---------------------------------------------------------------------------
304
373
  // fromCookieSchema — bridge for cookie values
305
374
  // ---------------------------------------------------------------------------
@@ -357,26 +426,12 @@ export function fromCookieSchema<T>(schema: StandardSchemaV1<T>): Codec<T> {
357
426
  * 2. An array schema wrapped in `.catch([])`, which swallows the failure
358
427
  * that would otherwise trigger the array attempt.
359
428
  *
360
- * It also serializes an empty array to `null` (omitting the key) where
361
- * `fromSchema` writes `''`.
429
+ * Serialization is identical to `fromSchema`.
362
430
  */
363
- export function fromArraySchema<T>(schema: StandardSchemaV1<T>): {
364
- parse(value: string | string[] | undefined): T;
365
- serialize(value: T): string | string[] | null;
366
- } {
431
+ export function fromArraySchema<T>(schema: StandardSchemaV1<T>): SearchValueCodec<T> {
367
432
  return {
368
433
  parse: (value: string | string[] | undefined): T =>
369
434
  parseThroughSchema(schema, arrayFirst, value),
370
- serialize(value: T): string | string[] | null {
371
- if (value === null || value === undefined) {
372
- return null;
373
- }
374
- // TIM-1353: return string[] so buildSearchParams emits repeated keys
375
- // (?tag=a&tag=b) instead of comma-joining into one key (?tag=a%2Cb).
376
- if (Array.isArray(value)) {
377
- return value.length === 0 ? null : value.map(String);
378
- }
379
- return String(value);
380
- },
435
+ serialize: serializeSearchValue,
381
436
  };
382
437
  }
@@ -339,10 +339,9 @@ function getDefaultSerialized(codec: SearchParamCodec<unknown>): string | string
339
339
  * objects and wraps them with fromSchema. Reads .urlKey from codecs.
340
340
  *
341
341
  * The returned codec is typed as `SearchParamCodec<unknown>` because the
342
- * codec map uses that type. At runtime, the value may be a `Codec<T>` from
343
- * `fromSchema` (whose serialize returns `string | null`) or a nuqs parser
344
- * (whose serialize returns `string | string[] | null`). Both are safe
345
- * because `buildSearchParams` handles the union.
342
+ * codec map uses that type. Both `fromSchema` results and nuqs parsers may
343
+ * serialize to `string | string[] | null`; `buildSearchParams` handles the
344
+ * union.
346
345
  */
347
346
  function resolveField(
348
347
  fieldName: string,
@@ -359,7 +358,7 @@ function resolveField(
359
358
  // for absent params, and InferField widens the output type to
360
359
  // T | undefined. design/23-search-params.md §"Implicit Optionality"
361
360
  if (isStandardSchema(value)) {
362
- return { codec: fromSchema(value) as SearchParamCodec<unknown> };
361
+ return { codec: fromSchema(value) };
363
362
  }
364
363
 
365
364
  throw new Error(
@@ -380,7 +379,7 @@ function resolveField(
380
379
  *
381
380
  * ```ts
382
381
  * import { defineSearchParams, withDefault, withUrlKey } from '@timber-js/app/search-params'
383
- * import { parseAsString, parseAsStringEnum } from 'nuqs'
382
+ * import { parseAsString, parseAsStringEnum } from 'nuqs/server'
384
383
  * import { z } from 'zod/v4'
385
384
  *
386
385
  * export const searchParams = defineSearchParams({
@@ -45,7 +45,7 @@ import { parseTotal } from './parse-total.ts';
45
45
  * Works with any codec — nuqs parsers, custom codecs, fromSchema results.
46
46
  *
47
47
  * ```ts
48
- * import { parseAsInteger } from 'nuqs'
48
+ * import { parseAsInteger } from 'nuqs/server'
49
49
  * import { withDefault } from '@timber-js/app/search-params'
50
50
  *
51
51
  * const page = withDefault(parseAsInteger, 1)
@@ -97,7 +97,7 @@ export function withDefault<T>(
97
97
  * the aliases come along automatically.
98
98
  *
99
99
  * ```ts
100
- * import { parseAsString } from 'nuqs'
100
+ * import { parseAsString } from 'nuqs/server'
101
101
  * import { withUrlKey } from '@timber-js/app/search-params'
102
102
  *
103
103
  * export const searchable = {
@@ -108,7 +108,7 @@ export function withDefault<T>(
108
108
  *
109
109
  * Composes with withDefault:
110
110
  * ```ts
111
- * import { parseAsInteger } from 'nuqs'
111
+ * import { parseAsInteger } from 'nuqs/server'
112
112
  * withUrlKey(withDefault(parseAsInteger, 1), 'p')
113
113
  * ```
114
114
  */