@decocms/blocks 8.9.1 → 8.11.0

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 (409) hide show
  1. package/dist/index.d.ts +1 -1
  2. package/dist/index.d.ts.map +1 -1
  3. package/dist/index.js +1 -1
  4. package/dist/index.js.map +1 -1
  5. package/dist/protocol/channel.d.ts +98 -0
  6. package/dist/protocol/channel.d.ts.map +1 -0
  7. package/dist/protocol/channel.js +58 -0
  8. package/dist/protocol/channel.js.map +1 -0
  9. package/dist/protocol/client.js +2 -2
  10. package/dist/protocol/client.js.map +1 -1
  11. package/dist/protocol/conformance/blockMetaVectors.json +214 -0
  12. package/dist/protocol/conformance/contentHashFixtures.d.ts +22 -0
  13. package/dist/protocol/conformance/contentHashFixtures.d.ts.map +1 -1
  14. package/dist/protocol/conformance/contentHashFixtures.js +55 -0
  15. package/dist/protocol/conformance/contentHashFixtures.js.map +1 -1
  16. package/dist/protocol/conformance/index.d.ts +2 -1
  17. package/dist/protocol/conformance/index.d.ts.map +1 -1
  18. package/dist/protocol/conformance/index.js +2 -1
  19. package/dist/protocol/conformance/index.js.map +1 -1
  20. package/dist/protocol/conformance/vectors.d.ts +33 -0
  21. package/dist/protocol/conformance/vectors.d.ts.map +1 -0
  22. package/dist/protocol/conformance/vectors.js +3 -0
  23. package/dist/protocol/conformance/vectors.js.map +1 -0
  24. package/dist/protocol/index.d.ts +11 -1
  25. package/dist/protocol/index.d.ts.map +1 -1
  26. package/dist/protocol/index.js +11 -1
  27. package/dist/protocol/index.js.map +1 -1
  28. package/dist/protocol/keys.d.ts +1 -1
  29. package/dist/protocol/keys.js +1 -1
  30. package/dist/v8/background.d.ts +13 -0
  31. package/dist/v8/background.d.ts.map +1 -1
  32. package/dist/v8/background.js +41 -0
  33. package/dist/v8/background.js.map +1 -1
  34. package/dist/v8/blockMeta.d.ts +27 -0
  35. package/dist/v8/blockMeta.d.ts.map +1 -0
  36. package/dist/v8/blockMeta.js +75 -0
  37. package/dist/v8/blockMeta.js.map +1 -0
  38. package/dist/v8/blockStore.d.ts +43 -0
  39. package/dist/v8/blockStore.d.ts.map +1 -0
  40. package/dist/v8/blockStore.js +95 -0
  41. package/dist/v8/blockStore.js.map +1 -0
  42. package/dist/v8/boundedJson.d.ts +5 -0
  43. package/dist/v8/boundedJson.d.ts.map +1 -1
  44. package/dist/v8/boundedJson.js +10 -2
  45. package/dist/v8/boundedJson.js.map +1 -1
  46. package/dist/v8/boundedMap.d.ts +19 -0
  47. package/dist/v8/boundedMap.d.ts.map +1 -0
  48. package/dist/v8/boundedMap.js +52 -0
  49. package/dist/v8/boundedMap.js.map +1 -0
  50. package/dist/v8/builtins/data.d.ts +18 -2
  51. package/dist/v8/builtins/data.d.ts.map +1 -1
  52. package/dist/v8/builtins/data.js +17 -1
  53. package/dist/v8/builtins/data.js.map +1 -1
  54. package/dist/v8/builtins/index.d.ts.map +1 -1
  55. package/dist/v8/builtins/index.js +2 -1
  56. package/dist/v8/builtins/index.js.map +1 -1
  57. package/dist/v8/builtins/legacy.d.ts +6 -3
  58. package/dist/v8/builtins/legacy.d.ts.map +1 -1
  59. package/dist/v8/builtins/legacy.js +6 -3
  60. package/dist/v8/builtins/legacy.js.map +1 -1
  61. package/dist/v8/canonical.d.ts +8 -0
  62. package/dist/v8/canonical.d.ts.map +1 -1
  63. package/dist/v8/canonical.js +15 -0
  64. package/dist/v8/canonical.js.map +1 -1
  65. package/dist/v8/cli/builtins.d.ts.map +1 -1
  66. package/dist/v8/cli/builtins.js +1 -0
  67. package/dist/v8/cli/builtins.js.map +1 -1
  68. package/dist/v8/cli/check/index.d.ts +10 -0
  69. package/dist/v8/cli/check/index.d.ts.map +1 -1
  70. package/dist/v8/cli/check/index.js +91 -7
  71. package/dist/v8/cli/check/index.js.map +1 -1
  72. package/dist/v8/cli/content.d.ts +12 -25
  73. package/dist/v8/cli/content.d.ts.map +1 -1
  74. package/dist/v8/cli/content.js +46 -75
  75. package/dist/v8/cli/content.js.map +1 -1
  76. package/dist/v8/cli/index.d.ts +2 -2
  77. package/dist/v8/cli/index.d.ts.map +1 -1
  78. package/dist/v8/cli/index.js +2 -2
  79. package/dist/v8/cli/index.js.map +1 -1
  80. package/dist/v8/cli/remote/commands.d.ts +71 -0
  81. package/dist/v8/cli/remote/commands.d.ts.map +1 -0
  82. package/dist/v8/cli/remote/commands.js +644 -0
  83. package/dist/v8/cli/remote/commands.js.map +1 -0
  84. package/dist/v8/cli/remote/diff.d.ts +15 -0
  85. package/dist/v8/cli/remote/diff.d.ts.map +1 -0
  86. package/dist/v8/cli/remote/diff.js +102 -0
  87. package/dist/v8/cli/remote/diff.js.map +1 -0
  88. package/dist/v8/cli/remote/env.d.ts +35 -0
  89. package/dist/v8/cli/remote/env.d.ts.map +1 -0
  90. package/dist/v8/cli/remote/env.js +84 -0
  91. package/dist/v8/cli/remote/env.js.map +1 -0
  92. package/dist/v8/cli/remote/http.d.ts +149 -0
  93. package/dist/v8/cli/remote/http.d.ts.map +1 -0
  94. package/dist/v8/cli/remote/http.js +381 -0
  95. package/dist/v8/cli/remote/http.js.map +1 -0
  96. package/dist/v8/cli/remote/local.d.ts +90 -0
  97. package/dist/v8/cli/remote/local.d.ts.map +1 -0
  98. package/dist/v8/cli/remote/local.js +309 -0
  99. package/dist/v8/cli/remote/local.js.map +1 -0
  100. package/dist/v8/cli/root.d.ts +29 -0
  101. package/dist/v8/cli/root.d.ts.map +1 -1
  102. package/dist/v8/cli/root.js +28 -0
  103. package/dist/v8/cli/root.js.map +1 -1
  104. package/dist/v8/cli/run.d.ts +13 -1
  105. package/dist/v8/cli/run.d.ts.map +1 -1
  106. package/dist/v8/cli/run.js +310 -124
  107. package/dist/v8/cli/run.js.map +1 -1
  108. package/dist/v8/cli/schema/builtinSchemas.d.ts.map +1 -1
  109. package/dist/v8/cli/schema/builtinSchemas.js +28 -10
  110. package/dist/v8/cli/schema/builtinSchemas.js.map +1 -1
  111. package/dist/v8/cli/schema/generate.js +1 -1
  112. package/dist/v8/cli/schema/generate.js.map +1 -1
  113. package/dist/v8/cli/skills.d.ts +25 -0
  114. package/dist/v8/cli/skills.d.ts.map +1 -0
  115. package/dist/v8/cli/skills.js +70 -0
  116. package/dist/v8/cli/skills.js.map +1 -0
  117. package/dist/v8/client.d.ts +9 -9
  118. package/dist/v8/client.d.ts.map +1 -1
  119. package/dist/v8/client.js +138 -50
  120. package/dist/v8/client.js.map +1 -1
  121. package/dist/v8/cms.d.ts +2 -1
  122. package/dist/v8/cms.d.ts.map +1 -1
  123. package/dist/v8/cms.js +55 -46
  124. package/dist/v8/cms.js.map +1 -1
  125. package/dist/v8/content.d.ts +39 -78
  126. package/dist/v8/content.d.ts.map +1 -1
  127. package/dist/v8/content.js +155 -195
  128. package/dist/v8/content.js.map +1 -1
  129. package/dist/v8/contentIndex.d.ts +71 -0
  130. package/dist/v8/contentIndex.d.ts.map +1 -0
  131. package/dist/v8/contentIndex.js +137 -0
  132. package/dist/v8/contentIndex.js.map +1 -0
  133. package/dist/v8/draft.d.ts +7 -7
  134. package/dist/v8/draft.d.ts.map +1 -1
  135. package/dist/v8/draft.js +10 -9
  136. package/dist/v8/draft.js.map +1 -1
  137. package/dist/v8/draftChanges.d.ts +59 -32
  138. package/dist/v8/draftChanges.d.ts.map +1 -1
  139. package/dist/v8/draftChanges.js +139 -75
  140. package/dist/v8/draftChanges.js.map +1 -1
  141. package/dist/v8/errors.d.ts +21 -0
  142. package/dist/v8/errors.d.ts.map +1 -1
  143. package/dist/v8/errors.js +22 -0
  144. package/dist/v8/errors.js.map +1 -1
  145. package/dist/v8/hostedSource.d.ts +57 -0
  146. package/dist/v8/hostedSource.d.ts.map +1 -0
  147. package/dist/v8/hostedSource.js +18 -0
  148. package/dist/v8/hostedSource.js.map +1 -0
  149. package/dist/v8/identity.d.ts +1 -1
  150. package/dist/v8/identity.js +1 -1
  151. package/dist/v8/index.d.ts +1 -0
  152. package/dist/v8/index.d.ts.map +1 -1
  153. package/dist/v8/index.js +1 -0
  154. package/dist/v8/index.js.map +1 -1
  155. package/dist/v8/matchRoute.js +7 -4
  156. package/dist/v8/matchRoute.js.map +1 -1
  157. package/dist/v8/pin.d.ts +34 -0
  158. package/dist/v8/pin.d.ts.map +1 -0
  159. package/dist/v8/pin.js +156 -0
  160. package/dist/v8/pin.js.map +1 -0
  161. package/dist/v8/preview/StudioBridge.d.ts +8 -8
  162. package/dist/v8/preview/StudioBridge.d.ts.map +1 -1
  163. package/dist/v8/preview/StudioBridge.js +8 -10
  164. package/dist/v8/preview/StudioBridge.js.map +1 -1
  165. package/dist/v8/preview/StudioChannel.d.ts +51 -0
  166. package/dist/v8/preview/StudioChannel.d.ts.map +1 -0
  167. package/dist/v8/preview/StudioChannel.js +104 -0
  168. package/dist/v8/preview/StudioChannel.js.map +1 -0
  169. package/dist/v8/preview/index.d.ts +3 -0
  170. package/dist/v8/preview/index.d.ts.map +1 -1
  171. package/dist/v8/preview/index.js +3 -0
  172. package/dist/v8/preview/index.js.map +1 -1
  173. package/dist/v8/remoteLoader.d.ts +42 -5
  174. package/dist/v8/remoteLoader.d.ts.map +1 -1
  175. package/dist/v8/remoteLoader.js +317 -259
  176. package/dist/v8/remoteLoader.js.map +1 -1
  177. package/dist/v8/resolver.d.ts +22 -8
  178. package/dist/v8/resolver.d.ts.map +1 -1
  179. package/dist/v8/resolver.js +37 -32
  180. package/dist/v8/resolver.js.map +1 -1
  181. package/dist/v8/revisionId.d.ts +11 -0
  182. package/dist/v8/revisionId.d.ts.map +1 -0
  183. package/dist/v8/revisionId.js +13 -0
  184. package/dist/v8/revisionId.js.map +1 -0
  185. package/dist/v8/settings.d.ts +6 -6
  186. package/dist/v8/settings.d.ts.map +1 -1
  187. package/dist/v8/settings.js +8 -7
  188. package/dist/v8/settings.js.map +1 -1
  189. package/dist/v8/telemetry.d.ts +4 -2
  190. package/dist/v8/telemetry.d.ts.map +1 -1
  191. package/dist/v8/telemetry.js +2 -2
  192. package/dist/v8/telemetry.js.map +1 -1
  193. package/dist/v8/types.d.ts +52 -40
  194. package/dist/v8/types.d.ts.map +1 -1
  195. package/dist/v8/variants.d.ts +7 -2
  196. package/dist/v8/variants.d.ts.map +1 -1
  197. package/dist/v8/variants.js +21 -24
  198. package/dist/v8/variants.js.map +1 -1
  199. package/dist/v8/vite/index.d.ts +2 -2
  200. package/dist/v8/vite/index.js +1 -1
  201. package/dist/v8/vite/index.js.map +1 -1
  202. package/package.json +3 -2
  203. package/skills/deco-apps/SKILL.md +82 -0
  204. package/skills/deco-apps/references/algolia.md +51 -0
  205. package/skills/deco-apps/references/commerce-types.md +132 -0
  206. package/skills/deco-apps/references/instrumented-fetch.md +144 -0
  207. package/skills/deco-apps/references/magento.md +55 -0
  208. package/skills/deco-apps/references/messaging.md +76 -0
  209. package/skills/deco-apps/references/shopify.md +69 -0
  210. package/skills/deco-apps/references/vendored-loaders.md +135 -0
  211. package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
  212. package/skills/deco-apps/references/vtex.md +150 -0
  213. package/skills/deco-apps/references/wake.md +75 -0
  214. package/skills/deco-cms-schema/SKILL.md +80 -0
  215. package/skills/deco-cms-schema/references/annotations.md +147 -0
  216. package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
  217. package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
  218. package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
  219. package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
  220. package/skills/deco-go-live/SKILL.md +127 -0
  221. package/skills/deco-go-live/references/content-releases.md +90 -0
  222. package/skills/deco-go-live/references/process.md +106 -0
  223. package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
  224. package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
  225. package/skills/deco-go-live/references/qa-inventory.md +120 -0
  226. package/skills/deco-go-live/references/react-spa.md +183 -0
  227. package/skills/deco-go-live/references/seo-analytics.md +114 -0
  228. package/skills/deco-go-live/references/traffic-ramp.md +87 -0
  229. package/skills/deco-go-live/references/worker-runtime.md +93 -0
  230. package/skills/deco-go-live/scripts/preflight.sh +221 -0
  231. package/skills/deco-images-media/SKILL.md +64 -0
  232. package/skills/deco-images-media/references/asset-upload.md +191 -0
  233. package/skills/deco-images-media/references/components-per-binding.md +167 -0
  234. package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
  235. package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
  236. package/skills/deco-images-media/references/troubleshooting.md +147 -0
  237. package/skills/deco-images-media/references/video.md +122 -0
  238. package/skills/deco-make-editable/SKILL.md +94 -0
  239. package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
  240. package/skills/deco-make-editable/references/content-shapes.md +198 -0
  241. package/skills/deco-make-editable/references/from-figma.md +110 -0
  242. package/skills/deco-make-editable/references/i18n-fields.md +112 -0
  243. package/skills/deco-make-editable/references/inventory.md +79 -0
  244. package/skills/deco-make-editable/references/pixel-parity.md +175 -0
  245. package/skills/deco-make-editable/references/seeding-content.md +119 -0
  246. package/skills/deco-nextjs-site/SKILL.md +74 -0
  247. package/skills/deco-nextjs-site/references/caching.md +116 -0
  248. package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
  249. package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
  250. package/skills/deco-nextjs-site/references/rendering.md +171 -0
  251. package/skills/deco-nextjs-site/references/setup.md +190 -0
  252. package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
  253. package/skills/deco-site-authoring/SKILL.md +75 -0
  254. package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
  255. package/skills/deco-site-authoring/references/loaders.md +192 -0
  256. package/skills/deco-site-authoring/references/pages.md +156 -0
  257. package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
  258. package/skills/deco-site-authoring/references/sections.md +158 -0
  259. package/skills/deco-site-authoring/references/seo.md +116 -0
  260. package/skills/deco-site-workflow/SKILL.md +92 -0
  261. package/skills/deco-site-workflow/references/check.md +116 -0
  262. package/skills/deco-site-workflow/references/cli-reference.md +104 -0
  263. package/skills/deco-site-workflow/references/content-layout.md +93 -0
  264. package/skills/deco-site-workflow/references/content-sync.md +146 -0
  265. package/skills/deco-site-workflow/references/delivery.md +51 -0
  266. package/skills/deco-site-workflow/references/deploy.md +87 -0
  267. package/skills/deco-site-workflow/references/schema.md +173 -0
  268. package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
  269. package/skills/deco-storefront-caching/SKILL.md +67 -0
  270. package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
  271. package/skills/deco-storefront-caching/references/case-study.md +82 -0
  272. package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
  273. package/skills/deco-storefront-caching/references/nextjs.md +60 -0
  274. package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
  275. package/skills/deco-storefront-caching/references/verification.md +136 -0
  276. package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
  277. package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
  278. package/skills/deco-storefront-performance/SKILL.md +81 -0
  279. package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
  280. package/skills/deco-storefront-performance/references/hydration.md +116 -0
  281. package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
  282. package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
  283. package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
  284. package/skills/deco-storefront-performance/references/render-location.md +152 -0
  285. package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
  286. package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
  287. package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
  288. package/skills/deco-tanstack-site/SKILL.md +68 -0
  289. package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
  290. package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
  291. package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
  292. package/skills/deco-tanstack-site/references/server-functions.md +123 -0
  293. package/skills/deco-tanstack-site/references/setup.md +153 -0
  294. package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
  295. package/skills/deco-v7-to-v8-migration/SKILL.md +122 -0
  296. package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
  297. package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
  298. package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
  299. package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
  300. package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
  301. package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
  302. package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
  303. package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
  304. package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
  305. package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
  306. package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
  307. package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
  308. package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
  309. package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
  310. package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
  311. package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
  312. package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
  313. package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
  314. package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
  315. package/skills/deco-v7-to-v8-migration/references/verify.md +20 -0
  316. package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
  317. package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
  318. package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
  319. package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
  320. package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
  321. package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
  322. package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
  323. package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
  324. package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
  325. package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
  326. package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
  327. package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
  328. package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
  329. package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
  330. package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
  331. package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +176 -0
  332. package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
  333. package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
  334. package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
  335. package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
  336. package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
  337. package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
  338. package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
  339. package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
  340. package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
  341. package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
  342. package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
  343. package/skills/deco-variants/SKILL.md +57 -0
  344. package/skills/deco-variants/references/caching-variants.md +63 -0
  345. package/skills/deco-variants/references/custom-matchers.md +83 -0
  346. package/skills/deco-variants/references/draft-preview.md +59 -0
  347. package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
  348. package/skills/deco-variants/references/multivariate.md +85 -0
  349. package/skills/deco-variants/references/v7-matchers.md +71 -0
  350. package/src/index.ts +2 -0
  351. package/src/protocol/channel.ts +127 -0
  352. package/src/protocol/client.ts +2 -2
  353. package/src/protocol/conformance/blockMetaVectors.json +214 -0
  354. package/src/protocol/conformance/contentHashFixtures.ts +74 -0
  355. package/src/protocol/conformance/index.ts +9 -1
  356. package/src/protocol/conformance/vectors.ts +36 -0
  357. package/src/protocol/index.ts +32 -0
  358. package/src/protocol/keys.ts +1 -1
  359. package/src/v8/background.ts +42 -0
  360. package/src/v8/blockMeta.ts +100 -0
  361. package/src/v8/blockStore.ts +124 -0
  362. package/src/v8/boundedJson.ts +20 -2
  363. package/src/v8/boundedMap.ts +53 -0
  364. package/src/v8/builtins/data.ts +26 -2
  365. package/src/v8/builtins/index.ts +2 -1
  366. package/src/v8/builtins/legacy.ts +6 -3
  367. package/src/v8/canonical.ts +15 -0
  368. package/src/v8/cli/builtins.ts +1 -0
  369. package/src/v8/cli/check/index.ts +97 -7
  370. package/src/v8/cli/content.ts +49 -91
  371. package/src/v8/cli/index.ts +2 -2
  372. package/src/v8/cli/remote/commands.ts +834 -0
  373. package/src/v8/cli/remote/diff.ts +100 -0
  374. package/src/v8/cli/remote/env.ts +107 -0
  375. package/src/v8/cli/remote/http.ts +484 -0
  376. package/src/v8/cli/remote/local.ts +343 -0
  377. package/src/v8/cli/root.ts +40 -0
  378. package/src/v8/cli/run.ts +366 -135
  379. package/src/v8/cli/schema/builtinSchemas.ts +29 -10
  380. package/src/v8/cli/schema/generate.ts +1 -1
  381. package/src/v8/cli/skills.ts +91 -0
  382. package/src/v8/client.ts +162 -60
  383. package/src/v8/cms.ts +62 -53
  384. package/src/v8/content.ts +179 -229
  385. package/src/v8/contentIndex.ts +183 -0
  386. package/src/v8/draft.ts +15 -14
  387. package/src/v8/draftChanges.ts +151 -85
  388. package/src/v8/errors.ts +37 -0
  389. package/src/v8/hostedSource.ts +67 -0
  390. package/src/v8/identity.ts +1 -1
  391. package/src/v8/index.ts +1 -0
  392. package/src/v8/matchRoute.ts +7 -4
  393. package/src/v8/pin.ts +176 -0
  394. package/src/v8/preview/StudioBridge.ts +8 -10
  395. package/src/v8/preview/StudioChannel.ts +116 -0
  396. package/src/v8/preview/index.ts +3 -0
  397. package/src/v8/remoteLoader.ts +350 -286
  398. package/src/v8/resolver.ts +56 -33
  399. package/src/v8/revisionId.ts +14 -0
  400. package/src/v8/settings.ts +10 -9
  401. package/src/v8/telemetry.ts +3 -3
  402. package/src/v8/types.ts +52 -40
  403. package/src/v8/variants.ts +30 -26
  404. package/src/v8/vite/index.ts +3 -3
  405. package/dist/v8/cli/serve/server.d.ts +0 -29
  406. package/dist/v8/cli/serve/server.d.ts.map +0 -1
  407. package/dist/v8/cli/serve/server.js +0 -296
  408. package/dist/v8/cli/serve/server.js.map +0 -1
  409. package/src/v8/cli/serve/server.ts +0 -348
