@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
@@ -1,214 +1,207 @@
1
1
  /**
2
- * `remoteLoader`: hosted releases from `delivery.decocms.com`, over a fallback
3
- * (the content module, or any loader). See /next/hosted-releases-internals.
4
- * Drafts aren't a loader's job: the CMS layers a draft's changes over what
5
- * `load()` returns (see ./draftChanges.ts).
2
+ * `remoteLoader`: hosted releases from `delivery.decocms.com`, read at
3
+ * runtime only (see /next/hosted-releases-internals). Content is never
4
+ * bundled: with `site`, the release comes from the CDN or not at all. Sites
5
+ * talk only to the CDN, with plain HTTP (ETag, `If-None-Match`, 304).
6
6
  *
7
- * - `load()` never touches the network: it returns the release this process
8
- * last swapped in, or the fallback's content until then. Nothing persists
9
- * across restarts: every boot starts from the fallback.
10
- * - `update()` (the CMS calls it in the background, on first use and then
11
- * every interval, and once per draft request, which waits for it, so a
12
- * draft always shows over the latest release: `cms.checkRelease()`) reads
13
- * `sites/<site>/latest.json`,
14
- * `{ revision, schemaHash, publishedAt, previewHosts }`. Whoever is newer wins: when it
15
- * names a revision other than the one this process last swapped in, its
16
- * `schemaHash` equals the fallback's, and its `publishedAt` is later than
17
- * the fallback's `committedAt` (the commit time of the git HEAD
18
- * `deco content` built it from), it downloads
19
- * `sites/<site>/revisions/<revision>.json`,
20
- * `{ revision, schemaHash, blocks, previewHosts }`, and swaps it in whole. Otherwise, and on any error, memory stays as it is.
21
- * A fallback without a `schemaHash` never swaps; one without a `committedAt`
22
- * (a custom loader, an older content module, a build outside git) counts as
23
- * the oldest. Studio writes `publishedAt` on Publish, on "Make current" (a
24
- * rollback) and on Resync, so a rollback wins over the bundles of earlier
25
- * commits and a deploy of a later commit wins over the rollback. Commit
26
- * time, not build time: a slow build of an older commit that finishes after
27
- * a publish still loses to it.
28
- * Pointers aren't ordered among themselves, and the fallback's content is
29
- * never compared: only the two timestamps are.
30
- * - `previewHosts` (host patterns) is where the site may be previewed: Studio
31
- * knows the site's addresses and writes them into the release metadata
32
- * whenever it writes `latest.json` or a revision (delivery is trusted).
33
- * Previews are checked against the current release's list: the last
34
- * `latest.json` read, whether or not its revision was swapped in (a newer
35
- * bundle still previews where Studio says). With no list to check
36
- * (PO 2026-10-22), previews are allowed on every host: a site with no
37
- * `latest.json` yet (a 404), or one whose `latest.json` has no
38
- * `previewHosts` (published before Studio wrote the list; its next publish
39
- * writes one). A read that fails (a network error, a 5xx, a malformed
40
- * `latest.json`) isn't "no list": until a read succeeds, previews stay
41
- * closed, and a later failure keeps the last answer (a 404 once a list
42
- * was read is a failure too: a published site stays published).
43
- * A preview request before this process has read `latest.json` reads it
44
- * then (only `latest.json`, once, shared); a read older than the interval
45
- * is read again the same way, so `dev: true` follows Studio too.
46
- * - With `dev: true`, it never swaps, so local files win. `createCMS` passes
47
- * its `dev` option, or `NODE_ENV === "development"` when the site omits it;
48
- * this loader reads no environment itself.
49
- * - A release larger than `MAX_SNAPSHOT_BYTES` is refused while it downloads,
50
- * before it's buffered whole (a Worker isolate has 128 MB).
51
- * - A client can ask for a published release by its commit SHA
52
- * (`cms.client({ version })`): it's read from
53
- * `sites/<site>/revisions/<sha>.json` on first use and kept in memory, a
54
- * few at a time (the least recently used dropped first), since a revision
55
- * never changes. One built with another schema than the bundled content is
56
- * an error, never half a page.
57
- * - Without `site` it's a plain loader over the fallback.
7
+ * - **The index.** `sites/<site>/latest.json` is the current revision's
8
+ * index (`{ revision, sequence, previewHosts, blocks: { <name>: { version,
9
+ * meta?, data? } } }`). The first use loads it (calls made meanwhile share
10
+ * the load; a failed load isn't kept and rejects with a
11
+ * `ContentUnavailableError`, a 404 included: never an empty site). A poll
12
+ * (the CMS starts one in the background every interval, and a draft
13
+ * request's release check is one) sends `If-None-Match` on the held ETag, so
14
+ * an unchanged index is a 304: nothing is downloaded or parsed. A read is
15
+ * adopted only when its `sequence` is higher than the held one, so a
16
+ * slightly stale CDN answer never moves the isolate backwards; the index
17
+ * that was current is kept as the previous one (one only). A failed poll
18
+ * keeps the held index.
19
+ * - **Blocks.** `sites/<site>/blocks/<hash>.json`, immutable, fetched with
20
+ * plain `fetch()` (it reads through the CDN cache) when a request needs one,
21
+ * into an LRU per isolate keyed by hash and bounded by bytes (32 MiB of
22
+ * JSON text). Concurrent requests share one fetch per hash; a failed fetch
23
+ * (a 404 included) isn't kept.
24
+ * - **Revisions by id** (`cms.client({ version: <id> })`): the
25
+ * `revisions/<id>/index.json` of that revision, read on first use and kept,
26
+ * three at a time, since a revision never changes. Bodies by hash as usual.
27
+ * - Each fetch has 10 s (headers and body), sends no credential, and refuses
28
+ * a body over 16 MiB while it downloads. Unknown keys are ignored.
29
+ * - `previewHosts`: as before, from the last `latest.json` read whose index
30
+ * was adopted (a 304, or a stale answer with a lower or equal `sequence`,
31
+ * keeps the list it had). A site with no `latest.json` yet (a 404), or one without
32
+ * `previewHosts`, previews on every host; until a read succeeds, previews
33
+ * stay closed, and a later failure keeps the last answer.
34
+ * - Without `site` it's a plain loader over the content it's given.
58
35
  *
59
36
  * Instances are process-wide singletons, like `createCMS`'s.
60
37
  */
