@decocms/blocks 8.0.0 → 8.1.0-next.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 (175) hide show
  1. package/bin/deco.js +13 -0
  2. package/package.json +39 -3
  3. package/src/cms/applySectionConventions.ts +26 -2
  4. package/src/cms/blockSource.ts +37 -0
  5. package/src/cms/client.ts +5 -0
  6. package/src/cms/deferredTrigger.ts +58 -0
  7. package/src/cms/draftSource.ts +171 -57
  8. package/src/cms/index.ts +32 -3
  9. package/src/cms/loader.ts +318 -59
  10. package/src/cms/registry.ts +22 -0
  11. package/src/cms/renderJson.ts +179 -0
  12. package/src/cms/resolve.ts +396 -95
  13. package/src/cms/schema.ts +9 -5
  14. package/src/cms/sectionLoaders.ts +106 -56
  15. package/src/hooks/Image.tsx +70 -6
  16. package/src/hooks/LiveControls.tsx +30 -8
  17. package/src/hooks/Stats.tsx +134 -0
  18. package/src/hooks/index.ts +5 -0
  19. package/src/hooks/useLoadMore.ts +100 -0
  20. package/src/index.ts +37 -0
  21. package/src/middleware/observability.ts +173 -16
  22. package/src/preview/DraftPreviewBadge.tsx +306 -0
  23. package/src/preview/decoMark.ts +11 -0
  24. package/src/preview/index.ts +8 -0
  25. package/src/protocol/assets.ts +124 -0
  26. package/src/protocol/canonical.ts +7 -0
  27. package/src/protocol/ciphertext.ts +6 -0
  28. package/src/protocol/client.ts +170 -0
  29. package/src/protocol/conformance/cases/assets.ts +81 -0
  30. package/src/protocol/conformance/cases/guards.ts +314 -0
  31. package/src/protocol/conformance/cases/reads.ts +168 -0
  32. package/src/protocol/conformance/cases/types.ts +9 -0
  33. package/src/protocol/conformance/cases/wire.ts +138 -0
  34. package/src/protocol/conformance/cases/writes.ts +345 -0
  35. package/src/protocol/conformance/contentHashFixtures.ts +79 -0
  36. package/src/protocol/conformance/context.ts +222 -0
  37. package/src/protocol/conformance/index.ts +140 -0
  38. package/src/protocol/errors.ts +142 -0
  39. package/src/protocol/index.ts +39 -0
  40. package/src/protocol/keys.ts +279 -0
  41. package/src/protocol/params.ts +67 -0
  42. package/src/protocol/secrets.ts +231 -0
  43. package/src/protocol/server/assets.ts +119 -0
  44. package/src/protocol/server/auth.ts +49 -0
  45. package/src/protocol/server/bodyCache.ts +84 -0
  46. package/src/protocol/server/content.ts +175 -0
  47. package/src/protocol/server/core.ts +112 -0
  48. package/src/protocol/server/handler.ts +102 -0
  49. package/src/protocol/server/http.ts +139 -0
  50. package/src/protocol/server/index.ts +11 -0
  51. package/src/protocol/server/methods/apply.ts +341 -0
  52. package/src/protocol/server/methods/read.ts +156 -0
  53. package/src/protocol/server/rpc.ts +136 -0
  54. package/src/protocol/storage/fs/hash.ts +21 -0
  55. package/src/protocol/storage/fs/index.ts +338 -0
  56. package/src/protocol/storage/fs/lock.ts +68 -0
  57. package/src/protocol/storage/fs/transaction.ts +183 -0
  58. package/src/protocol/storage/fs/unsupported.ts +15 -0
  59. package/src/protocol/storage/memory.ts +238 -0
  60. package/src/protocol/storage.ts +182 -0
  61. package/src/protocol/types.ts +172 -0
  62. package/src/sdk/abTesting.ts +60 -3
  63. package/src/sdk/analytics.ts +72 -2
  64. package/src/sdk/cacheHeaders.ts +210 -10
  65. package/src/sdk/cacheStorage.ts +287 -0
  66. package/src/sdk/cachedLoader.ts +143 -90
  67. package/src/sdk/crypto.ts +16 -2
  68. package/src/sdk/deepOmit.ts +52 -0
  69. package/src/sdk/encoding.ts +2 -5
  70. package/src/sdk/experiments.ts +314 -0
  71. package/src/sdk/fetchCache.ts +269 -0
  72. package/src/sdk/fetchTimeout.ts +58 -0
  73. package/src/sdk/flags.ts +38 -8
  74. package/src/sdk/index.ts +7 -0
  75. package/src/sdk/instrumentedFetch.ts +25 -2
  76. package/src/sdk/nonce.ts +46 -0
  77. package/src/sdk/normalizeUrls.ts +2 -2
  78. package/src/sdk/observability.ts +8 -1
  79. package/src/sdk/otel.ts +131 -25
  80. package/src/sdk/otelHttpLog.ts +4 -4
  81. package/src/sdk/otelHttpMeter.ts +39 -13
  82. package/src/sdk/otelHttpTracer.ts +4 -4
  83. package/src/sdk/redirects.ts +113 -5
  84. package/src/sdk/responseCache.ts +82 -0
  85. package/src/sdk/urlUtils.ts +49 -0
  86. package/src/sdk/useSuggestions.ts +1 -1
  87. package/src/v8/analytics.ts +50 -0
  88. package/src/v8/background.ts +107 -0
  89. package/src/v8/builtins/data.ts +23 -0
  90. package/src/v8/builtins/index.ts +26 -0
  91. package/src/v8/builtins/lazy.ts +23 -0
  92. package/src/v8/builtins/legacy.ts +65 -0
  93. package/src/v8/builtins/matchers.ts +31 -0
  94. package/src/v8/builtins/multivariate.ts +25 -0
  95. package/src/v8/builtins/secret.ts +82 -0
  96. package/src/v8/canonical.ts +117 -0
  97. package/src/v8/ciphertext.ts +158 -0
  98. package/src/v8/cli/builtins.ts +20 -0
  99. package/src/v8/cli/check/index.ts +774 -0
  100. package/src/v8/cli/check/messages.ts +168 -0
  101. package/src/v8/cli/content.ts +287 -0
  102. package/src/v8/cli/index.ts +17 -0
  103. package/src/v8/cli/log.ts +18 -0
  104. package/src/v8/cli/main.ts +12 -0
  105. package/src/v8/cli/root.ts +66 -0
  106. package/src/v8/cli/run.ts +236 -0
  107. package/src/v8/cli/schema/builtinSchemas.ts +236 -0
  108. package/src/v8/cli/schema/generate.ts +507 -0
  109. package/src/v8/cli/schema/index.ts +63 -0
  110. package/src/v8/cli/schema/tsProgram.ts +497 -0
  111. package/src/v8/cli/schema/typeToSchema.ts +689 -0
  112. package/src/v8/cli/serve/server.ts +303 -0
  113. package/src/v8/cli/watch.ts +86 -0
  114. package/src/v8/client.ts +147 -0
  115. package/src/v8/cms.ts +237 -0
  116. package/src/v8/content.ts +195 -0
  117. package/src/v8/draft.ts +136 -0
  118. package/src/v8/errors.ts +59 -0
  119. package/src/v8/fetch.ts +152 -0
  120. package/src/v8/identity.ts +65 -0
  121. package/src/v8/index.ts +39 -0
  122. package/src/v8/json.ts +74 -0
  123. package/src/v8/matchRoute.ts +204 -0
  124. package/src/v8/remoteLoader.ts +282 -0
  125. package/src/v8/resolver.ts +278 -0
  126. package/src/v8/secrets.ts +17 -0
  127. package/src/v8/telemetry.ts +533 -0
  128. package/src/v8/types.ts +240 -0
  129. package/src/cms/blockSource.test.ts +0 -76
  130. package/src/cms/client.browserBundle.test.ts +0 -44
  131. package/src/cms/draftSource.test.ts +0 -343
  132. package/src/cms/layoutCacheRace.test.ts +0 -181
  133. package/src/cms/loadDecofileDirectory.test.ts +0 -109
  134. package/src/cms/loader.test.ts +0 -200
  135. package/src/cms/registry.test.ts +0 -110
  136. package/src/cms/resolve.test.ts +0 -980
  137. package/src/cms/schema.test.ts +0 -356
  138. package/src/cms/sectionLoaderContext.test.ts +0 -111
  139. package/src/cms/sectionLoaders.test.ts +0 -533
  140. package/src/cms/sectionMixins.test.ts +0 -167
  141. package/src/cms/stickyFlags.test.ts +0 -117
  142. package/src/flags/flags.test.ts +0 -148
  143. package/src/hooks/Image.test.ts +0 -100
  144. package/src/hooks/RenderSection.test.tsx +0 -81
  145. package/src/matchers/builtins.test.ts +0 -318
  146. package/src/matchers/override.test.ts +0 -205
  147. package/src/middleware/hydrationContext.test.ts +0 -61
  148. package/src/middleware/observability.test.ts +0 -242
  149. package/src/middleware/validateSection.test.ts +0 -147
  150. package/src/sdk/abTesting.test.ts +0 -326
  151. package/src/sdk/cacheHeaders.test.ts +0 -115
  152. package/src/sdk/cachedLoader.test.ts +0 -122
  153. package/src/sdk/cachedLoaderModule.test.ts +0 -209
  154. package/src/sdk/cn.test.ts +0 -34
  155. package/src/sdk/composite.test.ts +0 -121
  156. package/src/sdk/cookie.test.ts +0 -108
  157. package/src/sdk/encoding.test.ts +0 -71
  158. package/src/sdk/env.test.ts +0 -33
  159. package/src/sdk/flags.test.ts +0 -91
  160. package/src/sdk/http.test.ts +0 -71
  161. package/src/sdk/inflightTimeout.test.ts +0 -35
  162. package/src/sdk/instrumentedFetch.test.ts +0 -559
  163. package/src/sdk/invoke.test.ts +0 -115
  164. package/src/sdk/logger.test.ts +0 -432
  165. package/src/sdk/otel.test.ts +0 -526
  166. package/src/sdk/otelAdapters.test.ts +0 -89
  167. package/src/sdk/otelHttpLog.test.ts +0 -457
  168. package/src/sdk/otelHttpMeter.test.ts +0 -292
  169. package/src/sdk/otelHttpTracer.test.ts +0 -474
  170. package/src/sdk/requestContextStorage.browser.test.ts +0 -29
  171. package/src/sdk/urlRedaction.test.ts +0 -73
  172. package/src/sdk/useDevice.test.ts +0 -130
  173. package/src/sdk/useScript.test.ts +0 -128
  174. package/src/sdk/useSuggestions.test.ts +0 -230
  175. package/tsconfig.json +0 -7
