@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,183 @@
1
+ # React and SPA leftovers
2
+
3
+ A Fresh site rendered islands on full page loads and tolerated Preact habits.
4
+ A v8 TanStack site is React with client-side navigation: components are reused
5
+ across routes, inline scripts inserted on the client don't run, and React is
6
+ strict about controlled inputs and hydration. Most of these pass a reload test
7
+ and fail on a **SPA click**.
8
+
9
+ Always test by clicking links the app rendered. A `click()` on an `<a>` you
10
+ appended to `body` does a full reload. Confirm SPA navigation with
11
+ `performance.getEntriesByType("navigation").length === 1` after the click.
12
+
13
+ How to write sections and client components on v8 is in
14
+ **deco-site-authoring**; this file is only the go-live sweep.
15
+
16
+ ## Preact and Fresh leftovers
17
+
18
+ Found by a Playwright sweep, production against local, on one store:
19
+
20
+ | Symptom | Root cause | Fix |
21
+ |---|---|---|
22
+ | Typing in an input erases every letter | `value={…}` without `onChange` (Preact tolerated it; React makes it read-only) | `defaultValue` |
23
+ | Modal or zoom never opens on mobile | a controlled checkbox (`open={false}`) without `onChange` | uncontrolled, `defaultChecked` |
24
+ | "Add to cart" from a secondary component does nothing | `window.STOREFRONT.CART.addToCart` or `window.addToCart`: the Fresh global SDK doesn't exist | call the site's cart server function |
25
+ | A form does nothing | `hx-post` replaced by `preventDefault` and a TODO | wire it to a server function |
26
+ | A popup library never loads | `<script src>` inside a client-rendered section never runs | load it on demand |
27
+ | A label doesn't open its modal | raw HTML strings with `htmlFor` or `className` | `for` and `class` inside strings |
28
+ | An error on every keystroke | `onInput={useScript(...)}` passes a string as the handler | a function handler |
29
+ | The second lookup never renders | code removed React-owned DOM children by hand | reset state |
30
+ | Search steals focus every 300 ms | `setInterval(focus)` never cleared | bounded attempts, cancel on close and navigation |
31
+ | A double click adds two items | no in-flight guard | pending guards |
32
+ | A click before hydration is lost | | read `el.checked` on mount |
33
+
34
+ ```bash
35
+ grep -rnE "window\.STOREFRONT|window\.addToCart|hx-(post|get|on|trigger)" src
36
+ grep -rnE "on[A-Z][a-zA-Z]+=\{useScript" src
37
+ grep -rnE "open=\{false\}" src
38
+ grep -rnE "<script[^>]+src=" src
39
+ grep -rnE "\.removeChild\(|\.innerHTML\s*=|replaceChildren\(" src
40
+ ```
41
+
42
+ For `value=` without `onChange`, run dev with the console open on every form.
43
+ React warns: "You provided a `value` prop without an `onChange` handler".
44
+
45
+ ## Inline scripts do not run on SPA navigation
46
+
47
+ `useScript` and `useScriptAsDataURI` still exist in `@decocms/compat-v7`
48
+ (v7's output, byte for byte), and `inlineScript(js)` is the string form they
49
+ point to. React inserts a `<script>` on the client without running it. Only
50
+ scripts parsed from the server HTML run. Seen: a countdown frozen at
51
+ 00:00:00, a header under the timer, a sticky gallery that never shrinks. All
52
+ fine after F5.
53
+
54
+ Pattern: keep the inline script for the first paint, make it idempotent, and
55
+ also run it from `useLayoutEffect` with a cleanup.
56
+
57
+ ```tsx
58
+ const init = (id: string) => {
59
+ const el = document.getElementById(id) as (HTMLElement & { __started?: boolean; __stop?: () => void }) | null;
60
+ if (!el || el.__started) return; // idempotent
61
+ el.__started = true;
62
+ const stops: (() => void)[] = [];
63
+ el.__stop = () => stops.forEach((s) => s()); // remove listeners and observers
64
+ // ...
65
+ };
66
+ useLayoutEffect(() => { init(id); return () => document.getElementById(id)?.__stop?.(); }, []);
67
+ ```
68
+
69
+ `useScript(fn)` serializes `fn.toString()`, which can differ between the
70
+ server and the client build and break hydration. Its own docs mark it
71
+ deprecated in favor of `inlineScript` with a plain string.
72
+
73
+ ```bash
74
+ grep -rlnE "useScript\(|useScriptAsDataURI\(|inlineScript\(|<script" src
75
+ ```
76
+
77
+ 🧪 For each hit: reach the page by a SPA click and check it works. Go
78
+ listing → product → back three times; listener counts must stay flat.
79
+
80
+ ## Same-route navigation reuses components
81
+
82
+ Product → product is the same route (the catch-all), so the page component is
83
+ reused.
84
+
85
+ 1. `<img>` nodes reused with a new `src` show the previous product's photos for about 1.2 s. Fix: a `key` per product group on the gallery.
86
+ 2. `if (!items.length) return null` **before** a hook: an instance moving from a product without that block to one with it calls more hooks → React error #310, and the page renders only header and footer. One store had 13 more components with the same pattern.
87
+
88
+ ```tsx
89
+ <Gallery key={product.inProductGroupWithID ?? product.productID} … />
90
+ ```
91
+
92
+ ```bash
93
+ grep -rn "rules-of-hooks" eslint.config.* .eslintrc* biome.json 2>/dev/null || echo "rules-of-hooks not enabled"
94
+ ```
95
+
96
+ Test any home-made scan against a known bug first. One awk scan "passed" with
97
+ zero hits because macOS awk did not support the regex.
98
+
99
+ 🧪 SPA-click product → product between products **with and without**
100
+ optional blocks (video, size guide); the first gallery `<img>` must change.
101
+
102
+ ## Hydration error #418
103
+
104
+ **What happened** (~2,750 users a day, 90% on mobile listings): tag-manager
105
+ scripts appended to `body` during parse landed between `</main>` and React's
106
+ own tail scripts. React claimed them during hydration → #418, and the whole
107
+ page re-rendered on the client.
108
+
109
+ - Keep every node after `<main>` one React rendered. `DecoDocument` renders its `children` after the page; put the site's own trailing UI there, not in raw HTML.
110
+ - CMS or platform HTML with unbalanced tags in `dangerouslySetInnerHTML` → balance it before rendering; truncate HTML at word boundaries, not as plain text.
111
+ - Block HTML inside `<p>` breaks the parse → use `<div>`.
112
+ - `location.origin` read during SSR → pass the origin in.
113
+
114
+ ```bash
115
+ grep -rn "dangerouslySetInnerHTML" src
116
+ ```
117
+
118
+ 🧪 Mobile emulation, 6× CPU, tag manager on, scroll during load, about 20
119
+ listing loads: zero #418. After hydration, any third-party `<script>` in
120
+ `document.body.children` with a `__reactFiber$*` key is a bug.
121
+
122
+ ## Server functions cancelled on navigation
123
+
124
+ **What happened:** a TanStack server function is cancelled when the user
125
+ navigates away mid-request. Cancelled at 50–250 ms, it never reached the
126
+ platform. "+" then "checkout" lost the item. Also, on Fresh the add-to-cart
127
+ call was not awaited, so the "added" sheet opened at once; awaited, it opened
128
+ 0.7 s late.
129
+
130
+ - Open the UI optimistically before the `await`; close it on failure.
131
+ - Track pending cart writes; full-page links (especially checkout) wait for them.
132
+ - `fetch(..., { keepalive: true })` on `pagehide` for writes.
133
+
134
+ 🧪 WebKit: change the quantity and click "checkout" within 300 ms. The
135
+ checkout shows the new quantity.
136
+
137
+ ## Stale chunks after deploy
138
+
139
+ Every deploy removes old hashed chunks. Open tabs then get 404s on
140
+ `/assets/*.js` (103 to 254 per deploy on one store). The router reloads only
141
+ on route-chunk failures; a lazy section's chunk fails into the error boundary
142
+ (a product page without photos, price or buy button). The v8 packages add no
143
+ handler for this.
144
+
145
+ - Listen to Vite's `vite:preloadError` and reload once per chunk, guarded in `sessionStorage` with a cooldown of about 30 s.
146
+ - Add a small inline guard in `<head>` for when the main entry itself 404s.
147
+
148
+ 🧪 Open a tab, deploy, then SPA-navigate in that tab to a page with lazy
149
+ sections.
150
+
151
+ ## Preload on intent
152
+
153
+ `createDecoRouter` defaults to `defaultPreload: "intent"`: hovering a link
154
+ loads that page's data. On v7, intent preload cost one store 197 GB of egress
155
+ in 2.5 days (each hover fetched a 1.6 MB product payload). Measure the
156
+ payload of a page load before go-live. If it is large, trim it
157
+ (**deco-storefront-performance**) or pass `defaultPreload: false`.
158
+
159
+ ## Browser memory leaks
160
+
161
+ **What happened (minicart):** 1–2 GB per open; the browser died at 3–4 GB.
162
+
163
+ - Signal shims (`useSignalEffect`, `useComputed` without deps) → render loops.
164
+ - A store hook expecting `{ unsubscribe }` while the source returns a function → subscriptions pile up. Use `useSyncExternalStore` with a stable `subscribe`.
165
+ - Every cart item re-rendered on open and close → make open/close CSS-only and memoize the list.
166
+ - `removeEventListener` with a new arrow function does nothing → keep the reference.
167
+
168
+ 🧪 DevTools Memory: open and close the minicart 10 times with the tag manager
169
+ on; a heap snapshot before and after must be flat.
170
+
171
+ ## Legacy service worker
172
+
173
+ An old site's service worker kept intercepting requests on one store.
174
+ Removing `register()` does not uninstall it for past visitors. Ship a `sw.js`
175
+ at the same path that unregisters itself.
176
+
177
+ ```js
178
+ self.addEventListener("install", () => self.skipWaiting());
179
+ self.addEventListener("activate", async () => {
180
+ await self.registration.unregister();
181
+ (await self.clients.matchAll()).forEach((c) => c.navigate(c.url));
182
+ });
183
+ ```
@@ -0,0 +1,114 @@
1
+ # SEO, analytics and search parity
2
+
3
+ Analytics and SEO break **silently** at cutover: no error, no 5xx, just a
4
+ lower number in a dashboard days later. Compare with the old site, not with
5
+ expectations. On-page SEO (titles, canonical, JSON-LD) is written in
6
+ **deco-site-authoring**; this file is the go-live comparison.
7
+
8
+ ## Tag manager timing
9
+
10
+ **What happened:** a performance change loaded the tag manager only on the
11
+ first user gesture. Shoppers reached checkout without the cookies its tags set
12
+ (an A/B tool, consent, affiliates, about 15 ad platforms). Orders per visitor
13
+ fell from 0.51% to 0.41%: **about 20% of orders**. Even ungated, the snippet
14
+ sat at 68% of the HTML and started at 2.2 to 2.7 s.
15
+
16
+ - Load the tag manager from `<head>`, as the old site did, with no gesture or idle gate. Accept the lab-score cost unless a conversion test says otherwise.
17
+ - Don't load the same script twice (eagerly and from a component).
18
+ - SPA: your own page-view event must fire again on client navigation. `DecoDocument` ships v7's `DECO.events` bus and `dataLayer`, and an observer that dispatches the events elements declare with `data-event` (on view, or on click with `data-event-trigger="click"`); it watches the DOM with a `MutationObserver`, so elements a navigation adds are covered.
19
+ - Send tracker payloads in the format the old site used. On one store `add_to_cart` was dropped silently (1 of 587 buyers tracked, against 635 of 679 before).
20
+
21
+ ```bash
22
+ grep -rnE "requestIdleCallback|first.?interaction|pointerdown|onFirstGesture" src | grep -iE "gtm|tag|analytics"
23
+ curl -s "$CANDIDATE/" | grep -o "googletagmanager.com/gtm.js[^\"']*" | head -1
24
+ ```
25
+
26
+ 🧪 Playwright with no gesture: the tag-manager script is requested within
27
+ about 500 ms of the first byte, as on the old site. After the same journey on
28
+ both stacks, compare `document.cookie` names at checkout entry.
29
+
30
+ ## Vendors that stop silently
31
+
32
+ | What happened | Fix |
33
+ |---|---|
34
+ | the analytics section was never rendered after the port (two stores) | render the tag manager in the root document; its `<noscript>` right after `<body>` |
35
+ | a vendor the old framework mounted on its own sent zero events, and A/B results were lost | mount every vendor explicitly in the root document |
36
+ | a vendor's `defer` script, while the vendor was down, held `DOMContentLoaded` for ~211 s | load third-party scripts `async` |
37
+ | UTMs did not reach the order form's marketing data | read, merge, write before checkout |
38
+
39
+ ```bash
40
+ curl -s "$CANDIDATE/" | grep -oE "googletagmanager|<vendor-marker>" | sort | uniq -c
41
+ ```
42
+
43
+ The day after go-live, check each vendor's own report against the same day
44
+ last week.
45
+
46
+ ## Indexability and status codes
47
+
48
+ - **At ratio 0 the public host served `noindex` and `Disallow: /`** because the old site decided indexability from its own hostname. The v8 split handler sends `x-forwarded-host`; confirm the old site reads it. Check this **before** creating the route ([traffic-ramp.md](./traffic-ramp.md#traps)).
49
+ - Previews are `noindex` on purpose: any request with `?__draft=` (`off` included) or the draft cookie answers `X-Robots-Tag: noindex, nofollow`. A crawler never has the cookie, but a shared preview link does carry `?__draft=`.
50
+ - Soft 404s: a catch-all that renders "not found" with HTTP 200. On TanStack, a route sets the response's status with the `x-page-status` header (`PAGE_STATUS_HEADER`), which the worker turns into the status. A status set while rendering does not reach the response.
51
+ - A loader failure must not be cached as "not found": a page whose loader failed sets `x-deco-degraded` (`DEGRADED_HEADER`), and the example `pageCache` never stores it (**deco-storefront-caching**). Check that yours does the same.
52
+ - Pagination `rel=next/prev` and canonical lost in the port: compare the head of a listing's page 2 on both sides.
53
+
54
+ ```bash
55
+ curl -s -A Googlebot "https://$HOST/robots.txt" | head
56
+ curl -s -A Googlebot "https://$HOST/" | grep -io '<meta[^>]*robots[^>]*>'
57
+ curl -sI "https://$HOST/" | grep -i x-robots-tag # nothing on a published page
58
+ for p in /category-that-does-not-exist /product-that-does-not-exist/p /blog; do
59
+ curl -s -o /dev/null -w "$p %{http_code}\n" "$CANDIDATE$p"; done # compare with the old site
60
+ ```
61
+
62
+ ## Redirect sweep
63
+
64
+ On v8 the routed redirects are the rules of the one saved block of type
65
+ `redirects` (`Redirects` by convention). The worker answers them before any
66
+ route. Rules from the old site behave differently in a few places:
67
+
68
+ - **Earlier rule wins.** For two rules with the same `from` (or two templates of one shape), routing keeps the earlier one. `deco check` does not flag duplicates inside the redirects block (it reports conflicts only between separate `redirect` blocks), so dedupe the list yourself. A CSV that relied on "last one wins" changes destinations; on one store reordering changed 88 of them.
69
+ - **Self-loops are dropped.** A rule whose `to` is the path its `from` matches is ignored.
70
+ - **Query-scoped sources match exactly.** `from: "/shoes?map=c"` matches only that exact query string and wins over a path-only `/shoes`.
71
+ - **The visitor's query string is carried over** unless the rule sets `discardQueryParameters`, so `gclid` survives.
72
+ - **A full URL in `from`** (`https://…`) never matches a request path. Rewrite it as a path or drop it.
73
+ - **Status:** `permanent: true` is 301, otherwise 307; `status` (301, 302, 307 or 308) wins.
74
+ - **Old block types are not routed.** `deco check` warns about v7 redirect blocks (`website/loaders/redirect.ts`, `website/loaders/redirects.ts`), per-rule `redirect` blocks and a second `redirects` block. Fold them into the one block.
75
+
76
+ ```bash
77
+ deco check 2>&1 | grep -iE "redirect" # leftover v7 or extra redirect blocks
78
+ jq -r '.redirects[] | (.from // .redirect.from)' .deco/blocks/Redirects.json | sort | uniq -d # duplicate sources
79
+ ```
80
+
81
+ Then sweep **every** rule against the old site in production (status and
82
+ final `Location`), not a sample:
83
+
84
+ ```bash
85
+ jq -r '.. | objects | select(has("from") and has("to")) | .from' .deco/blocks/Redirects.json \
86
+ | grep -vE ':|\*' | while read -r from; do
87
+ a=$(curl -s -o /dev/null -w "%{http_code} %{redirect_url}" "$OLD$from")
88
+ b=$(curl -s -o /dev/null -w "%{http_code} %{redirect_url}" "$CANDIDATE$from")
89
+ [ "${a/$OLD/}" = "${b/$CANDIDATE/}" ] || echo "DIFF $from | $a | $b"
90
+ done
91
+ ```
92
+
93
+ (Templates with `:name` or `*` are skipped by the `grep`; test a few by hand.)
94
+
95
+ ## Sitemaps
96
+
97
+ - The old framework's sitemap handlers do not exist on v8. Serve the sitemap from a real route, or from `createDecoWorker({ routes })`. A static `public/sitemap.xml` left in the repo masks a missing route.
98
+ - Stream sitemap responses. `.text()` on the whole XML ran the worker out of memory on two stores.
99
+
100
+ ```bash
101
+ curl -s "$CANDIDATE/sitemap.xml" | grep -o "<loc>[^<]*" | sed 's/<loc>//' | head -200 | while read -r u; do
102
+ curl -s -o /dev/null -w "%{http_code} $u\n" "$u"; done | grep -v "^200"
103
+ ```
104
+
105
+ ## Search and listing behavior
106
+
107
+ From one store's fixes after launch:
108
+
109
+ - A facet change must **delete `page`** and keep `q`, `sort` and other params. Filtering from page 2 returned 0 results.
110
+ - "Did you mean" only on a confirmed zero total of an unfiltered, first-page text search. Never rewrite filtered URLs.
111
+ - Autocomplete must query the **typed term**, and fall back to the top suggestion only when it is empty.
112
+ - Some search APIs reject large page sizes (one returned 400 above 50). Batch SKU lists, and filter out missing products after sorting: one missing SKU broke a whole wishlist.
113
+ - Total counts that include out-of-stock items while the grid shows only in-stock ones confuse pagination.
114
+ - Empty CMS rules render empty boxes. Guard empty text in code.
@@ -0,0 +1,87 @@
1
+ # Traffic ramp: splitting the host with the old site
2
+
3
+ During the ramp the new worker takes every request on the production host and
4
+ sends a share of visitors to the old origin. On a TanStack site this is
5
+ `abTestingRoutes` from `@decocms/compat-v7/tanstack/worker`, v7's
6
+ `withABTesting` as a `routes` handler for `createDecoWorker`.
7
+
8
+ ```ts
9
+ // src/worker-entry.ts
10
+ import { abTestingRoutes } from "@decocms/compat-v7/tanstack/worker";
11
+
12
+ const abTesting = abTestingRoutes({
13
+ worker: () => worker,
14
+ kvBinding: "SITES_KV", // the default
15
+ shouldBypassAB: (_request, url) => isNewSiteOnly(url.pathname),
16
+ });
17
+
18
+ const worker = createDecoWorker({
19
+ // …
20
+ routes: async (request, env, ctx) => (await abTesting(request, env, ctx)) ?? siteRoutes(request),
21
+ });
22
+ export default worker;
23
+ ```
24
+
25
+ ## How a visitor gets a bucket
26
+
27
+ - The config is a KV entry under the request's **hostname**: `{ workerName, fallbackOrigin, abTest: { ratio } }`, with `ratio` from 0 to 1. Without the binding, without an entry for the host, or without `fallbackOrigin`, the handler returns `null` and the worker serves everyone.
28
+ - The bucket comes from, in order: the `?_deco_bucket=worker|fallback` override; the `_deco_bucket=<bucket>:<ratio %>` cookie, if it was set under the current ratio; the FNV-1a hash of `cf-connecting-ip` against the ratio (a random draw without that header).
29
+ - Every answer that goes through the split carries `x-deco-bucket` (a bypassed request does not). The cookie is set again when the bucket or the ratio changed, so changing the ratio re-draws everyone.
30
+ - The "worker" bucket is the worker called back, so it goes on to the site's other routes, its page cache and the page. If that call throws and `circuitBreaker` is on (the default), the visitor gets the old origin, tagged `fallback`.
31
+ - The "fallback" bucket gets `proxyToFallback`: the request goes to `fallbackOrigin` with `x-forwarded-host` set to the public host, redirects are not followed, and the old hostname is rewritten back to the public one in `Set-Cookie` domains, `Location`, and the text of 2xx bodies (streamed).
32
+
33
+ ## Traps
34
+
35
+ **The worker answers some paths before the split.** `createDecoWorker` runs,
36
+ in this order: `/deco/_liveness`; a 404 for v7's admin paths (`/deco/*`,
37
+ `/live/*`, `/.decofile`); the CMS redirects; then `routes`. So:
38
+
39
+ - An old page served from the fallback bucket that calls `/live/invoke/...`, `/deco/render` or any other `/live/*` or `/deco/*` path on the same host gets a 404 from the worker. Those calls never reach the old origin. Test the fallback bucket's interactions (add to cart, partial loads, forms) at 0%, before any visitor is on it.
40
+ - The new site's redirects apply to both buckets. A rule meant for the new URL scheme also redirects visitors on the old site.
41
+
42
+ **`shouldBypassAB` reads backwards.** `true` means "serve from this worker,
43
+ skip the draw". Return `true` for routes that exist only on the new site
44
+ (headless login and account routes, the sitemap, the platform proxies the new
45
+ site owns). Leave shared proxies (checkout, `/api`) in the draw unless both
46
+ buckets can use the new site's proxy.
47
+
48
+ **Old-site responses leave like any route response.** The worker adds
49
+ `CDN-Cache-Control: no-store` when the old origin sets none. On an HTML
50
+ response it also adds each of its security headers the old origin did not
51
+ set, including `Cross-Origin-Opener-Policy: same-origin-allow-popups` and a
52
+ `Content-Security-Policy` with a `frame-ancestors` list. Diff the old site's headers through the worker
53
+ against the old site direct ([proxy-headers-checkout.md](./proxy-headers-checkout.md#header-diff-against-the-old-site)).
54
+
55
+ **Indexing at 0%.** The old site may decide `noindex` from its own hostname.
56
+ It receives `x-forwarded-host` with the public host; confirm it honors it.
57
+ Check `robots.txt` and the robots meta on the public host before you create the
58
+ route ([seo-analytics.md](./seo-analytics.md#indexability-and-status-codes)).
59
+
60
+ **Existing proxies.** Checkout, `/api`, media: test each in both buckets. On
61
+ one store the split broke proxies the site already had.
62
+
63
+ ## Forcing a bucket
64
+
65
+ ```bash
66
+ for b in worker fallback; do
67
+ for p in / /checkout/ /robots.txt /sitemap.xml; do
68
+ curl -s -o /dev/null -D - "https://$HOST$p?_deco_bucket=$b" \
69
+ | tr -d '\r' | awk -v b="$b" -v p="$p" '/^HTTP/{s=$2} tolower($1)=="x-deco-bucket:"{x=$2} END{print b, p, s, x}'
70
+ done
71
+ done
72
+ ```
73
+
74
+ The override also sets the cookie, so a browser stays in the forced bucket
75
+ for the next pages. Clear `_deco_bucket` to get a fresh draw.
76
+
77
+ ## Rollback
78
+
79
+ Set `abTest.ratio` to `0` in the host's KV entry: every visitor without a
80
+ current cookie draws `fallback`, and old cookies were set under another ratio,
81
+ so they draw again. If the split handler was removed from the code, rollback is
82
+ a code rollback instead; know which one you have.
83
+
84
+ ## After 100%
85
+
86
+ Keep the handler at ratio 1 for a few days (a rollback is then one KV write),
87
+ then remove it and the KV entry in a normal deploy.
@@ -0,0 +1,93 @@
1
+ # Worker runtime: memory, shared state, deadlines, observability
2
+
3
+ A Worker isolate has **128 MB**, serves many requests at once, and can be
4
+ recycled at any time. Whatever was fine in a long-lived server process is a
5
+ risk here. These checks apply to a TanStack site behind `createDecoWorker`
6
+ from `@decocms/tanstack/worker`. On Next.js, see **deco-nextjs-site** for the
7
+ runtime it deploys to.
8
+
9
+ ## Memory: 128 MB per isolate
10
+
11
+ What filled memory on storefronts that went live:
12
+
13
+ | Symptom | Root cause | Fix |
14
+ |---|---|---|
15
+ | `exceededMemory` at go-live (~147 MB resident) | the whole content (~9.6 MB of JSON, far more once parsed) in the bundle **and** a second copy loaded at runtime | one copy only. On v8, `createCMS({ site })` keeps content out of the bundle |
16
+ | OOM on one landing page | a block asked the commerce API for `count: 100`: an 11 MB response, ~90 MB of objects | cap counts in code (≤ 48) and include the cap in the cache key |
17
+ | OOM on the sitemap (two stores) | `await upstream.text()` and `replaceAll` on the whole XML | stream: `new Response(upstream.body)` or a `TransformStream` |
18
+ | Redirect table in memory (~18k rows) | the table bundled as code | keep it in the redirects block (content), not in a bundled module |
19
+
20
+ What v8 itself holds per isolate: hosted block bodies in an LRU bounded at
21
+ 32 MB of JSON text (parsed objects take more), and the release index. Measure
22
+ the rest.
23
+
24
+ ```bash
25
+ ls -la dist/server/ 2>/dev/null; find dist -name '*.js' -size +2M 2>/dev/null # anything big in the bundle?
26
+ grep -rnE "\.deco/blocks/[^\"']+\.json|blocks\.gen" src # content bundled into the worker
27
+ grep -rnE "\.text\(\)" src | grep -iE "sitemap|proxy|upstream" # large bodies buffered
28
+ grep -rhoE '"count":\s*[0-9]+' .deco/blocks | sort | uniq -c | sort -rn | head # big counts in content
29
+ ```
30
+
31
+ Go-live gate: memory under about 80% of the limit during a load test on the
32
+ candidate. Raising the memory limit hides the cause; find what fills memory.
33
+
34
+ ## Module-scope state leaks between users
35
+
36
+ One isolate serves many users at once. One store leaked **personal data**
37
+ because `new QueryClient()` sat at module scope in `src/router.tsx`.
38
+
39
+ ```bash
40
+ grep -rn "new QueryClient" src/ # must be inside getRouter(), passed through createDecoRouter({ context })
41
+ grep -rnE "^(export )?(const|let) [a-zA-Z_]+ = new (Map|Set|WeakMap)\(" src/ | grep -v test
42
+ ```
43
+
44
+ A module-level `Map` or cache may hold only data that is the same for every
45
+ user. Test with two session cookies against one warm isolate.
46
+
47
+ Workers also refuse random values at module scope ("Disallowed operation
48
+ called within global scope"). Draw them on the first request, as
49
+ `abTestingRoutes` does with its token.
50
+
51
+ ## Deadlines on every await
52
+
53
+ Symptom: a 524 after about 100 s with ~1 ms of CPU (`outcome=canceled`).
54
+
55
+ | Cause | Fix |
56
+ |---|---|
57
+ | upstream fetch without a deadline | `createInstrumentedFetch` from `@decocms/blocks/fetch` can retry and break circuits (`retry`, `circuitBreaker`, both off unless set), but has no timeout of its own: pass `signal: AbortSignal.timeout(…)` per call (for example 20 s for data, longer for a proxied checkout) |
58
+ | site cache or KV read that stalls | race it against a short deadline; a timeout is a miss |
59
+ | a module-level single-flight map whose owner request went away | give joiners a deadline and drop the entry past it; keep the owner's work alive with `ctx.waitUntil` |
60
+ | background work that needs `env` | capture what it needs during the request |
61
+
62
+ The framework's own shared content fetches follow these rules: each has 10 s,
63
+ stays alive through the platform's `waitUntil` whoever started it, and a
64
+ request that joins one waits no longer than its deadline (then the next
65
+ request fetches again). The framework does this because on Workers a
66
+ request's I/O can stop with its response, so a fetch another request started
67
+ may never settle. Your own shared maps need the same deadlines.
68
+
69
+ ```bash
70
+ grep -n "compatibility_date\|compatibility_flags" wrangler.jsonc
71
+ grep -rnE "AbortSignal\.timeout|signal:" src | wc -l # zero is a finding
72
+ grep -rn "createInstrumentedFetch" src
73
+ ```
74
+
75
+ ## Observability
76
+
77
+ You cannot see `exceededMemory`, `canceled` or the 524 pattern without it.
78
+
79
+ - [ ] Workers observability on in `wrangler.jsonc` (`"observability": { "enabled": true }`) and `wrangler tail` works against the candidate.
80
+ - [ ] The CMS telemetry on: `createCMS({ site, token })` or a `telemetry.endpoint`. Without either, the request metric and the upstream metric go nowhere ([content-releases.md](./content-releases.md#telemetry)).
81
+ - [ ] `telemetry.resource` sets `service.version` to the commit, so a code rollback is visible.
82
+
83
+ ## Framework bumps
84
+
85
+ - Compare memory P50 and P99 before and after **every** `@decocms/*` bump. On v7 one minor bump added 27 MB.
86
+ - Bump all `@decocms/*` packages together, and check that one copy of each is installed (`bun pm ls | grep @decocms`, or your package manager's equivalent). Mixed versions run code the bump was not tested with.
87
+ - Re-run `deco schema` and `deco check` after a bump: the schema generator changes with the CLI.
88
+
89
+ ## Portability and CI
90
+
91
+ - Keep platform bindings behind the site's own small interfaces, so the site can move to another runtime if a platform limit is hit.
92
+ - Do not hand out write access to the Worker's dashboard or CI: a commit there can bind another store's namespaces.
93
+ - Know how a content-only change reaches production: with `site`, a publish; without it, a deploy.