@decocms/blocks 8.10.0 โ†’ 8.12.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 (210) hide show
  1. package/dist/index.d.ts +1 -1
  2. package/dist/index.d.ts.map +1 -1
  3. package/dist/index.js.map +1 -1
  4. package/dist/protocol/conformance/blockMetaVectors.json +80 -0
  5. package/dist/protocol/index.d.ts +5 -2
  6. package/dist/protocol/index.d.ts.map +1 -1
  7. package/dist/protocol/index.js +5 -2
  8. package/dist/protocol/index.js.map +1 -1
  9. package/dist/v8/blockMeta.d.ts +33 -4
  10. package/dist/v8/blockMeta.d.ts.map +1 -1
  11. package/dist/v8/blockMeta.js +70 -13
  12. package/dist/v8/blockMeta.js.map +1 -1
  13. package/dist/v8/cli/index.d.ts +1 -0
  14. package/dist/v8/cli/index.d.ts.map +1 -1
  15. package/dist/v8/cli/index.js +1 -0
  16. package/dist/v8/cli/index.js.map +1 -1
  17. package/dist/v8/cli/run.d.ts +2 -0
  18. package/dist/v8/cli/run.d.ts.map +1 -1
  19. package/dist/v8/cli/run.js +30 -1
  20. package/dist/v8/cli/run.js.map +1 -1
  21. package/dist/v8/cli/skills.d.ts +25 -0
  22. package/dist/v8/cli/skills.d.ts.map +1 -0
  23. package/dist/v8/cli/skills.js +70 -0
  24. package/dist/v8/cli/skills.js.map +1 -0
  25. package/dist/v8/client.d.ts +6 -4
  26. package/dist/v8/client.d.ts.map +1 -1
  27. package/dist/v8/client.js +26 -70
  28. package/dist/v8/client.js.map +1 -1
  29. package/dist/v8/cms.d.ts.map +1 -1
  30. package/dist/v8/cms.js +1 -2
  31. package/dist/v8/cms.js.map +1 -1
  32. package/dist/v8/contentIndex.d.ts +18 -7
  33. package/dist/v8/contentIndex.d.ts.map +1 -1
  34. package/dist/v8/contentIndex.js +46 -17
  35. package/dist/v8/contentIndex.js.map +1 -1
  36. package/dist/v8/draftChanges.d.ts.map +1 -1
  37. package/dist/v8/draftChanges.js +4 -1
  38. package/dist/v8/draftChanges.js.map +1 -1
  39. package/dist/v8/index.d.ts +1 -1
  40. package/dist/v8/index.d.ts.map +1 -1
  41. package/dist/v8/remoteLoader.d.ts +4 -2
  42. package/dist/v8/remoteLoader.d.ts.map +1 -1
  43. package/dist/v8/remoteLoader.js +13 -3
  44. package/dist/v8/remoteLoader.js.map +1 -1
  45. package/dist/v8/types.d.ts +47 -7
  46. package/dist/v8/types.d.ts.map +1 -1
  47. package/package.json +3 -2
  48. package/skills/deco-apps/SKILL.md +82 -0
  49. package/skills/deco-apps/references/algolia.md +51 -0
  50. package/skills/deco-apps/references/commerce-types.md +132 -0
  51. package/skills/deco-apps/references/instrumented-fetch.md +144 -0
  52. package/skills/deco-apps/references/magento.md +55 -0
  53. package/skills/deco-apps/references/messaging.md +76 -0
  54. package/skills/deco-apps/references/shopify.md +69 -0
  55. package/skills/deco-apps/references/vendored-loaders.md +135 -0
  56. package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
  57. package/skills/deco-apps/references/vtex.md +150 -0
  58. package/skills/deco-apps/references/wake.md +75 -0
  59. package/skills/deco-cms-schema/SKILL.md +80 -0
  60. package/skills/deco-cms-schema/references/annotations.md +147 -0
  61. package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
  62. package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
  63. package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
  64. package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
  65. package/skills/deco-go-live/SKILL.md +127 -0
  66. package/skills/deco-go-live/references/content-releases.md +90 -0
  67. package/skills/deco-go-live/references/process.md +106 -0
  68. package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
  69. package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
  70. package/skills/deco-go-live/references/qa-inventory.md +120 -0
  71. package/skills/deco-go-live/references/react-spa.md +183 -0
  72. package/skills/deco-go-live/references/seo-analytics.md +114 -0
  73. package/skills/deco-go-live/references/traffic-ramp.md +87 -0
  74. package/skills/deco-go-live/references/worker-runtime.md +93 -0
  75. package/skills/deco-go-live/scripts/preflight.sh +221 -0
  76. package/skills/deco-images-media/SKILL.md +64 -0
  77. package/skills/deco-images-media/references/asset-upload.md +191 -0
  78. package/skills/deco-images-media/references/components-per-binding.md +167 -0
  79. package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
  80. package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
  81. package/skills/deco-images-media/references/troubleshooting.md +147 -0
  82. package/skills/deco-images-media/references/video.md +122 -0
  83. package/skills/deco-make-editable/SKILL.md +94 -0
  84. package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
  85. package/skills/deco-make-editable/references/content-shapes.md +203 -0
  86. package/skills/deco-make-editable/references/from-figma.md +110 -0
  87. package/skills/deco-make-editable/references/i18n-fields.md +112 -0
  88. package/skills/deco-make-editable/references/inventory.md +79 -0
  89. package/skills/deco-make-editable/references/pixel-parity.md +175 -0
  90. package/skills/deco-make-editable/references/seeding-content.md +119 -0
  91. package/skills/deco-nextjs-site/SKILL.md +74 -0
  92. package/skills/deco-nextjs-site/references/caching.md +116 -0
  93. package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
  94. package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
  95. package/skills/deco-nextjs-site/references/rendering.md +172 -0
  96. package/skills/deco-nextjs-site/references/setup.md +190 -0
  97. package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
  98. package/skills/deco-site-authoring/SKILL.md +75 -0
  99. package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
  100. package/skills/deco-site-authoring/references/loaders.md +192 -0
  101. package/skills/deco-site-authoring/references/pages.md +158 -0
  102. package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
  103. package/skills/deco-site-authoring/references/sections.md +158 -0
  104. package/skills/deco-site-authoring/references/seo.md +116 -0
  105. package/skills/deco-site-workflow/SKILL.md +101 -0
  106. package/skills/deco-site-workflow/references/check.md +116 -0
  107. package/skills/deco-site-workflow/references/cli-reference.md +106 -0
  108. package/skills/deco-site-workflow/references/content-layout.md +93 -0
  109. package/skills/deco-site-workflow/references/content-sync.md +146 -0
  110. package/skills/deco-site-workflow/references/delivery.md +51 -0
  111. package/skills/deco-site-workflow/references/deploy.md +87 -0
  112. package/skills/deco-site-workflow/references/schema.md +173 -0
  113. package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
  114. package/skills/deco-storefront-caching/SKILL.md +67 -0
  115. package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
  116. package/skills/deco-storefront-caching/references/case-study.md +82 -0
  117. package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
  118. package/skills/deco-storefront-caching/references/nextjs.md +60 -0
  119. package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
  120. package/skills/deco-storefront-caching/references/verification.md +136 -0
  121. package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
  122. package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
  123. package/skills/deco-storefront-performance/SKILL.md +81 -0
  124. package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
  125. package/skills/deco-storefront-performance/references/hydration.md +116 -0
  126. package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
  127. package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
  128. package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
  129. package/skills/deco-storefront-performance/references/render-location.md +152 -0
  130. package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
  131. package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
  132. package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
  133. package/skills/deco-tanstack-site/SKILL.md +68 -0
  134. package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
  135. package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
  136. package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
  137. package/skills/deco-tanstack-site/references/server-functions.md +123 -0
  138. package/skills/deco-tanstack-site/references/setup.md +153 -0
  139. package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
  140. package/skills/deco-v7-to-v8-migration/SKILL.md +123 -0
  141. package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
  142. package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
  143. package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
  144. package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
  145. package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
  146. package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
  147. package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
  148. package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
  149. package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
  150. package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
  151. package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
  152. package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
  153. package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
  154. package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
  155. package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
  156. package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
  157. package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
  158. package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
  159. package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
  160. package/skills/deco-v7-to-v8-migration/references/verify.md +23 -0
  161. package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
  162. package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
  163. package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
  164. package/skills/deco-v7-to-v8-migration/scripts/checkContentReads.ts +32 -0
  165. package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
  166. package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
  167. package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
  168. package/skills/deco-v7-to-v8-migration/scripts/contentReads.ts +157 -0
  169. package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
  170. package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
  171. package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
  172. package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
  173. package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
  174. package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
  175. package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
  176. package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
  177. package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
  178. package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +180 -0
  179. package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
  180. package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
  181. package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
  182. package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
  183. package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
  184. package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
  185. package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
  186. package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
  187. package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
  188. package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
  189. package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
  190. package/skills/deco-variants/SKILL.md +57 -0
  191. package/skills/deco-variants/references/caching-variants.md +63 -0
  192. package/skills/deco-variants/references/custom-matchers.md +83 -0
  193. package/skills/deco-variants/references/draft-preview.md +59 -0
  194. package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
  195. package/skills/deco-variants/references/multivariate.md +85 -0
  196. package/skills/deco-variants/references/v7-matchers.md +71 -0
  197. package/src/index.ts +1 -1
  198. package/src/protocol/conformance/blockMetaVectors.json +80 -0
  199. package/src/protocol/index.ts +8 -1
  200. package/src/v8/blockMeta.ts +75 -11
  201. package/src/v8/cli/index.ts +1 -0
  202. package/src/v8/cli/run.ts +35 -1
  203. package/src/v8/cli/skills.ts +91 -0
  204. package/src/v8/client.ts +32 -77
  205. package/src/v8/cms.ts +1 -2
  206. package/src/v8/contentIndex.ts +49 -19
  207. package/src/v8/draftChanges.ts +5 -1
  208. package/src/v8/index.ts +1 -1
  209. package/src/v8/remoteLoader.ts +13 -3
  210. package/src/v8/types.ts +48 -7
