@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,175 @@
1
+ # Proving nothing changed
2
+
3
+ Every conversion PR is checked three ways before merge: the HTML, the pixels,
4
+ and a live edit. A PR built from a Figma file is compared with the design
5
+ instead of with `main`.
6
+
7
+ ## Two servers side by side
8
+
9
+ Run `main` and the branch at once. A separate worktree keeps `main` untouched:
10
+
11
+ ```sh
12
+ git worktree add ../site-main origin/main
13
+ (cd ../site-main && bun install --frozen-lockfile && npx vite dev --port 5192) &
14
+ npx vite dev --port 5191 &
15
+ ```
16
+
17
+ On a hosted site the branch reads its new blocks from a draft (see
18
+ [seeding-content.md](./seeding-content.md#a-hosted-site-site-set)). Add the
19
+ `__draft` value from `deco drafts url <name>` to every branch URL
20
+ (`?__draft=…`). Three things to know about draft pages on a site whose
21
+ document is `DecoDocument` (`@decocms/tanstack/react`):
22
+
23
+ - Once hydrated, a draft page shows a badge, fixed at the bottom left
24
+ (`[data-deco-preview-badge]`). Hide it before taking screenshots.
25
+ - If the link names a draft that cannot be read (deleted, or its host
26
+ failing), the page renders the release and shows a notice
27
+ (`[data-deco-preview-unavailable]`) instead of the badge.
28
+ - If the host is not allowed to preview, the page renders the release with
29
+ no badge and no notice (see "Draft hosts" in the `@decocms/tanstack`
30
+ README). So check that the badge is there: without it, the screenshot
31
+ compared the wrong content.
32
+
33
+ ## HTML parity
34
+
35
+ Strip what is expected to differ (scripts and comments) and diff the rest.
36
+ The draft badge mounts in the browser after hydration, so it is not in the
37
+ server HTML:
38
+
39
+ ```python
40
+ # body.py: normalize a page for diffing. Usage: curl -s URL | python3 body.py
41
+ import re, sys
42
+ s = sys.stdin.read()
43
+ t = re.search(r"<title>(.*?)</title>", s, flags=re.S)
44
+ print("TITLE", t.group(1) if t else None)
45
+ b = s[s.find("<body"):]
46
+ b = re.sub(r"<script.*?</script>", "", b, flags=re.S)
47
+ b = re.sub(r"<!--.*?-->", "", b, flags=re.S) # also React's streaming markers
48
+ print(b.replace("><", ">\n<"))
49
+ ```
50
+
51
+ ```sh
52
+ for p in / /pt /pricing /pt/pricing /docs/some-article; do
53
+ f=$(echo "$p" | tr / _)
54
+ curl -s "localhost:5192$p" | python3 body.py > "/tmp/main$f"
55
+ curl -s "localhost:5191$p?__draft=$DRAFT" | python3 body.py > "/tmp/new$f"
56
+ echo "$p: $(diff "/tmp/main$f" "/tmp/new$f" | grep -c '^[<>]') changed lines"
57
+ done
58
+ ```
59
+
60
+ Zero changed lines is the goal. The site writes the loop that renders
61
+ sections, so it controls the markup: if a wrapper element appears, remove it
62
+ rather than accept it.
63
+
64
+ Include a few pages you did **not** convert but whose components you moved or
65
+ touched. They must be identical too.
66
+
67
+ ## Pixel parity
68
+
69
+ Full-page screenshots of each page, in each language, at desktop and mobile
70
+ widths, on both servers, then a per-pixel diff.
71
+
72
+ Headless Chrome's `--screenshot` flag can hang on a Vite dev server (the HMR
73
+ socket never goes idle). `playwright-core` with a local Chromium works:
74
+
75
+ ```js
76
+ // shot.mjs: npm i playwright-core in a scratch folder; CHROMIUM=path to a Chromium binary
77
+ import { chromium } from "playwright-core";
78
+ const DRAFT = process.env.DRAFT ? `?__draft=${process.env.DRAFT}` : "";
79
+ const browser = await chromium.launch({ executablePath: process.env.CHROMIUM });
80
+ for (const [w, h] of [[1440, 900], [390, 844]])
81
+ for (const [name, port, query] of [["main", 5192, ""], ["new", 5191, DRAFT]])
82
+ for (const path of ["/", "/pt", "/pricing"]) {
83
+ const page = await browser.newPage({ viewport: { width: w, height: h } });
84
+ page.on("pageerror", (e) => console.error(name, path, String(e)));
85
+ await page.goto(`http://localhost:${port}${path}${query}`, { waitUntil: "load" });
86
+ // The badge mounts after hydration; no badge means the release rendered, not the draft.
87
+ if (query) await page.waitForSelector("[data-deco-preview-badge]", { timeout: 10_000 });
88
+ await page.addStyleTag({ content: "[data-deco-preview-badge]{display:none!important}" });
89
+ // Scroll once so reveal-on-scroll animations and lazy images run.
90
+ await page.evaluate(async () => {
91
+ for (let y = 0; y < document.body.scrollHeight; y += 400) { scrollTo(0, y); await new Promise((r) => setTimeout(r, 50)); }
92
+ scrollTo(0, 0);
93
+ });
94
+ await page.waitForLoadState("networkidle").catch(() => {});
95
+ await page.waitForTimeout(700);
96
+ await page.screenshot({ path: `shots/${name}${path.replaceAll("/", "_")}-${w}.png`, fullPage: true });
97
+ await page.close();
98
+ }
99
+ await browser.close();
100
+ ```
101
+
102
+ ```python
103
+ # diff.py: pip install pillow
104
+ from PIL import Image, ImageChops
105
+ import glob
106
+ for m in sorted(glob.glob("shots/main*.png")):
107
+ n = m.replace("main", "new", 1)
108
+ a, b = Image.open(m).convert("L"), Image.open(n).convert("L")
109
+ if a.size != b.size: print(m, "SIZE", a.size, b.size); continue
110
+ d = ImageChops.difference(a, b); px = [p for p in d.getdata() if p]
111
+ print(m, "identical" if not px else f"{len(px)} px, max {max(px)}/255 in {d.getbbox()}")
112
+ ```
113
+
114
+ Reading the result:
115
+
116
+ - A different page height, or any visible difference, is a regression.
117
+ - In a real conversion, a few dozen pixels at an intensity of 7/255 or less,
118
+ around a transition (a select chevron, an animated demo), were rendering
119
+ noise. Crop that box from both images and look before dismissing it.
120
+ - Sections that stream in (a `Suspense` boundary per section) can be caught
121
+ half-rendered. If one run shows a fallback, wait for it to go away
122
+ (`page.waitForSelector`) instead of raising the timeout everywhere.
123
+
124
+ ## Against a Figma design
125
+
126
+ With no `main` to compare with, the baseline is the design:
127
+
128
+ 1. Call `get_screenshot` on each section frame (desktop and mobile). Save as
129
+ `tests/visual-qa/baselines/<device>/<order>-<Section>.png`.
130
+ 2. Screenshot each section of the page at the frame's width (1440 and 375 are
131
+ common). If the site renders an attribute per section, use it as a
132
+ locator; otherwise screenshot by section element order.
133
+ 3. Compare by eye and list each mismatch. A pixel diff against a Figma render
134
+ is noisy (font rendering, antialiasing); it finds regions, it does not
135
+ judge them.
136
+
137
+ What to compare, per section:
138
+
139
+ - **Layout:** direction, alignment, grid columns, max width and centering,
140
+ order of elements.
141
+ - **Spacing:** padding, gaps, vertical rhythm between sections.
142
+ - **Type:** family, size, weight, line height, letter spacing, case, color.
143
+ - **Color:** backgrounds, borders, buttons, links, hover states.
144
+ - **Images:** the right asset, aspect ratio, crop (`object-fit`), radius.
145
+ - **Responsive:** both widths, and no jump at the breakpoints in between
146
+ (768px, 1024px).
147
+
148
+ Write the mismatches as a table and fix them one by one:
149
+
150
+ | # | Device | Section | Issue | Expected | Actual | Fix |
151
+ |---|---|---|---|---|---|---|
152
+ | 1 | desktop | Hero | title size | 48px | 36px | use the `display` text token |
153
+ | 2 | mobile | Header | menu icon missing | present | missing | render the menu button below `md` |
154
+
155
+ Re-screenshot after each fix and mark the row fixed. Done means every row is
156
+ fixed at both widths.
157
+
158
+ ## Live edit
159
+
160
+ With the branch running, change the content and watch it land:
161
+
162
+ - change a text in each language and confirm it changes on that language's
163
+ pages only;
164
+ - empty a `fooPt` and confirm the secondary language falls back to `foo`;
165
+ - remove and reorder sections of a page and confirm the rendered order follows;
166
+ - break a required field and confirm `deco check` names it (`deco check
167
+ --draft=<name>` on a hosted site: without a flag it checks production).
168
+
169
+ With content in git, edit the block files (`deco content --watch` reloads the
170
+ page). On a hosted site, make the same edits in the draft, from Studio or with
171
+ `deco push --draft=<name>`. Restore the content afterwards.
172
+
173
+ Then the real path, end to end: open the page in Studio, edit, preview, and
174
+ publish (with the owner's OK) or discard the draft. Confirm the change on the
175
+ site. This is the half of the goal that the pixel checks do not prove.
@@ -0,0 +1,119 @@
1
+ # Seeding content from the current code
2
+
3
+ Never retype content. Extract it from the code that ships today. Byte-identical
4
+ content is what makes the [pixel comparison](./pixel-parity.md) mean
5
+ something: if a single apostrophe changed, you cannot tell a typo from a
6
+ regression.
7
+
8
+ ## Extract with a throwaway script
9
+
10
+ Most hardcoded content is already data: a `COPY` object, a `LINKS` array. Load
11
+ it in isolation and write the block JSON from it.
12
+
13
+ ```ts
14
+ // scripts/seed-header.ts (run once with `bun scripts/seed-header.ts`, then delete)
15
+ import fs from "node:fs";
16
+ import { LINKS } from "../src/components/Header.constants";
17
+
18
+ const block = {
19
+ __resolveType: "header-menu",
20
+ links: LINKS.map(({ label, labelPt, href }) => ({ label, labelPt, href })),
21
+ };
22
+ const name = "Header menu";
23
+ fs.writeFileSync(`.deco/blocks/${encodeURIComponent(name)}.json`, `${JSON.stringify(block, null, 2)}\n`);
24
+ ```
25
+
26
+ - If the constant lives in a component file that imports React or CSS, move it
27
+ to its own module first (the component then imports it). That is a
28
+ refactor with no visual change; commit it separately.
29
+ - Component references in the data (`icon: RocketIcon`) cannot go into JSON.
30
+ Replace them with string keys and keep a closed list in code:
31
+ `const ICONS = { rocket: RocketIcon, book: BookIcon }`, with
32
+ `icon: keyof typeof ICONS` in `Props`. Editors then pick from a list instead
33
+ of typing a free-text name. `deco-cms-schema` shows how the form renders it.
34
+ - Text written straight in JSX has no constant to load. Copy it with the
35
+ script anyway (read the file, cut the strings), or paste it once and check
36
+ the [HTML diff](./pixel-parity.md#html-parity) shows no change.
37
+ - Once the block exists, delete the constant. Keeping it "as a fallback"
38
+ creates a second source of truth.
39
+
40
+ The file name is `encodeURIComponent(name)` plus `.json`, directly in
41
+ `.deco/blocks` (subfolders are not read).
42
+
43
+ ## Content in git (no `site`)
44
+
45
+ A site created with `createCMS({ blocks, content })` and no `site` reads the
46
+ content module, `.deco/blocks.gen.ts`, bundled with the build.
47
+
48
+ ```sh
49
+ deco schema # .deco/index.ts → .deco/schema.gen.json
50
+ deco content # .deco/blocks → .deco/blocks.gen.ts
51
+ deco check # every saved block against the schema (no DECO_SITE set)
52
+ ```
53
+
54
+ During `vite dev`, `deco content --watch` rewrites the module on each save,
55
+ and the `decoContent()` plugin (included in `decoTanstack()`) swaps the new
56
+ content into the running CMS and reloads open pages. Edit a block file, and
57
+ the page shows it.
58
+
59
+ ## A hosted site (`site` set)
60
+
61
+ A site created with `createCMS({ blocks, site })` reads its content from the
62
+ delivery CDN at runtime. The CLI finds the same site in `DECO_SITE` (the
63
+ environment, `.env`, `.dev.vars` or `vars` in the wrangler config). The local
64
+ `.deco/blocks` is what `deco pull` wrote, and changes travel as drafts:
65
+
66
+ ```sh
67
+ deco pull # production into .deco/blocks
68
+ # write or edit the seeded files
69
+ deco diff # what changed since the pull
70
+ deco push --draft=header-menu # one save into the draft (creates it); prints its preview link
71
+ deco check --draft=header-menu # the draft against the local .deco/schema.gen.json
72
+ deco drafts url header-menu # the preview link again
73
+ ```
74
+
75
+ - `deco push` sends only the blocks changed since the pull. Deletes are sent
76
+ only with `--prune`.
77
+ - One push is one save, at most 500 blocks and 8 MiB. A larger push fails with
78
+ "don't fit one save": push fewer blocks at a time.
79
+ - `deco check --draft` validates the draft against the schema on disk, so it
80
+ checks the branch's new types before anything is deployed.
81
+ - Open the preview link on a local dev server of the branch to see the seeded
82
+ content with the new code. A draft page shows a "Preview mode" badge. With
83
+ no badge, the page rendered the release: either the host is not allowed to
84
+ preview (no notice; see "Draft hosts" in the `@decocms/tanstack` README, and
85
+ `deco-site-workflow`), or the draft could not be read (a notice says so).
86
+
87
+ The full set of content commands (`drafts`, `publish`, `releases`, rollback)
88
+ is in `deco-site-workflow`.
89
+
90
+ ## Order of publish and deploy
91
+
92
+ On a hosted site, content and code ship separately. Pick the order so that the
93
+ live site never runs code that reads a block that is not published yet:
94
+
95
+ 1. Publish the draft with the **new** blocks first. Old code never reads them,
96
+ so this changes nothing on the live site.
97
+ 2. Deploy the code that reads them. The production deploy should also run
98
+ `deco schema push` (see `deco-site-workflow`): that is what gives Studio
99
+ the forms for the new types.
100
+ 3. Only then publish changes to **existing** blocks that the old code would
101
+ not understand, such as a page whose sections now use a new section type.
102
+
103
+ Do not run `deco publish` without the site owner's explicit OK for that
104
+ publish.
105
+
106
+ ## What `deco check` covers
107
+
108
+ `deco check` validates each saved block against the generated schema:
109
+
110
+ - required fields that are missing, unknown fields, wrong types, values
111
+ outside an `@options` list;
112
+ - a `__resolveType` that names no block type, built-in or saved block;
113
+ - a block placed in a field it does not fit;
114
+ - page paths that conflict, and redirect rules outside the redirects block.
115
+
116
+ It does not check that an internal link (`href: "/pricing"`) points at a page
117
+ that exists, and an empty string passes a required string field. If either
118
+ matters for your site, add a small script to CI that walks `.deco/blocks` for
119
+ link fields and compares them with the page paths and the site's own routes.
@@ -0,0 +1,74 @@
1
+ ---
2
+ name: deco-nextjs-site
3
+ description: "Wiring a Next.js App Router site to @decocms/nextjs 8 (with @decocms/blocks 8, Next 16, React 19): the block map in .deco/index.tsx and the two createCMS handles, withDeco in next.config, the proxy (@decocms/nextjs/proxy: decideDraft, decideVisitor, decideAssignments, the /_draft and /_assignments rewrites, or draftProxy), reading and rendering resolved pages in Server Components (@decocms/nextjs/server: bindDraft, contentClient, assignedClient; matchRoute, redirects, notFound), page metadata from the page's seo block, ISR caching on the assignments route (revalidate = 600, never force-static, assignmentsKey for a CDN), the Studio bridge (StudioBridge, StudioPage, withStudioCsp), the next/image loader (@decocms/nextjs/image-loader) and the request metric (@decocms/nextjs/instrumentation). Load it for any v8 site built on Next.js: scaffolding, a draft that does not show, a page that renders on every request instead of caching, Studio not driving the page, or wrong metadata."
4
+ ---
5
+
6
+ # Deco on Next.js (v8)
7
+
8
+ `@decocms/nextjs` 8 is a set of small helpers a Next.js App Router site calls
9
+ from its own `proxy.ts`, layouts, pages and `next.config`. It makes no hosting
10
+ assumption: no CDN, no platform rules. Content comes from `@decocms/blocks`
11
+ (`createCMS`, `client.resolve`, `matchRoute`); this package adds draft
12
+ previews, tests and campaigns decided once per request, Next's cache, and the
13
+ Studio bridge.
14
+
15
+ Load the reference for the job in front of you. Every name below exists in
16
+ `packages/nextjs/src` or `packages/blocks/src/v8`. The full working app is
17
+ `examples/nextjs-binding-smoke` in this repository: when this skill and that
18
+ example disagree, the example wins.
19
+
20
+ ## When to load what
21
+
22
+ | Reference | Load it when |
23
+ |---|---|
24
+ | [`references/setup.md`](./references/setup.md) | Starting a site or adding Deco to a Next app: packages, file layout, the block map, the two CMS handles, `withDeco`, scripts, the image loader, the request metric |
25
+ | [`references/proxy-and-drafts.md`](./references/proxy-and-drafts.md) | Writing `proxy.ts`; a Studio draft link shows the published page; preview hosts; the draft route and `bindDraft`; the preview badge |
26
+ | [`references/rendering.md`](./references/rendering.md) | Reading and rendering a page in a Server Component: routes, redirects, `resolve`, sections, client components, errors |
27
+ | [`references/metadata-seo.md`](./references/metadata-seo.md) | `<title>` or description wrong or missing; the `seo` block; noindex on drafts |
28
+ | [`references/caching.md`](./references/caching.md) | ISR, the assignments route, a page that renders on every request, a CDN in front, stale content after publish |
29
+ | [`references/studio-bridge.md`](./references/studio-bridge.md) | Studio cannot select or reload sections, "." opens the wrong page, CSP blocks Studio, a local Studio |
30
+
31
+ ## The shape of a request
32
+
33
+ 1. `proxy.ts` decides once: the version (a Studio link's draft or old
34
+ release, on an allowed host), the visitor (`deco_segment` cookie) and every
35
+ test and campaign on or off.
36
+ 2. A published CMS page is rewritten to `/_assignments/<segment>/<path>`. The
37
+ page reads no request, so Next caches it (ISR).
38
+ 3. A preview request is rewritten to `/_draft/<path>`. That route is dynamic,
39
+ binds the draft with `bindDraft`, and is never cached.
40
+ 4. Both routes build one content client, match the path, follow redirects,
41
+ resolve the page and render its sections.
42
+
43
+ ## Rules that are easy to break
44
+
45
+ - The route folders are `app/%5Fdraft/...` and `app/%5Fassignments/...`. A
46
+ folder named `_draft` is private in Next and never routes.
47
+ - Never call `bindDraft`, `headers()`, `cookies()` or `searchParams` on the
48
+ assignments route or in the root layout. Any of them makes Next render the
49
+ page on every request.
50
+ - Never `export const dynamic = "force-static"` on a CMS page. Use
51
+ `revalidate`.
52
+ - The proxy imports a CMS handle with an empty block map
53
+ (`createCMS({ blocks: {}, ...cmsConfig })`), so no section reaches the proxy
54
+ bundle.
55
+ - Never edit generated files (`.deco/schema.gen.json`, `.deco/blocks.gen.ts`).
56
+ Change the types or the content and run the CLI again.
57
+
58
+ ## Not in v8
59
+
60
+ v7's `createNextSetup`, `createDecoRouteHandlers`, `createDecoPreviewPage`,
61
+ the `/setup` and `/routeHandlers` subpaths, `src/sections/*` shims as block
62
+ keys, `generate:deco` and the `/deco/*` admin routes do not exist in
63
+ `@decocms/nextjs` 8. Moving a v7 site: load `deco-v7-to-v8-migration`.
64
+
65
+ ## Related skills
66
+
67
+ - `deco-site-workflow`: the `deco` CLI (`schema`, `schema push`, `check`,
68
+ `pull`, `push --draft`, `publish`) and how releases reach the site.
69
+ - `deco-site-authoring`: writing sections, pages and loaders.
70
+ - `deco-cms-schema`: how a Props type becomes the Studio form.
71
+ - `deco-variants`: multivariate blocks, tests and campaigns.
72
+ - `deco-images-media`: image providers, quality and LCP.
73
+ - `deco-storefront-caching`: cache keys and egress, with the Next equivalents.
74
+ - `deco-tanstack-site`: the same wiring on TanStack Start.
@@ -0,0 +1,116 @@
1
+ # Caching and ISR on Next
2
+
3
+ The binding caches nothing itself. It shapes requests so Next's own cache
4
+ (ISR, keyed by path) can keep published pages, while previews and
5
+ per-visitor decisions stay out of it.
6
+
7
+ ## The assignments route
8
+
9
+ Next caches a page by its path. Tests and campaigns change what a page shows,
10
+ so the proxy puts its decision into the path:
11
+
12
+ ```
13
+ /shoes → /_assignments/<segment>/shoes
14
+ ```
15
+
16
+ - The segment lists every test of the saved `experiments` block on or off for
17
+ this visitor, and every campaign of the saved `campaigns` block running or
18
+ not now. `-` means none; otherwise it is base64url, one spelling per set.
19
+ - The visitor id is never in it. Visitors on the same side of every test
20
+ share one path and one cache entry.
21
+ - A campaign starting or ending moves every visitor to a new path.
22
+ - The rewritten request carries no visitor and no draft header. The page
23
+ builds its client from the path alone (`assignedClient`), so it reads no
24
+ request.
25
+
26
+ ```tsx
27
+ // src/app/%5Fassignments/[assignments]/[[...path]]/page.tsx
28
+ export const revalidate = 600; // 10 minutes; never force-static
29
+ export async function generateStaticParams() {
30
+ return []; // nothing at build time: each path renders on first request, then is cached
31
+ }
32
+ ```
33
+
34
+ ## What the numbers mean
35
+
36
+ `revalidate = 600`: Next serves a stored page for 10 minutes. The first
37
+ request after that still gets the stored copy while Next renders the page
38
+ again in the background. So:
39
+
40
+ - A published change shows within about 10 minutes on a page people visit.
41
+ - A page nobody opened for longer shows its old copy once more.
42
+ - A banner can switch on a few minutes late. That delay is accepted.
43
+
44
+ On a site with `site`, the CMS also checks for a new release every `interval`
45
+ (default and minimum 60 000 ms). A re-render picks up whatever release the
46
+ process holds at that moment.
47
+
48
+ Never use `force-static` on a CMS page. A page that never expires keeps what
49
+ it rendered first, forever.
50
+
51
+ ## What makes a page render on every request
52
+
53
+ Any of these anywhere in the route, its layouts included:
54
+
55
+ - `headers()`, `cookies()` or `searchParams`;
56
+ - `bindDraft` (it reads `headers()`), so the `contentClient(cms)` pattern
57
+ that needs it (use `assignedClient` here);
58
+ - `export const dynamic = "force-dynamic"`.
59
+
60
+ A client component calling `useSearchParams()` does not stop the cache, but
61
+ renders on the client up to its nearest `<Suspense>`.
62
+
63
+ Check with `curl -sI https://<host>/<path>` twice: the second response should
64
+ show `x-nextjs-cache: HIT` (or `STALE` after 10 minutes). The example app's
65
+ smoke test checks exactly this.
66
+
67
+ ## Rules the route depends on
68
+
69
+ - **Direct hits are a 404.** The proxy answers `/_assignments/…` and
70
+ `/_draft/…` with 404 (`isAssignmentsRoutePath`, `isDraftRoutePath`), so only
71
+ its own rewrite reaches the route. Otherwise anyone could switch a test on
72
+ by typing a path.
73
+ - **Unknown names stay off, not 404.** `assignedClient` keeps off a test at 0%
74
+ and drops a test or campaign the content doesn't have. It returns `null`
75
+ (answer `notFound()`) only for a segment the proxy never writes. Next would
76
+ cache a 404 under the path, and a path written just before a publish must
77
+ still render.
78
+ - **Previews never land here.** `rewriteToAssignmentsRoute` returns `null` for
79
+ any preview; those render on the dynamic `/_draft` route.
80
+ - **Only CMS pages.** The proxy calls it only for paths its `isCmsPage` (the
81
+ site's own function) accepts.
82
+
83
+ ## A CDN in front of Next
84
+
85
+ The URL the visitor asked for (`/shoes`) answers by their cookie and the
86
+ current time, even though Next's entry is shared. So when the content saves
87
+ tests or campaigns, the rewrite marks the response
88
+ `Cache-Control: private, no-cache`. Do not override that with a shared
89
+ `s-maxage` at the CDN.
90
+
91
+ A site that caches pages in front of Next keys on the assignments, never on
92
+ the visitor:
93
+
94
+ ```ts
95
+ import { assignmentsKey, decideAssignments } from "@decocms/nextjs/proxy";
96
+
97
+ const key = assignmentsKey(await decideAssignments(proxyCms, draft, visitor));
98
+ // the version, the tests on and the campaigns running; "" when there are none
99
+ ```
100
+
101
+ Never store a response that carries `?__draft=` or the `__deco_draft` cookie.
102
+ Those responses carry `Cache-Control: max-age=0, no-cache, must-revalidate`
103
+ and `Vary: Cookie`.
104
+
105
+ ## Stale content after publishing
106
+
107
+ 1. Wait out `revalidate` and request the page twice: the second request
108
+ gets the new render.
109
+ 2. Check the release the process holds: a site with `site` reloads it every
110
+ `interval`.
111
+ 3. Check that no CDN or `headers()` rule adds a long shared `max-age` on top.
112
+ 4. A page on the draft route is never stale: if the draft shows the change
113
+ and the published page doesn't, it is the cache, not the content.
114
+
115
+ Cache keys, hit rate and egress in general: load `deco-storefront-caching`.
116
+ Tests and campaigns content: load `deco-variants`.
@@ -0,0 +1,100 @@
1
+ # Metadata from blocks
2
+
3
+ On Next, a page's `<title>`, description and other head tags come from
4
+ `generateMetadata`. On a Deco page, the source is the page block's `seo`
5
+ field. This file covers the wiring; what to put in SEO content and JSON-LD is
6
+ in `deco-site-authoring`.
7
+
8
+ ## The seo block
9
+
10
+ `@decocms/blocks` types it as `Seo { title: string; description: string }`,
11
+ and the built-in `page` block carries an optional `seo` next to `sections`.
12
+ There is no built-in `seo` block function: the site registers one in its block
13
+ map, so Studio can draw the form and saved pages can reference it.
14
+
15
+ ```tsx
16
+ // .deco/index.tsx
17
+ import type { Blocks, Seo } from "@decocms/blocks";
18
+
19
+ export default {
20
+ seo: (input: Seo) => input,
21
+ // … sections …
22
+ } satisfies Blocks;
23
+ ```
24
+
25
+ ```json
26
+ {
27
+ "__resolveType": "page",
28
+ "name": "Summer shirt",
29
+ "path": "/:slug/p",
30
+ "seo": {
31
+ "__resolveType": "seo",
32
+ "title": "Summer shirt | My store",
33
+ "description": "Light cotton shirt for hot days."
34
+ },
35
+ "sections": []
36
+ }
37
+ ```
38
+
39
+ When `resolve` runs the page, `seo` is resolved too: `page.seo` holds what the
40
+ `seo` function returned.
41
+
42
+ Need more fields (canonical, Open Graph image, noindex)? Give the site's `seo`
43
+ function its own Props type that extends `Seo`, and type the resolved page
44
+ with your own interface instead of `Page`. The CMS passes the props through;
45
+ nothing in the binding reads them.
46
+
47
+ ## generateMetadata
48
+
49
+ ```tsx
50
+ // src/app/%5Fassignments/[assignments]/[[...path]]/page.tsx
51
+ import type { Metadata } from "next";
52
+ import { openPage, pathnameFor } from "../../../../open-page.server";
53
+
54
+ type Props = { params: Promise<{ assignments: string; path?: string[] }> };
55
+
56
+ export async function generateMetadata({ params }: Props): Promise<Metadata> {
57
+ const { assignments, path } = await params;
58
+ const page = await openPage(pathnameFor(path), assignments);
59
+ return { title: page.seo?.title, description: page.seo?.description };
60
+ }
61
+ ```
62
+
63
+ - `openPage` is wrapped in React's `cache()` ([rendering.md](./rendering.md)),
64
+ so the metadata and the page share one resolve per request.
65
+ - On the assignments route, read only `params`. Reading `headers()`,
66
+ `cookies()` or `searchParams` in `generateMetadata` makes the page render
67
+ on every request, the same as in the page.
68
+ - On the draft route, call `bindDraft` before `openPage` in
69
+ `generateMetadata` too: Next may run it before the page body.
70
+ - Leave a field `undefined` when the page has no `seo`. Next then uses the
71
+ root layout's `metadata` (site defaults, a `title.template`).
72
+
73
+ ## Drafts are noindex
74
+
75
+ A preview must never be indexed. Two layers already do it:
76
+
77
+ - The proxy's `applyDraft` sets `X-Robots-Tag: noindex, nofollow`,
78
+ `Cache-Control: max-age=0, no-cache, must-revalidate` and `Vary: Cookie` on
79
+ every preview response.
80
+ - `withDeco`'s header rules add `X-Robots-Tag: noindex, nofollow` to any
81
+ request with `?__draft=` or the `__deco_draft` cookie.
82
+
83
+ Do not remove either to "fix" a header conflict. If a site-wide rule in
84
+ `headers()` sets `Cache-Control`, `withDeco` already places the draft rules
85
+ first.
86
+
87
+ ## Head tags the binding adds
88
+
89
+ `StudioPage` renders `<meta name="deco:page" content="<path template>">`.
90
+ React hoists it into `<head>`; it does not change the page's markup or SEO.
91
+
92
+ ## Checks
93
+
94
+ - `curl -s https://<host>/<path> | grep -i '<title>'` shows the page's
95
+ `seo.title`, not the layout default.
96
+ - A page with a `:slug` path has one `seo` for every slug. Per-item titles
97
+ (a product name) come from a loader that the `seo` block reads; load
98
+ `deco-site-authoring`.
99
+ - `curl -sI 'https://<host>/<path>?__draft=<name>'` shows
100
+ `X-Robots-Tag: noindex, nofollow`.