61
- import { readBoundedJson, timeoutSignal } from "./boundedJson.ts";
38
+
39
+ import { keepAlive } from "./background.ts";
40
+ import type { BlockIndex, BlockMeta, IndexEntry } from "./blockMeta.ts";
41
+ import { BlockStore, type FetchedBody } from "./blockStore.ts";
42
+ import { readBoundedJson, readBoundedJsonSized, timeoutSignal } from "./boundedJson.ts";
43
+ import { BoundedMap } from "./boundedMap.ts";
44
+ import { PEEK_RELEASE, peekRelease } from "./content.ts";
45
+ import type { IndexedContent } from "./contentIndex.ts";
46
+ import { ContentUnavailableError, errors } from "./errors.ts";
62
47
  import {
63
- BoundedMap,
64
- isSnapshot,
65
- PEEK_RELEASE,
66
- PREVIEW_HOSTS,
67
- peekRelease,
48
+ HOSTED,
49
+ type HostedSource,
68
50
  previewHostsOf,
69
- READ_REVISION,
70
51
  type ReleasePreviewHosts,
71
- } from "./content.ts";
72
- import { errors } from "./errors.ts";
52
+ } from "./hostedSource.ts";
73
53
  import { clearGlobals, contentIdentity } from "./identity.ts";
74
54
  import { isPlainObject } from "./json.ts";
55
+ import { isRevisionId } from "./revisionId.ts";
75
56
  import type { Loader, Snapshot } from "./types.ts";
76
57
 
77
- /** The hosted delivery origin: release pointers and revisions. */
58
+ /** The hosted delivery origin. */
78
59
  const HOSTED_DELIVERY_ORIGIN = "https://delivery.decocms.com";
79
- /** test-only: replaces the delivery origin in local end-to-end runs. Not documented, not exported. */
60
+ /**
61
+ * test-only: replaces the delivery origin (it may carry a path prefix) in
62
+ * local end-to-end runs. Not documented, not exported.
63
+ */
80
64
  const TEST_DELIVERY_ORIGIN = Symbol.for("decocms.blocks.test.deliveryOrigin");
81
65
 
82
66
  const INSTANCE_PREFIX = "decocms.blocks.remote:";
83
67
  const FETCH_TIMEOUT_MS = 10_000;
84
- /** The largest release accepted, in bytes of JSON. */
85
- const MAX_SNAPSHOT_BYTES = 64 * 1024 * 1024;
86
- /** Published releases kept in memory once read (a client asked for one by its SHA). */
68
+ /** The largest index (`latest.json`, a revision's `index.json`) accepted, in bytes of JSON. */
69
+ const MAX_INDEX_BYTES = 16 * 1024 * 1024;
70
+ /** The largest block body accepted, in bytes of JSON. */
71
+ const MAX_BLOCK_BYTES = 16 * 1024 * 1024;
72
+ /** Revision indexes kept in memory once read (a client asked for one by its id). */
87
73
  const CACHED_REVISIONS = 3;
88
- // OPEN: a revision is the git commit SHA; only SHA-1 (40 hex) object names are accepted.
89
- const REVISION = /^[0-9a-f]{40}$/;
90
- const SCHEMA_HASH = /^[0-9a-f]{64}$/;
91
74
  /** How long a failed read of the preview hosts waits before a preview request tries again. */
92
75
  const PREVIEW_HOSTS_RETRY_MS = 10_000;
93
76
  /** How old the preview hosts may get before a preview request reads them again (without `interval`). */
94
77
  const PREVIEW_HOSTS_MAX_AGE_MS = 60_000;
