@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,221 @@
1
+ #!/usr/bin/env bash
2
+ # Read-only go-live preflight for a site on @decocms/blocks 8 (TanStack Start
3
+ # behind createDecoWorker; most repo checks also make sense on Next.js).
4
+ #
5
+ # Usage: preflight.sh <site-repo-dir> [candidate-url] [old-site-url]
6
+ # site-repo-dir the site repo (static checks)
7
+ # candidate-url https://host serving the new site (HTTP checks)
8
+ # old-site-url https://host serving the old site (header diff)
9
+ # Env: CHECKOUT_PATH (default /checkout/)
10
+ #
11
+ # Prints PASS / WARN / FAIL per check and never writes anything. It runs no
12
+ # deco command: run `deco schema --check` and `deco check` yourself.
13
+ # Browser-only checks (marked 🧪 in SKILL.md) are not covered.
14
+
15
+ set -u
16
+ REPO="${1:?usage: preflight.sh <site-repo-dir> [candidate-url] [old-site-url]}"
17
+ CAND="${2:-}"; CAND="${CAND%/}"
18
+ OLD="${3:-}"; OLD="${OLD%/}"
19
+ CHECKOUT="${CHECKOUT_PATH:-/checkout/}"
20
+ UA="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0 Safari/537.36"
21
+
22
+ fails=0; warns=0
23
+ pass() { printf ' \033[32mPASS\033[0m %s\n' "$1"; }
24
+ warn() { printf ' \033[33mWARN\033[0m %s\n' "$1"; warns=$((warns + 1)); }
25
+ fail() { printf ' \033[31mFAIL\033[0m %s\n' "$1"; fails=$((fails + 1)); }
26
+ show() { sed 's/^/ /' | head -n "${1:-5}"; }
27
+ section() { printf '\n== %s\n' "$1"; }
28
+
29
+ SRC="$REPO/src"
30
+ [ -d "$SRC" ] || SRC="$REPO"
31
+ # grep the site's source, skipping generated, vendored and test files and comment lines
32
+ g() {
33
+ grep -rnE "$@" --include='*.ts' --include='*.tsx' --include='*.js' --include='*.mjs' \
34
+ --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=.deco --exclude-dir=.git \
35
+ --exclude-dir=.output --exclude-dir=.next \
36
+ --exclude='*.gen.ts' --exclude='*.test.*' --exclude='*.spec.*' "$SRC" 2>/dev/null |
37
+ grep -vE '^[^:]+:[0-9]+:\s*(//|\*|/\*)'
38
+ }
39
+
40
+ WRANGLER=""
41
+ for f in wrangler.jsonc wrangler.json wrangler.toml; do [ -f "$REPO/$f" ] && WRANGLER="$REPO/$f" && break; done
42
+
43
+ section "Packages and content (references/content-releases.md)"
44
+
45
+ if [ -f "$REPO/package.json" ]; then
46
+ v=$(grep -oE '"@decocms/blocks"\s*:\s*"[^"]+"' "$REPO/package.json" | head -1)
47
+ case "$v" in
48
+ *'"^8'* | *'"8'* | *'"~8'* | *'workspace:'*) pass "@decocms/blocks: ${v#*: }" ;;
49
+ "") fail "@decocms/blocks is not a dependency" ;;
50
+ *) warn "@decocms/blocks ${v#*: }: this skill is for v8" ;;
51
+ esac
52
+ fi
53
+
54
+ hits=$(g 'createDecoWorkerEntry|@decocms/start|registerSections|registerCachePattern|createCachedLoader|/deco/invoke|DECO_FAST_DEPLOY')
55
+ if [ -z "$hits" ]; then pass "no v7 runtime APIs in source"
56
+ else fail "v7 APIs left in source (see deco-v7-to-v8-migration)"; echo "$hits" | show 8; fi
57
+
58
+ if [ -f "$REPO/.deco/schema.gen.json" ]; then
59
+ if grep -qE '"blocksMajor"\s*:\s*8' "$REPO/.deco/schema.gen.json"; then pass 'schema.gen.json has "blocksMajor": 8'
60
+ else fail 'schema.gen.json lacks "blocksMajor": 8: Studio edits the site as v7 and deco check fails'; fi
61
+ else warn "no .deco/schema.gen.json: run deco schema and commit it"; fi
62
+
63
+ files=$(g 'createCMS(<[^>]*>)?\(' | cut -d: -f1 | sort -u)
64
+ if [ -z "$files" ]; then warn "createCMS not found in source"
65
+ else
66
+ # the createCMS({ ... }) call itself, comments dropped
67
+ call=$(for f in $files; do awk '/createCMS(<[^>]*>)?\(/{f=1} f{sub(/\/\/.*/, ""); print} f&&/\}\)/{f=0}' "$f"; done)
68
+ if echo "$call" | grep -qE '(^|[^A-Za-z_.])site\s*[:,}]'; then pass "createCMS has site: releases come from the CDN"
69
+ else warn "createCMS without site: content is bundled and every content change needs a deploy"; fi
70
+ fi
71
+
72
+ hits=$(g "\.deco/blocks/[^\"']+\.json")
73
+ [ -z "$hits" ] && pass "no direct imports of .deco/blocks/*.json" ||
74
+ { warn "direct imports of saved blocks: a publish never reaches them"; echo "$hits" | show; }
75
+
76
+ section "Worker runtime (references/worker-runtime.md)"
77
+
78
+ if g 'createDecoWorker(<[^>]*>)?\(' >/dev/null; then pass "createDecoWorker in source"
79
+ else warn "no createDecoWorker in source (fine on Next.js; on TanStack the worker features are missing)"; fi
80
+
81
+ hits=$(g 'new QueryClient\(')
82
+ if [ -z "$hits" ]; then pass "no QueryClient"
83
+ elif echo "$hits" | grep -q 'router.tsx' && awk '/getRouter/{f=1} f&&/new QueryClient\(/{found=1} END{exit !found}' "$SRC/router.tsx" 2>/dev/null; then
84
+ pass "new QueryClient() appears after getRouter in router.tsx (confirm it is not at module scope)"
85
+ else fail "new QueryClient() possibly at module scope: it leaks data between users"; echo "$hits" | show; fi
86
+
87
+ hits=$(g '^(export )?(const|let) [A-Za-z_]+ = new (Map|Set)\(')
88
+ [ -z "$hits" ] && pass "no module-level Map/Set" ||
89
+ { warn "module-level Map/Set: must hold only data that is the same for every user, with deadlines on shared promises"; echo "$hits" | show; }
90
+
91
+ if [ -n "$WRANGLER" ]; then
92
+ if grep -qE '"?observability"?' "$WRANGLER" && grep -A2 -E '"?observability"?' "$WRANGLER" | grep -q 'true'; then
93
+ pass "Workers observability enabled"
94
+ else warn "observability not enabled in $(basename "$WRANGLER"): exceededMemory and canceled are invisible"; fi
95
+ mem=$(grep -oE '"?memory_mb"?\s*[:=]\s*[0-9]+' "$WRANGLER")
96
+ [ -n "$mem" ] && warn "custom memory limit ($mem): a stopgap; find what fills memory"
97
+ fi
98
+
99
+ hits=$(g '\.text\(\)' | grep -iE 'sitemap|proxy|upstream|checkout')
100
+ [ -z "$hits" ] && pass "no .text() buffering in sitemap/proxy code" ||
101
+ { warn "large responses buffered with .text(): stream them"; echo "$hits" | show; }
102
+
103
+ n=$(g 'AbortSignal\.timeout' | wc -l | tr -d ' ')
104
+ [ "$n" = "0" ] && warn "no AbortSignal.timeout in source: upstream fetches have no deadline" || pass "$n upstream deadline(s) (AbortSignal.timeout)"
105
+
106
+ if g 'telemetry\s*:|token\s*:' | grep -q .; then pass "telemetry options present (confirm token or endpoint is set in production)"
107
+ else warn "no telemetry option seen: request and upstream metrics go nowhere"; fi
108
+
109
+ section "Cache (deco-storefront-caching)"
110
+
111
+ if g 'pageCache' >/dev/null; then pass "pageCache passed to the worker"
112
+ else warn "no pageCache: every request renders (fine only if a CDN in front caches pages)"; fi
113
+
114
+ hits=$(g '\.catch\(\(\)\s*=>\s*(null|undefined|\[\])\)' | grep -viE 'cache\.(match|put|delete)')
115
+ [ -z "$hits" ] && pass "no errors swallowed to null" ||
116
+ { warn "errors swallowed to null: may be cached as not-found or out-of-stock (use DEGRADED_HEADER)"; echo "$hits" | show; }
117
+
118
+ section "Traffic split (references/traffic-ramp.md)"
119
+ if g 'abTestingRoutes' >/dev/null; then
120
+ pass "abTestingRoutes in use: test both buckets with ?_deco_bucket=worker|fallback"
121
+ g 'shouldBypassAB' >/dev/null || warn "no shouldBypassAB: routes only the new site has will be split too"
122
+ else pass "no traffic split handler (skip if the cutover is a straight switch)"; fi
123
+
124
+ section "React / Fresh leftovers (references/react-spa.md)"
125
+
126
+ hits=$(g 'window\.STOREFRONT|window\.addToCart|hx-(post|get|on|trigger)')
127
+ [ -z "$hits" ] && pass "no Fresh global SDK / htmx leftovers" || { fail "Fresh/htmx leftovers"; echo "$hits" | show 10; }
128
+
129
+ hits=$(g 'on[A-Z][a-zA-Z]+=\{useScript')
130
+ [ -z "$hits" ] && pass "no on*={useScript(...)} handlers" || { fail "an event handler receives a string from useScript"; echo "$hits" | show; }
131
+
132
+ n=$(g 'useScript\(|useScriptAsDataURI\(' | cut -d: -f1 | sort -u | wc -l | tr -d ' ')
133
+ [ "$n" = "0" ] || warn "$n file(s) with useScript/useScriptAsDataURI: test each by SPA click; prefer inlineScript"
134
+
135
+ if ls "$REPO"/eslint.config.* "$REPO"/.eslintrc* "$REPO"/biome.json* >/dev/null 2>&1 &&
136
+ grep -qE 'rules-of-hooks|useHookAtTopLevel' "$REPO"/eslint.config.* "$REPO"/.eslintrc* "$REPO"/biome.json* 2>/dev/null; then
137
+ pass "hook-order lint configured"
138
+ else warn "no rules-of-hooks (ESLint) or useHookAtTopLevel (Biome): hooks after an early return cause React #310"; fi
139
+
140
+ g 'preloadError' >/dev/null && pass "stale-chunk handler present" ||
141
+ warn "no vite:preloadError handler: open tabs break after each deploy"
142
+
143
+ if g 'createDecoRouter(<[^>]*>)?\(' >/dev/null && ! g 'defaultPreload' >/dev/null; then
144
+ warn "createDecoRouter with the default defaultPreload \"intent\": measure the payload a hover fetches"
145
+ fi
146
+
147
+ section "Analytics (references/seo-analytics.md)"
148
+ g 'googletagmanager|GoogleTagManager|gtm\.js' >/dev/null && pass "tag manager referenced in source" ||
149
+ warn "tag manager not referenced in source (injected elsewhere? not mounted?)"
150
+ hits=$(g 'requestIdleCallback|firstInteraction|onFirstGesture' | grep -iE 'gtm|tag|analytic')
151
+ [ -z "$hits" ] && pass "no gesture/idle gate around tags" ||
152
+ { fail "tag manager gated behind a gesture or idle (about 20% of orders lost on one store)"; echo "$hits" | show; }
153
+ [ -f "$REPO/public/sitemap.xml" ] && warn "static public/sitemap.xml: it may mask a missing sitemap route"
154
+
155
+ if [ -n "$CAND" ]; then
156
+ section "HTTP: candidate $CAND"
157
+ cc() { curl -s -m 20 -A "$UA" "$@"; }
158
+ code() { cc -o /dev/null -w '%{http_code}' "$@"; }
159
+ # final status, skipping 103 Early Hints
160
+ status() { grep -E '^HTTP/' | grep -v ' 103' | tail -1 | awk '{print $2}'; }
161
+
162
+ [ "$(cc "$CAND/deco/_liveness")" = "OK" ] && pass "/deco/_liveness → OK (createDecoWorker in front)" ||
163
+ warn "/deco/_liveness did not answer OK (not behind createDecoWorker?)"
164
+ c=$(code "$CAND/live/_meta")
165
+ [ "$c" = "404" ] && pass "v7 admin path /live/_meta → 404" || warn "/live/_meta → $c (expected 404 from the worker)"
166
+
167
+ c=$(code "$CAND/")
168
+ [ "$c" = "200" ] && pass "/ → 200" || fail "/ → $c"
169
+
170
+ # the first-visit visitor cookie, the split cookie and Cloudflare's own are expected
171
+ h=$(cc -o /dev/null -D - "$CAND/" | tr -d '\r')
172
+ sc=$(echo "$h" | grep -i '^set-cookie:' | grep -viE '^set-cookie: *(deco_segment|_deco_bucket|__cf_bm|_cfuvid|cf_clearance)=')
173
+ [ -z "$sc" ] && pass "anonymous / sets no cookie besides deco_segment" ||
174
+ { warn "anonymous / sets other cookies: a page cache must not store it"; echo "$sc" | cut -c1-90 | show; }
175
+ echo "$h" | grep -qi '^x-robots-tag:.*noindex' && fail "/ sends X-Robots-Tag noindex" || pass "/ has no X-Robots-Tag noindex"
176
+ xc=$(cc -o /dev/null -D - "$CAND/" | tr -d '\r' | grep -iE '^(x-cache|cf-cache-status):' | tr '\n' ' ')
177
+ echo "$xc" | grep -qi 'hit' && pass "2nd request: $xc" || warn "2nd request not a HIT: ${xc:-no cache header}"
178
+
179
+ h=$(cc -o /dev/null -D - "$CAND/?__draft=off" | tr -d '\r')
180
+ if echo "$h" | grep -qi '^cache-control: *max-age=0, no-cache, must-revalidate' && echo "$h" | grep -qi '^x-robots-tag:.*noindex'; then
181
+ pass "?__draft= preview answers no-cache and noindex"
182
+ else warn "?__draft=off did not answer the preview headers (worker not in front?)"; fi
183
+
184
+ h=$(cc -o /dev/null -D - -H 'If-Modified-Since: Tue, 20 Oct 2026 00:00:00 GMT' -H 'If-None-Match: "x"' "$CAND$CHECKOUT" | tr -d '\r')
185
+ c=$(echo "$h" | status)
186
+ if [ "$c" = "304" ]; then fail "$CHECKOUT answers 304 to validators: stale checkout from the browser cache"
187
+ elif echo "$h" | grep -qiE '^(last-modified|etag):'; then warn "$CHECKOUT sends Last-Modified/ETag: the browser will revalidate"
188
+ else pass "$CHECKOUT → $c without validators"; fi
189
+ coop=$(echo "$h" | grep -i '^cross-origin-opener-policy:' | cut -d: -f2- | xargs)
190
+ [ -n "$coop" ] && warn "$CHECKOUT sends Cross-Origin-Opener-Policy: $coop (compare with the old site)"
191
+
192
+ loops=""
193
+ for p in '/%7Bx%7D' '/x%7B' '/%5Bx%5D' '/%7Cx' '/%5Ex' '/%60x'; do
194
+ n=$(cc -o /dev/null -L --max-redirs 10 -w '%{num_redirects}' "$CAND$p")
195
+ [ "${n:-0}" -ge 5 ] && loops="$loops ${p};"
196
+ done
197
+ [ -z "$loops" ] && pass "no redirect loops on encoded paths" || fail "redirect loop (5+ hops) on:$loops"
198
+
199
+ robots=$(cc "$CAND/robots.txt")
200
+ echo "$robots" | grep -qE '^Disallow:\s*/\s*$' && fail "robots.txt has Disallow: /" || pass "robots.txt does not block everything"
201
+ cc "$CAND/" | grep -qiE '<meta[^>]+robots[^>]+noindex' && fail "home has meta noindex" || pass "home indexable"
202
+ cc "$CAND/" | grep -q 'googletagmanager.com' && pass "tag manager in home HTML" || warn "tag manager not in home HTML (host-gated? injected late?)"
203
+
204
+ c=$(code "$CAND/this-page-should-not-exist-$RANDOM")
205
+ [ "$c" = "404" ] && pass "missing page → 404" || fail "missing page → $c (soft 404)"
206
+
207
+ if [ -n "$OLD" ]; then
208
+ section "Header diff: old $OLD × candidate"
209
+ for p in / "$CHECKOUT"; do
210
+ for hdr in cross-origin-opener-policy cross-origin-embedder-policy content-security-policy permissions-policy x-frame-options referrer-policy strict-transport-security; do
211
+ a=$(curl -s -m 20 -A "$UA" -o /dev/null -D - "$OLD$p" | tr -d '\r' | grep -i "^$hdr:" | cut -d: -f2- | xargs)
212
+ b=$(cc -o /dev/null -D - "$CAND$p" | tr -d '\r' | grep -i "^$hdr:" | cut -d: -f2- | xargs)
213
+ [ "$a" = "$b" ] || warn "$p $hdr: old='${a:-<none>}' candidate='${b:-<none>}'"
214
+ done
215
+ done
216
+ pass "header diff done (differences listed above, if any)"
217
+ fi
218
+ fi
219
+
220
+ printf '\n%s FAIL, %s WARN. Also run: deco schema --check && deco check. Browser checks (🧪) are in SKILL.md.\n' "$fails" "$warns"
221
+ [ "$fails" = "0" ]
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: deco-images-media
3
+ description: "Images and video on @decocms/blocks 8 sites. Covers @decocms/blocks/image (createImageUrl, ImageProvider, decoCdn with domain, quality, sources and legacyHosts; srcSet and preloadLink), platform providers listed before decoCdn (vtexCatalog and the other @decocms/apps-vtex/image providers, shopifyCdn from @decocms/apps-shopify/image), Image, Picture, Source and ImageUrlProvider from @decocms/tanstack/react, createDecoImageLoader for next/image from @decocms/nextjs/image-loader, quality tiers, sizes and LCP preload, video served by the Deco media host (audio stripped unless ?muted=false) with a plain <video>, and the v8 asset upload endpoint plus the procedure for moving assets to a new host and rewriting their URLs in .deco/blocks. Load it when images are blurry, slow, oversized or broken, when wiring images on a new v8 site, when a video has no sound, or for an asset migration."
4
+ ---
5
+
6
+ # Images and media on v8 sites
7
+
8
+ A v8 site builds **one `ImageUrl`** from a list of providers and hands it to its
9
+ binding. Every resized URL on the site comes from that one function. Most image
10
+ bugs on v8 come from three places: the provider list (a source no provider
11
+ matches is passed through at full size), the quality tier the Deco CDN is asked
12
+ for, and an uploaded source that is smaller than the slot needs.
13
+
14
+ ```ts
15
+ // src/imageUrl.ts — one per site
16
+ import { createImageUrl, decoCdn } from "@decocms/blocks/image";
17
+ import { vtexCatalog } from "@decocms/apps-vtex/image";
18
+
19
+ export const imageUrl = createImageUrl({
20
+ providers: [vtexCatalog(), decoCdn({ sources: "all", quality: "high" })],
21
+ });
22
+ ```
23
+
24
+ Providers are tried in order. The first one whose `match(src)` is true and whose
25
+ `format` returns a URL wins. Empty `src` gives `""`; `data:` URIs and sources
26
+ no provider matches come back unchanged.
27
+
28
+ ## When to load what
29
+
30
+ | Reference | Load it when |
31
+ |---|---|
32
+ | [`providers-and-cdn.md`](./references/providers-and-cdn.md) | Writing `imageUrl`, choosing `decoCdn` options, adding a VTEX or Shopify provider, writing a provider for another platform, CSP `img-src` |
33
+ | [`components-per-binding.md`](./references/components-per-binding.md) | Rendering images: `Image`/`Picture`/`Source` on TanStack, the next/image loader on Next.js, `srcSet`/`preloadLink` anywhere else; image fields in section props |
34
+ | [`quality-and-lcp.md`](./references/quality-and-lcp.md) | Picking quality tiers, per-image quality, `sizes`, preloading the LCP image |
35
+ | [`troubleshooting.md`](./references/troubleshooting.md) | Images are soft, pixelated, too heavy, 404/508, not resized, or shift the layout |
36
+ | [`video.md`](./references/video.md) | A video has no sound, autoplay does not start, or you are adding a video field |
37
+ | [`asset-upload.md`](./references/asset-upload.md) | Uploads from the site editor, or moving assets off an old host and rewriting URLs in `.deco/blocks` |
38
+
39
+ ## Rules that hold everywhere
40
+
41
+ - **One `ImageUrl` per site.** v7's `registerImageCdnDomain` and
42
+ `registerImageQuality` are gone. Their values are now `decoCdn({ domain, quality })`.
43
+ - **Platform providers go before `decoCdn`.** A provider with `sources: "all"`
44
+ matches every source, so anything listed after it never runs.
45
+ - **`decoCdn()` with no `sources` only resizes Deco-hosted URLs.** Other hosts
46
+ pass through at full size. The TanStack default (`DECO_IMAGE_URL`) uses
47
+ `sources: "all"`.
48
+ - **Quality on the Deco CDN is a tier name.** It ignores numbers.
49
+ - **Set `width` and `height`** on every image, so the browser reserves the box.
50
+ - **Preload one image per page**, the LCP one. Preloading more images makes them
51
+ compete for bandwidth.
52
+ - **Never send a video through `ImageUrl`.** `decoCdn` builds an `/image?…` URL
53
+ and drops the source's query string, `?muted=false` included.
54
+
55
+ ## Related skills
56
+
57
+ - `deco-tanstack-site` and `deco-nextjs-site`: where the binding is wired (root
58
+ document, `next.config`, CSP).
59
+ - `deco-cms-schema`: field annotations and help text editors see.
60
+ - `deco-site-workflow`: `deco pull`, `diff`, `push --draft`, `check`, `publish`.
61
+ - `deco-storefront-performance`: LCP and CLS beyond images.
62
+ - `deco-v7-to-v8-migration`: moving a v7 image helper to `createImageUrl`.
63
+ - `image-optimizer` (decocms/skills): generic HTML image practice (`srcset`,
64
+ `sizes`, `fetchpriority`, formats).
@@ -0,0 +1,191 @@
1
+ # Uploading assets and rewriting their URLs
2
+
3
+ Two jobs: how uploads work on v8, and how to move a set of assets to a new host
4
+ and point every block at the new URLs.
5
+
6
+ ## The v8 upload endpoint
7
+
8
+ Uploads sit beside the content protocol. The site editor sends each file as
9
+ `PUT /assets/<name>` to the content endpoint, with the file as the body and its
10
+ own `Content-Type`. Whether an endpoint takes uploads is in its `describe`
11
+ answer: `assets` is `{ dir, urlPrefix: "/assets/", maxBytes }`, or `null` when
12
+ the endpoint is read-only or uploads go to hosted storage.
13
+
14
+ What the handler enforces (`packages/blocks/src/protocol/server/assets.ts`,
15
+ naming rules in `protocol/assets.ts`):
16
+
17
+ | Rule | Detail |
18
+ |---|---|
19
+ | Method | `PUT` only; anything else gets 405. |
20
+ | Types | `image/png`, `image/jpeg`, `image/webp`, `image/avif`, `image/gif`, `image/x-icon`, `video/mp4`, `video/webm`, `font/woff2`, `font/woff`, `font/ttf`, `font/otf`, `application/pdf` and a few legacy font and icon types. Others get 415. |
21
+ | SVG | Refused unless the handler is created with `allowSvg`, because SVG can carry scripts that run on the site's origin. |
22
+ | Name | Last path segment only. Accents removed; anything but letters, digits, `.`, `_`, `-` becomes `-`; capped at 200 characters. |
23
+ | Extension | Must match the type (`banner.html` sent as `image/png` gets 415). A name without one gets the type's (`.jpg` for JPEG). The extension is lowercased. |
24
+ | Size | Up to `maxBytes`; 413 above it. Empty bodies are refused. |
25
+ | Collisions | Never overwrites. A taken name gets a random suffix: `banner-3f9a2c.jpg`. |
26
+ | Read-only endpoint | 403. Endpoint without uploads: 404. |
27
+ | Response | `201 { "path": "/assets/<stored name>" }`. That path is what the editor stores in the field. |
28
+
29
+ ### Where the file lands
30
+
31
+ With the filesystem storage (`@decocms/blocks/protocol/storage/fs`, which
32
+ serves a local working tree to the site editor), uploads go to
33
+ `public/assets/` under the app root, or the `assetsDir` option. The default
34
+ `maxBytes` is 25 MB (`assetsMaxBytes` option).
35
+
36
+ So a local upload is **a new file in the repository**, and the field holds the
37
+ relative path `/assets/<name>`. The site serves it from `public/` like any other
38
+ static file. Commit the file and deploy it with the code. If content that
39
+ points at `/assets/x.jpg` is published before the deploy that adds the file,
40
+ the image is a 404 in production until the deploy lands.
41
+
42
+ A relative `/assets/…` path is not a Deco-hosted URL, so the default `decoCdn()`
43
+ does not resize it (see [troubleshooting.md](./troubleshooting.md#not-resized)).
44
+ Upload images at the size they will be shown, or handle these paths with a
45
+ provider of your own.
46
+
47
+ For hosted drafts, `describe` reports `assets: null` and the editor uploads to
48
+ hosted storage. That storage is not part of this repository, so the URL format
49
+ it returns is not documented here. Read a field after uploading to see it.
50
+
51
+ ### What v8 does not have
52
+
53
+ - No `deco` CLI command uploads assets.
54
+ - `createAssetHandler` is internal to `@decocms/blocks` (not exported), so a site
55
+ cannot mount its own upload route from the package.
56
+ - The Fresh-era admin upload API and its cookie-based scripts are not part of
57
+ v8.
58
+
59
+ For bulk uploads to a hosted asset store, use that store's own tools and
60
+ then rewrite URLs as below.
61
+
62
+ ## Moving assets and rewriting URLs in `.deco/blocks`
63
+
64
+ Use this when assets move host: an old bucket shuts down, a migration from
65
+ another CMS, or URLs from a retired CDN. In one measured run, 1,060 assets moved
66
+ this way in about 5 minutes of upload time.
67
+
68
+ ### 0. Start from current content
69
+
70
+ On a site whose content lives in Studio, run `deco pull` first, so
71
+ `.deco/blocks` matches what is published and `deco push` sends only your
72
+ changes. On a site whose content is in git, work on a branch. The commands are
73
+ covered in `deco-site-workflow`.
74
+
75
+ ### 1. Inventory every reference
76
+
77
+ ```bash
78
+ mkdir -p .context
79
+ grep -rhoE 'https?://[a-zA-Z0-9.-]*old-host\.example[^"'"'"'[:space:]\\)]*' .deco/blocks src \
80
+ | sort -u > .context/old-urls.txt
81
+ wc -l .context/old-urls.txt
82
+ ```
83
+
84
+ Search code (`src`) too: hardcoded URLs move with the content.
85
+
86
+ Watch for **wrapped URLs**. Some transform services wrap the original with a
87
+ single slash, such as `https://transform.example/tr:w-1620/https:/old-host.example/a.jpg`.
88
+ The regex above misses the inner one. After the bulk pass, grep for the bare
89
+ host name, without a scheme.
90
+
91
+ ### 2. Upload each asset and record a mapping
92
+
93
+ For each URL: download it, read the real `Content-Type` (old URLs are often
94
+ UUIDs with no extension), give the file the matching extension, upload it,
95
+ and append one line to a mapping file:
96
+
97
+ ```json
98
+ {"old":"https://old-host.example/a/7f3c…","new":"https://<new host>/<path>/banner.jpg","mime":"image/jpeg"}
99
+ ```
100
+
101
+ Rules that save a rerun:
102
+
103
+ - Dedupe the inventory first (`sort -u`). Uploading a URL twice creates two
104
+ assets.
105
+ - Map MIME to extension from the download response, not from the URL. A file
106
+ saved as `.bin` will not render. On the v8 endpoint a wrong extension is
107
+ refused (415).
108
+ - Keep a separate error log, and retry only the failures.
109
+ - Run a few uploads in parallel (around 6), not hundreds. Watch for rate
110
+ limiting and expiring credentials in the error log.
111
+
112
+ ### 3. Check the mapping before touching any file
113
+
114
+ ```bash
115
+ # every URL was mapped
116
+ wc -l .context/old-urls.txt .context/asset-mapping.jsonl
117
+ diff <(sort -u .context/old-urls.txt) \
118
+ <(sed -n 's/.*"old":"\([^"]*\)".*/\1/p' .context/asset-mapping.jsonl | sort -u)
119
+ # every entry has a new URL
120
+ grep -cv '"new":"' .context/asset-mapping.jsonl # must print 0
121
+ ```
122
+
123
+ If any check fails, stop and fix the mapping first.
124
+
125
+ ### 4. Replace with plain strings, not regex
126
+
127
+ URLs are full of characters that mean something in regex and `sed` (`/`, `.`,
128
+ `?`, `&`). Use exact string replacement:
129
+
130
+ ```ts
131
+ // .context/rewrite.ts — run with: bun .context/rewrite.ts (or node)
132
+ import { readFileSync, readdirSync, writeFileSync } from "node:fs";
133
+ import { join } from "node:path";
134
+
135
+ const map = readFileSync(".context/asset-mapping.jsonl", "utf8")
136
+ .split("\n").filter(Boolean).map((l) => JSON.parse(l) as { old: string; new: string });
137
+ const dir = ".deco/blocks";
138
+ let total = 0;
139
+ for (const file of readdirSync(dir).filter((f) => f.endsWith(".json"))) {
140
+ const path = join(dir, file);
141
+ const before = readFileSync(path, "utf8");
142
+ let after = before;
143
+ for (const { old, new: next } of map) {
144
+ const n = after.split(old).length - 1;
145
+ if (n) { total += n; after = after.split(old).join(next); }
146
+ }
147
+ if (after !== before) writeFileSync(path, after);
148
+ }
149
+ console.log(`replaced ${total} references`);
150
+ ```
151
+
152
+ Write the file back byte for byte apart from the URLs: do not re-serialize
153
+ the JSON, so the git diff shows only the URL lines. (`deco diff` compares a
154
+ hash of each block's canonical JSON, so formatting alone does not show there.)
155
+
156
+ ### 5. Verify
157
+
158
+ ```bash
159
+ grep -rn "old-host.example" .deco/blocks src # expect nothing
160
+ ```
161
+
162
+ Anything left is usually a wrapped URL. Replace the whole wrapping URL with the
163
+ new one; the image CDN does the resizing, so the old transform wrapper is not
164
+ needed.
165
+
166
+ Then:
167
+
168
+ - `deco diff` lists changed blocks by name: only the blocks you expect
169
+ should be there. `git diff .deco/blocks` shows the lines.
170
+ - Open a few changed pages locally and check the images load.
171
+ - `deco push --draft=<name>`, then `deco check --draft=<name>` and preview the
172
+ draft. Nothing goes live until `deco publish --draft=<name>`.
173
+
174
+ `deco check` validates block structure, not URLs: image and video fields
175
+ accept any string. Checking that images load is up to you.
176
+
177
+ ### 6. Keep the mapping
178
+
179
+ `.context/` is often git-ignored. If the mapping matters later (rollback,
180
+ audit, a second pass over code), save it somewhere committed.
181
+
182
+ ## Pitfalls
183
+
184
+ | Pitfall | What happens | Fix |
185
+ |---|---|---|
186
+ | URL with no extension | File uploaded with the wrong type, or refused | Use the download's `Content-Type` |
187
+ | Same URL uploaded twice | Two assets, the mapping keeps one | Dedupe first, track in the mapping |
188
+ | Wrapped URLs | Stragglers after the bulk pass | Grep the bare host after step 4 |
189
+ | `sed` replacement | Broken URLs, partial matches | Plain string replacement |
190
+ | Credentials expire mid-run | Uploads start failing quietly | Watch the error log, retry failures |
191
+ | Publishing before the files exist | 404 images in production | Upload and deploy first, publish content last |
@@ -0,0 +1,167 @@
1
+ # Components per binding
2
+
3
+ `@decocms/blocks/image` builds URLs. Each binding turns them into markup its own
4
+ way. In every case the binding gets the site's `ImageUrl` (see
5
+ [providers-and-cdn.md](./providers-and-cdn.md)); it knows no commerce platform
6
+ itself.
7
+
8
+ ## TanStack Start: `@decocms/tanstack/react`
9
+
10
+ Exports: `Image`, `Picture`, `Source`, `ImageUrlProvider`, `useImageUrl`,
11
+ `DECO_IMAGE_URL`, and the prop types `ImageProps`, `PictureProps`,
12
+ `SourceProps`. They keep v7's props and markup, so a v7 call site moves by
13
+ changing the import.
14
+
15
+ ### Wire the site's `ImageUrl` once
16
+
17
+ ```tsx
18
+ // src/router.tsx
19
+ import { ImageUrlProvider } from "@decocms/tanstack/react";
20
+ import { createDecoRouter } from "@decocms/tanstack/router";
21
+ import { imageUrl } from "./imageUrl";
22
+
23
+ createDecoRouter({
24
+ routeTree,
25
+ Wrap: ({ children }) => <ImageUrlProvider value={imageUrl}>{children}</ImageUrlProvider>,
26
+ });
27
+ ```
28
+
29
+ Without a provider, components use `DECO_IMAGE_URL`:
30
+ `createImageUrl({ providers: [decoCdn({ sources: "all" })] })`. That sends
31
+ every source, VTEX and Shopify images included, through
32
+ `assets.decocms.com` with no quality tier. A storefront almost always wants its
33
+ own `imageUrl` with the platform provider first.
34
+
35
+ `ImageUrlProvider` is a React context. A nested provider overrides it for one
36
+ subtree, which is how you give one area a different tier (see
37
+ [quality-and-lcp.md](./quality-and-lcp.md)). `useImageUrl()` returns the nearest
38
+ one, for code that needs a URL outside the components (a CSS background, an
39
+ Open Graph tag).
40
+
41
+ ### `Image`
42
+
43
+ ```tsx
44
+ <Image src={src} width={640} height={480} alt={alt} />
45
+ ```
46
+
47
+ | Prop | Default | Effect |
48
+ |---|---|---|
49
+ | `src`, `width` | required | `width` is the 1x width and the base of the srcset. |
50
+ | `height` | none | Sent to the provider and set on the `<img>`. |
51
+ | `fit` | `"cover"` | Passed to the provider. |
52
+ | `preload` | `false` | Renders a `<link rel="preload" as="image">` next to the `<img>`, and sets `loading="eager"` and `fetchPriority="high"`. |
53
+ | `media` | none | `media` on that preload link. |
54
+ | `sizes` | `"(max-width: 768px) 100vw, 50vw"` when there is a srcset | Override it to match the real layout. |
55
+ | `srcSet` | built | Overrides the generated srcset. |
56
+ | `loading` | `"lazy"`, or `"eager"` with `preload` | |
57
+ | `decoding` | `"async"` | |
58
+
59
+ Every other `<img>` attribute passes through. There is **no `quality` prop**:
60
+ quality comes from the `ImageUrl`.
61
+
62
+ The generated srcset has two width candidates, `width` and `2 × width`
63
+ (`height` scaled the same way), written as `<url> 640w, <url> 1280w`.
64
+
65
+ ### `Picture` and `Source`
66
+
67
+ Art direction: one `Source` per media query and an `Image` fallback.
68
+
69
+ ```tsx
70
+ <Picture preload={isLcp}>
71
+ <Source media="(max-width: 767px)" src={mobile} width={375} height={184} />
72
+ <Source media="(min-width: 768px)" src={desktop} width={1280} height={480} />
73
+ <Image src={desktop} width={1280} height={480} alt={alt} />
74
+ </Picture>
75
+ ```
76
+
77
+ With `<Picture preload>`, each `Source` renders its own preload link with its
78
+ `media`, so the browser preloads only the one that applies. `Source` takes
79
+ `src`, `width`, `height`, `fit` (default `"cover"`), `fetchPriority` and any
80
+ `<source>` attribute. Do not also set `preload` on the fallback `Image` inside a
81
+ preloading `Picture`: that adds a second preload with no `media`.
82
+
83
+ ## Next.js: `@decocms/nextjs/image-loader`
84
+
85
+ next/image renders the markup; Deco only provides the loader.
86
+
87
+ ```ts
88
+ // src/image-loader.ts
89
+ import { createDecoImageLoader } from "@decocms/nextjs/image-loader";
90
+ import { imageUrl } from "./imageUrl";
91
+ export default createDecoImageLoader(imageUrl);
92
+ ```
93
+
94
+ ```js
95
+ // next.config: images: { loader: "custom", loaderFile: "./src/image-loader.ts" }
96
+ ```
97
+
98
+ The loader receives `{ src, width, quality }` from next/image:
99
+
100
+ - If `imageUrl.isOptimizable(src)`, it returns `imageUrl(src, { width, quality })`.
101
+ next/image passes no height or fit, so providers get width only.
102
+ - Otherwise it calls `fallback(props)`. With no `fallback`, or one that returns
103
+ `null`, `src` comes back unchanged.
104
+
105
+ For local `/public` files or other hosts no provider handles, use Next's own
106
+ optimizer as the fallback:
107
+
108
+ ```ts
109
+ import { createDecoImageLoader, nextImageOptimizer } from "@decocms/nextjs/image-loader";
110
+ export default createDecoImageLoader(imageUrl, { fallback: nextImageOptimizer });
111
+ ```
112
+
113
+ `nextImageOptimizer` builds `/_next/image?url=&w=&q=`, turning tiers into
114
+ 60/70/80/100. The host still has to be allowed in `images.remotePatterns`.
115
+
116
+ Quality: next/image's `quality` prop is a number. `decoCdn` ignores numbers, so
117
+ on Deco-CDN images the tier set in `decoCdn({ quality })` decides.
118
+ `vtexCatalogWebp` and `vtexFileManager` do read numbers; `vtexCatalog`,
119
+ `vtexCatalogFrame` and `shopifyCdn` ignore quality.
120
+
121
+ `sizes`, priority and preload are next/image's own props; follow the Next.js
122
+ docs for your version. Wiring `next.config` is covered in `deco-nextjs-site`.
123
+
124
+ ## Any other renderer: `srcSet` and `preloadLink`
125
+
126
+ Both take the `ImageUrl` as the first argument.
127
+
128
+ ```ts
129
+ import { srcSet, preloadLink, parseSrcSet } from "@decocms/blocks/image";
130
+
131
+ srcSet(imageUrl, src, { width: 640, height: 480 }); // factors [1, 2]
132
+ srcSet(imageUrl, src, { widths: [320, 640, 1280], ratio: 0.75 }); // explicit widths, height = round(w × ratio)
133
+ preloadLink(imageUrl, src, { width: 1280, sizes: "100vw", media: "(min-width: 768px)" });
134
+ ```
135
+
136
+ - `srcSet` options: `width`, `widths` (wins over `width` and `factors`),
137
+ `factors` (default `[1, 2]`, truncated), `height`, `ratio`, `fit`, `quality`.
138
+ Returns `undefined` for an empty `src` or no candidates. Without `width` or
139
+ `widths` it writes `NaN` candidates, as v7 did: always pass one.
140
+ - `preloadLink` returns `{ rel: "preload", as: "image", href, imageSrcSet?,
141
+ imageSizes?, media?, fetchPriority }`, `fetchPriority` defaulting to
142
+ `"high"`. Spread it into a `<link>` or a route's head links.
143
+ - `parseSrcSet(s)` splits a srcset attribute into `{ url, w?, x? }`, keeping
144
+ URLs with commas whole. Useful in tests.
145
+
146
+ ## Image fields in section props
147
+
148
+ The schema generator gives an image picker to a string prop typed with the
149
+ alias `ImageWidget`, and a video picker to `VideoWidget`. Both are exported
150
+ from `@decocms/compat-v7/types/widgets` (plain `string` aliases).
151
+ `@format image-uri` or `@format video-uri` on a string does the same.
152
+
153
+ ```ts
154
+ import type { ImageWidget } from "@decocms/compat-v7/types/widgets";
155
+
156
+ interface Props {
157
+ /** @description Desktop image, at least 2560×960 (2× the 1280×480 slot) */
158
+ image: ImageWidget;
159
+ alt: string;
160
+ }
161
+ ```
162
+
163
+ `deco check` does not validate these values: `image-uri` and `video-uri` accept
164
+ any string, so a broken URL passes the check. Put the 2x pixel size in the
165
+ field's `@description` (the generated schema carries it to the editor's form), so
166
+ editors upload large enough files. Field annotations in general are in
167
+ `deco-cms-schema`.