@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,90 @@
1
+ # CLS from third-party scripts and late content
2
+
3
+ Load when: CLS is above 0.1 (poor above 0.25); a review widget, trust seal, chat bubble or
4
+ banner script pushes content after load; the footer jumps.
5
+
6
+ Nothing here is specific to v8. Third-party scripts are the usual cause on storefronts,
7
+ followed by section fallbacks that are shorter than the section they stand in for.
8
+
9
+ ## 1. Find the element that moved
10
+
11
+ Quickest: paste this in the console, then reload with the console open.
12
+
13
+ ```js
14
+ new PerformanceObserver((list) => {
15
+ for (const entry of list.getEntries()) {
16
+ if (entry.hadRecentInput) continue;
17
+ console.log("shift", entry.value.toFixed(4), entry.sources?.map((s) =>
18
+ `${s.node?.nodeName}#${s.node?.id}.${s.node?.className}`));
19
+ }
20
+ }).observe({ type: "layout-shift", buffered: true });
21
+ ```
22
+
23
+ Each line is one shift, with its score and the nodes that moved. Then find what happened
24
+ just before it: a script, a stylesheet, a font, an image without dimensions. A Performance
25
+ trace shows that directly ([`trace-reading.md`](./trace-reading.md)). Lighthouse lists the
26
+ largest shifts under "Avoid large layout shifts".
27
+
28
+ Real case: a trace showed one shift of **0.59** at 1.2 s. The node was a trust-seal
29
+ container in the footer. Just before it, the seal's script loaded and injected CSS that
30
+ grew the container from 0 to ~60 px. Reserving the height and loading the script after
31
+ hydration removed the shift.
32
+
33
+ ## 2. Usual offenders and fixes
34
+
35
+ | Source | What it does | Fix |
36
+ |---|---|---|
37
+ | Review or trust-seal widget | Injects markup and CSS after load | Reserve its height; load the script when idle |
38
+ | Chat or WhatsApp bubble | Adds a floating element | Fixed position only; load after hydration |
39
+ | Inline `<script>` that loads CSS | Restyles content already painted | Move it into a component that loads it after hydration |
40
+ | A section fallback | Shorter than the section that replaces it | Give the fallback the section's height |
41
+ | Images without size | Height unknown until the image loads | `width` and `height` on every image (`Image` from `@decocms/tanstack/react` takes them) |
42
+ | Web fonts | Text reflows when the font swaps | Preload the main font (`createDecoWorker({ preload: { fonts } })` sends `Link` preload headers) and use a fallback font with close metrics |
43
+
44
+ ## 3. A deferred script component
45
+
46
+ Load a third-party script after hydration, when the browser is idle, into a container
47
+ with reserved height:
48
+
49
+ ```tsx
50
+ import { useEffect, useRef } from "react";
51
+
52
+ export function DeferredScript({ id, src, dataset = {}, minHeight = 60 }: {
53
+ id: string; src: string; dataset?: Record<string, string>; minHeight?: number;
54
+ }) {
55
+ const ref = useRef<HTMLDivElement>(null);
56
+ useEffect(() => {
57
+ if (!ref.current || document.getElementById(id)) return;
58
+ const load = () => {
59
+ const script = document.createElement("script");
60
+ script.id = id;
61
+ script.async = true;
62
+ script.src = src;
63
+ for (const [k, v] of Object.entries(dataset)) script.dataset[k] = v;
64
+ ref.current?.appendChild(script);
65
+ };
66
+ if ("requestIdleCallback" in window) {
67
+ const handle = requestIdleCallback(load, { timeout: 3000 });
68
+ return () => cancelIdleCallback(handle);
69
+ }
70
+ const timer = setTimeout(load, 2000);
71
+ return () => clearTimeout(timer);
72
+ }, [id, src]);
73
+ return <div ref={ref} id={`${id}-container`} style={{ minHeight }} />;
74
+ }
75
+ ```
76
+
77
+ - Measure the widget's final height on mobile and desktop and use it as `minHeight`.
78
+ - The `id` check stops a second copy after a client-side navigation.
79
+ - If the script must run before first paint (consent, some analytics), it cannot be
80
+ deferred. Reserve the space instead.
81
+ - A site with a strict CSP must allow the script's origin.
82
+
83
+ ## 4. Verify
84
+
85
+ - The console observer shows no shift above ~0.01 for the widget's container.
86
+ - Lighthouse mobile CLS on the page, before and after, on the same build of the rest.
87
+ - Check a page where the widget is below the fold: a shift there still counts if it
88
+ happens in the viewport while the visitor scrolls.
89
+
90
+ For Core Web Vitals work beyond CLS, see `improving-web-vitals-tanstack` (decocms/skills).
@@ -0,0 +1,116 @@
1
+ # Hydration: mismatches, sections that never wake up, and flashes
2
+
3
+ Load when: React logs a hydration mismatch; a section shows its server markup but clicks
4
+ and effects do nothing; part of the page goes blank or flashes a fallback on load.
5
+
6
+ Most of this is plain React 19 and TanStack Start. The v8-specific parts are the streamed
7
+ block promises (section 2) and the per-block `<Suspense>` (section 3).
8
+
9
+ ## 1. Mismatches: find the element, then the cause
10
+
11
+ React's error names the element whose server HTML differs from the first client render.
12
+ Compare the server HTML (view-source, or `curl`) with the DOM in DevTools at that spot.
13
+ Test with a hard reload: a client-side navigation renders on the client only and hides
14
+ the problem.
15
+
16
+ | Cause | Example | Fix |
17
+ |---|---|---|
18
+ | A value only the server has | `process.env.STORE_NAME` in a component: set on the server, `undefined` in the browser bundle | Pass it from the server in loader data, or use a build-time value (`import.meta.env.VITE_*`) that both bundles get |
19
+ | Time, randomness, locale | `Date.now()`, `Math.random()`, `toLocaleString()` with the server's time zone | Compute on the server and pass the result, or render it in an effect |
20
+ | Browser-only state in render | `window`, `localStorage`, `matchMedia`, the cart count from a cookie | Render a stable placeholder, fill it in `useEffect` |
21
+ | Invalid nesting | `<a>` inside `<a>`, `<div>` inside `<p>`, a `<button>` inside a `<button>` | The browser repairs the HTML before React sees it. Fix the markup (below) |
22
+ | A browser extension | Injected attributes on `<html>` or `<body>` | Reproduce in a clean profile before you change code |
23
+
24
+ `DecoDocument` already sets `suppressHydrationWarning` on `<body>`. It covers that
25
+ element's own attributes only, not its children.
26
+
27
+ ### `suppressHydrationWarning`, only where the content really differs
28
+
29
+ Some content is meant to differ: a cart badge, a greeting, a wishlist heart. Put the
30
+ attribute on the element whose text differs, not on a wrapper:
31
+
32
+ ```tsx
33
+ // Wrong: hides every mismatch in the subtree, including real bugs
34
+ <div suppressHydrationWarning><Header /><CartBadge count={count} /></div>
35
+
36
+ // Right: one element, one known difference
37
+ <span suppressHydrationWarning>{count}</span>
38
+ ```
39
+
40
+ It works one level deep and only for text and attributes. For anything bigger, render a
41
+ placeholder on the server and the real thing after mount.
42
+
43
+ ### Nested links
44
+
45
+ A card that is a link, with a "see more" link inside it, is `<a>` inside `<a>`. React warns
46
+ (`validateDOMNesting`) and the browser splits the outer link. Give the inner component a
47
+ prop that renders a `<span>` when it is already inside a link:
48
+
49
+ ```tsx
50
+ export function SeeMore({ href, insideLink }: { href: string; insideLink?: boolean }) {
51
+ return insideLink ? <span className="see-more">See more</span> : <a href={href} className="see-more">See more</a>;
52
+ }
53
+ ```
54
+
55
+ Find candidates with `rg -l '<a[^>]*>.*<a' src/ --glob '*.tsx'`, then read the components a
56
+ card renders.
57
+
58
+ ## 2. A streamed section that never hydrates (TanStack Start)
59
+
60
+ Symptom: the section looks right, but no effect runs and no handler fires. It hides behind
61
+ plain links (navigation still works) and behind reduced motion (a scroll animation that
62
+ never starts looks like a static grid).
63
+
64
+ Seen on TanStack Start 1.166 with block promises returned through the page server function
65
+ and streamed: a block still pending when the document streamed arrived as a late
66
+ resolution script, and the browser's copy of its promise never settled.
67
+
68
+ Check, after any change to the page route or a TanStack upgrade:
69
+
70
+ 1. Load a page whose blocks call the upstream. In the console, confirm that every block
71
+ promise in the route's loader data is fulfilled.
72
+ 2. Pick a section's DOM node and confirm it has a key starting with `__reactFiber`.
73
+
74
+ If either fails, await every block on the server before returning. TTFB then becomes the
75
+ slowest block (see [`render-location.md`](./render-location.md#3-streamed-blocks-vs-awaited-blocks)),
76
+ so say so in the route file and in the PR. The `deco-v7-to-v8-migration` skill has the same
77
+ note for migrated sites.
78
+
79
+ ## 3. Flashes and blank frames
80
+
81
+ In the example page route, each section block renders inside its own `<Suspense>` with
82
+ a fallback. What the visitor
83
+ sees between the server HTML and the hydrated page depends on that fallback and on how
84
+ the section's component loads.
85
+
86
+ | Symptom | Cause | Fix |
87
+ |---|---|---|
88
+ | A section paints, goes blank or shows its fallback, then paints again | The component is loaded with `React.lazy`, and its module is not ready during hydration, so React drops the server HTML and shows the fallback | Import above-the-fold section components statically in the view map. Keep `React.lazy` for sections below the fold |
89
+ | The page jumps when a section resolves | The fallback is shorter than the section | Give the fallback the section's height (`min-height`, aspect ratio). See [`cls-third-party.md`](./cls-third-party.md) |
90
+ | A section shows the route's failure UI (the example app renders "This content is temporarily unavailable") | The block failed on the server | Read the server log for that block's error. It is a loader failure, not a render problem |
91
+
92
+ To see a flash frame by frame, record a trace with screenshots
93
+ ([`trace-reading.md`](./trace-reading.md)).
94
+
95
+ ## 4. Keys and DOM warnings
96
+
97
+ Fix these even when nothing looks broken: they hide real errors in the console, and a
98
+ wrong key reuses the wrong DOM node.
99
+
100
+ | Warning | Fix |
101
+ |---|---|
102
+ | `Each child in a list should have a unique "key" prop` | A stable id: `key={product.productID}`. An index only for static lists |
103
+ | `Encountered two children with the same key` | The id is not unique (two cards in the same product group). Combine: `` key={`${product.productID}-${index}`} `` |
104
+ | `Invalid DOM property 'fetchpriority'` | `fetchPriority`. Same for SVG: `strokeLinecap`, `fillRule`, `clipRule` |
105
+ | `Invalid DOM property 'class'` | `className` (a Preact leftover) |
106
+ | `value` without `onChange` | Add `onChange`, or use `defaultValue` |
107
+ | `selected` on `<option>` | `value` on the `<select>` |
108
+
109
+ ## Checklist
110
+
111
+ - [ ] Hard reload, console open, zero hydration errors on home, listing, product page
112
+ - [ ] Every block promise fulfilled; a section node has `__reactFiber…`
113
+ - [ ] Above-the-fold sections imported statically
114
+ - [ ] Fallbacks the height of their section
115
+ - [ ] `suppressHydrationWarning` only on single elements with known differences
116
+ - [ ] No nested `<a>`, no key or DOM-property warnings
@@ -0,0 +1,107 @@
1
+ # N+1 calls in block functions
2
+
3
+ Load when: SSR time grows with the number of products on the page; the same upstream
4
+ operation shows up dozens of times for one page; VTEX answers 429.
5
+
6
+ In v8 the loaders a site uses are its own code: the migration vendors v7's app loaders
7
+ into the site, and new ones call a thin client (`createVtexClient` from
8
+ `@decocms/apps-vtex`, and the other `@decocms/apps-*`). Nothing in the framework batches
9
+ or caches those calls. An N+1 is in your code, and so is the fix.
10
+
11
+ ## The pattern
12
+
13
+ ```ts
14
+ // RED FLAG: one upstream call per product
15
+ export async function productShelf(props: { products: Product[] }) {
16
+ const products = await Promise.all(
17
+ props.products.map(async (p) => ({ ...p, specs: await fetchSpecs(p.productID) })),
18
+ );
19
+ return { component: "shelf", props: { products } };
20
+ }
21
+ ```
22
+
23
+ A 24-product shelf is 24 extra round trips before the section can render. A burst like
24
+ that can draw 429s from VTEX, and the VTEX client retries a 429 on idempotent requests
25
+ (2 retries with backoff by default), which adds more wait. A home page with several
26
+ shelves multiplies it.
27
+
28
+ | Pattern | Severity | Example |
29
+ |---|---|---|
30
+ | Upstream call inside `.map()` | Critical | `products.map((p) => fetchSpecs(p.id))` |
31
+ | Data already in the product | High | refetching specs or SKUs the search returned |
32
+ | Per-item call where a batch exists | High | one Master Data search per id |
33
+ | `await` inside a `for` loop | Medium | `for (const p of products) await fetch(p)` |
34
+ | Unbounded `Promise.all` | Medium | `Promise.all(hundredItems.map(fetch))` |
35
+
36
+ ## Fix order
37
+
38
+ **1. Is the data already there?** Most N+1s fetch what the search already returned. An
39
+ Intelligent Search product carries its specification groups and its SKUs, and the
40
+ schema.org mapping in the site's loaders puts them on the product
41
+ (`@decocms/compat-v7/commerce/types`):
42
+
43
+ | Per-item VTEX call | Already on the product as |
44
+ |---|---|
45
+ | `/api/catalog_system/pvt/products/{id}/Specification` | `product.isVariantOf.additionalProperty` |
46
+ | `/api/catalog_system/pub/products/variations/{id}` | `product.isVariantOf.hasVariant` |
47
+
48
+ Delete the call and read the field. If components expect the old shape (numeric spec ids,
49
+ the Catalog API's `{ Id, Name, Value[] }`), write a small adapter from
50
+ `additionalProperty` and keep it next to the components. Get the exact spec names from a
51
+ real search response first: some stores have names with double spaces or trailing
52
+ blanks.
53
+
54
+ **2. Is it per page, not per product?** Related products, "buy together" and cross-selling
55
+ are one call for the page, not one per card. `createVtexClient(...).catalog.crossSelling`
56
+ takes one product id. Call it once for the page's product.
57
+
58
+ **3. Can it batch?** Some APIs take many ids in one call:
59
+
60
+ - Price simulation: `vtex.checkout.simulation({ items: [...] })` takes every SKU of the
61
+ shelf in one `items` array. Build the list, call once, then map results back by id.
62
+ - Master Data: `vtex.masterdata.search(entity, { where: "id=1 OR id=2 OR id=3" })`.
63
+ - Intelligent Search: one `vtex.search.products` call with a facet or query that selects
64
+ the set (a collection, a list of ids your store supports) instead of one search per item.
65
+
66
+ **4. Genuinely per item?** Then bound it. Cap the fan-out, keep the call off the critical
67
+ path (a `Lazy<T>` prop, or a client component that fetches when visible), and cache it
68
+ upstream (see `deco-storefront-caching`). Never `Promise.all` over a list you do not
69
+ control the length of.
70
+
71
+ ## The N+1 that has no loop
72
+
73
+ Two sections each fetch the same product to derive the same facet, then run the same
74
+ faceted search. Inside each block it looks like one call. Across the page it is four.
75
+ That is a duplicate-call problem, not a loop. See [`request-dedupe.md`](./request-dedupe.md).
76
+
77
+ Do not "fix" it by switching to a different upstream API. On one store the tempting swap
78
+ (legacy Catalog to Intelligent Search) changed the shape of `product.category`, which the
79
+ facet was built from, so the shelf silently showed other products. Remove the duplicate
80
+ call you have.
81
+
82
+ ## Find them
83
+
84
+ ```bash
85
+ # upstream calls inside map/forEach/for in the site's code
86
+ grep -rnE "\.map\(\s*async|forEach\(\s*async" src/ .deco/index.ts
87
+ grep -rnE "for \(.*\) *\{" -A3 src/ | grep -n "await"
88
+ # who calls the thin clients
89
+ grep -rnE "\.(search|catalog|checkout|masterdata|io)\.[a-zA-Z]+\(" src/
90
+ ```
91
+
92
+ ## Verify
93
+
94
+ Count calls, do not eyeball the page. The method is in
95
+ [`request-dedupe.md`](./request-dedupe.md#count-the-calls): one log line per upstream
96
+ call in dev, or the `http.client.request.duration` metric in production. After the fix,
97
+ one page load shows one line per operation, not one per product. Then confirm the end
98
+ result with the `curl` timing in `SKILL.md`, on the same URL, cold and warm.
99
+
100
+ ## Checklist
101
+
102
+ - [ ] No upstream call inside `.map(async` in a block function
103
+ - [ ] Specs and SKUs read from the product, not refetched
104
+ - [ ] Cross-selling called once per page
105
+ - [ ] Simulation batched into one `items` array
106
+ - [ ] Every `Promise.all` over external data has a bounded input
107
+ - [ ] Calls counted before and after
@@ -0,0 +1,130 @@
1
+ # Navigation: variant switches, prefetch, scroll and feedback
2
+
3
+ Load when: clicking a size or colour on the product page takes >500 ms; one variant click
4
+ makes two `/_serverFn/` requests; forward navigation keeps the old scroll position; a
5
+ click gives no feedback for seconds; hovering a grid of cards loads the upstream.
6
+
7
+ TanStack Start only. A client-side navigation in v8 calls the page server function (one
8
+ `/_serverFn/` request), which routes, resolves the page's blocks and calls the upstream,
9
+ the same work as a full page render.
10
+
11
+ ## What you already have
12
+
13
+ - `createDecoRouter` turns on `scrollRestoration` and sets `defaultPreload: "intent"`
14
+ (prefetch on hover or focus). You can pass `defaultPreload` to change it.
15
+ - `DecoDocument` renders `NavigationProgress` (a bar at the top while the router loads)
16
+ and `StableOutlet` (keeps the content's height during a navigation, so the footer does
17
+ not jump). A site with its own document can import both from `@decocms/tanstack/react`.
18
+
19
+ ## 1. Variant switches
20
+
21
+ Two kinds of "variant", two mechanics:
22
+
23
+ | Case | Data needed | Do |
24
+ |---|---|---|
25
+ | Same product, other SKU (size, voltage) | Already loaded: `product.isVariantOf.hasVariant` | Change the URL with `history.replaceState`: **zero requests** |
26
+ | Other product (a colour that is its own product) | A new product | Navigate: exactly one request, with a loading state |
27
+
28
+ A product page usually loads every SKU in the first render. A `?skuId=` in the URL is for
29
+ sharing and bookmarks. If the page route passes the search string to the page server
30
+ function, any change to it reloads the whole page. Do not route a same-product SKU change
31
+ through the router:
32
+
33
+ ```tsx
34
+ const [current, setCurrent] = useState(() => relativeUrl(product.url));
35
+
36
+ const onVariant = useCallback((event: React.MouseEvent, href: string) => {
37
+ event.preventDefault();
38
+ setCurrent(href);
39
+ window.history.replaceState(null, "", href);
40
+ }, []);
41
+
42
+ <a href={href} onClick={(e) => onVariant(e, href)} aria-current={href === current}>
43
+ {label}
44
+ </a>
45
+ ```
46
+
47
+ Use a plain `<a>` with `preventDefault`, not `<Link>`: a `<Link>` asks the router, and the
48
+ router fetches. The router does not see this URL change; that is the point. A reload or a
49
+ shared link opens the right SKU as long as the page reads `skuId` on the server.
50
+
51
+ ### The double fetch
52
+
53
+ A `<Link to="…?skuId=160">` with prefetch on intent fires twice: hover prefetches one URL,
54
+ the click loads another (with a different search string), and the prefetched result is
55
+ not reused. On variant links, turn prefetch off: `<Link preload={false}>`. Prefetch is for
56
+ pages you do not have yet; a variant of the page you are on is not one.
57
+
58
+ ## 2. Prefetch on dense grids
59
+
60
+ With `defaultPreload: "intent"`, moving the mouse across a listing page prefetches each
61
+ card's product page. Each one is a server function call that resolves a full page against
62
+ the upstream. On a grid of 48 cards that can be dozens of upstream page loads per visitor
63
+ who never clicks.
64
+
65
+ Measure it: record a HAR while you move the mouse over a grid, then count `/_serverFn/`
66
+ entries. Options, in order of preference:
67
+
68
+ 1. Let the site's `pageCache` answer them. The worker calls it for server-function
69
+ requests too, so a cached product page costs no upstream. See `deco-storefront-caching`.
70
+ 2. Turn prefetch off on card links only (`preload={false}`), and keep it on menus and
71
+ other links people hover with intent.
72
+ 3. `createDecoRouter({ defaultPreload: false })`, and opt in per link.
73
+
74
+ ## 3. Scroll to top on forward navigation
75
+
76
+ `scrollRestoration` restores the position on back and forward. If forward navigation (a
77
+ card click to a product page) sometimes leaves the new page scrolled down, scroll on
78
+ resolved navigations that are not history traversal:
79
+
80
+ ```ts
81
+ // src/router.tsx, after createDecoRouter
82
+ if (typeof window !== "undefined") {
83
+ let lastAction: string | undefined;
84
+ router.history.subscribe(({ action }) => {
85
+ lastAction = action.type;
86
+ });
87
+ router.subscribe("onResolved", (event) => {
88
+ // PUSH and REPLACE are forward navigations; BACK, FORWARD and GO are restored by the router
89
+ if (event.pathChanged && (lastAction === "PUSH" || lastAction === "REPLACE")) {
90
+ window.scrollTo({ top: 0 });
91
+ }
92
+ });
93
+ }
94
+ ```
95
+
96
+ Check that back still restores the old position after adding it.
97
+
98
+ ## 4. Feedback on the clicked element
99
+
100
+ `NavigationProgress` is a thin bar. On product cards, a spinner over the clicked card is
101
+ clearer. `useRouterState` tells you a navigation to that card's path is pending:
102
+
103
+ ```tsx
104
+ import { Link, useRouterState } from "@tanstack/react-router";
105
+
106
+ export function CardLink({ to, children, className }: { to: string; children: React.ReactNode; className?: string }) {
107
+ const pending = useRouterState({
108
+ select: (s) => s.isLoading && s.location.pathname === to && s.resolvedLocation?.pathname !== to,
109
+ });
110
+ return (
111
+ <Link to={to} className={`relative ${className ?? ""}${pending ? " pointer-events-none" : ""}`}>
112
+ {children}
113
+ {pending && <span className="absolute inset-0 grid place-items-center bg-white/60" aria-hidden>…</span>}
114
+ </Link>
115
+ );
116
+ }
117
+ ```
118
+
119
+ Use it on the card image. On text links the overlay looks odd; the top bar is enough.
120
+
121
+ ## Verify
122
+
123
+ Record a HAR (a script, so both runs click the same things) and count `/_serverFn/`
124
+ requests:
125
+
126
+ - Same-product variant click: **0**.
127
+ - Other-product variant click: **1**.
128
+ - Card click after hovering it: **1** in total, not 2.
129
+
130
+ Then time the click to the next paint in a Performance trace ([`trace-reading.md`](./trace-reading.md)).
@@ -0,0 +1,163 @@
1
+ # Payload trim: smaller Product graphs before they reach the HTML
2
+
3
+ Load when: a listing page's HTML is several MB; a `/_serverFn/` navigation response is
4
+ huge; the HTML holds thousands of `UnitPriceSpecification` entries; JSON-LD is large.
5
+
6
+ ## Why the HTML is heavy
7
+
8
+ On TanStack Start, what a block returns becomes route loader data. It is serialised into
9
+ the HTML for hydration, and again into the `/_serverFn/` response of every client-side
10
+ navigation. On Next.js, props passed to client components go into the RSC payload. Every
11
+ field the block returns is shipped, whether a component reads it or not.
12
+
13
+ A VTEX `Product` (schema.org shape, `@decocms/compat-v7/commerce/types`) is mostly ballast
14
+ for a product card:
15
+
16
+ - `offers.offers[].priceSpecification`: one `UnitPriceSpecification` per installment plan,
17
+ often ~30 per offer.
18
+ - `isSimilarTo[]`: up to ~10 full `Product` graphs, for colour swatches.
19
+ - `additionalProperty`: dozens of entries.
20
+ - `image[]`: every image of the product.
21
+
22
+ Measured on a listing page of a VTEX store after trimming:
23
+
24
+ | | before | after |
25
+ |---|---|---|
26
+ | Raw HTML | 28.7 MB | 2.89 MB (−89.9%) |
27
+ | `UnitPriceSpecification` count | 63,744 | 585 (−99.1%) |
28
+ | `PropertyValue` count | 82,877 | 11,577 (−86.0%) |
29
+ | `ImageObject` count | 13,497 | 1,921 (−85.8%) |
30
+
31
+ ## Rule: check every reader, then trim what nobody reads
32
+
33
+ List the components that read the product on that page and what each reads. A typical
34
+ listing:
35
+
36
+ | Reader | Reads | Keep |
37
+ |---|---|---|
38
+ | `useOffer` (`@decocms/compat-v7/commerce/sdk/useOffer`) | `offers.offers[0]`: price, availability, seller, the `ListPrice` spec and the best `Installment` | `ListPrice` + best `Installment` |
39
+ | Product card | name, url, `productID`, first image, some `additionalProperty`, `isVariantOf.hasVariant` for sizes | the card's fields; `hasVariant` |
40
+ | Colour swatches | on each `isSimilarTo[]`: availability, thumbnails, the colour property, `isVariantOf.productGroupID` | only those |
41
+ | Quick-buy size selector | each `hasVariant[]` offer: availability and its price specs | slimmed specs, not dropped |
42
+ | Product page | the whole graph | **do not trim** |
43
+
44
+ Your store's components may read more. Grep them before you remove a field.
45
+
46
+ ## The trim functions
47
+
48
+ ```ts
49
+ // src/sdk/productPayload.ts
50
+ import type {
51
+ AggregateOffer,
52
+ Product,
53
+ ProductListingPage,
54
+ UnitPriceSpecification,
55
+ } from "@decocms/compat-v7/commerce/types";
56
+ import { bestInstallment } from "@decocms/compat-v7/commerce/sdk/useOffer";
57
+
58
+ const LIST_PRICE = "https://schema.org/ListPrice";
59
+ const SWATCH_PROPS = new Set(["Color"]); // your store's colour property names
60
+
61
+ /** ListPrice plus the installment useOffer would pick, nothing else. */
62
+ const slimSpecs = (specs: UnitPriceSpecification[] = []): UnitPriceSpecification[] => {
63
+ const list = specs.find((s) => s.priceType === LIST_PRICE);
64
+ const best = specs.reduce(bestInstallment, null);
65
+ return [list, best].filter((s): s is UnitPriceSpecification => !!s);
66
+ };
67
+
68
+ const slimOffers = (agg: AggregateOffer | undefined, dropSpecs = false) => {
69
+ const first = agg?.offers?.[0];
70
+ if (!agg || !first) return agg;
71
+ return { ...agg, offers: [{ ...first, priceSpecification: dropSpecs ? [] : slimSpecs(first.priceSpecification) }] };
72
+ };
73
+
74
+ const isThumb = (img: { alternateName?: string; url?: string }) =>
75
+ /thumb/i.test(img.alternateName ?? "") || /thumb/i.test(img.url ?? "");
76
+
77
+ /** isSimilarTo[]: what a swatch reads. */
78
+ const slimSimilar = (p: Product): Product => {
79
+ const thumbs = p.image?.filter(isThumb);
80
+ return {
81
+ ...p,
82
+ image: thumbs?.length ? thumbs : p.image?.slice(0, 1),
83
+ additionalProperty: p.additionalProperty?.filter((x) => SWATCH_PROPS.has(x.name ?? "")),
84
+ offers: slimOffers(p.offers, true), // swatches read availability only
85
+ isVariantOf: p.isVariantOf && ({ productGroupID: p.isVariantOf.productGroupID } as Product["isVariantOf"]),
86
+ isSimilarTo: undefined, // never nest: a later change would grow it geometrically
87
+ };
88
+ };
89
+
90
+ export const trimProductForCard = (p: Product): Product => ({
91
+ ...p,
92
+ offers: slimOffers(p.offers),
93
+ isSimilarTo: p.isSimilarTo?.map(slimSimilar),
94
+ isVariantOf: p.isVariantOf && {
95
+ ...p.isVariantOf,
96
+ hasVariant: p.isVariantOf.hasVariant?.map((v) => ({ ...v, offers: slimOffers(v.offers) })),
97
+ },
98
+ });
99
+
100
+ export const trimListingPage = (page: ProductListingPage | null) =>
101
+ page?.products?.length ? { ...page, products: page.products.map(trimProductForCard) } : page;
102
+ ```
103
+
104
+ `bestInstallment` is the reducer `useOffer` uses, so the card shows the same installment
105
+ after the trim as before. The functions build new objects and never mutate their input.
106
+ That matters in v8: a block's result is shared by every place in the request that named
107
+ the same block with the same inputs, and the product page may be one of them.
108
+
109
+ Adapt the swatch filter (`isThumb`, `SWATCH_PROPS`) to what your store's components read.
110
+ Thumbnail naming differs between stores.
111
+
112
+ ## Where to apply it
113
+
114
+ In the block function or vendored loader that returns the products for a card list, just
115
+ before it returns:
116
+
117
+ ```ts
118
+ export async function productListingPage(props: Props) {
119
+ const page = await loadListing(props); // your mapping to schema.org
120
+ return trimListingPage(page);
121
+ }
122
+ ```
123
+
124
+ - Every path that renders cards must trim: the first render, "load more", infinite scroll,
125
+ and any server function that returns products. A path you forget brings back the full
126
+ payload and breaks nothing visibly.
127
+ - Keep the product page on the full graph. Use a different block (or a prop) for cards.
128
+ - Trimming does not shrink an upstream cache that stores the raw VTEX response. It shrinks
129
+ the HTML, the `/_serverFn/` responses, and a page cache that stores either.
130
+
131
+ ## JSON-LD on listing pages
132
+
133
+ Structured data is serialised too. A listing's JSON-LD is an `ItemList` of `ListItem` with
134
+ `url` and `position`; the full `Product` belongs on the product page. One store emitted a
135
+ `"Products"` type (not in schema.org, so no crawler read it) at 2.75 MB per listing page.
136
+ The `ItemList` form was 6,198 bytes. Feed the SEO block from the same loader block as the
137
+ page (so the client runs it once) and map to the small shape there.
138
+
139
+ ## Personal data in the HTML
140
+
141
+ Never embed shopper data (cart, postal code, name, session) in server-rendered HTML or
142
+ loader data of a page that can be cached. One cached copy serves it to the next visitor.
143
+ Load it in a client component after hydration. Cache rules are in `deco-storefront-caching`.
144
+
145
+ ## Verify
146
+
147
+ ```bash
148
+ URL=https://www.example.com/some-listing
149
+ curl -s "$URL" | wc -c # raw HTML bytes
150
+ curl -s --compressed -o /dev/null -w '%{size_download}\n' "$URL" # bytes on the wire
151
+ curl -s "$URL" | grep -o UnitPriceSpecification | wc -l # bloat marker, should fall ~99%
152
+ ```
153
+
154
+ Do the same for the navigation response: open the page, click to another listing, and
155
+ read the `/_serverFn/` response size in DevTools.
156
+
157
+ Visual checks after the trim:
158
+
159
+ - [ ] Cards show price, list price and installment text as before
160
+ - [ ] Colour swatches render and link to the right products
161
+ - [ ] The size selector disables out-of-stock sizes
162
+ - [ ] "Load more" and infinite scroll render trimmed cards correctly
163
+ - [ ] The product page is unchanged