78
+ /** A block hash: `blockVersion`, base64url of 16 bytes. */
79
+ const HASH_RE = /^[A-Za-z0-9_-]{22}$/;
80
+ /** The one entry whose body an index carries inline. */
81
+ const INLINE_BLOCK = "CMS";
95
82
 
96
83
  interface RemoteLoaderOptions {
97
84
  site?: string;
98
85
  /** ms between release checks, used when `createCMS` has no `interval` of its own. */
99
86
  interval?: number;
100
- /** Local development: never swap in a release, so local files win. */
101
- dev?: boolean;
102
- }
103
-
104
- /** `sites/<site>/latest.json`: the release a site serves. */
105
- interface Latest {
106
- revision: string;
107
- schemaHash: string;
108
- publishedAt: string;
109
- /** Where the site may be previewed; `undefined` when Studio wrote none. */
110
- previewHosts: string[] | undefined;
111
87
  }
112
88
 
113
- /** A revision file's body. */
114
- interface Revision {
115
- blocks: Record<string, unknown>;
116
- schemaHash: string;
89
+ /** A parsed `latest.json` and its ETag. */
90
+ interface LatestRead {
91
+ content: IndexedContent;
92
+ etag: string | null;
117
93
  previewHosts: string[] | undefined;
118
94
  }
119
95
 
120
- class RemoteLoader implements Loader {
96
+ class RemoteLoader implements Loader, HostedSource {
97
+ readonly [HOSTED] = true as const;
121
98
  readonly #site: string;
122
- /** The `interval` this loader was created with; `createCMS` reads it. */
123
99
  readonly interval: number | undefined;
124
- #fallback: Snapshot | Loader;
125
- /** The fallback's content as last loaded, for a fallback that is itself a loader. */
126
- #fallbackSnapshot: Snapshot | undefined;
127
- /** The release this process last swapped in; `undefined` serves the fallback. */
128
- #current: Snapshot | undefined;
129
- readonly #dev: boolean;
130
- /** Published releases read by SHA; immutable, so a hit is never revalidated. */
131
- readonly #revisions = new BoundedMap<string, Promise<Snapshot>>(CACHED_REVISIONS);
100
+ readonly blocks: BlockStore;
101
+ /** The index this process holds; `undefined` until the first load succeeds. */
102
+ #current: { content: IndexedContent; etag: string | null } | undefined;
103
+ #previous: IndexedContent | undefined;
104
+ /** A read of `latest.json` in flight: the first load, a poll or a preview-hosts read. */
105
+ #reading: Promise<boolean> | undefined;
106
+ readonly #revisions = new BoundedMap<string, Promise<IndexedContent>>(CACHED_REVISIONS);
132
107
  /**
133
- * The preview hosts the last read of `latest.json` found (its list, or
134
- * `"every"`: a 404, or no `previewHosts` in it), and when. A failed read
135
- * leaves it as it was.
108
+ * The preview hosts of the held release, from the last read of
109
+ * `latest.json` that was adopted (its list, or `"every"`: a 404, or no
110
+ * `previewHosts` in it), and when it was last confirmed. A failed read, or
111
+ * a stale one, leaves the list as it was.
136
112
  */
137
113
  #hosts: { list: readonly string[] | "every"; at: number } | undefined;
138
- /** A read of `latest.json` for its preview hosts, in flight. */
139
114
  #hostsRead: Promise<void> | undefined;
140
- /** When that read last failed. */
141
115
  #hostsFailedAt = Number.NEGATIVE_INFINITY;
142
116
 
143
- constructor(
144
- fallback: Snapshot | Loader,
145
- options: { site: string; interval?: number; dev?: boolean },
146
- ) {
147
- this.#fallback = fallback;
117
+ constructor(options: { site: string; interval?: number }) {
148
118
  this.#site = options.site;
149
119
  this.interval = options.interval;
150
- this.#dev = options.dev === true;
120
+ this.blocks = new BlockStore((hash, name) => this.#fetchBlock(hash, name));
151
121
  }
152
122
 
153
- /** A hot reload hands the same instance new fallback content. */
154
- adopt(fallback: Snapshot | Loader): void {
155
- if (fallback === this.#fallback) return;
156
- this.#fallback = fallback;
157
- this.#fallbackSnapshot = undefined;
123
+ /** Hosted content is read lazily, by index and hash; there is no whole snapshot to load. */
124
+ load(): Promise<Snapshot> {
125
+ return Promise.reject(
126
+ errors.loaderFailed(
127
+ "hosted releases are read through createCMS (an index plus blocks by hash), not as one snapshot",
128
+ ),
129
+ );
158
130
  }
159
131
 
160
- /** What `load()` would return now, from memory only (see `peekRelease`). */
161
- [PEEK_RELEASE](): Snapshot | undefined {
162
- return this.#current ?? peekRelease(this.#fallback) ?? this.#fallbackSnapshot;
132
+ peek(): IndexedContent | undefined {
133
+ return this.#current?.content;
163
134
  }
164
135
 
165
- load(): Promise<Snapshot> {
166
- if (this.#current !== undefined) return Promise.resolve(this.#current);
167
- return this.#loadFallback();
136
+ previous(): IndexedContent | undefined {
137
+ return this.#previous;
168
138
  }
169
139
 
170
- async update(): Promise<{ updated: boolean }> {
171
- if (this.#dev) return { updated: false };
172
- const fallback = this.#fallbackSnapshot ?? (await this.#loadFallback());
173
- if (fallback.schemaHash === undefined) return { updated: false };
174
- const site = encodeURIComponent(this.#site);
175
- const latest = await this.#latest(site);
176
- // Another schema: keep what this process serves (the fallback, or the last swap).
177
- if (latest.schemaHash !== fallback.schemaHash) return { updated: false };
178
- // The bundle is newer: keep what this process serves.
179
- // OPEN: a process that already swapped a release in keeps it (memory stays as it is).
180
- if (!isNewer(latest.publishedAt, fallback.committedAt)) return { updated: false };
181
- if (latest.revision === this.#current?.revision) return { updated: false };
182
- const revision = await this.#revision(site, latest);
183
- const next: Snapshot = {
184
- revision: latest.revision,
185
- blocks: revision.blocks,
186
- schemaHash: latest.schemaHash,
187
- };
188
- if (revision.previewHosts !== undefined) next.previewHosts = revision.previewHosts;
189
- if (fallback.aliases !== undefined) next.aliases = fallback.aliases;
190
- this.#current = next;
191
- return { updated: true };
140
+ async current(): Promise<IndexedContent> {
141
+ const held = this.#current;
142
+ if (held !== undefined) return held.content;
143
+ await this.#read();
144
+ const loaded = this.#current as { content: IndexedContent } | undefined;
145
+ if (loaded === undefined) {
146
+ throw new ContentUnavailableError("format", "latest.json: no index was read");
147
+ }
148
+ return loaded.content;
149
+ }
150
+
151
+ async poll(): Promise<{ updated: boolean }> {
152
+ if (this.#current === undefined) {
153
+ await this.current();
154
+ return { updated: false };
155
+ }
156
+ return { updated: await this.#read() };
157
+ }
158
+
159
+ async revision(id: string): Promise<IndexedContent> {
160
+ if (!isRevisionId(id)) throw errors.loaderFailed(`"${id}" is not a release's revision id`);
161
+ for (const content of [this.#current?.content, this.#previous]) {
162
+ if (content?.revision === id) return content;
163
+ }
164
+ const held = this.#revisions.get(id);
165
+ if (held !== undefined) return held;
166
+ const label = `revision ${id}`;
167
+ const pending = request(
168
+ `${deliveryOrigin()}/sites/${this.#sitePath()}/revisions/${id}/index.json`,
169
+ label,
170
+ ).then(async (response) => {
171
+ const body = await readBody(response, label, MAX_INDEX_BYTES);
172
+ const content = this.#parseIndex(body, label);
173
+ if (content.revision !== id) {
174
+ throw new ContentUnavailableError("format", `${label}: names another revision`);
175
+ }
176
+ return content;
177
+ });
178
+ this.#revisions.set(id, pending);
179
+ // Shared with later clients: kept alive past the request that started it.
180
+ keepAlive(pending);
181
+ // A failed read isn't kept, so the next client tries again.
182
+ pending.catch(() => {
183
+ if (this.#revisions.get(id) === pending) this.#revisions.delete(id);
184
+ });
185
+ return pending;
192
186
  }
193
187
 
194
188
  /**
195
- * The current release's preview hosts (see `PREVIEW_HOSTS`): the last
196
- * successful read of `latest.json`, reading it first when there is none yet
197
- * or it is older than the interval (`peek`: never). `"every"` when
198
- * the site has no `latest.json` (a 404) or it names no `previewHosts`;
199
- * `"unknown"` while no read has succeeded (a failed one is retried after a
200
- * pause), so previews stay closed rather than open on an error.
189
+ * The current release's preview hosts: the last successful read of
190
+ * `latest.json`, reading it first when there is none yet or it is older than
191
+ * the interval (`peek`: never). `"every"` when the site has no `latest.json`
192
+ * (a 404) or it names no `previewHosts`; `"unknown"` while no read has
193
+ * succeeded (a failed one is retried after a pause).
201
194
  */
202
- async [PREVIEW_HOSTS](peek = false): Promise<ReleasePreviewHosts> {
195
+ async previewHosts(peek = false): Promise<ReleasePreviewHosts> {
203
196
  const known = this.#hosts;
204
197
  const maxAge = this.interval ?? PREVIEW_HOSTS_MAX_AGE_MS;
205
198
  const stale = known === undefined || Date.now() - known.at >= maxAge;
206
199
  if (!peek && stale && Date.now() - this.#hostsFailedAt >= PREVIEW_HOSTS_RETRY_MS) {
207
- this.#hostsRead ??= this.#latest(encodeURIComponent(this.#site))
200
+ this.#hostsRead ??= this.#read()
208
201
  .then(
209
202
  () => undefined,
210
203
  () => {
211
- // A 404 is an answer (`#latest` recorded it), not a failure.
204
+ // A 404 is an answer (`#readLatest` recorded it), not a failure.
212
205
  if (this.#hosts === known) this.#hostsFailedAt = Date.now();
213
206
  },
214
207
  )
@@ -222,173 +215,197 @@ class RemoteLoader implements Loader {
222
215
  return list === "every" ? list : list.slice();
223
216
  }
224
217
 
225
- /** A published release by its commit SHA (see `READ_REVISION`). */
226
- async [READ_REVISION](sha: string): Promise<Snapshot> {
227
- if (!REVISION.test(sha)) throw errors.loaderFailed(`"${sha}" is not a release's commit SHA`);
228
- if (this.#current?.revision === sha) return this.#current;
229
- const fallback = this.#fallbackSnapshot ?? (await this.#loadFallback());
230
- if (fallback.revision === sha) return fallback;
231
- if (fallback.schemaHash === undefined) {
232
- throw errors.loaderFailed(
233
- `the release ${sha} can't be checked against this code: the bundled content has no schemaHash (run deco content)`,
234
- );
235
- }
236
- const snapshot = await this.#readRevision(sha);
237
- if (snapshot.schemaHash !== fallback.schemaHash) {
238
- throw errors.loaderFailed(
239
- `the release ${sha} was published with another schema than this code's ` +
240
- `(${snapshot.schemaHash} ≠ ${fallback.schemaHash}): preview it on a deploy of its own code`,
241
- );
218
+ /** One read of `latest.json` at a time (shared); resolves with whether it adopted a new index. */
219
+ #read(): Promise<boolean> {
220
+ if (this.#reading === undefined) {
221
+ const pending = this.#readAndAdopt();
222
+ this.#reading = pending;
223
+ const settle = () => {
224
+ if (this.#reading === pending) this.#reading = undefined;
225
+ };
226
+ pending.then(settle, settle);
227
+ // Shared with later requests: kept alive past the request that started it.
228
+ keepAlive(pending);
242
229
  }
243
- if (fallback.aliases === undefined) return snapshot;
244
- return { ...snapshot, aliases: fallback.aliases };
230
+ return this.#reading;
245
231
  }
246
232
 
247
- /** Reads a revision once; a failed read isn't kept, so the next client tries again. */
248
- #readRevision(sha: string): Promise<Snapshot> {
249
- const held = this.#revisions.get(sha);
250
- if (held !== undefined) return held;
251
- const site = encodeURIComponent(this.#site);
252
- const pending = this.#fetchRevision(site, sha, "the revision asked for").then((body) => {
253
- const snapshot: Snapshot = {
254
- revision: sha,
255
- blocks: body.blocks,
256
- schemaHash: body.schemaHash,
257
- };
258
- if (body.previewHosts !== undefined) snapshot.previewHosts = body.previewHosts;
259
- return snapshot;
260
- });
261
- this.#revisions.set(sha, pending);
262
- pending.catch(() => {
263
- if (this.#revisions.get(sha) === pending) this.#revisions.delete(sha);
264
- });
265
- return pending;
233
+ async #readAndAdopt(): Promise<boolean> {
234
+ const held = this.#current;
235
+ const read = await this.#readLatest(held?.etag ?? null);
236
+ if (read === null) return false;
237
+ const current = this.#current;
238
+ const at = Date.now();
239
+ // The newest index wins, by sequence: a stale CDN answer never moves the
240
+ // isolate back, its preview hosts included (the held list counts as read now).
241
+ if (current !== undefined && read.content.sequence <= current.content.sequence) {
242
+ this.#hosts =
243
+ this.#hosts === undefined
244
+ ? { list: read.previewHosts ?? "every", at }
245
+ : { list: this.#hosts.list, at };
246
+ return false;
247
+ }
248
+ // The adopted release's metadata. No `previewHosts` (none written): every host, as with no latest.json.
249
+ this.#hosts = { list: read.previewHosts ?? "every", at };
250
+ if (current !== undefined) this.#previous = current.content;
251
+ this.#current = { content: read.content, etag: read.etag };
252
+ return current !== undefined;
266
253
  }
267
254
 
268
- async #fetchRevision(site: string, sha: string, expected: string): Promise<Revision> {
269
- const label = `revision ${sha}`;
270
- const response = await fetchWithTimeout(
271
- `${deliveryOrigin()}/sites/${site}/revisions/${sha}.json`,
255
+ /** `latest.json`, revalidating `etag`: `null` for a 304. */
256
+ async #readLatest(etag: string | null): Promise<LatestRead | null> {
257
+ const label = "latest.json";
258
+ const response = await request(
259
+ `${deliveryOrigin()}/sites/${this.#sitePath()}/latest.json`,
260
+ label,
261
+ etag,
262
+ (status) => {
263
+ // Not published yet: no list, so previews are allowed on every host (PO 2026-10-22).
264
+ // A site this process has read a list for can't be unpublished: a 404 then
265
+ // (a CDN fault, a publish caught mid-write) is a failed read, so it keeps the list.
266
+ if (status === 404 && !Array.isArray(this.#hosts?.list)) {
267
+ this.#hosts = { list: "every", at: Date.now() };
268
+ }
269
+ },
272
270
  );
273
- if (!response.ok) {
274
- await response.body?.cancel();
275
- throw new Error(`${label}: HTTP ${response.status}`);
276
- }
277
- const body = await readBoundedJson(response, label, MAX_SNAPSHOT_BYTES);
278
- if (
279
- !isPlainObject(body) ||
280
- body.revision !== sha ||
281
- typeof body.schemaHash !== "string" ||
282
- !isPlainObject(body.blocks)
283
- ) {
284
- throw new Error(`${label}: unexpected format, or not ${expected}`);
271
+ if (response.status === 304) {
272
+ if (this.#hosts !== undefined) this.#hosts = { list: this.#hosts.list, at: Date.now() };
273
+ return null;
285
274
  }
286
- return {
287
- blocks: body.blocks,
288
- schemaHash: body.schemaHash,
289
- previewHosts: previewHostsOf(body.previewHosts),
290
- };
275
+ const body = await readBody(response, label, MAX_INDEX_BYTES);
276
+ const content = this.#parseIndex(body, label);
277
+ const previewHosts = previewHostsOf((body as Record<string, unknown>).previewHosts);
278
+ // Its preview hosts are taken only with its index (`#readAndAdopt`).
279
+ return { content, etag: response.headers.get("etag"), previewHosts };
291
280
  }
292
281
 
293
- async #loadFallback(): Promise<Snapshot> {
294
- const fallback = this.#fallback;
295
- const snapshot = isSnapshot(fallback) ? fallback : await (fallback as Loader).load();
296
- if (fallback === this.#fallback) this.#fallbackSnapshot = snapshot;
297
- return snapshot;
298
- }
299
-
300
- async #latest(site: string): Promise<Latest> {
301
- const response = await fetchWithTimeout(`${deliveryOrigin()}/sites/${site}/latest.json`);
302
- if (!response.ok) {
303
- await response.body?.cancel();
304
- // Not published yet: no list, so previews are allowed on every host (PO 2026-10-22).
305
- // A site this process has read a list for can't be unpublished: a 404 then
306
- // (a CDN fault, a publish caught mid-write) is a failed read, so it keeps the list.
307
- if (response.status === 404 && !Array.isArray(this.#hosts?.list)) {
308
- this.#hosts = { list: "every", at: Date.now() };
309
- }
310
- throw new Error(`latest.json: HTTP ${response.status}`);
282
+ /** An index body (`latest.json` or a revision's `index.json`), checked. */
283
+ #parseIndex(body: unknown, label: string): IndexedContent {
284
+ const format = (why: string) => new ContentUnavailableError("format", `${label}: ${why}`);
285
+ if (!isPlainObject(body) || !isRevisionId(body.revision)) throw format("unexpected format");
286
+ const sequence = body.sequence;
287
+ if (typeof sequence !== "number" || !Number.isSafeInteger(sequence) || sequence < 1) {
288
+ throw format("sequence must be a positive integer");
311
289
  }
312
- const body: unknown = await response.json();
313
- if (
314
- !isPlainObject(body) ||
315
- typeof body.revision !== "string" ||
316
- !REVISION.test(body.revision) ||
317
- typeof body.schemaHash !== "string" ||
318
- !SCHEMA_HASH.test(body.schemaHash) ||
319
- typeof body.publishedAt !== "string" ||
320
- Number.isNaN(Date.parse(body.publishedAt))
321
- ) {
322
- throw new Error("latest.json: unexpected format");
290
+ if (!isPlainObject(body.blocks)) throw format("blocks must be an object");
291
+ const blocks = Object.create(null) as BlockIndex;
292
+ for (const [name, raw] of Object.entries(body.blocks)) {
293
+ if (!isPlainObject(raw) || typeof raw.version !== "string" || !HASH_RE.test(raw.version)) {
294
+ throw format(`the entry "${name}" has no version`);
295
+ }
296
+ const entry: IndexEntry = { version: raw.version };
297
+ const meta = metaOf(raw.meta);
298
+ if (meta !== undefined) entry.meta = meta;
299
+ if (name === INLINE_BLOCK && raw.data !== undefined) entry.data = raw.data;
300
+ blocks[name] = entry;
323
301
  }
324
- const previewHosts = previewHostsOf(body.previewHosts);
325
- // The current release's metadata, whether or not its revision is swapped in.
326
- // No `previewHosts` (published before Studio wrote the list): every host, as with no latest.json.
327
- this.#hosts = { list: previewHosts ?? "every", at: Date.now() };
328
- return {
329
- revision: body.revision,
330
- schemaHash: body.schemaHash,
331
- publishedAt: body.publishedAt,
332
- previewHosts,
333
- };
302
+ return { revision: body.revision, sequence, blocks, source: this.blocks };
334
303
  }
335
304
 
336
- async #revision(site: string, latest: Latest): Promise<Revision> {
337
- const body = await this.#fetchRevision(site, latest.revision, "the revision latest.json names");
338
- if (body.schemaHash !== latest.schemaHash) {
339
- throw new Error(`revision ${latest.revision}: not the schema latest.json names`);
305
+ /** `blocks/<hash>.json`. */
306
+ async #fetchBlock(hash: string, name: string): Promise<FetchedBody> {
307
+ const label = `block "${name}" (${hash})`;
308
+ if (!HASH_RE.test(hash)) throw new ContentUnavailableError("format", `${label}: not a hash`);
309
+ const response = await request(
310
+ `${deliveryOrigin()}/sites/${this.#sitePath()}/blocks/${hash}.json`,
311
+ label,
312
+ );
313
+ try {
314
+ const { value, bytes } = await readBoundedJsonSized(response, label, MAX_BLOCK_BYTES);
315
+ return { body: value, bytes };
316
+ } catch (error) {
317
+ throw unavailable(label, error, "format");
340
318
  }
341
- return body;
342
319
  }
320
+
321
+ #sitePath(): string {
322
+ return encodeURIComponent(this.#site);
323
+ }
324
+ }
325
+
326
+ /** An entry's `meta`, kept to its known keys and shapes; `undefined` when none. */
327
+ function metaOf(raw: unknown): BlockMeta | undefined {
328
+ if (!isPlainObject(raw)) return undefined;
329
+ const meta: BlockMeta = {};
330
+ if (typeof raw.type === "string") meta.type = raw.type;
331
+ if (typeof raw.path === "string") meta.path = raw.path;
332
+ if (Array.isArray(raw.refs)) {
333
+ const refs = raw.refs.filter((ref): ref is string => typeof ref === "string");
334
+ if (refs.length > 0) meta.refs = refs;
335
+ }
336
+ return Object.keys(meta).length > 0 ? meta : undefined;
343
337
  }
344
338
 
345
- /** A loader over the fallback alone: `remoteLoader` without `site`. */
339
+ /** A loader over the content it's given alone: `remoteLoader` without `site`. */
346
340
  class LocalLoader implements Loader {
347
- #fallback: Snapshot | Loader;
341
+ #content: Snapshot | Loader;
348
342
 
349
- constructor(fallback: Snapshot | Loader) {
350
- this.#fallback = fallback;
343
+ constructor(content: Snapshot | Loader) {
344
+ this.#content = content;
351
345
  }
352
346
 
353
- adopt(fallback: Snapshot | Loader): void {
354
- this.#fallback = fallback;
347
+ adopt(content: Snapshot | Loader): void {
348
+ this.#content = content;
355
349
  }
356
350
 
357
351
  [PEEK_RELEASE](): Snapshot | undefined {
358
- return peekRelease(this.#fallback);
352
+ return peekRelease(this.#content);
359
353
  }
360
354
 
361
355
  load(): Promise<Snapshot> {
362
- const fallback = this.#fallback;
363
- return isSnapshot(fallback) ? Promise.resolve(fallback) : fallback.load();
356
+ const content = this.#content;
357
+ return typeof (content as Loader).load === "function"
358
+ ? (content as Loader).load()
359
+ : Promise.resolve(content as Snapshot);
364
360
  }
365
361
  }
366
362
 
367
363
  /**
368
- * Hosted releases over a fallback. `createCMS` builds it for you when `site`
369
- * is set. Without `site`, it's a loader over the fallback alone.
364
+ * Hosted releases: `createCMS` builds it for you when `site` is set. With
365
+ * `site`, content comes only from the CDN, so `content` must be `undefined`
366
+ * (nothing is bundled). Without `site`, it's a loader over
367
+ * `content` alone.
370
368
  */
371
- export function remoteLoader(fallback: Snapshot | Loader, options: RemoteLoaderOptions): Loader {
369
+ export function remoteLoader(
370
+ content: Snapshot | Loader | undefined,
371
+ options: RemoteLoaderOptions,
372
+ ): Loader {
372
373
  const { site } = options ?? {};
373
374
  const hosted = Boolean(site);
375
+ if (hosted && content !== undefined) {
376
+ throw new TypeError(
377
+ "remoteLoader: with site, content comes from the delivery CDN at runtime; pass undefined as content",
378
+ );
379
+ }
380
+ if (!hosted && content === undefined) {
381
+ throw new TypeError("remoteLoader: without site, pass the content to serve");
382
+ }
374
383
  const key = Symbol.for(
375
- `${INSTANCE_PREFIX}${contentIdentity(fallback)}${hosted ? `|site:${site}` : "|local"}`,
384
+ hosted
385
+ ? `${INSTANCE_PREFIX}site:${site}`
386
+ : `${INSTANCE_PREFIX}${contentIdentity(content as Snapshot | Loader)}|local`,
376
387
  );
377
388
  const store = globalThis as unknown as Record<symbol, RemoteLoader | LocalLoader | undefined>;
378
389
  const existing = store[key];
379
- if (existing instanceof Object && typeof existing.adopt === "function") {
380
- if (existing instanceof RemoteLoader && existing.interval !== options.interval) {
381
- console.warn(
382
- "[decocms/blocks] remoteLoader was called again for the same site with different options " +
383
- "(interval); keeping the first instance's options.",
384
- );
390
+ // Duck-typed, so an instance a second copy of this module made is reused too.
391
+ if (existing instanceof Object && typeof existing.load === "function") {
392
+ if (hosted && (existing as Partial<HostedSource>)[HOSTED] === true) {
393
+ if ((existing as RemoteLoader).interval !== options.interval) {
394
+ console.warn(
395
+ "[decocms/blocks] remoteLoader was called again for the same site with different options " +
396
+ "(interval); keeping the first instance's options.",
397
+ );
398
+ }
399
+ return existing;
400
+ }
401
+ if (!hosted && typeof (existing as LocalLoader).adopt === "function") {
402
+ (existing as LocalLoader).adopt(content as Snapshot | Loader);
403
+ return existing;
385
404
  }
386
- existing.adopt(fallback);
387
- return existing;
388
405
  }
389
406
  const instance = hosted
390
- ? new RemoteLoader(fallback, { site: site!, interval: options.interval, dev: options.dev })
391
- : new LocalLoader(fallback);
407
+ ? new RemoteLoader({ site: site as string, interval: options.interval })
408
+ : new LocalLoader(content as Snapshot | Loader);
392
409
  store[key] = instance;
393
410
  return instance;
394
411
  }
@@ -398,19 +415,66 @@ export function resetRemoteLoaders(): void {
398
415
  }
399
416
 
400
417
  /**
401
- * Whether a release published at `publishedAt` is newer than content built
402
- * from a commit made at `committedAt`. Content without a `committedAt` is the
403
- * oldest.
404
- * OPEN: a `committedAt` that doesn't parse as a date counts as missing.
418
+ * GETs `url` (no credentials, 10 s for headers; `If-None-Match: etag` when
419
+ * given). Resolves with a 2xx, or with a 304 to a request that sent an ETag.
420
+ * Every other outcome is a `ContentUnavailableError`: the timeout, the
421
+ * network, any other HTTP status (`onStatus` sees it first).
405
422
  */
406
- function isNewer(publishedAt: string, committedAt: string | undefined): boolean {
407
- const committed = committedAt === undefined ? Number.NaN : Date.parse(committedAt);
408
- return Number.isNaN(committed) || Date.parse(publishedAt) > committed;
423
+ async function request(
424
+ url: string,
425
+ label: string,
426
+ etag?: string | null,
427
+ onStatus?: (status: number) => void,
428
+ ): Promise<Response> {
429
+ let response: Response;
430
+ const headers: Record<string, string> = {};
431
+ if (etag) headers["if-none-match"] = etag;
432
+ try {
433
+ response = await fetch(url, { headers, signal: timeoutSignal(FETCH_TIMEOUT_MS) });
434
+ } catch (error) {
435
+ throw unavailable(label, error, "network");
436
+ }
437
+ if (response.status === 304 && etag) {
438
+ void response.body?.cancel().catch(() => {});
439
+ return response;
440
+ }
441
+ if (!response.ok) {
442
+ void response.body?.cancel().catch(() => {});
443
+ onStatus?.(response.status);
444
+ throw new ContentUnavailableError("http", `${label}: HTTP ${response.status}`, {
445
+ status: response.status,
446
+ });
447
+ }
448
+ return response;
409
449
  }
410
450
 
411
- /** No credentials: delivery is public. */
412
- function fetchWithTimeout(url: string): Promise<Response> {
413
- return fetch(url, { signal: timeoutSignal(FETCH_TIMEOUT_MS) });
451
+ async function readBody(response: Response, label: string, maxBytes: number): Promise<unknown> {
452
+ try {
453
+ return await readBoundedJson(response, label, maxBytes);
454
+ } catch (error) {
455
+ throw unavailable(label, error, "format");
456
+ }
457
+ }
458
+
459
+ /** A failed fetch or body read as a `ContentUnavailableError`; a timeout is always `"timeout"`. */
460
+ function unavailable(
461
+ label: string,
462
+ error: unknown,
463
+ otherwise: "network" | "format",
464
+ ): ContentUnavailableError {
465
+ if (error instanceof ContentUnavailableError) return error;
466
+ const name = error instanceof Error ? error.name : undefined;
467
+ const message = error instanceof Error ? error.message : String(error);
468
+ if (name === "TimeoutError" || name === "AbortError") {
469
+ return new ContentUnavailableError(
470
+ "timeout",
471
+ `${label}: no answer within ${FETCH_TIMEOUT_MS} ms`,
472
+ { cause: error },
473
+ );
474
+ }
475
+ // A connection that drops mid-body is the network's, not the body's.
476
+ const reason = otherwise === "format" && error instanceof TypeError ? "network" : otherwise;
477
+ return new ContentUnavailableError(reason, `${label}: ${message}`, { cause: error });
414
478
  }
415
479
 
416
480
  function deliveryOrigin(): string {