@@ -0,0 +1,240 @@
1
+ /**
2
+ * The VTEX invoke keys v7's VTEX app answered from its own invoke map (PO
3
+ * decision 7, 2026-10-15). v7's `setupApps` registered every named export of
4
+ * the app's loader and action modules under `<module>/<export>`, so
5
+ * `invoke.vtex.actions.checkout.addItemsToCart(props)` reached
6
+ * `addItemsToCart` in `vtex/actions/checkout`, a module with no default
7
+ * export and so no handler file of its own. Each migration chooses what
8
+ * those keys become (`--vtex-invoke`):
9
+ *
10
+ * - `keep`: v7's handler, vendored into `src/vendor` like any app loader, so
11
+ * the call works as it did;
12
+ * - `v8`: no v7 code. A key the v8 VTEX client (`@decocms/apps-vtex`) has an
13
+ * operation for becomes a function over that client in
14
+ * `src/server/vtex-invoke.server.ts`; any other is the
15
+ * `unportedVtexInvoke` stub, which rejects, and a report line.
16
+ *
17
+ * There is no default (PO 2026-10-15: "each migration could choose this"): a
18
+ * site that calls such keys and gave no choice stops before anything is
19
+ * written (`VtexInvokeChoiceNeeded`); a site without them needs no flag.
20
+ */
21
+ import fs from "node:fs";
22
+ import path from "node:path";
23
+ import type { Framework } from "./framework";
24
+ import { locateAppModule, relativeSpecifier } from "./vendor";
25
+
26
+ export type VtexInvokeMode = "keep" | "v8";
27
+ export const VTEX_INVOKE_MODES: readonly VtexInvokeMode[] = ["keep", "v8"];
28
+
29
+ /**
30
+ * The site calls keys of v7's VTEX invoke map and the migration wasn't told
31
+ * what they become. Thrown before anything is written; the message lists the
32
+ * keys and both choices.
33
+ */
34
+ export class VtexInvokeChoiceNeeded extends Error {
35
+ readonly keys: readonly string[];
36
+ constructor(keys: readonly string[]) {
37
+ super(
38
+ [
39
+ `This site calls ${keys.length === 1 ? "1 VTEX key" : `${keys.length} VTEX keys`} that v7's VTEX app answered from its own invoke map:`,
40
+ ...keys.map((key) => ` - ${key}`),
41
+ "",
42
+ "Choose what they become and run the migration again (nothing was changed yet):",
43
+ " --vtex-invoke keep copy v7's handlers into src/vendor, so each call works as it did",
44
+ " --vtex-invoke v8 no v7 code: @decocms/apps-vtex's client where it has the operation",
45
+ " (the cart, simulation, sellers), else a stub that rejects, listed in the report",
46
+ "Either way the report lists every key and what it became (references/server-functions.md).",
47
+ ].join("\n"),
48
+ );
49
+ this.name = "VtexInvokeChoiceNeeded";
50
+ this.keys = keys;
51
+ }
52
+ }
53
+
54
+ /** A key of v7's VTEX invoke map: a named export of one of the app's modules. */
55
+ export interface VtexInvokeMapKey {
56
+ /** The module's v7 key, `vtex/actions/checkout`. */
57
+ moduleKey: string;
58
+ /** The export v7 called, `addItemsToCart`. */
59
+ exportName: string;
60
+ /** The installed module. */
61
+ module: NonNullable<ReturnType<typeof locateAppModule>>;
62
+ }
63
+
64
+ /** The invoke-map entry `key` names, when the installed v7 VTEX app has that module and export. */
65
+ export function vtexInvokeMapKey(root: string, key: string): VtexInvokeMapKey | undefined {
66
+ const match = /^(vtex\/(?:loaders|actions)\/.+)\/([A-Za-z_$][\w$]*)$/.exec(key);
67
+ if (!match) return undefined;
68
+ const [, moduleKey, exportName] = match;
69
+ const module = locateAppModule(root, moduleKey);
70
+ if (!module) return undefined;
71
+ const text = fs.readFileSync(module.file, "utf8");
72
+ const exported = new RegExp(
73
+ `\\bexport\\s+(?:async\\s+)?function\\s*\\*?\\s*${exportName}\\b|\\bexport\\s+(?:const|let)\\s+${exportName}\\b|\\bexport\\s*\\{[^}]*\\b${exportName}\\b[^}]*\\}`,
74
+ );
75
+ return exported.test(text) ? { moduleKey, exportName, module } : undefined;
76
+ }
77
+
78
+ /** One v7 invoke-map key on the v8 VTEX client. */
79
+ interface V8Operation {
80
+ /** The function in the generated module. */
81
+ name: string;
82
+ /** The props v7's handler took (the ones the call uses). */
83
+ props: string;
84
+ /** The call, over `vtex` (the client) and `shopper` (the shopper's cookies). */
85
+ call: string;
86
+ /** Whether VTEX's Set-Cookie values come back (`VtexResponse`) and go to the browser. */
87
+ cookies: boolean;
88
+ /** What differs from v7's handler, for the report. */
89
+ differs: string;
90
+ }
91
+
92
+ const NO_HTTPS = "item images keep VTEX's http: URLs (v7 rewrote them to https:)";
93
+
94
+ /** The v7 VTEX invoke-map keys the v8 client has an operation for. */
95
+ export const V8_VTEX_OPERATIONS: Record<string, V8Operation> = {
96
+ "vtex/actions/checkout/getOrCreateCart": {
97
+ name: "getOrCreateCart",
98
+ props: "{ orderFormId?: string }",
99
+ call: "vtex.checkout.orderForm(shopper)",
100
+ cookies: true,
101
+ differs: `the cart comes from the shopper's checkout.vtex.com cookie (v7 fetched props.orderFormId when given); ${NO_HTTPS}`,
102
+ },
103
+ "vtex/actions/checkout/addItemsToCart": {
104
+ name: "addItemsToCart",
105
+ props:
106
+ "{ orderFormId: string; orderItems: { id: string | number; seller: string; quantity: number }[] }",
107
+ call: "vtex.checkout.addItems(props.orderFormId, props.orderItems.map((item) => ({ ...item, id: Number(item.id) })), shopper)",
108
+ cookies: true,
109
+ differs: `no allowedOutdatedData=paymentData (v7's default), and each SKU id is sent as a number (the v8 client's type; v7 sent it as given); ${NO_HTTPS}`,
110
+ },
111
+ "vtex/actions/checkout/updateCartItems": {
112
+ name: "updateCartItems",
113
+ props: "{ orderFormId: string; orderItems: { index: number; quantity: number }[] }",
114
+ call: "vtex.checkout.updateItems(props.orderFormId, props.orderItems, shopper)",
115
+ cookies: true,
116
+ differs: `no allowedOutdatedData=paymentData and no noSplitItem; ${NO_HTTPS}`,
117
+ },
118
+ "vtex/actions/checkout/addCouponToCart": {
119
+ name: "addCouponToCart",
120
+ props: "{ orderFormId: string; text: string }",
121
+ call: "vtex.checkout.addCoupon(props.orderFormId, props.text, shopper)",
122
+ cookies: true,
123
+ differs: NO_HTTPS,
124
+ },
125
+ "vtex/actions/checkout/updateOrderFormAttachment": {
126
+ name: "updateOrderFormAttachment",
127
+ props:
128
+ "{ orderFormId: string; attachment: string; body: Record<string, unknown>; expectedOrderFormSections?: string[] }",
129
+ call: "vtex.checkout.attachment(props.orderFormId, props.attachment, { ...(props.expectedOrderFormSections ? { expectedOrderFormSections: props.expectedOrderFormSections } : {}), ...props.body }, shopper)",
130
+ cookies: true,
131
+ differs: `expectedOrderFormSections only when the caller passes it (v7 sent its full section list); ${NO_HTTPS}`,
132
+ },
133
+ "vtex/actions/checkout/simulateCart": {
134
+ name: "simulateCart",
135
+ props:
136
+ "{ items: { id: number | string; quantity: number; seller: string }[]; postalCode: string; country?: string }",
137
+ call: 'vtex.checkout.simulation({ items: props.items.map((item) => ({ ...item, id: String(item.id) })), postalCode: props.postalCode, country: props.country ?? "BRA" }, shopper)',
138
+ cookies: false,
139
+ differs:
140
+ "no RnbBehavior=1 (v7's default), and the cookies VTEX sets on a simulation aren't forwarded",
141
+ },
142
+ "vtex/actions/checkout/getSellersByRegion": {
143
+ name: "getSellersByRegion",
144
+ props: "{ postalCode: string; salesChannel?: string }",
145
+ call: 'vtex.checkout.regions({ postalCode: props.postalCode, country: "BRA", salesChannel: props.salesChannel }, shopper).then((regions) => (regions[0]?.sellers?.length ? regions[0] : null))',
146
+ cookies: false,
147
+ differs: "the cookies VTEX sets on the call aren't forwarded",
148
+ },
149
+ };
150
+
151
+ /** Where the generated functions go. */
152
+ export const V8_VTEX_FILE = path.join("src", "server", "vtex-invoke.server.ts");
153
+
154
+ /**
155
+ * The v8 operation for `key` on `framework`, or the reason there is none.
156
+ * Next.js server actions set cookies only through `cookies()`, which
157
+ * percent-encodes the value (`checkout.vtex.com=__ofid=…` would reach VTEX as
158
+ * `__ofid%3D…`), so a cart call that returns VTEX's cookies isn't mapped there.
159
+ */
160
+ export function v8Operation(
161
+ key: string,
162
+ framework: Framework,
163
+ ): { operation: V8Operation } | { reason: string } {
164
+ const operation = V8_VTEX_OPERATIONS[key];
165
+ if (!operation) {
166
+ return {
167
+ reason:
168
+ "@decocms/apps-vtex's client has no operation for it (its checkout, sessions, masterdata and io.graphql cover the rest by hand)",
169
+ };
170
+ }
171
+ if (framework === "nextjs" && operation.cookies) {
172
+ return {
173
+ reason: `the v8 call (${operation.call.replace(/,? shopper\)/, ")")}) returns VTEX's Set-Cookie values, and a Next.js server action can only set cookies through cookies(), which percent-encodes them (checkout.vtex.com's __ofid=… would reach VTEX as __ofid%3D…): call it from a route handler that appends its setCookies to the Response`,
174
+ };
175
+ }
176
+ return { operation };
177
+ }
178
+
179
+ /** `src/server/vtex-invoke.server.ts`: the mapped keys over the site's VTEX client. */
180
+ export function writeV8Module(
181
+ root: string,
182
+ framework: Framework,
183
+ keys: string[],
184
+ ): { file: string; clientFile: string | undefined } {
185
+ const file = path.join(root, V8_VTEX_FILE);
186
+ const clientFile = ["vtex.ts", "vtex.tsx"]
187
+ .map((f) => path.join(root, "src", "clients", f))
188
+ .find((f) => fs.existsSync(f));
189
+ const operations = keys.map((key) => [key, V8_VTEX_OPERATIONS[key]] as const);
190
+ const usesCookies = operations.some(([, op]) => op.cookies);
191
+ const lines = [
192
+ "/**",
193
+ " * v7's VTEX invoke calls on the v8 VTEX client (@decocms/apps-vtex), migrated with --vtex-invoke v8:",
194
+ " * no v7 code. Each takes (props, request) as v7's handler did, and is called by its server function.",
195
+ " * Generated by the deco-v7-to-v8-migration skill; it's your code now.",
196
+ " */",
197
+ ...(usesCookies && framework === "tanstack"
198
+ ? ['import { getResponseHeaders } from "@tanstack/react-start/server";']
199
+ : []),
200
+ ...(usesCookies ? ['import type { VtexResponse } from "@decocms/apps-vtex";'] : []),
201
+ `import { vtexClient } from "${relativeSpecifier(file, clientFile ?? path.join(root, "src", "clients", "vtex.ts"))}";`,
202
+ "",
203
+ "/** The shopper's cookies, sent to VTEX (the client drops malformed pairs). */",
204
+ 'const shopperOf = (request: Request) => ({ cookie: request.headers.get("cookie") ?? undefined });',
205
+ ];
206
+ if (usesCookies) {
207
+ lines.push(
208
+ "",
209
+ "/**",
210
+ " * VTEX's Set-Cookie values, sent to the browser as v7's VTEX app sent them: Intelligent Search's",
211
+ " * session cookies stay on the server, and each cookie's Domain is this site's host.",
212
+ " */",
213
+ "async function forward<T>(response: Promise<VtexResponse<T>>, request: Request): Promise<T> {",
214
+ " const { data, setCookies } = await response;",
215
+ " const host = new URL(request.url).hostname;",
216
+ " const headers = getResponseHeaders();",
217
+ " for (const cookie of setCookies) {",
218
+ ' if (cookie.startsWith("vtex_is_session=") || cookie.startsWith("vtex_is_anonymous=")) continue;',
219
+ // biome-ignore lint/suspicious/noTemplateCurlyInString: generated source with a template literal
220
+ ' headers.append("set-cookie", cookie.replace(/(;\\s*)domain=[^;]*/i, `$1Domain=${host}`));',
221
+ " }",
222
+ " return data;",
223
+ "}",
224
+ );
225
+ }
226
+ for (const [key, op] of operations) {
227
+ lines.push(
228
+ "",
229
+ `/** ${key}. Differs from v7's: ${op.differs}. */`,
230
+ `export async function ${op.name}(props: ${op.props}, request: Request) {`,
231
+ " const vtex = vtexClient();",
232
+ " const shopper = shopperOf(request);",
233
+ op.cookies ? ` return forward(${op.call}, request);` : ` return ${op.call};`,
234
+ "}",
235
+ );
236
+ }
237
+ fs.mkdirSync(path.dirname(file), { recursive: true });
238
+ fs.writeFileSync(file, `${lines.join("\n")}\n`);
239
+ return { file, clientFile };
240
+ }
@@ -0,0 +1,30 @@
1
+ /** Saved-block helpers shared by the steps. */
2
+
3
+ import path from "node:path";
4
+ import { readSavedBlocks, type SavedBlocks } from "@decocms/blocks/cli";
5
+
6
+ export type JsonObject = Record<string, unknown>;
7
+
8
+ export function isPlainObject(value: unknown): value is JsonObject {
9
+ return typeof value === "object" && value !== null && !Array.isArray(value);
10
+ }
11
+
12
+ /** Calls `visit` on every object inside `value` that has a string `__resolveType`, outermost first. */
13
+ export function forEachBlock(
14
+ value: unknown,
15
+ visit: (block: JsonObject & { __resolveType: string }) => void,
16
+ ): void {
17
+ if (Array.isArray(value)) {
18
+ for (const item of value) forEachBlock(item, visit);
19
+ return;
20
+ }
21
+ if (!isPlainObject(value)) return;
22
+ if (typeof value.__resolveType === "string")
23
+ visit(value as JsonObject & { __resolveType: string });
24
+ for (const child of Object.values(value)) forEachBlock(child, visit);
25
+ }
26
+
27
+ /** The site's saved blocks, read by the same rule `deco content` uses. */
28
+ export function readContent(root: string): SavedBlocks {
29
+ return readSavedBlocks(path.join(root, ".deco", "blocks"));
30
+ }
@@ -0,0 +1,57 @@
1
+ ---
2
+ name: deco-variants
3
+ description: "Variants on @decocms/blocks 8: the built-in multivariate block ({ rule, value } with lazy values, first true rule wins, later rules never run), the built-in rules always, never, experiment and campaign, A/B tests as the saved block experiments (split-traffic: a percentage per test, a sticky visitor id in the deco_segment cookie, @decocms/blocks/experiments) and scheduled content as the saved block campaigns (calendar), v7's matchers from @decocms/compat-v7/matchers (device, cookie, host, pathname, queryString, location, multi, sticky random), custom rules in the block map, previewing a variant, a test or a moment from a Studio draft link (__variant, __test, __campaign, __at), and keeping variant pages cacheable (assignmentsKey, one cache entry per set of assignments). Load it for A/B tests, scheduled or segmented content, a variant that never shows or always shows, matcher bugs after a v7 migration, or a variant page that misses the cache."
4
+ ---
5
+
6
+ # Variants on @decocms/blocks 8
7
+
8
+ A variant is a value picked per request by a rule. In v8 that is the built-in block `multivariate`: a list of `{ rule, value }`, where the first rule that resolves to `true` wins and its value is the result. Rules are block functions that return a boolean. Four are built in (`always`, `never`, `experiment`, `campaign`). A site adds more in its block map, or registers v7's from `@decocms/compat-v7/matchers`.
9
+
10
+ A/B tests and campaign dates are content, not code. The saved block `experiments` (type `split-traffic`) holds each test's percentage. The saved block `campaigns` (type `calendar`) holds each campaign's window. The binding decides both once per request at the edge, and the page cache keys on what it decided.
11
+
12
+ Code is in `packages/blocks/src/v8/builtins/` (`multivariate.ts`, `matchers.ts`, `experiments.ts`, `campaigns.ts`, `legacy.ts`), `packages/blocks/src/v8/experiments.ts` (the `@decocms/blocks/experiments` export), `packages/blocks/src/v8/variants.ts` and `draft.ts` (previews), and `packages/compat-v7/src/matchers/`.
13
+
14
+ ## When to load what
15
+
16
+ | Reference | Load it when |
17
+ |---|---|
18
+ | [`references/multivariate.md`](./references/multivariate.md) | Writing or reading variant JSON; a variant never shows, always shows, or a slot is empty; `deco check` says "a variant's value must be a lazy block"; v7 `website/flags/multivariate*.ts` content |
19
+ | [`references/experiments-and-campaigns.md`](./references/experiments-and-campaigns.md) | Setting up an A/B test or a scheduled promotion; ramping a test; a campaign that never starts; `deco check` says "no test" or "no campaign"; tagging analytics with the test arm |
20
+ | [`references/v7-matchers.md`](./references/v7-matchers.md) | Content migrated from v7 uses `website/matchers/device.ts`, `cookie.ts`, `location.ts`, `random.ts` and others; `UNKNOWN_BLOCK` on a v7 matcher; wiring `matcherContext` and the `deco_segment` cookie |
21
+ | [`references/custom-matchers.md`](./references/custom-matchers.md) | Writing a site's own rule; a rule that needs the request, the visitor or the date; a rule that does not appear in Studio's rule picker |
22
+ | [`references/draft-preview.md`](./references/draft-preview.md) | Previewing one variant, a test switched on, or a future date from a Studio link; a preview link that shows the saved content instead |
23
+ | [`references/caching-variants.md`](./references/caching-variants.md) | A page with variants misses the cache or shows the wrong variant from cache; deciding whether a rule is safe behind a page cache; purging variant pages |
24
+
25
+ ## The model in one example
26
+
27
+ ```json
28
+ {
29
+ "__resolveType": "multivariate",
30
+ "variants": [
31
+ { "rule": { "__resolveType": "experiment", "name": "promo-copy" },
32
+ "value": { "__resolveType": "lazy", "value": { "__resolveType": "promo-banner", "title": "Free shipping on every order" } } },
33
+ { "rule": { "__resolveType": "always" },
34
+ "value": { "__resolveType": "lazy", "value": { "__resolveType": "promo-banner", "title": "Free shipping over $50" } } }
35
+ ]
36
+ }
37
+ ```
38
+
39
+ With the saved block `experiments` set to `{ "__resolveType": "split-traffic", "promo-copy": 50 }`, half the visitors see the first banner. Each visitor keeps their side across visits.
40
+
41
+ ## Rules of thumb
42
+
43
+ - Order is the logic. Put narrow rules first and `always` last. With no `always`, a visitor that matches no rule gets `undefined` for that slot.
44
+ - Prefer `experiment` and `campaign` over request-reading rules. The binding decides them once at the edge and the page cache keys on them. A rule that reads a cookie, a header or the location changes the page by something the cache key does not hold (see [`caching-variants.md`](./references/caching-variants.md)).
45
+ - Keep a test's name stable. A visitor's side is a hash of the test name and their id, so renaming a test re-draws everyone.
46
+ - Run one A/B system per site. The saved block `experiments` and v7's sticky `random` both write `deco_segment`.
47
+
48
+ ## Reading results
49
+
50
+ v8 decides who is in a test. It does not count conversions. Send the arm with your analytics events (see [`experiments-and-campaigns.md`](./references/experiments-and-campaigns.md#reading-the-results)), then use the `ab-testing` skill in decocms/skills for sample size, significance and sample-ratio checks.
51
+
52
+ ## Related skills
53
+
54
+ - `deco-v7-to-v8-migration`: registers v7's matchers in the block map, renames legacy flag types, and reports random tests and date rules to move by hand into `experiments` and `campaigns`.
55
+ - `deco-storefront-caching`: the site's `pageCache` and its key in full.
56
+ - `deco-tanstack-site` and `deco-nextjs-site`: where the worker or proxy that decides assignments is wired.
57
+ - `deco-cms-schema`: how a rule's props become its Studio form.
@@ -0,0 +1,63 @@
1
+ # Keeping variant pages cacheable
2
+
3
+ A page with variants can be cached when its cache key holds everything its rules read. v8 is built so that the two content rules, `experiment` and `campaign`, are always in the key. Other rules are the site's job.
4
+
5
+ This page covers the variant side of caching. The `deco-storefront-caching` skill covers the site's `pageCache` in full.
6
+
7
+ ## What the binding decides
8
+
9
+ On every page and server-function request, before any cache lookup, the binding:
10
+
11
+ 1. reads the visitor (`readVisitor`: the `deco_segment` cookie, or a new visitor with a fresh id);
12
+ 2. decides every test of `experiments` and every campaign of `campaigns` for that visitor and that moment;
13
+ 3. hands those **assignments** to the cache and to the page, which renders exactly them and decides nothing again.
14
+
15
+ **TanStack** (`createDecoWorker` in `@decocms/tanstack/worker`): the site's `pageCache(page)` gets `page.assignments`. Put `assignmentsKey(page.assignments)` in the key. It is `x=<tests on>|c=<campaigns running>` with names sorted, and `""` when none are on, so visitors on the same side of every test share one entry. The visitor's id is never in it. The visitor's first-visit cookie is added after `pageCache` answers, so a stored copy never carries one visitor's cookie, and a new visitor served from the cache still gets theirs.
16
+
17
+ **Next.js** (`@decocms/nextjs/proxy`): `rewriteToAssignmentsRoute` rewrites a CMS page to `/_assignments/<assignments>/<path>`. That route renders with `assignedClient(cms, segment)` from `@decocms/nextjs/server`, reads no request, and is cached by ISR once per path and set of assignments. When the content has tests or campaigns, the response to the visitor's own URL is marked `Cache-Control: private, no-cache`, so a CDN in front does not share it by URL alone. A test at 0% stays off on that route even if the segment says on. Answer a direct request to `/_assignments/…` with a 404 (`isAssignmentsRoutePath`).
18
+
19
+ ## Costs to plan for
20
+
21
+ - **Each running test doubles the entries per page.** With `n` tests the key can take `2^n` values. `liveAssignmentKeys(cms)` lists them all (with the running campaigns and with none). Hit rate falls with every test left running: remove finished tests from `experiments`.
22
+ - **A campaign starting or ending moves every page to new entries.** Expect a cold cache at that moment.
23
+ - **A test at 0% costs nothing**: nobody is in it, so it never adds a key value in live traffic.
24
+
25
+ ## The cold-visitor problem is gone for `experiment`
26
+
27
+ On v7, a cached page decided the variant for every new visitor who hit it until the entry expired. All cold visitors in that window saw the same arm, and a busy page could show one arm to hundreds of visitors in a row.
28
+
29
+ v8's `experiment` rule does not have this problem. Each new visitor gets an id and a roll at the edge before the cache lookup, and the lookup uses their assignments. Two new visitors on different sides read different entries.
30
+
31
+ v7's sticky `random` from `@decocms/compat-v7` still decides during render. A response that sets `deco_segment` must never be stored, so a visitor's first page of a random test is always rendered fresh. Then `cohortSegment(request)` puts their group in the key. Moving the test into `experiments` removes both costs.
32
+
33
+ ## Rule by rule
34
+
35
+ | Rule | In the key? | What to do |
36
+ |---|---|---|
37
+ | `always`, `never` | Not needed | Same result for everyone |
38
+ | `experiment`, `campaign` | Yes, through `assignmentsKey` | Nothing |
39
+ | `device` (compat) | Only if your key has the device | The worker-entry example keys on `detectDevice`; keep it |
40
+ | `pathname` (compat) | The path is in the key | Nothing |
41
+ | `queryString` (compat) | Depends on your key | The example drops tracking parameters (`utm_*` and the like) from the key, so a rule on them shows one visitor's variant to another |
42
+ | `host` (compat) | Depends on your key | The example keys on the full URL, host included. Safe only when your key does too |
43
+ | `cookie`, `location` (compat) | No | Add the value to the key, skip caching for those pages, or personalize in the browser |
44
+ | `random` (compat) | Through `cohortSegment` | See above; prefer `experiments` |
45
+ | A custom rule that reads the request | No | Same as `cookie` |
46
+ | A custom rule on `currentClient().date` | No | The page keeps the variant of the moment it was cached until it expires. Use a campaign instead |
47
+
48
+ ## Three ways out for a request-reading rule
49
+
50
+ 1. **Put it in the key.** Add the value to your segment (on TanStack, the segment parts your worker entry builds; the example's `buildSegment` has a region and a sales channel). Keep the number of values small: each one multiplies the entries.
51
+ 2. **Do not cache those pages.** Return without storing for requests the rule cares about. Fine for low-traffic pages; expensive on the home page.
52
+ 3. **Personalize in the browser.** Render a neutral page that caches for everyone, then pick the variant in a client component (a location banner, a returning-visitor message). The first paint cannot show the variant, so keep it below the fold or make the swap small.
53
+
54
+ Signed-in, cart and account content belongs in option 3 or uncached. Never put a shopper's identity in a shared key.
55
+
56
+ ## Checklist: a variant page misses the cache or shows the wrong arm
57
+
58
+ 1. **Is it a preview?** A `?__draft=` link or the draft cookie never reaches `pageCache` (see [`draft-preview.md`](./draft-preview.md)).
59
+ 2. **Does the response set a cookie?** The worker-entry example never stores a response that sets one (other than `_deco_bucket`). The worker adds the visitor's own cookie after `pageCache`, so that one does not count. v7's `deco_segment` writer from compat does count.
60
+ 3. **Does a rule read the request?** List the rules on the page (follow saved rule blocks too) and check each against the table above.
61
+ 4. **How many tests are running?** `2^n` entries per page split the hits.
62
+ 5. **Is the wrong arm stable for one URL?** A rule reads something that is not in the key. Compare the same URL with two different values of the suspect cookie or header.
63
+ 6. **Old arm after a change to a test?** Publishing a release changes the content revision in `cacheVersion`, so pages move to new entries on their own. If an old arm persists, check that your key carries `cacheVersion(cms, buildHash, page.url)`. The example's purge (`POST /_cache/purge`) drops a path under every assignments key when you need it sooner.
@@ -0,0 +1,83 @@
1
+ # Custom rules
2
+
3
+ A rule is a block function that returns a boolean. A site adds one by adding a key to its block map (the default export of `.deco/index.ts`). There is no matcher kind to declare and no flag to set.
4
+
5
+ ## The smallest rule
6
+
7
+ ```ts
8
+ // .deco/index.ts
9
+ import { type Blocks, currentClient } from "@decocms/blocks";
10
+
11
+ interface WeekdayProps {
12
+ /** @title Days (0 = Sunday) */
13
+ days?: number[];
14
+ }
15
+
16
+ /**
17
+ * @title Weekday
18
+ * @description True on the days listed, in UTC.
19
+ */
20
+ const weekday = ({ days = [] }: WeekdayProps): boolean =>
21
+ days.includes(currentClient().date.getUTCDay());
22
+
23
+ export default {
24
+ weekday,
25
+ // …sections and loaders
26
+ } satisfies Blocks;
27
+ ```
28
+
29
+ Content uses it like any rule: `{ "__resolveType": "weekday", "days": [0, 6] }`.
30
+
31
+ ## How Studio finds it
32
+
33
+ `deco schema` reads each block function's props type and its awaited return type. A function whose return type is `boolean` (or a promise of one) goes in the `matchers` group, and the `rule` field of every variant offers that group. So:
34
+
35
+ - Declare the return type. A function typed as returning `any` gets the warning "returns any, so it isn't offered for any field".
36
+ - The props type becomes the rule's form. The JSDoc on the function and its props sets titles and descriptions. The `deco-cms-schema` skill covers the tags and the shapes that break a form.
37
+ - Run `deco schema` after adding a rule. The picker offers only what the generated schema lists.
38
+
39
+ ## What a rule can read
40
+
41
+ A v8 block function gets only its inputs. Everything else comes from one of these:
42
+
43
+ - **The client**, through `currentClient()` from `@decocms/blocks`: `client.visitor` (the visitor, or `null`), `client.date` (the moment campaigns run at), `client.version`, and `client.resolve(name)` to read another saved block. Call `currentClient()` at the start of the function, before any `await`: on runtimes without `AsyncLocalStorage` it is only set while the function runs synchronously.
44
+ - **The request**, through the framework, the way `@decocms/compat-v7`'s `matcherContext` does it: TanStack Start's `getRequest()` from `@tanstack/react-start/server`, or Next's `headers()` from `next/headers`. On a TanStack client-side navigation the request is the server-function call, not the page, so its URL is not the page's.
45
+ - **Props** saved in the content.
46
+
47
+ Prefer props and the client over the request. A rule that reads the request (a cookie, a header, the location, the query) makes the page depend on something the binding's assignments do not hold, so a page cache keyed on them can serve one visitor's variant to another. Read [`caching-variants.md`](./caching-variants.md) before shipping one.
48
+
49
+ ## Errors
50
+
51
+ A rule that throws fails its block with `BLOCK_FAILED`, and the page with it. v7 treated a throwing matcher as "no match", and so do the compat matchers. If that is what you want, catch inside the rule and return `false`.
52
+
53
+ ```ts
54
+ import { getRequest } from "@tanstack/react-start/server";
55
+
56
+ const hasPromoCookie = (): boolean => {
57
+ try {
58
+ return (getRequest().headers.get("cookie") ?? "").includes("promo=1");
59
+ } catch {
60
+ return false;
61
+ }
62
+ };
63
+ ```
64
+
65
+ ## Naming
66
+
67
+ - The key in the block map is the type the content writes. Keys in the block map win over built-ins, so a key named `campaign` or `experiment` replaces the built-in rule (and `deco check` stops checking its names). Pick a new name unless that is the intent.
68
+ - To keep v7 content working, register the rule under v7's type name (for example `website/matchers/environment.ts`, which `@decocms/compat-v7` leaves to the site because it read the process environment).
69
+ - Saved blocks cannot take a built-in name (`deco check`: "has the name of a built-in block").
70
+
71
+ ## Rules with several parts
72
+
73
+ Combine rules without writing code:
74
+
75
+ - Order the variants: the first true rule wins, so "A and not B" is a `B → fallback` variant above an `A → value` variant.
76
+ - `multi` from `@decocms/compat-v7/matchers` gives `and` and `or` over inner rules (see [`v7-matchers.md`](./v7-matchers.md)).
77
+
78
+ v8 has no `negate` matcher. Reordering the variants usually covers it: put the case to exclude first, with the fallback value.
79
+
80
+ ## Not needed in v8
81
+
82
+ - v7's `export const cacheable = true` on a matcher, and the framework's cache-decision gates. v8 has no such flag: the binding decides what the cache keys on (see [`caching-variants.md`](./caching-variants.md)).
83
+ - A "flag" file per value type. `multivariate` takes any value.
@@ -0,0 +1,59 @@
1
+ # Previewing a variant, a test or a moment
2
+
3
+ An editor wants to see variant B before it is live, a test that sits at 0%, or the Black Friday page a week early. A Studio preview link carries all three. Code: `packages/blocks/src/v8/draft.ts` (parsing) and `packages/blocks/src/v8/variants.ts` (forcing a variant).
4
+
5
+ You rarely build these links by hand: Studio writes them. This page is for reading one, debugging one that shows the saved content instead, or building one in a tool.
6
+
7
+ ## What a link carries
8
+
9
+ A preview link is `?__draft=<value>`. The value is a version plus preview parameters:
10
+
11
+ - **The version**: a draft pointer, `<host[:port]><path[?query]>@<version>`, or a published release's revision id.
12
+ - **Forced variants**, inside a draft pointer's query: `__variant=<block>@<path>=<index>`, one per multivariate.
13
+ - **The moment**: `__at=<ISO date-time with offset>`, which becomes the client's `date` (campaigns are checked at it).
14
+ - **Tests**: `__test=<name>=on|off`, which becomes the client's `experiments`.
15
+ - **Campaigns**: `__campaign=<name>=on|off`, which becomes the client's `campaigns`.
16
+
17
+ Each parameter value is URL-encoded as a whole. The last `__test` or `__campaign` for a name wins. After a revision id, only `__at`, `__test` and `__campaign` are allowed: `<id>?__at=…&__test=…`. Forced variants need a draft pointer.
18
+
19
+ The binding reads the link with `cms.readVersion(request)`. It answers `{ version, date?, experiments?, campaigns? }`, shaped to spread into `cms.client()`, and `null` for a value that does not parse. `parseVersion(value)` from `@decocms/blocks` parses a raw value the same way, with no host check. Only `cms.readVersion` checks the request's host against the preview hosts, so a visitor on the live site never picks a version or switches a test. Build on `cms.readVersion`, not on `parseVersion`, when the value comes from a request.
20
+
21
+ ## Forcing a variant
22
+
23
+ `__variant=<block>@<path>=<index>` addresses one multivariate:
24
+
25
+ - `block` is the saved block's name (`Home Page`, `Header`).
26
+ - `path` is the dot-separated keys and list indexes to the multivariate inside that block's saved JSON, or empty for the saved block itself. It walks the JSON as saved, including a `lazy` block's `value`.
27
+ - `index` is the variant to show, counted from 0.
28
+
29
+ | Address | Forces |
30
+ |---|---|
31
+ | `Home Page@sections.3=1` | The second variant of the multivariate at `sections[3]` of `Home Page` |
32
+ | `Header@=0` | The first variant of the saved block `Header`, itself a multivariate |
33
+ | `Home@sections.0.variants.1.value.value.title=0` | The first variant of the `title` multivariate of the section held by variant 1 of the multivariate at `sections[0]` (through that variant's `lazy` wrapper) |
34
+
35
+ The addressed multivariate keeps only that variant, with its rule set to `true`. No other rule in it runs. The body is copied along the addressed path only; the shared content is never touched. Legacy multivariate type names count too.
36
+
37
+ `formatDraftPointer({ host, path, version, variants })` builds a pointer with its `__variant` parameters, and `parseDraftPointer(value)` reads one back: `variants` lists `{ block, path, index }`. Both are exported from `@decocms/blocks`. `formatDraftPointer` throws on parts that would not parse back.
38
+
39
+ ## A preview that shows the saved content
40
+
41
+ An address that does not reach a multivariate with that variant is ignored, so a stale link renders the content as saved instead of failing. Check, in order:
42
+
43
+ 1. **The block was renamed** or the section moved: the `block` or `path` no longer points at a multivariate.
44
+ 2. **The index is past the end** of `variants`.
45
+ 3. **The path skips the `lazy` wrapper**: a multivariate inside a variant's value is under `value.value`, not `value`.
46
+ 4. **The value does not parse**: `parseDraftPointer` returns `null` for a stray `@`, an empty path segment (`a..b`), an index with more than four digits, or a preview parameter (`__at`, `__test`, `__campaign`) left inside the pointer. `parseVersion` lifts those out first.
47
+ 5. **The host is not a preview host**: the link renders the release. Preview hosts come from the release metadata Studio writes, plus `createCMS({ preview: { hosts } })`.
48
+
49
+ ## Previewing tests and campaigns
50
+
51
+ - `__test=<name>=on` shows the test's variants even at 0%, so a test can be checked before any visitor sees it. A name the saved block `experiments` does not have stays out.
52
+ - `__campaign=<name>=on` shows a campaign outside its window. `__at` moves the clock instead, so every campaign is checked at that moment.
53
+ - A bound in `__at` follows the same format as a campaign bound: an ISO 8601 date-time with an offset.
54
+
55
+ ## What a preview never does
56
+
57
+ - It never reaches the page cache. Any request with a draft signal answers `Cache-Control: max-age=0, no-cache, must-revalidate`, `Vary: Cookie` and `noindex`.
58
+ - It never sends the visitor cookie. Studio is not a visitor.
59
+ - It does not change who is in a test for real visitors. Forcing is per request.
@@ -0,0 +1,104 @@
1
+ # A/B tests and campaigns
2
+
3
+ Two kinds of rule are content in v8, each read from one saved block:
4
+
5
+ | Rule | Saved block | Its type | What it holds |
6
+ |---|---|---|---|
7
+ | `experiment { name }` | `experiments` | `split-traffic` | Each test's name and the whole percentage of visitors in it (0 to 100) |
8
+ | `campaign { name }` | `campaigns` | `calendar` | Each campaign's name and one window, `{ start?, end? }` |
9
+
10
+ Code: `packages/blocks/src/v8/builtins/experiments.ts`, `builtins/campaigns.ts`, and `packages/blocks/src/v8/experiments.ts` (exported as `@decocms/blocks/experiments`).
11
+
12
+ ## A/B tests
13
+
14
+ In `.deco/blocks/experiments.json`:
15
+
16
+ ```json
17
+ { "__resolveType": "split-traffic", "promo-copy": 30, "new-header": 0 }
18
+ ```
19
+
20
+ ```json
21
+ { "rule": { "__resolveType": "experiment", "name": "promo-copy" },
22
+ "value": { "__resolveType": "lazy", "value": "…variant B…" } }
23
+ ```
24
+
25
+ Put the control last, under `always`.
26
+
27
+ ### How a visitor is assigned
28
+
29
+ - A visitor has an id: 16 random bytes as 22 base64url characters, stored in the `deco_segment` cookie for a year. The cookie is not `HttpOnly`, so an analytics script can read it.
30
+ - For each test, the visitor's roll is a hash of `<test name>:<id>` (MurmurHash3, in `bucketing.ts`), a fixed number from 0 to 99.99. The visitor is in the test when the roll is below the percentage.
31
+ - Nothing per test is stored. One id serves every test, a new test needs no new state, and two tests are independent of each other.
32
+ - The decision is the same on a server, in a browser and in an app: `assign(experiments, visitor)` is a pure function.
33
+
34
+ What follows from that:
35
+
36
+ - **Ramping only adds people.** Moving 10 to 30 keeps everyone who was in and adds more. The roll does not move, the threshold does.
37
+ - **Renaming a test re-draws everyone.** The name is part of the hash.
38
+ - **0 is off, 100 is everyone.** A fractional percentage is rounded. An entry that is not a finite number is left out.
39
+ - **No visitor, no test.** A client created without a visitor has every test off, unless the test is given to it.
40
+
41
+ ### Who reads the visitor
42
+
43
+ The binding does it, once per request. On `@decocms/tanstack`, `createDecoWorker` calls `readVisitor(request)` (the cookie, or a new visitor), decides every test and campaign, and hands both to the app on the `x-deco-visitor` and `x-deco-assignments` headers. It removes any copy of those headers sent from outside. `contentClient(cms)` from `@decocms/tanstack/server` builds the client from them, so the page decides nothing again. On `@decocms/nextjs`, the proxy does the same with `decideVisitor` and `rewriteToAssignmentsRoute` (or `decideAssignments`) from `@decocms/nextjs/proxy`. The cookie goes out only on a first visit, and never from a preview.
44
+
45
+ Code outside a binding (a mobile app, a script) uses the exports of `@decocms/blocks/experiments`: `readVisitor`, `parseVisitor`, `serializeVisitor`, `newVisitor` and `assign`, then passes the visitor to `cms.client({ visitor })`.
46
+
47
+ ### Forcing a test
48
+
49
+ `cms.client({ experiments: { "promo-copy": true } })` turns a test on (or off with `false`) whatever the visitor and the percentage. A name the saved block does not have stays out. Studio's preview link does this with `__test=<name>=on|off` (see [`draft-preview.md`](./draft-preview.md)).
50
+
51
+ This gives a safe launch path:
52
+
53
+ 1. Add the test at `0` and the variant behind `experiment { name }`.
54
+ 2. Preview it with the test switched on.
55
+ 3. Publish, then raise the percentage.
56
+
57
+ ### Visitors from v7
58
+
59
+ The cookie keeps v7's name and format. A v7 visitor gets an id on their next visit, and v7's stored decisions are honoured while the percentage they were made at holds. After it moves, a v7 visitor in a test that grows stays in, and one out of a test that shrinks stays out. To keep a v7 random test's groups, move it into `experiments` under the same name (the `deco-v7-to-v8-migration` skill reports each one). Do not also register v7's `random` matcher: two writers of `deco_segment` undo each other.
60
+
61
+ ## Campaigns
62
+
63
+ In `.deco/blocks/campaigns.json`:
64
+
65
+ ```json
66
+ {
67
+ "__resolveType": "calendar",
68
+ "black-friday": { "start": "2026-11-27T00:00:00-03:00", "end": "2026-11-30T00:00:00-03:00" }
69
+ }
70
+ ```
71
+
72
+ ```json
73
+ { "rule": { "__resolveType": "campaign", "name": "black-friday" }, "value": { "__resolveType": "lazy", "value": "…" } }
74
+ ```
75
+
76
+ - A window runs from `start` (inclusive) to `end` (exclusive). An empty or missing bound is open.
77
+ - A bound must be an ISO 8601 date-time with an offset (`Z` or `±hh:mm`). A date alone, a date-time without an offset, a day the calendar does not have or a free-text date reads as "never". `deco check` reports such a bound as an error and suggests a fix. Write the store's own offset.
78
+ - The moment checked is the client's `date`: `cms.client({ date })`, or when the client was created. A preview can set it with `__at` (see [`draft-preview.md`](./draft-preview.md)).
79
+ - `cms.client({ campaigns: { "black-friday": true } })` forces a campaign on or off, like a test.
80
+ - There are no inline dates on a rule. A `campaign` rule always names a campaign, so all date logic lives in one block. v7's date matcher has no alias: the migration renames it to `date`, and `deco check` reports every `date` rule with how to move it into `campaigns`.
81
+
82
+ ### Recurring schedules
83
+
84
+ v7's cron matcher has no v8 counterpart. Write each occurrence as its own window, or write a custom rule that reads `currentClient().date` (see [`custom-matchers.md`](./custom-matchers.md)). A custom date rule is not part of the assignments the cache keys on, so read [`caching-variants.md`](./caching-variants.md) first.
85
+
86
+ ## `deco check` messages
87
+
88
+ | Message | Fix |
89
+ |---|---|
90
+ | `no test "<name>" in the saved block "experiments": this rule is always false` | Add the test to `experiments`, or fix the name |
91
+ | `no campaign "<name>" in the saved block "campaigns": this rule is always false` | Add the campaign, or fix the name |
92
+ | `this campaign rule names no campaign, so it is always false` | Set `name` |
93
+ | `the campaign "<name>" starts at "…"` (or `ends at`), followed by `a date without a time or offset`, `which has no offset` or `which isn't written as a campaign reads it`, then `so it never runs` | Write the bound as the message suggests: date, `T`, time and offset |
94
+ | `unknown block type "date"` | Move the rule to `campaign` as the message says |
95
+
96
+ ## Reading the results
97
+
98
+ v8 decides who sees what. It does not record conversions, and its analytics module does not add the test arm to events. Send the arm yourself:
99
+
100
+ - On TanStack, `requestAssignments()` from `@decocms/tanstack/server` returns each test on or off for the request, as the worker decided it. Pass the arms the page rendered to your analytics events.
101
+ - On any binding, the page's own client gives the same answer: `const [tests] = await client.resolve("experiments")` gives each test's name and `true` or `false`, never a percentage.
102
+ - In the browser, the `deco_segment` cookie holds the visitor; `parseVisitor` and `assign` from `@decocms/blocks/experiments` give the same answer as the server for a given `experiments` block.
103
+
104
+ Count users, not sessions: the id is per visitor. Then use the `ab-testing` skill in decocms/skills to plan the sample size, check the sample ratio and read significance.