@@ -0,0 +1,139 @@
1
+ # Proxy, headers and checkout
2
+
3
+ The worker sits in front of everything: store pages, a proxied checkout,
4
+ `/api`, media and, during the ramp, the old site. A header the new stack adds
5
+ or a proxy that behaves differently shows up as lost conversion, not as an
6
+ error. Always compare with the old site.
7
+
8
+ On v8 the framework ships no commerce proxy. A proxied checkout is the site's
9
+ own code in `createDecoWorker({ routes })`. What the worker does to every
10
+ response on the way out still applies to it:
11
+
12
+ - On an HTML response, it sets each of its security headers **only when the response has none**: `X-Content-Type-Options`, `Referrer-Policy`, `Permissions-Policy`, `X-XSS-Protection`, `Strict-Transport-Security`, `Cross-Origin-Opener-Policy: same-origin-allow-popups`, and a `Content-Security-Policy`: the site's `csp` option with Studio's origins added, or, with no `csp`, only a `frame-ancestors` listing Studio's origins. So a proxied page that sends no CSP of its own can then be framed only by Studio (no `X-Frame-Options` is sent).
13
+ - It sets `CDN-Cache-Control: no-store` on any response that names none.
14
+ - It keeps one `Set-Cookie` per cookie (name, Domain and Path).
15
+ - A `routes` response gets no `preload` hints.
16
+
17
+ ## Header diff against the old site
18
+
19
+ **What happened:** the v7 TanStack worker sent `Cross-Origin-Opener-Policy:
20
+ same-origin-allow-popups` on all HTML; the proxied checkout had none and the
21
+ old Fresh site never sent COOP. Every store โ†’ checkout navigation switched
22
+ browsing-context group: popups lost `window.opener`, `window.name` was wiped,
23
+ and WebKit reset its timing clock. v8 sends the same default.
24
+
25
+ Fix: set the header yourself on the responses that must not carry it. The
26
+ worker never overwrites a header the response already has.
27
+
28
+ ```ts
29
+ // in your routes proxy, on the proxied checkout's response
30
+ const out = new Response(upstream.body, upstream);
31
+ out.headers.set("Cross-Origin-Opener-Policy", "unsafe-none");
32
+ return out;
33
+ ```
34
+
35
+ For pages the app renders, set it in the route's `headers` (they reach the document response). If the
36
+ old site sent no COOP anywhere, decide it once for the whole site.
37
+
38
+ ```bash
39
+ for host in "$OLD" "$CANDIDATE"; do
40
+ for p in / /checkout/; do
41
+ echo "== $host$p"
42
+ curl -sI -A "Mozilla/5.0 Chrome/139" "$host$p" \
43
+ | grep -iE "cross-origin|content-security|permissions-policy|x-frame|referrer-policy|strict-transport"
44
+ done
45
+ done
46
+ ```
47
+
48
+ Any header the new stack adds that the old one did not is a parity risk on
49
+ same-origin navigations to proxied pages. The CSP is also the site's: pass it
50
+ as `createDecoWorker({ csp: { enforce, reportOnly, frameAncestors } })`
51
+ (**deco-tanstack-site**). Start with `reportOnly` if the old site had none.
52
+
53
+ ## Checkout HTML, 304 and bfcache
54
+
55
+ **What happened (two rounds):**
56
+
57
+ 1. A proxy forced `private, no-store` on the checkout HTML, so it was never restored from bfcache. "Back" reloaded in 3 to 10 s, lost the coupon or card, and fired the tag-manager steps again.
58
+ 2. Relaxing it to `private, no-cache, max-age=0, must-revalidate` made the browser store the HTML **with the platform's `Last-Modified`**. The next visit sent `If-Modified-Since`, the proxy passed it on, the platform answered 304, and the browser rendered a stale checkout. Anonymous conversion dropped from 28.8% to 23.8%.
59
+
60
+ Fix: on `GET` of the checkout paths, strip `If-Modified-Since` and
61
+ `If-None-Match` before proxying, and delete `Last-Modified` and `ETag` from the
62
+ checkout HTML. Keep `CDN-Cache-Control: no-store` (the worker's default).
63
+
64
+ ```bash
65
+ curl -sD- -o /dev/null -A "Mozilla/5.0 Chrome/139" \
66
+ -H "If-Modified-Since: Tue, 20 Oct 2026 00:00:00 GMT" "$CANDIDATE/checkout/" \
67
+ | grep -iE "^HTTP|last-modified|etag|cache-control"
68
+ # expect 200, no Last-Modified, no ETag
69
+ ```
70
+
71
+ ๐Ÿงช bfcache: DevTools โ†’ Application โ†’ Back/forward cache on the checkout, **on
72
+ a deployed preview**. A dev server's proxy may bypass the worker. In the
73
+ browser, `performance.getEntriesByType('navigation')[0].transferSize` of about
74
+ 300 bytes means a 304 was reused.
75
+
76
+ Large proxied bodies: stream them (`new Response(upstream.body, upstream)`);
77
+ never `await upstream.text()` on a whole page ([worker-runtime.md](./worker-runtime.md#memory-128-mb-per-isolate)).
78
+
79
+ ## Third-party checkout scripts
80
+
81
+ **What happened:** an inline shim fixed a JS error in a store's custom
82
+ checkout script. Unblocking that code path made a broken call post
83
+ `marketingData` and **remove the coupon**, and an order-form patch made a
84
+ payment guard swallow "place order". The old site never reached that code,
85
+ because the error stopped it first.
86
+
87
+ - Errors that also happen on the old site may be load-bearing. In checkout, parity beats correctness.
88
+ - Byte-compare the proxied checkout HTML, old against new, and list every injected inline script. Put each injection behind a flag you can turn off.
89
+ - Measure payment-method pick โ†’ transaction on both stacks before blaming the migration.
90
+ - A third party that posts the order form's marketing data replaces the whole object. Read, merge, then write, so UTMs and your own tags survive.
91
+ - Never `<link rel=prefetch>` a third-party script that the next page loads with `crossorigin`. A cache mismatch stopped one checkout from mounting for about 2 hours.
92
+ - Store cart and checkout must share the same order-form cookie.
93
+
94
+ ```bash
95
+ strip() { sed -E 's/[0-9a-f]{8,}//g; s/[0-9]{10,}//g'; }
96
+ diff <(curl -s "$OLD/checkout/" | strip) <(curl -s "$CANDIDATE/checkout/" | strip) | head -50
97
+ ```
98
+
99
+ ## Bugs that only exist on the real host
100
+
101
+ Previews on a `workers.dev` or preview domain miss them.
102
+
103
+ | Symptom | Root cause |
104
+ |---|---|
105
+ | server-side calls to `https://www.<domain>` hit the old site | a Worker's fetch to its own public hostname does not run the Worker again; it goes to the zone's origin |
106
+ | tags or analytics behave differently in production | tags gated on the hostname |
107
+ | a Studio draft link shows the release on the real host | once a release carries `previewHosts` (Studio writes them), drafts preview only on those hosts plus `createCMS({ preview: { hosts } })`; any other host gets the release |
108
+
109
+ ```bash
110
+ grep -rn "https://www\.<domain>" src # server-side self-fetch, host checks
111
+ ```
112
+
113
+ For every hit of the domain in `src/`, ask: what changes when the host **is**
114
+ this one? Test with the production `Host` before the route goes live.
115
+
116
+ ## Self-redirect loop on encoded paths
117
+
118
+ **What happened on v7 TanStack sites:** the router compared the request's
119
+ path with the one it would build and redirected on a mismatch. Braces were not
120
+ re-encoded, so `/{x}` โ†’ 307 `/{x}` โ†’ the browser re-encodes โ†’ loop
121
+ (`ERR_TOO_MANY_REDIRECTS`, ~17k 307s a day from one login modal's
122
+ `<img src="{{qRCodeUrl}}">`). The v8 worker adds no guard for this. If the
123
+ fuzz below loops, answer such paths with a 404 in `routes`, before the router.
124
+
125
+ ```bash
126
+ for p in '/%7Bx%7D' '/x%7B' '/foo-%7Bx%7D-1/p' '/%5Bx%5D' '/%7Cx' '/%5Ex' '/a%20b'; do
127
+ curl -s -o /dev/null -L --max-redirs 10 -A "Mozilla/5.0 Chrome/139" \
128
+ -w "$p %{http_code} hops=%{num_redirects}\n" "$CANDIDATE$p"
129
+ done # 5 or more hops (or curl error 47) is a loop
130
+ ```
131
+
132
+ It is not only braces: `^` also looped on one store. Fuzz every character the
133
+ router may decode and not re-encode.
134
+
135
+ ## Requests the worker answers itself
136
+
137
+ - `/deco/_liveness` answers `OK`. Use it for uptime checks, not `/`.
138
+ - `/deco/*`, `/live/*` and `/.decofile` answer 404 (v7's admin paths). Old tooling or monitors that call them see 404s; update them. During a ramp this also affects the old site ([traffic-ramp.md](./traffic-ramp.md#traps)).
139
+ - A page request with `Authorization` answers `Cache-Control: private, no-cache, no-store, must-revalidate`, whatever the app set.
@@ -0,0 +1,150 @@
1
+ # QA checklist template
2
+
3
+ Fill this from the [inventory](./qa-inventory.md). Keep only the sections the
4
+ site has, put a real file and a real URL in each row, and add a row for every
5
+ site-specific block the template doesn't cover. Mark the purchase path (home โ†’
6
+ listing โ†’ product โ†’ cart โ†’ checkout) as P0.
7
+
8
+ Record PASS / FAIL / N/A per row. "Not checked" is not N/A.
9
+
10
+ Test every interactive row twice: after a full load (F5) and after reaching
11
+ the page by a **SPA click** ([react-spa.md](./react-spa.md)).
12
+
13
+ ## A. Build and content
14
+
15
+ | # | Test | How to verify | Where |
16
+ |---|---|---|---|
17
+ | A1 | Build succeeds | the site's build script exits 0 | `vite.config.ts` / `next.config.*` |
18
+ | A2 | Schema is current | `deco schema --check` exits 0 | `.deco/schema.gen.json` |
19
+ | A3 | Content fits the schema | `deco check` (and `--draft=<name>` for the draft under test): 0 errors | `.deco/blocks` |
20
+ | A4 | Every saved block type exists | `deco check` reports no `no saved block or block type` | `.deco/index.ts` |
21
+ | A5 | Dev server starts clean | no errors in the terminal or the browser console | worker entry, root route |
22
+
23
+ ## B. Page loads (one row per route template)
24
+
25
+ | # | Test | How to verify | Route |
26
+ |---|---|---|---|
27
+ | B1 | Home renders every section | visual check, console clean | `/` |
28
+ | B2 | Listing renders the product grid | a real category URL | catch-all |
29
+ | B3 | Product page renders every section | a real product URL, one with and one without optional blocks | catch-all |
30
+ | B4 | Search renders results and the empty state | a real term, then nonsense | catch-all or search route |
31
+ | B5 | Institutional pages render | one per template | catch-all |
32
+ | B6 | Not found is a real 404 | `curl -o /dev/null -w '%{http_code}'` on a made-up path โ†’ 404 | catch-all |
33
+ | B7 | A lazy section loads and its fallback is sane | throttle the network; scroll to it | lazy blocks |
34
+
35
+ ## C. Header
36
+
37
+ | # | Test | How to verify |
38
+ |---|---|---|
39
+ | C1 | Announcement bar renders (and rotates, if it does) | visual |
40
+ | C2 | Menu opens on mobile, closes on Escape and on the overlay | click, key, click |
41
+ | C3 | Mega-menu opens on hover on desktop | hover each top item |
42
+ | C4 | Search opens, suggests the **typed** term, submits | type a product name |
43
+ | C5 | Minicart opens; the badge counts items | add an item |
44
+ | C6 | Login or account entry works | click it, signed out and signed in |
45
+
46
+ ## D. Sliders and carousels (one row per instance)
47
+
48
+ | # | Test | How to verify |
49
+ |---|---|---|
50
+ | D1 | Previous and next work | click the arrows |
51
+ | D2 | Dots work | click the dots |
52
+ | D3 | Autoplay advances, if configured | wait one interval |
53
+ | D4 | Listeners are cleaned up | navigate away and back 3ร—; listener count stays flat |
54
+
55
+ ## E. Product page
56
+
57
+ | # | Test | How to verify |
58
+ |---|---|---|
59
+ | E1 | Gallery loads; zoom works | click or hover the main image |
60
+ | E2 | Variant picker changes the SKU, price and URL, and stays on the site | pick each dimension |
61
+ | E3 | Product โ†’ product by SPA click shows the new product's images at once | click a related product |
62
+ | E4 | Buy button adds the item, shows a loading state, opens the minicart | click once; double click adds once |
63
+ | E5 | Shipping estimate returns options; the URL doesn't change | enter a postal code |
64
+ | E6 | Out-of-stock state shows; buy button disabled | an unavailable SKU |
65
+ | E7 | Reviews, recommendations, wishlist, share render or fail quietly | each block present on the page |
66
+ | E8 | Breadcrumb links work | click each item |
67
+
68
+ ## F. Cart
69
+
70
+ | # | Test | How to verify |
71
+ |---|---|---|
72
+ | F1 | Items show image, name, price, quantity | add two different items |
73
+ | F2 | Quantity change and remove update the total | +, โˆ’, remove |
74
+ | F3 | Coupon applies and survives a reload | a valid and an invalid code |
75
+ | F4 | Free-shipping progress updates | add items near the threshold |
76
+ | F5 | **Change quantity, then go to checkout within 300 ms**: checkout shows the new quantity | WebKit and Chromium |
77
+ | F6 | Checkout button reaches checkout with the same cart | compare the order form |
78
+
79
+ ## G. Listing and search
80
+
81
+ | # | Test | How to verify |
82
+ |---|---|---|
83
+ | G1 | Filters apply; from page 2 they reset to page 1 | apply a filter on page 2 |
84
+ | G2 | Sort reorders and keeps the filters | change sort with a filter on |
85
+ | G3 | Pagination or "load more" works and keeps `q` and `sort` | page 2, 3 |
86
+ | G4 | Price range filter works | slider or inputs |
87
+ | G5 | Empty result shows the fallback | a nonsense term |
88
+ | G6 | Cards link to the product; discount flags render | click, visual |
89
+ | G7 | Title, description, canonical and `rel=next/prev` match the old site | view source on page 1 and 2 |
90
+
91
+ ## H. Modals and drawers
92
+
93
+ One row per drawer or modal in the inventory: it opens, closes on Escape,
94
+ closes on the overlay and on its close button, and opens again after a SPA
95
+ navigation.
96
+
97
+ ## I. Footer
98
+
99
+ | # | Test | How to verify |
100
+ |---|---|---|
101
+ | I1 | Newsletter submits and shows success and error | a valid and an invalid email |
102
+ | I2 | Links, social icons and payment icons render | visual; links open the right targets |
103
+ | I3 | Back-to-top works | click |
104
+
105
+ ## J. Content editing (Studio)
106
+
107
+ | # | Test | How to verify |
108
+ |---|---|---|
109
+ | J1 | Each block type in use has a usable form | open one of each in Studio (**deco-cms-schema**) |
110
+ | J2 | A draft previews on the hosts editors use | `deco drafts url <name>` โ†’ the page shows the draft |
111
+ | J3 | A preview is never cached | the draft response has `Cache-Control: max-age=0, no-cache, must-revalidate` and `X-Robots-Tag: noindex, nofollow` |
112
+ | J4 | A publish reaches the live site within about a minute | publish a small change; reload |
113
+ | J5 | Each running test and campaign renders both sides | preview links with `__test` / `__campaign` (**deco-variants**) |
114
+
115
+ ## K. Analytics
116
+
117
+ | # | Test | How to verify |
118
+ |---|---|---|
119
+ | K1 | Tag manager loads from `<head>` without a gesture | network panel, no interaction |
120
+ | K2 | Page view fires on load **and** on SPA navigation | `dataLayer` after a click |
121
+ | K3 | `view_item`, `select_item`, `add_to_cart` fire with the old payload shape | compare with the old site |
122
+ | K4 | Every vendor in the inventory receives events | its own dashboard the next day |
123
+
124
+ ## L. Console and network health
125
+
126
+ | # | Test | What to look for |
127
+ |---|---|---|
128
+ | L1 | No hydration errors | React #418, #423, #425; "did not match" warnings |
129
+ | L2 | No hook-order errors | React #310 on product โ†’ product |
130
+ | L3 | No `Cannot read properties of undefined` | a loader result without a guard |
131
+ | L4 | No 404 on `/assets/*` after a deploy | keep a tab open across a deploy |
132
+ | L5 | No duplicate upstream calls per page | the server log or `http.client.request.duration` per provider (**deco-storefront-performance**) |
133
+
134
+ ## M. Performance and cache sanity
135
+
136
+ | # | Test | How to verify |
137
+ |---|---|---|
138
+ | M1 | Browser heap stays flat over 10 SPA navigations | DevTools Memory |
139
+ | M2 | Minicart open/close 10ร— leaves the heap flat | heap snapshots before and after |
140
+ | M3 | Anonymous pages send no `Set-Cookie` except the first-visit `deco_segment` | `curl -sI` without cookies |
141
+ | M4 | The second anonymous request is a cache hit | `X-Cache: HIT` from the site's page cache (**deco-storefront-caching**) |
142
+ | M5 | Lazy sections load their chunk only when needed | network panel while scrolling |
143
+
144
+ ## Adapting it
145
+
146
+ 1. Remove the sections the site doesn't have.
147
+ 2. Add a section per site-specific feature (configurators, calculators, store locators, wizards): open, use, result, error.
148
+ 3. Swap platform rows (cart, checkout, shipping) for the site's commerce platform.
149
+ 4. Add rows for bugs found in earlier rounds.
150
+ 5. For end-to-end purchase tests that run in CI, see the **ecommerce-qa** skill in decocms/storefront-skills (the `@decocms/qa` engine). Its stack detection was written for older sites; check it recognizes a v8 site before relying on it.
@@ -0,0 +1,120 @@
1
+ # QA inventory: what this site actually has
2
+
3
+ A QA checklist is only useful when it is scoped to the site: no rows for
4
+ features it doesn't have, and a row for every block, route and interaction it
5
+ does have. Build the inventory first, then fill
6
+ [qa-checklist-template.md](./qa-checklist-template.md) from it.
7
+
8
+ Run everything from the site root (the folder that holds `.deco/`). Pull
9
+ production content first so `.deco/blocks` matches what is live:
10
+
11
+ ```bash
12
+ deco pull # production into .deco/blocks (see deco-site-workflow)
13
+ ```
14
+
15
+ ## 1. Health: schema and content
16
+
17
+ ```bash
18
+ deco schema --check # .deco/schema.gen.json is up to date with the block types
19
+ deco check # production content against the schema: 0 errors
20
+ ```
21
+
22
+ Every error here is a page that renders wrong. Fix them before QA starts, or
23
+ list them as known issues.
24
+
25
+ ## 2. Block types (the block map)
26
+
27
+ `.deco/index.ts` (or `.tsx`) exports the block map, the types `deco schema` turns into
28
+ Studio forms. Each key is a block type editors can pick.
29
+
30
+ ```bash
31
+ sed -n '1,200p' .deco/index.ts* # read the map and where each entry comes from
32
+ ```
33
+
34
+ Then count which types the content really uses. Types in the map that no
35
+ saved block uses need no QA row; types used everywhere need one per place.
36
+
37
+ ```bash
38
+ jq -r '.. | objects | .["__resolveType"]? // empty' .deco/blocks/*.json | sort | uniq -c | sort -rn
39
+ ```
40
+
41
+ ## 3. Pages and routes
42
+
43
+ Each saved page block has a `path` (a literal, `:name` segments, or a
44
+ trailing `*`). The site's catch-all route matches a URL against them with
45
+ `matchRoute`; other routes are the framework's own (TanStack `src/routes/`,
46
+ Next.js `app/`).
47
+
48
+ ```bash
49
+ jq -r 'select(.path) | "\(.path)\t\(input_filename | split("/") | last)"' .deco/blocks/*.json | sort
50
+ ls src/routes 2>/dev/null; find app -name 'page.tsx' 2>/dev/null
51
+ ```
52
+
53
+ For each template, pick one real URL (a real product slug, a real category)
54
+ for the checklist. Add the page types every store has even if the template is
55
+ generic: home, listing, product, search, not found, institutional.
56
+
57
+ ## 4. Redirects, experiments, campaigns
58
+
59
+ ```bash
60
+ jq '.redirects | length' .deco/blocks/Redirects.json 2>/dev/null # rules to sweep
61
+ jq . .deco/blocks/experiments.json .deco/blocks/campaigns.json 2>/dev/null # the saved blocks every test and campaign rule reads
62
+ grep -rl '"multivariate"' .deco/blocks | head # pages with variants
63
+ ```
64
+
65
+ Each running test or campaign needs a row per side: force each with a Studio
66
+ preview link (`__test`, `__campaign` on a draft link). **deco-variants** has
67
+ the details.
68
+
69
+ ## 5. Interactive components
70
+
71
+ ```bash
72
+ # client state and effects
73
+ grep -rlE "useState|useEffect|useReducer|useSyncExternalStore" src --include='*.tsx'
74
+ # event handlers
75
+ grep -rlE "onClick|onChange|onSubmit|addEventListener" src --include='*.tsx'
76
+ # direct DOM access (fragile under React)
77
+ grep -rlE "document\.(getElementById|querySelector)" src --include='*.tsx' --include='*.ts'
78
+ # inline scripts (test by SPA click, not only F5)
79
+ grep -rlE "useScript\(|useScriptAsDataURI\(|inlineScript\(|<script" src
80
+ ```
81
+
82
+ Group the hits by UI: header (menu, search, minicart), sliders, product page
83
+ (gallery, variant picker, buy button, shipping estimate), cart, listing
84
+ (filters, sort, pagination), modals and drawers, footer (newsletter).
85
+
86
+ ## 6. Server functions and loaders
87
+
88
+ Server functions replace v7's `/deco/invoke`. Each one is a request the
89
+ browser makes and a thing that can be cancelled by navigation.
90
+
91
+ ```bash
92
+ grep -rn "createServerFn" src | cut -d: -f1 | sort | uniq -c # TanStack
93
+ grep -rln '"use server"' src app 2>/dev/null # Next.js
94
+ ```
95
+
96
+ Mark the ones that write (cart, newsletter, login): they need a "write then
97
+ navigate at once" row ([react-spa.md](./react-spa.md#server-functions-cancelled-on-navigation)).
98
+
99
+ ## 7. Integrations
100
+
101
+ ```bash
102
+ jq -r '.dependencies // {} | keys[]' package.json | grep -E "^@decocms/" # apps-vtex, apps-shopify, โ€ฆ
103
+ grep -rliE "dataLayer|sendEvent|DECO\.events" src | head # analytics
104
+ grep -rliE "<vendor names you know of: reviews, chat, search, consent>" src
105
+ ```
106
+
107
+ Each integration gets a row: it loads, it receives events, and it fails
108
+ without breaking the page.
109
+
110
+ ## 8. Old-site behaviors
111
+
112
+ If the site was ported, diff the inventory against the old repo too: a
113
+ feature that exists there and has no row here was either dropped (get
114
+ sign-off) or forgotten ([process.md](./process.md#inventory-of-what-was-not-ported)).
115
+
116
+ ## Output
117
+
118
+ Write the inventory down as a short table before the checklist: block type โ†’
119
+ pages that use it โ†’ component file. That table is what makes each checklist row
120
+ point at a real file and a real URL.
@@ -0,0 +1,183 @@
1
+ # React and SPA leftovers
2
+
3
+ A Fresh site rendered islands on full page loads and tolerated Preact habits.
4
+ A v8 TanStack site is React with client-side navigation: components are reused
5
+ across routes, inline scripts inserted on the client don't run, and React is
6
+ strict about controlled inputs and hydration. Most of these pass a reload test
7
+ and fail on a **SPA click**.
8
+
9
+ Always test by clicking links the app rendered. A `click()` on an `<a>` you
10
+ appended to `body` does a full reload. Confirm SPA navigation with
11
+ `performance.getEntriesByType("navigation").length === 1` after the click.
12
+
13
+ How to write sections and client components on v8 is in
14
+ **deco-site-authoring**; this file is only the go-live sweep.
15
+
16
+ ## Preact and Fresh leftovers
17
+
18
+ Found by a Playwright sweep, production against local, on one store:
19
+
20
+ | Symptom | Root cause | Fix |
21
+ |---|---|---|
22
+ | Typing in an input erases every letter | `value={โ€ฆ}` without `onChange` (Preact tolerated it; React makes it read-only) | `defaultValue` |
23
+ | Modal or zoom never opens on mobile | a controlled checkbox (`open={false}`) without `onChange` | uncontrolled, `defaultChecked` |
24
+ | "Add to cart" from a secondary component does nothing | `window.STOREFRONT.CART.addToCart` or `window.addToCart`: the Fresh global SDK doesn't exist | call the site's cart server function |
25
+ | A form does nothing | `hx-post` replaced by `preventDefault` and a TODO | wire it to a server function |
26
+ | A popup library never loads | `<script src>` inside a client-rendered section never runs | load it on demand |
27
+ | A label doesn't open its modal | raw HTML strings with `htmlFor` or `className` | `for` and `class` inside strings |
28
+ | An error on every keystroke | `onInput={useScript(...)}` passes a string as the handler | a function handler |
29
+ | The second lookup never renders | code removed React-owned DOM children by hand | reset state |
30
+ | Search steals focus every 300 ms | `setInterval(focus)` never cleared | bounded attempts, cancel on close and navigation |
31
+ | A double click adds two items | no in-flight guard | pending guards |
32
+ | A click before hydration is lost | | read `el.checked` on mount |
33
+
34
+ ```bash
35
+ grep -rnE "window\.STOREFRONT|window\.addToCart|hx-(post|get|on|trigger)" src
36
+ grep -rnE "on[A-Z][a-zA-Z]+=\{useScript" src
37
+ grep -rnE "open=\{false\}" src
38
+ grep -rnE "<script[^>]+src=" src
39
+ grep -rnE "\.removeChild\(|\.innerHTML\s*=|replaceChildren\(" src
40
+ ```
41
+
42
+ For `value=` without `onChange`, run dev with the console open on every form.
43
+ React warns: "You provided a `value` prop without an `onChange` handler".
44
+
45
+ ## Inline scripts do not run on SPA navigation
46
+
47
+ `useScript` and `useScriptAsDataURI` still exist in `@decocms/compat-v7`
48
+ (v7's output, byte for byte), and `inlineScript(js)` is the string form they
49
+ point to. React inserts a `<script>` on the client without running it. Only
50
+ scripts parsed from the server HTML run. Seen: a countdown frozen at
51
+ 00:00:00, a header under the timer, a sticky gallery that never shrinks. All
52
+ fine after F5.
53
+
54
+ Pattern: keep the inline script for the first paint, make it idempotent, and
55
+ also run it from `useLayoutEffect` with a cleanup.
56
+
57
+ ```tsx
58
+ const init = (id: string) => {
59
+ const el = document.getElementById(id) as (HTMLElement & { __started?: boolean; __stop?: () => void }) | null;
60
+ if (!el || el.__started) return; // idempotent
61
+ el.__started = true;
62
+ const stops: (() => void)[] = [];
63
+ el.__stop = () => stops.forEach((s) => s()); // remove listeners and observers
64
+ // ...
65
+ };
66
+ useLayoutEffect(() => { init(id); return () => document.getElementById(id)?.__stop?.(); }, []);
67
+ ```
68
+
69
+ `useScript(fn)` serializes `fn.toString()`, which can differ between the
70
+ server and the client build and break hydration. Its own docs mark it
71
+ deprecated in favor of `inlineScript` with a plain string.
72
+
73
+ ```bash
74
+ grep -rlnE "useScript\(|useScriptAsDataURI\(|inlineScript\(|<script" src
75
+ ```
76
+
77
+ ๐Ÿงช For each hit: reach the page by a SPA click and check it works. Go
78
+ listing โ†’ product โ†’ back three times; listener counts must stay flat.
79
+
80
+ ## Same-route navigation reuses components
81
+
82
+ Product โ†’ product is the same route (the catch-all), so the page component is
83
+ reused.
84
+
85
+ 1. `<img>` nodes reused with a new `src` show the previous product's photos for about 1.2 s. Fix: a `key` per product group on the gallery.
86
+ 2. `if (!items.length) return null` **before** a hook: an instance moving from a product without that block to one with it calls more hooks โ†’ React error #310, and the page renders only header and footer. One store had 13 more components with the same pattern.
87
+
88
+ ```tsx
89
+ <Gallery key={product.inProductGroupWithID ?? product.productID} โ€ฆ />
90
+ ```
91
+
92
+ ```bash
93
+ grep -rn "rules-of-hooks" eslint.config.* .eslintrc* biome.json 2>/dev/null || echo "rules-of-hooks not enabled"
94
+ ```
95
+
96
+ Test any home-made scan against a known bug first. One awk scan "passed" with
97
+ zero hits because macOS awk did not support the regex.
98
+
99
+ ๐Ÿงช SPA-click product โ†’ product between products **with and without**
100
+ optional blocks (video, size guide); the first gallery `<img>` must change.
101
+
102
+ ## Hydration error #418
103
+
104
+ **What happened** (~2,750 users a day, 90% on mobile listings): tag-manager
105
+ scripts appended to `body` during parse landed between `</main>` and React's
106
+ own tail scripts. React claimed them during hydration โ†’ #418, and the whole
107
+ page re-rendered on the client.
108
+
109
+ - Keep every node after `<main>` one React rendered. `DecoDocument` renders its `children` after the page; put the site's own trailing UI there, not in raw HTML.
110
+ - CMS or platform HTML with unbalanced tags in `dangerouslySetInnerHTML` โ†’ balance it before rendering; truncate HTML at word boundaries, not as plain text.
111
+ - Block HTML inside `<p>` breaks the parse โ†’ use `<div>`.
112
+ - `location.origin` read during SSR โ†’ pass the origin in.
113
+
114
+ ```bash
115
+ grep -rn "dangerouslySetInnerHTML" src
116
+ ```
117
+
118
+ ๐Ÿงช Mobile emulation, 6ร— CPU, tag manager on, scroll during load, about 20
119
+ listing loads: zero #418. After hydration, any third-party `<script>` in
120
+ `document.body.children` with a `__reactFiber$*` key is a bug.
121
+
122
+ ## Server functions cancelled on navigation
123
+
124
+ **What happened:** a TanStack server function is cancelled when the user
125
+ navigates away mid-request. Cancelled at 50โ€“250 ms, it never reached the
126
+ platform. "+" then "checkout" lost the item. Also, on Fresh the add-to-cart
127
+ call was not awaited, so the "added" sheet opened at once; awaited, it opened
128
+ 0.7 s late.
129
+
130
+ - Open the UI optimistically before the `await`; close it on failure.
131
+ - Track pending cart writes; full-page links (especially checkout) wait for them.
132
+ - `fetch(..., { keepalive: true })` on `pagehide` for writes.
133
+
134
+ ๐Ÿงช WebKit: change the quantity and click "checkout" within 300 ms. The
135
+ checkout shows the new quantity.
136
+
137
+ ## Stale chunks after deploy
138
+
139
+ Every deploy removes old hashed chunks. Open tabs then get 404s on
140
+ `/assets/*.js` (103 to 254 per deploy on one store). The router reloads only
141
+ on route-chunk failures; a lazy section's chunk fails into the error boundary
142
+ (a product page without photos, price or buy button). The v8 packages add no
143
+ handler for this.
144
+
145
+ - Listen to Vite's `vite:preloadError` and reload once per chunk, guarded in `sessionStorage` with a cooldown of about 30 s.
146
+ - Add a small inline guard in `<head>` for when the main entry itself 404s.
147
+
148
+ ๐Ÿงช Open a tab, deploy, then SPA-navigate in that tab to a page with lazy
149
+ sections.
150
+
151
+ ## Preload on intent
152
+
153
+ `createDecoRouter` defaults to `defaultPreload: "intent"`: hovering a link
154
+ loads that page's data. On v7, intent preload cost one store 197 GB of egress
155
+ in 2.5 days (each hover fetched a 1.6 MB product payload). Measure the
156
+ payload of a page load before go-live. If it is large, trim it
157
+ (**deco-storefront-performance**) or pass `defaultPreload: false`.
158
+
159
+ ## Browser memory leaks
160
+
161
+ **What happened (minicart):** 1โ€“2 GB per open; the browser died at 3โ€“4 GB.
162
+
163
+ - Signal shims (`useSignalEffect`, `useComputed` without deps) โ†’ render loops.
164
+ - A store hook expecting `{ unsubscribe }` while the source returns a function โ†’ subscriptions pile up. Use `useSyncExternalStore` with a stable `subscribe`.
165
+ - Every cart item re-rendered on open and close โ†’ make open/close CSS-only and memoize the list.
166
+ - `removeEventListener` with a new arrow function does nothing โ†’ keep the reference.
167
+
168
+ ๐Ÿงช DevTools Memory: open and close the minicart 10 times with the tag manager
169
+ on; a heap snapshot before and after must be flat.
170
+
171
+ ## Legacy service worker
172
+
173
+ An old site's service worker kept intercepting requests on one store.
174
+ Removing `register()` does not uninstall it for past visitors. Ship a `sw.js`
175
+ at the same path that unregisters itself.
176
+
177
+ ```js
178
+ self.addEventListener("install", () => self.skipWaiting());
179
+ self.addEventListener("activate", async () => {
180
+ await self.registration.unregister();
181
+ (await self.clients.matchAll()).forEach((c) => c.navigate(c.url));
182
+ });
183
+ ```