package/bin/deco.js ADDED
@@ -0,0 +1,13 @@
1
+ #!/usr/bin/env node
2
+ // The `deco` command (spec: internals › How the CLI ships). A small JavaScript
3
+ // file that loads the CLI's TypeScript sources: Bun runs them as they are;
4
+ // under Node, tsx's loader is registered first.
5
+ const entry = new URL("../src/v8/cli/main.ts", import.meta.url);
6
+
7
+ if (typeof globalThis.Bun !== "undefined") {
8
+ await import(entry.href);
9
+ } else {
10
+ const { register } = await import("tsx/esm/api");
11
+ register();
12
+ await import(entry.href);
13
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@decocms/blocks",
3
- "version": "8.0.0",
3
+ "version": "8.1.0-next.0",
4
4
  "type": "module",
5
5
  "engines": {
6
6
  "node": ">=24"
@@ -12,12 +12,38 @@
12
12
  "directory": "packages/blocks"
13
13
  },
14
14
  "main": "./src/index.ts",
15
+ "files": [
16
+ "bin",
17
+ "src",
18
+ "!src/**/*.test.ts",
19
+ "!src/**/*.test.tsx",
20
+ "!src/**/__tests__",
21
+ "!src/**/__fixtures__",
22
+ "!src/**/__conformance__",
23
+ "!src/v8/testFixtures.ts"
24
+ ],
25
+ "bin": {
26
+ "deco": "./bin/deco.js"
27
+ },
15
28
  "exports": {
16
29
  ".": "./src/index.ts",
30
+ "./analytics": "./src/v8/analytics.ts",
17
31
  "./cms": "./src/cms/index.ts",
18
32
  "./cms/client": "./src/cms/client.ts",
19
33
  "./cms/loadDecofileDirectory": "./src/cms/loadDecofileDirectory.ts",
34
+ "./cli": "./src/v8/cli/index.ts",
35
+ "./fetch": "./src/v8/fetch.ts",
20
36
  "./hooks": "./src/hooks/index.ts",
37
+ "./preview": "./src/preview/index.ts",
38
+ "./protocol": "./src/protocol/index.ts",
39
+ "./protocol/keys": "./src/protocol/keys.ts",
40
+ "./protocol/server": "./src/protocol/server/index.ts",
41
+ "./protocol/storage/fs": {
42
+ "node": "./src/protocol/storage/fs/index.ts",
43
+ "default": "./src/protocol/storage/fs/unsupported.ts"
44
+ },
45
+ "./protocol/conformance": "./src/protocol/conformance/index.ts",
46
+ "./secrets": "./src/v8/secrets.ts",
21
47
  "./types": "./src/types/index.ts",
22
48
  "./types/widgets": "./src/types/widgets.ts",
23
49
  "./setup": "./src/setup.ts",
@@ -42,6 +68,8 @@
42
68
  "./sdk/abTesting": "./src/sdk/abTesting.ts",
43
69
  "./sdk/analytics": "./src/sdk/analytics.ts",
44
70
  "./sdk/cachedLoader": "./src/sdk/cachedLoader.ts",
71
+ "./sdk/responseCache": "./src/sdk/responseCache.ts",
72
+ "./sdk/cacheStorage": "./src/sdk/cacheStorage.ts",
45
73
  "./sdk/cacheHeaders": "./src/sdk/cacheHeaders.ts",
46
74
  "./sdk/clx": "./src/sdk/clx.ts",
47
75
  "./sdk/cn": "./src/sdk/cn.ts",
@@ -53,12 +81,16 @@
53
81
  "./sdk/djb2": "./src/sdk/djb2.ts",
54
82
  "./sdk/encoding": "./src/sdk/encoding.ts",
55
83
  "./sdk/env": "./src/sdk/env.ts",
84
+ "./sdk/fetchCache": "./src/sdk/fetchCache.ts",
85
+ "./sdk/fetchTimeout": "./src/sdk/fetchTimeout.ts",
86
+ "./sdk/experiments": "./src/sdk/experiments.ts",
56
87
  "./sdk/flags": "./src/sdk/flags.ts",
57
88
  "./sdk/http": "./src/sdk/http.ts",
58
89
  "./sdk/instrumentedFetch": "./src/sdk/instrumentedFetch.ts",
59
90
  "./sdk/invoke": "./src/sdk/invoke.ts",
60
91
  "./sdk/logger": "./src/sdk/logger.ts",
61
92
  "./sdk/mergeCacheControl": "./src/sdk/mergeCacheControl.ts",
93
+ "./sdk/nonce": "./src/sdk/nonce.ts",
62
94
  "./sdk/normalizeUrls": "./src/sdk/normalizeUrls.ts",
63
95
  "./sdk/observability": "./src/sdk/observability.ts",
64
96
  "./sdk/otel": "./src/sdk/otel.ts",
@@ -96,13 +128,17 @@
96
128
  "@opentelemetry/api": "^1.9.1",
97
129
  "@opentelemetry/semantic-conventions": "^1.41.1",
98
130
  "@tanstack/store": "^0.9.1",
131
+ "ajv": "^8.20.0",
99
132
  "clsx": "^2.1.1",
100
133
  "fast-json-patch": "^3.1.0",
101
- "tailwind-merge": "^3.3.1"
134
+ "tailwind-merge": "^3.3.1",
135
+ "tsx": "^4.22.5",
136
+ "zod": "^4.4.3"
102
137
  },
103
138
  "peerDependencies": {
104
139
  "react": "^19.0.0",
105
- "react-dom": "^19.0.0"
140
+ "react-dom": "^19.0.0",
141
+ "typescript": "^5.0.0"
106
142
  },
107
143
  "devDependencies": {
108
144
  "@types/react": "^19.0.0",
@@ -6,10 +6,12 @@
6
6
  * registerSectionsSync, setAsyncRenderingConfig, registerCacheableSections,
7
7
  * registerLayoutSections, registerSeoSections, and registerSection.
8
8
  */
9
- import { registerSection, registerSectionsSync } from "./registry";
9
+ import { registerSection, registerSectionsSync, setSectionRenderJson } from "./registry";
10
+ import type { RenderJson } from "./renderJson";
10
11
  import {
11
12
  type AsyncRenderingConfig,
12
13
  getAsyncRenderingConfig,
14
+ registerAlwaysDeferSections,
13
15
  registerEagerSections,
14
16
  registerNeverDeferSections,
15
17
  registerSeoSections,
@@ -24,12 +26,17 @@ import {
24
26
  export interface SectionMetaEntry {
25
27
  eager?: boolean;
26
28
  neverDefer?: boolean;
29
+ deferred?: boolean;
27
30
  cache?: string;
28
31
  layout?: boolean;
29
32
  sync?: boolean;
30
33
  clientOnly?: boolean;
31
34
  seo?: boolean;
32
35
  hasLoadingFallback?: boolean;
36
+ /** `export const renderJson = false` — drop the section from ?renderJson. */
37
+ renderJson?: false;
38
+ /** `export const renderJson = (props) => ...` — a projection fn (in `renderJsons`). */
39
+ hasRenderJson?: boolean;
33
40
  }
34
41
 
35
42
  export interface ApplySectionConventionsInput {
@@ -39,15 +46,18 @@ export interface ApplySectionConventionsInput {
39
46
  syncComponents?: Record<string, any>;
40
47
  /** LoadingFallback components from sections.gen.ts */
41
48
  loadingFallbacks?: Record<string, React.ComponentType<any>>;
49
+ /** renderJson projection functions from sections.gen.ts (?renderJson mobile path) */
50
+ renderJsons?: Record<string, RenderJson>;
42
51
  /** Lazy section loaders from import.meta.glob (used for clientOnly/loadingFallback registration) */
43
52
  sectionGlob?: Record<string, () => Promise<any>>;
44
53
  }
45
54
 
46
55
  export function applySectionConventions(input: ApplySectionConventionsInput): void {
47
- const { meta, syncComponents, loadingFallbacks, sectionGlob } = input;
56
+ const { meta, syncComponents, loadingFallbacks, renderJsons, sectionGlob } = input;
48
57
 
49
58
  const eagerSections: string[] = [];
50
59
  const neverDeferSections: string[] = [];
60
+ const alwaysDeferSections: string[] = [];
51
61
  const layoutSections: string[] = [];
52
62
  const seoSections: string[] = [];
53
63
  const cacheableSections: Record<string, CacheableSectionInput> = {};
@@ -55,6 +65,7 @@ export function applySectionConventions(input: ApplySectionConventionsInput): vo
55
65
  for (const [key, entry] of Object.entries(meta)) {
56
66
  if (entry.eager) eagerSections.push(key);
57
67
  if (entry.neverDefer) neverDeferSections.push(key);
68
+ if (entry.deferred) alwaysDeferSections.push(key);
58
69
  if (entry.layout) layoutSections.push(key);
59
70
  if (entry.seo) seoSections.push(key);
60
71
  if (entry.cache) cacheableSections[key] = entry.cache as CacheableSectionInput;
@@ -74,6 +85,15 @@ export function applySectionConventions(input: ApplySectionConventionsInput): vo
74
85
  });
75
86
  }
76
87
  }
88
+
89
+ // renderJson (?renderJson mobile path): a `= false` opt-out drops the
90
+ // section; a projection function trims its props. Set as a section option so
91
+ // the serializer reads it via getSectionOptions without loading the module.
92
+ if (entry.renderJson === false) {
93
+ setSectionRenderJson(key, false);
94
+ } else if (entry.hasRenderJson && renderJsons?.[key]) {
95
+ setSectionRenderJson(key, renderJsons[key]);
96
+ }
77
97
  }
78
98
 
79
99
  if (syncComponents && Object.keys(syncComponents).length > 0) {
@@ -88,6 +108,10 @@ export function applySectionConventions(input: ApplySectionConventionsInput): vo
88
108
  registerNeverDeferSections(neverDeferSections);
89
109
  }
90
110
 
111
+ if (alwaysDeferSections.length > 0) {
112
+ registerAlwaysDeferSections(alwaysDeferSections);
113
+ }
114
+
91
115
  // Always initialize asyncConfig so CMS Lazy deferral (`respectCmsLazy`) is
92
116
  // active — this is what makes the admin ⚡ toggle the source of truth. Without
93
117
  // it, asyncConfig stays null, `useAsync` is false in resolveDecoPage, and
@@ -123,6 +123,7 @@ export interface KVNamespace {
123
123
  // index:revision:<id> DJB2 hex revision of that snapshot (polled)
124
124
  // index:live pointer to the currently-live <id> (set post-deploy)
125
125
  // index:deployments JSON [{id, ts}] (newest last) — GC bookkeeping
126
+ // redirect:<id>:<path> ONE key per exact redirect (see below)
126
127
  // ---------------------------------------------------------------------------
127
128
 
128
129
  /** KV key holding the full decofile JSON for deployment `id`. */
@@ -144,6 +145,42 @@ export const LIVE_KEY = "index:live";
144
145
  * deployment snapshots so the sync script can GC all but the last N. */
145
146
  export const DEPLOYMENTS_KEY = "index:deployments";
146
147
 
148
+ // ---------------------------------------------------------------------------
149
+ // Exact redirects — one KV key each, deliberately NOT inside the decofile.
150
+ //
151
+ // A bulk-migration site can carry tens of thousands of rules. Inside the
152
+ // decofile they are resident in every isolate twice over: once in the parsed
153
+ // snapshot graph, once in the `RedirectMap` built from it — megabytes of a
154
+ // 128MB budget, for data that is read at most once per request and usually
155
+ // never. As their own keys they are looked up on demand and the list is never
156
+ // loaded at all.
157
+ //
158
+ // Only EXACT rules move. Glob rules (`/old/*`) cannot be addressed by key and
159
+ // must be scanned in order, so they stay in the decofile — there are tens of
160
+ // them, not thousands.
161
+ // ---------------------------------------------------------------------------
162
+
163
+ /** Key prefix holding deployment `id`'s exact redirects (one key per path). */
164
+ export function redirectPrefix(id: string): string {
165
+ return `redirect:${id}:`;
166
+ }
167
+
168
+ /**
169
+ * KV key for one exact redirect. `path` MUST already be normalized by
170
+ * `normalizePath` (`@decocms/blocks/sdk/redirects`) on both sides — the writer
171
+ * and the request-time lookup — or a rule is written under a key nothing ever
172
+ * asks for.
173
+ */
174
+ export function redirectKey(id: string, path: string): string {
175
+ return `${redirectPrefix(id)}${path}`;
176
+ }
177
+
178
+ /** Value stored at a `redirect:<id>:<path>` key. */
179
+ export interface StoredRedirect {
180
+ to: string;
181
+ status: 301 | 302;
182
+ }
183
+
147
184
  // ---------------------------------------------------------------------------
148
185
  // Deployment id resolution
149
186
  //
package/src/cms/client.ts CHANGED
@@ -25,6 +25,9 @@
25
25
  * `sdk/requestContextStorage.browser.ts`), so it's already safe for a
26
26
  * browser bundle.
27
27
  * - `schema.ts` has no imports at all.
28
+ * - `deferredTrigger.ts` has no imports at all — it only reads the
29
+ * `globalThis.__deco.asyncConfig` bag `resolve.ts` writes, which is exactly
30
+ * why it is a standalone module instead of living in `resolve.ts`.
28
31
  *
29
32
  * Deliberately NOT re-exported here: `loader.ts`, `resolve.ts`,
30
33
  * `sectionLoaders.ts`, `loadDecofileDirectory.ts`, `blockSource.ts`, and
@@ -33,6 +36,8 @@
33
36
  * storage concerns that only make sense server-side — import them from
34
37
  * `@decocms/blocks/cms` instead.
35
38
  */
39
+ export type { DeferredTrigger } from "./deferredTrigger";
40
+ export { DEFAULT_DEFERRED_TRIGGER, getDeferredTrigger } from "./deferredTrigger";
36
41
  export type { OnBeforeResolveProps, SectionModule, SectionOptions } from "./registry";
37
42
  export {
38
43
  getResolvedComponent,
@@ -0,0 +1,58 @@
1
+ /**
2
+ * Client-safe reader for the deferred-section trigger mode.
3
+ *
4
+ * Lives in its own module — with zero imports — so a browser bundle can reach
5
+ * it without dragging in `resolve.ts` (and its `node:async_hooks` /
6
+ * `node:fs/promises` chain). Same reasoning as `cms/client.ts`; see the header
7
+ * comment there.
8
+ *
9
+ * The value itself is written by `setAsyncRenderingConfig()` in `resolve.ts`,
10
+ * into the same `globalThis.__deco.asyncConfig` bag the server reads.
11
+ *
12
+ * WHERE THE SETTING HAS TO RUN: this is read in the browser, so
13
+ * `setAsyncRenderingConfig()` only takes effect if it runs in a module the
14
+ * client bundle also loads — normally `setup.ts`, imported from `router.tsx`.
15
+ * Set it from server-only code (the worker entry, `server.ts`) and the server
16
+ * defers the section as expected while the client silently falls back to
17
+ * `"intersection"`, which looks exactly like the option being ignored.
18
+ *
19
+ * WHO READS IT: only `@decocms/tanstack` (`DeferredSectionWrapper` in
20
+ * `hooks/DecoPageRenderer.tsx`). It lives here because that is where
21
+ * `AsyncRenderingConfig` lives; in `@decocms/nextjs` it is a no-op.
22
+ */
23
+
24
+ /**
25
+ * How a deferred (⚡) section decides it's time to fetch its real markup.
26
+ *
27
+ * - `"intersection"` — wait until the skeleton is within 300px of the viewport.
28
+ * Cheapest, and the default.
29
+ * - `"load"` — fetch as soon as the wrapper mounts, without waiting for scroll.
30
+ * This is what Deco on Fresh does through `DispatchAsyncRender`'s
31
+ * `partialTriggerMode: "load"`: the page ships a light skeleton HTML and then
32
+ * materializes every deferred section right after hydration. Sites migrating
33
+ * from Fresh need this to keep parity — under `"intersection"` alone, content
34
+ * below the fold does not exist until the user scrolls, which loses
35
+ * below-the-fold analytics impressions and leaves the document short.
36
+ *
37
+ * The tradeoff of `"load"` is a request burst: every deferred section fires its
38
+ * serverFn POST in the same commit, on first load and again on every SPA
39
+ * navigation. That is precisely what the rAF + observer path exists to avoid,
40
+ * and it is also exactly what Fresh does — so it is the right default for a
41
+ * migrated site and the wrong one for a page with many heavy deferred sections.
42
+ * The switch is site-wide; a per-section override (honouring the `loading` prop
43
+ * the CMS `Lazy.tsx` wrapper already carries, which the resolver currently
44
+ * discards) would be the finer-grained successor.
45
+ */
46
+ export type DeferredTrigger = "intersection" | "load";
47
+
48
+ export const DEFAULT_DEFERRED_TRIGGER: DeferredTrigger = "intersection";
49
+
50
+ /**
51
+ * Read the configured trigger. Falls back to `"intersection"` when
52
+ * `setAsyncRenderingConfig()` was never called or omitted the option, so
53
+ * existing sites are not regressed by a framework bump.
54
+ */
55
+ export function getDeferredTrigger(): DeferredTrigger {
56
+ const config = (globalThis as any).__deco?.asyncConfig;
57
+ return config?.deferredTrigger ?? DEFAULT_DEFERRED_TRIGGER;
58
+ }