@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,123 @@
1
+ # Playwright guardrails for cache and payload
2
+
3
+ Cache and egress gains regress quietly: one cookie in a section, one new query param, one product
4
+ object passed whole to a card. A Playwright spec that runs on every PR catches them. It works over
5
+ HTTP, so it tests the site as a visitor sees it. For the harness itself (config, fixtures, CI
6
+ setup) see `deco-e2e-testing` in decocms/skills.
7
+
8
+ ## Where to run it
9
+
10
+ `pageCache` does not run in `vite dev`. Run the spec against a build:
11
+
12
+ ```json
13
+ {
14
+ "scripts": {
15
+ "e2e:serve": "vite build && vite preview --port 4173 --strictPort",
16
+ "e2e:perf": "playwright test tests/e2e/perf-guardrails.spec.ts"
17
+ }
18
+ }
19
+ ```
20
+
21
+ Set `use.baseURL` to `http://127.0.0.1:4173` and `webServer.command` to `npm run e2e:serve` (or
22
+ `bun run e2e:serve`) in `playwright.config.ts`. Against a preview deployment, point `baseURL`
23
+ there instead; that also exercises the real Cache API.
24
+
25
+ Read expected header values from your worker entry's profiles instead of copying numbers into the
26
+ spec. If `PROFILES` and `browserCacheControl` are exported from a module the spec can import,
27
+ the spec follows a TTL change instead of failing on it.
28
+
29
+ ## What to assert
30
+
31
+ | Area | Assertion |
32
+ |---|---|
33
+ | Profiles | Each representative path answers the `Cache-Control` of its profile; the second request is `x-cache: HIT` |
34
+ | Private paths | `/cart`, `/checkout`, account pages: `private, no-cache, no-store, must-revalidate`, `x-cache: BYPASS` |
35
+ | Previews | `?__draft=off`: `max-age=0, no-cache, must-revalidate`, `vary` has `Cookie`, `x-robots-tag` has `noindex`, no `x-cache` |
36
+ | Signed-in shopper | The sign-in cookie gives `x-cache-reason: private` |
37
+ | Returning visitor | A cart or checkout cookie alone does not make the page private |
38
+ | Tracking params | `utm_*`, `gclid`, `fbclid`: 200, no `location`, same `x-cache-segment`, HIT once warm |
39
+ | No poisoning | A value sent in `gclid` never appears in the clean URL's HTML |
40
+ | No cookies on cached pages | A public page answers no `set-cookie` except `deco_segment` on a first visit |
41
+ | Payload | Raw HTML under a budget; a marker of heavy data (a schema.org type you trim) under a count |
42
+ | Assets | A fingerprinted asset is `public, max-age=31536000, immutable` |
43
+ | CLS | Home and a listing under 0.1 on desktop and mobile |
44
+
45
+ ## Spec sketch
46
+
47
+ ```ts
48
+ import { expect, test } from "@playwright/test";
49
+
50
+ const LISTING = "/some-category";
51
+ // Set from what you measure (see "Cache probe" below).
52
+ const BUDGET = { listingRawBytes: 800_000, priceSpecs: 200 };
53
+ const get = (request, path, headers = {}) =>
54
+ request.get(path, { headers, maxRedirects: 0 });
55
+
56
+ test("listing is stored and served from the cache", async ({ request }) => {
57
+ await get(request, LISTING);
58
+ const res = await get(request, LISTING);
59
+ expect(res.headers()["x-cache"]).toBe("HIT");
60
+ expect(res.headers()["x-cache-profile"]).toBe("listing");
61
+ expect(res.headers()["cache-control"]).toContain("public");
62
+ });
63
+
64
+ test("tracking params share the clean entry and never leak", async ({ request }) => {
65
+ const clean = await get(request, LISTING);
66
+ const tagged = await get(request, `${LISTING}?utm_source=g&gclid=POISON42&fbclid=f`);
67
+ expect(tagged.status()).toBe(200);
68
+ expect(tagged.headers()["location"]).toBeUndefined();
69
+ expect(tagged.headers()["x-cache-segment"]).toBe(clean.headers()["x-cache-segment"]);
70
+ const after = await get(request, LISTING);
71
+ expect(await after.text()).not.toContain("POISON42");
72
+ });
73
+
74
+ test("a preview is never cached", async ({ request }) => {
75
+ const res = await get(request, "/?__draft=off");
76
+ expect(res.headers()["cache-control"]).toBe("max-age=0, no-cache, must-revalidate");
77
+ expect(res.headers()["x-cache"]).toBeUndefined();
78
+ });
79
+
80
+ test("a returning visitor's cart cookie does not make the page private", async ({ request }) => {
81
+ const res = await get(request, "/", { cookie: "<cart-cookie>=x" });
82
+ expect(res.headers()["x-cache-reason"]).not.toBe("private");
83
+ });
84
+
85
+ test("listing HTML stays under budget", async ({ request }) => {
86
+ const body = await (await get(request, LISTING)).text();
87
+ expect(body.length).toBeLessThan(BUDGET.listingRawBytes);
88
+ expect((body.match(/UnitPriceSpecification/g) ?? []).length).toBeLessThan(BUDGET.priceSpecs);
89
+ });
90
+ ```
91
+
92
+ The cache is per data center on a real deployment and local to the machine on `vite preview`.
93
+ Run the warm-up request and the assertion from the same runner.
94
+
95
+ ## Probes worth keeping as scripts
96
+
97
+ **Visitor-profile fingerprint.** For a few listings, request the page with a set of profiles that
98
+ must see the same content: no cookies, the platform's segment cookie with only marketing fields,
99
+ tracking params in the URL, a test-bucket cookie on the same side. Fingerprint the ordered product
100
+ ids and fail on any mismatch. When one profile differs, the key or the segment is reading
101
+ something that does not change the content, or the content reads something the key misses.
102
+
103
+ **Empty upstream.** Give the loader a switch, off in production, that makes its upstream call
104
+ return `null` (an env variable or a test-only build flag). With the switch on, the page must answer `x-cache: BYPASS` with
105
+ `x-cache-reason: degraded`, twice in a row. With it off, the next request must render the full
106
+ page. This catches the most expensive bug in this skill: an empty page stored as valid.
107
+
108
+ **Cache probe.** A table of path, status, raw KB, `x-cache` and time for home, a clean listing, a
109
+ tagged listing and a product page, after one warm-up. Run it against production once to set
110
+ budgets about 30% above what you see, and after each deploy as a smoke check. The tagged and clean
111
+ listings should be within a few percent of each other.
112
+
113
+ ## Static checks
114
+
115
+ Grep the content for blocks that point at loaders you know bypass your trimming or caching (for
116
+ example a raw upstream search loader instead of the site's trimmed one). The saved blocks are
117
+ the JSON files in `.deco/blocks` (on a site that reads content at runtime, what `deco pull`
118
+ wrote); a test that greps them fails the PR before any request is made.
119
+
120
+ ## CI
121
+
122
+ Run `e2e:perf` and the probes on every PR that touches the worker entry, a loader, a section on a
123
+ cacheable page, or the segment.
@@ -0,0 +1,136 @@
1
+ # Verifying cache and egress changes
2
+
3
+ Run these after every change, in order. A page that is never stored (trap 1) makes the later
4
+ checks look better than they are.
5
+
6
+ The headers below are the ones the example worker entry sets. If your `pageCache` names them
7
+ differently, adapt the greps.
8
+
9
+ ## 0. Where to run
10
+
11
+ - Production or a preview deployment: the real thing. The Cache API is per data center, so a
12
+ second request from the same place is what tells you whether the first one stored.
13
+ - Locally: `pageCache` never runs in `vite dev`. Build and use `vite preview` (Miniflare runs the
14
+ Worker), as the example's `bun run build && bun run smoke` does.
15
+ - Always `GET`. `curl -I` sends `HEAD`, which never reaches `pageCache`. Use
16
+ `curl -s -o /dev/null -D -`.
17
+
18
+ ## 1. Is it stored?
19
+
20
+ ```bash
21
+ UA='Mozilla/5.0 (Macintosh) Chrome/140'
22
+ H='^(cache-control|cdn-cache-control|vary|x-cache|x-cache-reason|x-cache-profile|x-cache-segment|x-cache-version|x-cache-age|set-cookie)'
23
+ for p in / /some-category /some-product/p '/s?q=shirt'; do
24
+ echo "== $p"
25
+ for i in 1 2; do curl -s -o /dev/null -D - -A "$UA" "https://SITE$p" | grep -iE "$H"; echo; done
26
+ done
27
+ ```
28
+
29
+ Expect on the second request: `x-cache: HIT`, the profile you meant, `x-cache-version:
30
+ <build>.<revision>`, `vary: Accept-Encoding`, no `set-cookie` other than `deco_segment` on a first
31
+ visit (and the cookies in your `SAFE_COOKIES`, if a render set one). A `BYPASS` comes with `x-cache-reason`; `egress-traps.md` maps each reason to a cause.
32
+
33
+ After a deploy or a publish, `x-cache-version` changes and the first request is a `MISS` again.
34
+ That is expected.
35
+
36
+ ## 2. What must never be stored
37
+
38
+ ```bash
39
+ # A preview: no x-cache, revalidate header, noindex
40
+ curl -s -o /dev/null -D - "https://SITE/?__draft=off" | grep -iE '^(cache-control|vary|x-robots-tag|x-cache)'
41
+ # expect: cache-control: max-age=0, no-cache, must-revalidate ; vary: Cookie ; no x-cache
42
+
43
+ # A signed request
44
+ curl -s -o /dev/null -D - -H 'Authorization: Bearer x' "https://SITE/" | grep -i '^cache-control'
45
+ # expect: private, no-cache, no-store, must-revalidate
46
+
47
+ # A signed-in shopper (use the cookie your buildSegment reads)
48
+ curl -s -o /dev/null -D - -H 'Cookie: <sign-in-cookie>=1' "https://SITE/" | grep -iE '^x-cache'
49
+ # expect: x-cache: BYPASS, x-cache-reason: private
50
+
51
+ # Private paths
52
+ curl -s -o /dev/null -D - "https://SITE/cart" | grep -iE '^(cache-control|x-cache)'
53
+ # expect: private, no-cache, no-store, must-revalidate ; x-cache-reason: profile:private
54
+
55
+ # A missing page
56
+ curl -s -o /dev/null -D - "https://SITE/this-does-not-exist" | grep -iE '^(x-cache)'
57
+ # expect: x-cache-reason: status:404
58
+ ```
59
+
60
+ ## 3. Tracking params: shared entry, no poisoning
61
+
62
+ ```bash
63
+ curl -s -o /dev/null -D - -A "$UA" 'https://SITE/some-category?gclid=POISON42' | grep -iE '^x-cache'
64
+ curl -s -o /dev/null -D - -A "$UA" 'https://SITE/some-category?gclid=POISON42' | grep -iE '^x-cache'
65
+ curl -s -A "$UA" 'https://SITE/some-category' | grep -c POISON42 # must print 0
66
+ curl -s -o /dev/null -D - -A "$UA" 'https://SITE/some-category?utm_source=a&fbclid=b' | grep -iE '^x-cache:'
67
+ # expect HIT once the clean URL is warm, no redirect, same x-cache-segment
68
+ ```
69
+
70
+ A non-zero count means the stored HTML carries the raw URL. Fix it as trap 2 says.
71
+
72
+ ## 4. Same content, same entry
73
+
74
+ Different visitor profiles that should see the same page must land on the same entry. Compare a
75
+ fingerprint of the content (the ordered product ids on a listing) and the `x-cache-segment`:
76
+
77
+ ```bash
78
+ fp() { curl -s -A "$2" -H "Cookie: $3" "$1" | grep -oE 'data-product-id="[^"]*"' | md5sum; }
79
+ URL='https://SITE/some-category'
80
+ fp "$URL" "$UA" ""
81
+ fp "$URL?utm_source=test&gclid=abc" "$UA" ""
82
+ fp "$URL" "$UA" "<a marketing cookie your site sets>=x"
83
+ # all hashes equal; replace the grep with whatever marks a product card in your HTML
84
+ ```
85
+
86
+ Then change only what should split: a phone user agent must change `x-cache-segment`; a geo header
87
+ or region cookie must change it only if the content really differs by region.
88
+
89
+ ## 5. How big is what you store?
90
+
91
+ ```bash
92
+ curl -s --compressed -o /tmp/body -w '%{size_download} bytes compressed\n' 'https://SITE/some-category'
93
+ curl -s -o /tmp/body -w '%{size_download} bytes raw\n' -H 'Accept-Encoding: identity' 'https://SITE/some-category'
94
+ node .agents/skills/deco-storefront-caching/scripts/html-anatomy.mjs https://SITE/some-category
95
+ ```
96
+
97
+ `html-anatomy.mjs` prints the cache headers, the raw and gzip size, bytes per attribute, analytics
98
+ events in the markup, and every large blob repeated more than once. Repeated blobs are the usual
99
+ fix: emit once, reference by id. Set budgets from what you measure (see `perf-guardrails-e2e.md`).
100
+
101
+ ## 6. Failure mode: an empty page must not stick
102
+
103
+ Make the upstream fail on purpose (an env switch in your loader that returns `null`, or point the
104
+ client at a dead host on a preview deployment) and request a cacheable page twice.
105
+
106
+ - Expect `x-cache: BYPASS` with `x-cache-reason: degraded` (or `STALE-ERROR` if a good copy
107
+ existed), never `MISS` followed by `HIT`.
108
+ - Turn the switch off. The next request must render the full page at once, not after the fresh
109
+ window expires.
110
+
111
+ If the empty page was stored, the page does not set `x-deco-degraded` for that failure.
112
+
113
+ ## 7. Purge
114
+
115
+ ```bash
116
+ curl -s -X POST "https://SITE/_cache/purge" \
117
+ -H "Authorization: Bearer $PURGE_TOKEN" -H 'Content-Type: application/json' \
118
+ -d '{"paths":["/some-category"]}'
119
+ # expect {"purged":[...],"total":n}; the next GET of that path from the same data center is a MISS
120
+ ```
121
+
122
+ `total: 0` right after a HIT from the same data center means the purge's key differs from the
123
+ stored key.
124
+
125
+ ## 8. Telemetry, for 24 hours after the deploy
126
+
127
+ - `http.server.request.duration`, counted by `cache` and `http.route`: hit share per page template.
128
+ `BYPASS` growing on one route points at a new cookie or private header there.
129
+ - `http.client.request.duration` by `provider` and `operation`: upstream calls per page view should
130
+ drop. `cached=true` counts hits of your upstream `fetch` cache.
131
+ - 5xx share must not rise. A rise after "degraded" changes means a failure path now throws.
132
+ - CDN bandwidth per path (`deco-performance-audit` in decocms/skills).
133
+
134
+ The alert runbook is `docs/runbooks/cache-hit-drop.md`. Its diagnostic queries and its section on
135
+ loader caches name metrics and routes from the v7 line (`cache_hit_total`, `createCachedLoader`,
136
+ `/_cache/purge-loaders`); on v8 use the metrics above and the example's purge route.
@@ -0,0 +1,160 @@
1
+ # The worker page cache
2
+
3
+ `@decocms/tanstack/worker` gives you `createDecoWorker` and the helpers a cache needs. It stores
4
+ nothing itself. The cache is a function you pass as `pageCache`. The repo ships a complete one in
5
+ `examples/tanstack-worker-smoke/src/worker-entry.ts` (the package README links it): v7's edge
6
+ cache rebuilt on the Cloudflare Cache API. Copy it to `src/worker-entry.ts` and own it.
7
+
8
+ ## Wiring
9
+
10
+ ```ts
11
+ // src/worker-entry.ts — wrangler.jsonc "main": "./src/worker-entry.ts"
12
+ import { createDecoWorker } from "@decocms/tanstack/worker";
13
+ import handler, { createServerEntry } from "@tanstack/react-start/server-entry";
14
+ import { cms } from "./cms";
15
+
16
+ const worker = createDecoWorker<Env>({
17
+ serverEntry: createServerEntry({ fetch: handler.fetch }),
18
+ cms,
19
+ dev: import.meta.env.DEV,
20
+ pageCache, // your function; without it every request renders
21
+ });
22
+ ```
23
+
24
+ - `wrangler.jsonc` `main` must point at this file. If it points at TanStack Start's entry, the
25
+ worker and your cache never run.
26
+ - `__BUILD_HASH__` comes from `decoTanstack({ buildHash })` in `vite.config.ts`
27
+ (`@decocms/tanstack/vite`): the CI's sha when given, else `git`, else the time; `"dev"` in
28
+ `vite dev`.
29
+ - `pageCache` is never called in `vite dev`. Test caching on a build: `vite build`, then
30
+ `vite preview` (Miniflare). The example's `bun run smoke` does exactly that.
31
+ - `createStart(() => ({ serverFns: { fetch: decoServerFnFetch } }))` (`@decocms/tanstack/start`)
32
+ is what sends the `__cseg` token back on navigation data. See `deco-tanstack-site`.
33
+
34
+ ## What the worker already does
35
+
36
+ You do not write these. Do not add a second copy of them in `pageCache`.
37
+
38
+ | Behavior | Detail |
39
+ |---|---|
40
+ | Calls `pageCache` only for cacheable requests | `isCacheable`: `GET`, current release (`version === null`), no `?__draft=` (`off` included) and no draft cookie, no `Authorization`, not `/_build`, not dev. A `HEAD` never reaches it. |
41
+ | Previews | Always render. Answer `Cache-Control: max-age=0, no-cache, must-revalidate`, `Vary: Cookie`, `noindex`, and `CDN-Cache-Control: no-store`. |
42
+ | `Authorization` | The page renders and answers `private, no-cache, no-store, must-revalidate`, whatever the app set. |
43
+ | Default CDN header | Any response without `CDN-Cache-Control` leaves with `CDN-Cache-Control: no-store`. |
44
+ | Visitor cookie | `deco_segment` is set on a first visit only, and appended after `pageCache` answers. A stored copy never carries it; a visitor served from the cache still gets theirs. |
45
+ | `Set-Cookie` | One header per cookie (name + Domain + Path). |
46
+ | Fingerprinted assets | `public, max-age=31536000, immutable`, `Vary: Accept-Encoding`. Also under `/fonts/`. |
47
+ | CMS redirects | Answered before your `routes` and before `pageCache`. See `egress-traps.md`. |
48
+ | v7 admin paths | `/deco/*`, `/live/*`, `/.decofile` answer 404 with a private header. |
49
+ | Metric | `http.server.request.duration` with a `cache` label: `HIT` for your `HIT`, `STALE-HIT`, `STALE-ERROR`; `MISS`; `DRAFT` for previews (a draft signal or a Studio link's version); `BYPASS` otherwise, including every response `pageCache` did not answer. |
50
+
51
+ ## What `pageCache` receives
52
+
53
+ `PageCache<Env> = (page: PageRequest<Env>) => Promise<Response>`, where `page` has:
54
+
55
+ - `request`: as the app gets it (visitor and assignments on their headers).
56
+ - `url`, `device` (`detectDevice`: `mobile`, `tablet`, `desktop`), `env`, `ctx`.
57
+ - `visitor`: the visitor the worker read.
58
+ - `assignments`: each test and campaign on or off, as the page renders them.
59
+ - `render(scope?)`: renders the page, with `x-page-status` applied and without the visitor
60
+ cookie. Pass `{ csegToken }` so `DecoDocument` publishes the token.
61
+
62
+ Set `X-Cache` on your answer (`HIT`, `STALE-HIT`, `STALE-ERROR`, `MISS`, or anything else for a
63
+ bypass). The request metric reads it.
64
+
65
+ ## The helpers
66
+
67
+ All from `@decocms/tanstack/worker`:
68
+
69
+ | Helper | Use |
70
+ |---|---|
71
+ | `cacheVersion(cms, buildHash, url?)` | `<build>.<content revision>`. With the URL, the revision that page renders. Right after a publish a page whose new blocks are not loaded yet renders on the previous index, and this pins the same way, so a page is never stored under a revision it did not render. Without the URL (the purge), the current revision. Falls back to the build alone if the content can't be read. |
72
+ | `assignmentsKey(assignments)` | `x=<tests on>\|c=<campaigns running>`, names sorted and URL-encoded, empty parts left out, `""` for none (a `v=<version>` part comes first for a preview, which never reaches `pageCache`). Never the visitor id. |
73
+ | `liveAssignmentKeys(cms)` | Every assignments key a live request can carry now: each subset of the saved tests, with and without the running campaigns. For the purge. Grows as 2^tests. |
74
+ | `detectDevice(ua)`, `segmentKey(segment)` | Device class; a segment as one stable string (parts sorted, values URL-encoded, empty parts dropped). |
75
+ | `segmentToken(segment, version)` | The `__cseg` token (DJB2 hex of segment and version). `null` when the version is empty or `"dev"`. |
76
+ | `CSEG_PARAM` | `"__cseg"`, the query param `decoServerFnFetch` adds. Drop it from the key. |
77
+ | `isServerFnPath(pathname)`, `serverFnPagePath(url)` | Server-function URLs (`/_serverFn/`, `/_server/`) and the page a GET page load asks for (first local path in `payload`). |
78
+ | `isCacheable(request, { version, dev })`, `requestVersion(request)` | The worker's own gate and the version header. You rarely need them inside `pageCache`. |
79
+ | `DEGRADED_HEADER` | `"x-deco-degraded"`. Your page sets it to `true` when a loader it needs failed, on the document response (a route's `headers` reach it, as with `x-page-status`). Nothing in the framework sets it for you. Also exported from `@decocms/tanstack/server`. |
80
+
81
+ `markPrivate()` from `@decocms/tanstack/server` sets `Cache-Control: private, no-store` on a server
82
+ function called over HTTP (cart, user, wishlist). The example never stores such a response.
83
+
84
+ ## Profiles and TTLs (the example's values)
85
+
86
+ The example picks a profile per URL, first match wins. These are v7's numbers. Change them in
87
+ `PROFILES` and `pageProfile`.
88
+
89
+ | Profile | Matches | Edge fresh / swr / sie (s) | Browser `Cache-Control` |
90
+ |---|---|---|---|
91
+ | `private` | `/cart`, `/checkout`, `/account`, `/login`, `/my-account` | never stored | `private, no-cache, no-store, must-revalidate` |
92
+ | `none` | `/api/*`, `/deco/*` | never stored | same |
93
+ | `static` | `/`, `/sitemap.xml` | 900 / 7200 / 21600 | `public, max-age=120, s-maxage=900, stale-while-revalidate=1800, stale-if-error=7200` |
94
+ | `search` | `/s`, `/s/*`, any `?q=` | 60 / 300 / 1800 | `public, max-age=0, s-maxage=60, stale-while-revalidate=120, stale-if-error=600` |
95
+ | `product` | path ends in `/p` | 300 / 1800 / 7200 | `public, max-age=60, s-maxage=300, stale-while-revalidate=600, stale-if-error=3600` |
96
+ | `listing` | everything else | 120 / 900 / 3600 | `public, max-age=30, s-maxage=120, stale-while-revalidate=300, stale-if-error=1800` |
97
+
98
+ A GET server function takes its page's profile (`serverFnPagePath`). Any other server function
99
+ is `private`.
100
+
101
+ Why profiles at all (the v7 rationale still holds): product pages change on price and stock, so
102
+ they get a short fresh window and a long stale one; listings change with the catalog; search is
103
+ long-tail and mostly unique, so it gets the shortest window; `/` is the hottest URL and safest to
104
+ keep longest. `listing` is the default because it is the cautious middle.
105
+
106
+ ## How the example serves
107
+
108
+ - Fresh copy (age < `fresh`): `X-Cache: HIT`.
109
+ - Stale copy (age < `fresh + swr`): served as `STALE-HIT` with `X-Cache-Age`, and the page renders
110
+ again in `ctx.waitUntil`. The new render is stored only if it is a clean 200.
111
+ - The render throws, or answers 5xx or 429, or is degraded, and a copy younger than `fresh + sie`
112
+ exists: `STALE-ERROR` with `X-Cache-Reason`.
113
+ - Otherwise it renders: a clean 200 is stored and answered `MISS`; anything else is `BYPASS`.
114
+
115
+ The stored copy gets `Cache-Control: public, max-age=<fresh + max(swr, sie)>` so the Cache API
116
+ keeps it through the stale windows; the age comes from an `X-Deco-Stored-At` header that is
117
+ removed before the answer goes out. `HIT`, `STALE-*` and `MISS` answers carry
118
+ `X-Cache-Profile`, `X-Cache-Segment`, `X-Cache-Version` and `Vary: Accept-Encoding`. `BYPASS`
119
+ answers carry `X-Cache` and `X-Cache-Reason` and none of those. A `status:` bypass keeps the
120
+ render's own `Cache-Control`; the other bypasses set `private, no-cache, no-store, must-revalidate`.
121
+
122
+ What the example never stores:
123
+
124
+ | `X-Cache-Reason` on a `BYPASS` | Cause |
125
+ |---|---|
126
+ | `private` | `buildSegment` returned `loggedIn: true` |
127
+ | `profile:<name>` | The URL's profile is not public, or its edge `fresh` is 0 |
128
+ | `status:<code>` | The render was not a 200 (a CMS 404 page included) |
129
+ | `private-response` | `Cache-Control` has `private` or `no-store`, or a `Set-Cookie` outside `SAFE_COOKIES` (`_deco_bucket` in the example) |
130
+ | `degraded` | `x-deco-degraded: true` on the render |
131
+
132
+ A cookie in `SAFE_COOKIES` is stripped from the stored copy, so another visitor never gets it.
133
+
134
+ ## Server functions and the CDN (`__cseg`)
135
+
136
+ Client-side navigation loads page data with a GET server function. The example keys it like the
137
+ page (its payload canonicalized, variant params `skuId` and `idsku` dropped) and stores it in the
138
+ Cache API like any page.
139
+
140
+ It also lets the CDN in front keep that response, which is the only `CDN-Cache-Control: public`
141
+ the example sends. That happens only when the request's `__cseg` equals the token recomputed from
142
+ this request's segment, version and assignments. `decoServerFnFetch` adds the token the page
143
+ published. A stale or forged token gets `CDN-Cache-Control: no-store`. HTML pages always get
144
+ `CDN-Cache-Control: no-store` in the example: they are cached in the Worker's Cache API only.
145
+
146
+ ## Purge
147
+
148
+ The example answers `POST /_cache/purge` with `Authorization: Bearer <PURGE_TOKEN>` (a Worker
149
+ secret) and a body `{ "paths": ["/", "/shoes"], "segments"?: [{ "device": "desktop" }] }`.
150
+
151
+ - It drops each exact path (`/shoes` never drops `/shoes?page=2`) under the current version, for
152
+ each segment (each device when the body names none), each live assignments key, as a navigation
153
+ and as a programmatic fetch. Answer: `{ "purged": [...], "total": n }`.
154
+ - It reuses the same `cacheKey` function as the lookup, so the keys match byte for byte. Keep it
155
+ that way when you change the key.
156
+ - The Cache API is per data center. A purge reaches the copies in the data center that serves it.
157
+ - Each delete is a Cache API call; a request has a limit (the example's comment: 50 on Workers
158
+ Free, 1,000 on Paid). Past it the example answers 503 with `notPurged` to send again.
159
+ - You rarely need it for content: a publish changes the content revision, so every key moves.
160
+ Purge is for upstream data (a price change) on pages whose fresh window is long.
@@ -0,0 +1,97 @@
1
+ #!/usr/bin/env node
2
+ // Where do the bytes of a storefront page go? Zero dependencies (Node 18+).
3
+ //
4
+ // node .agents/skills/deco-storefront-caching/scripts/html-anatomy.mjs https://www.example.com/category
5
+ // node .agents/skills/deco-storefront-caching/scripts/html-anatomy.mjs ./saved-page.html
6
+ //
7
+ // Prints: raw/gzip size, cache headers (URL mode), bytes per attribute, the
8
+ // analytics `data-event` / `data-dt-event` breakdown, and every large blob
9
+ // (attribute value or inline script) that appears more than once — the usual
10
+ // culprit is the same payload emitted per card, per size or per instance.
11
+
12
+ import { readFileSync } from "node:fs";
13
+ import { gzipSync } from "node:zlib";
14
+
15
+ const target = process.argv[2];
16
+ if (!target) {
17
+ console.error("usage: node html-anatomy.mjs <url|file>");
18
+ process.exit(1);
19
+ }
20
+
21
+ let html;
22
+ if (/^https?:\/\//.test(target)) {
23
+ const res = await fetch(target, {
24
+ headers: { "user-agent": "Mozilla/5.0 (Macintosh) Chrome/140", accept: "text/html" },
25
+ });
26
+ html = await res.text();
27
+ // The worker's and the example page cache's headers (v8): what was decided and why.
28
+ const shown = [
29
+ "cache-control", "cdn-cache-control", "vary", "cf-cache-status", "age",
30
+ "x-cache", "x-cache-reason", "x-cache-profile", "x-cache-segment", "x-cache-version",
31
+ "x-cache-age", "x-deco-degraded", "set-cookie",
32
+ ];
33
+ console.log(`status: ${res.status}`);
34
+ for (const h of shown) {
35
+ const v = res.headers.get(h);
36
+ if (v) console.log(`${h}: ${v.slice(0, 120)}`);
37
+ }
38
+ } else {
39
+ html = readFileSync(target, "utf8");
40
+ }
41
+
42
+ const kb = (n) => `${(n / 1024).toFixed(0).padStart(7)} KB`;
43
+ const raw = Buffer.byteLength(html);
44
+ console.log(`\ntotal ${kb(raw)} raw, ${kb(gzipSync(html).length)} gzip\n`);
45
+
46
+ const byAttr = new Map();
47
+ const blobs = new Map();
48
+ // Group by the first 200 chars: repeated payloads usually differ only in a
49
+ // trailing id/props (e.g. the same script inlined per instance with its rootId).
50
+ const note = (key, value) => {
51
+ if (value.length < 1024) return;
52
+ const sig = `${key}|${value.slice(0, 200)}`;
53
+ const e = blobs.get(sig) ?? { key, n: 0, bytes: 0, sample: value };
54
+ e.n++;
55
+ e.bytes += value.length;
56
+ blobs.set(sig, e);
57
+ };
58
+ for (const m of html.matchAll(/\s([a-zA-Z:@\-]+)="([^"]*)"/g)) {
59
+ byAttr.set(m[1], (byAttr.get(m[1]) ?? 0) + m[2].length);
60
+ note(m[1], m[2]);
61
+ }
62
+ for (const m of html.matchAll(/<script[^>]*>([\s\S]*?)<\/script>/g)) {
63
+ byAttr.set("<script> body", (byAttr.get("<script> body") ?? 0) + m[1].length);
64
+ note("<script> body", m[1]);
65
+ }
66
+
67
+ console.log("bytes by attribute (top 12):");
68
+ for (const [k, v] of [...byAttr].sort((a, b) => b[1] - a[1]).slice(0, 12)) {
69
+ console.log(` ${k.padEnd(24)}${kb(v)} ${((v / raw) * 100).toFixed(0)}%`);
70
+ }
71
+
72
+ const events = new Map();
73
+ for (const m of html.matchAll(/\sdata-(?:dt-)?event="([^"]*)"/g)) {
74
+ let name = "?";
75
+ try {
76
+ const d = JSON.parse(decodeURIComponent(m[1].replace(/&quot;/g, '"')));
77
+ name = d.name ?? d.event ?? "?";
78
+ } catch {}
79
+ const e = events.get(name) ?? { n: 0, bytes: 0 };
80
+ e.n++;
81
+ e.bytes += m[1].length;
82
+ events.set(name, e);
83
+ }
84
+ if (events.size) {
85
+ console.log("\nanalytics events in markup:");
86
+ for (const [k, e] of [...events].sort((a, b) => b[1].bytes - a[1].bytes).slice(0, 8)) {
87
+ console.log(` ${String(k).padEnd(24)}${String(e.n).padStart(5)}x ${kb(e.bytes)}`);
88
+ }
89
+ }
90
+
91
+ const dupes = [...blobs.values()].filter((e) => e.n > 1).sort((a, b) => b.bytes - a.bytes);
92
+ if (dupes.length) {
93
+ console.log("\nlarge blobs repeated (same first 200 chars) — fix: emit once, reference it:");
94
+ for (const e of dupes.slice(0, 8)) {
95
+ console.log(` ${String(e.n).padStart(4)}x ~${kb(e.bytes / e.n)} each = ${kb(e.bytes)} [${e.key}] ${e.sample.slice(0, 60).replace(/\s+/g, " ")}…`);
96
+ }
97
+ }
@@ -0,0 +1,81 @@
1
+ ---
2
+ name: deco-storefront-performance
3
+ description: "Server and render performance for storefronts on @decocms/blocks 8 (mostly @decocms/tanstack on Cloudflare Workers; @decocms/nextjs where noted), indexed by symptom. Covers N+1 and duplicate upstream calls in block functions (the client's per-request memo, currentClient(), counting calls with createInstrumentedFetch's metric or a logging fetch), trimming schema.org Product graphs before they reach the HTML, render location (the built-in lazy block, streamed vs awaited blocks, the cost of a large Redirects block), hydration mismatches and flashes, CLS from third-party scripts, instant variant switching, scroll and navigation feedback, reading Chrome traces, and Worker memory (measuring per deploy, large tables out of the bundle, streaming big proxied bodies). Use when TTFB is slow but the HTML is small, the HTML is several MB, one VTEX operation runs many times per page, React logs a hydration error, a section flashes or shifts, a variant click refetches the page, or a Worker hits its 128 MB limit."
4
+ ---
5
+
6
+ # Storefront performance on v8
7
+
8
+ You have a v8 storefront that is slow or unstable in a specific way. This skill is
9
+ organised by symptom. Find the symptom below and load the one reference it names.
10
+
11
+ It is about server work, payload and render behaviour. It does not cover:
12
+
13
+ - **Edge and page caching** (`pageCache`, cache keys, hit rate, upstream caches): see
14
+ the skill `deco-storefront-caching`.
15
+ - **How blocks, sections and `lazy` are written**: see `deco-site-authoring`.
16
+ - **Wiring the TanStack site** (worker entry, page route, server functions): see
17
+ `deco-tanstack-site`. For Next.js, `deco-nextjs-site`.
18
+ - **The thin clients** (`createVtexClient` and its options): see `deco-apps`.
19
+ - **Generic browser-side craft** (Core Web Vitals, JS budgets, HTML size, PageSpeed
20
+ scoring): the decocms/skills skills `improving-web-vitals-tanstack`,
21
+ `client-js-budget`, `html-size-optimizer` and `pagespeed-score-model`.
22
+
23
+ ## When to load what
24
+
25
+ | Reference | Load it when |
26
+ |---|---|
27
+ | [`references/render-location.md`](./references/render-location.md) | TTFB is seconds but the HTML is small; a page resolves data it never shows; you are not sure which block is slow; the site has thousands of redirects |
28
+ | [`references/loaders-n-plus-1.md`](./references/loaders-n-plus-1.md) | One upstream call per product in a block function; SSR gets slower with shelf size; VTEX answers 429 |
29
+ | [`references/request-dedupe.md`](./references/request-dedupe.md) | The same upstream operation runs several times for one page; two sections fetch the same product; you want to count calls before and after |
30
+ | [`references/payload-trim.md`](./references/payload-trim.md) | The HTML or a `/_serverFn/` response is several MB; the HTML is full of `UnitPriceSpecification`; JSON-LD is huge |
31
+ | [`references/hydration.md`](./references/hydration.md) | React logs a hydration mismatch; a section shows server markup but never becomes interactive; a section flashes on load |
32
+ | [`references/cls-third-party.md`](./references/cls-third-party.md) | CLS is high; a widget, seal or chat script pushes content after load |
33
+ | [`references/navigation-ux.md`](./references/navigation-ux.md) | A variant click takes >500 ms or refetches the page; forward navigation keeps the old scroll position; clicks give no feedback; hover prefetch loads the upstream |
34
+ | [`references/trace-reading.md`](./references/trace-reading.md) | You need to find which element shifted, why the screen went blank, or where a slow navigation spends its time; local numbers disagree with production |
35
+ | [`references/worker-memory.md`](./references/worker-memory.md) | The Worker logs "exceeded memory limit" or its memory P90 grew after a deploy; a proxied sitemap or feed is large |
36
+
37
+ ## First, split the cost
38
+
39
+ Two numbers tell you which half of the skill you need:
40
+
41
+ ```bash
42
+ curl -s -o /dev/null -A "Mozilla/5.0 Chrome/120" "$URL" \
43
+ -w 'bytes %{size_download} ttfb %{time_starttransfer}s total %{time_total}s\n'
44
+ ```
45
+
46
+ - **Small body, long wait**: the server did work. Go to `render-location.md`,
47
+ then `loaders-n-plus-1.md` and `request-dedupe.md`. Trimming payload will not move
48
+ this number. One product page measured 29 KB on the wire and 4.6 s of wait.
49
+ - **Large body, short wait**: payload. Go to `payload-trim.md`.
50
+ - **Fast server, bad experience in the browser** (flash, shift, slow click): go to
51
+ `hydration.md`, `cls-third-party.md`, `navigation-ux.md` and `trace-reading.md`.
52
+
53
+ Measure the same URL two or three times. If one run is 0.2 s and the next is 3.6 s,
54
+ that is a cold isolate or a cache miss, not the page. Read `deco-storefront-caching`
55
+ before you optimise anything.
56
+
57
+ ## How v8 runs a page, in one paragraph
58
+
59
+ The worker (`createDecoWorker`) checks the CMS redirects on every `GET` or `HEAD` that is not an
60
+ asset or a server-function call, then calls the site's `pageCache` if it has one, then
61
+ renders. The page route of the example app (`examples/tanstack-worker-smoke`; wiring in
62
+ `deco-tanstack-site`) asks
63
+ one client (`contentClient(cms, request)`) for the page with `{ run: false }`, starts
64
+ one promise per section block with `client.resolve(block)`, awaits only the SEO block,
65
+ and streams the sections through `<Suspense>`/`<Await>`. A client runs each block
66
+ function once per distinct input, so equal blocks in one request share a result. Nothing
67
+ is shared between requests: the client never caches. A client-side navigation calls
68
+ the page server function (a `/_serverFn/` request), which does the same work.
69
+
70
+ The references build on that model. When a fix depends on it, they say so.
71
+
72
+ ## Rules for this skill
73
+
74
+ - **Measure, then attribute.** Count calls and time blocks before you change code.
75
+ Guessing from payload size pointed at the wrong section three times on one site.
76
+ - **Do not move above-the-fold or crawler-relevant content to the client to win a
77
+ number.** The goal is to stop work that is thrown away, not to hide work users need.
78
+ - **Prove a fix with a control.** Same URL, same device, same cache state, before and
79
+ after. A single before/after pair on a busy day is a guess.
80
+ - **Copy a block result before you change it.** Equal blocks in one request share the
81
+ same object. Mutating one in place changes the others.