@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/src/cms/loader.ts CHANGED
@@ -31,7 +31,21 @@ interface ALSLike<T> {
31
31
  // node:async_hooks with an empty shim). The namespace import avoids Rollup's
32
32
  // named-export validation, and the runtime check prevents construction errors.
33
33
  const ALS = (asyncHooks as any).AsyncLocalStorage;
34
- const blocksOverrideStorage: ALSLike<Record<string, unknown>> = ALS
34
+
35
+ /**
36
+ * A scoped blocks override, tagged with how it composes over the base:
37
+ * - `merge`: a PARTIAL decofile (admin preview payloads) — entries replace or
38
+ * delete their base twins, everything else survives (see mergeOverride).
39
+ * - `snapshot`: a COMPLETE decofile (draft preview) — it replaces the
40
+ * file-backed base entirely; only synthetic base blocks survive (see
41
+ * applyDraftSnapshot).
42
+ */
43
+ interface BlocksOverride {
44
+ mode: "merge" | "snapshot";
45
+ blocks: Record<string, unknown>;
46
+ }
47
+
48
+ const blocksOverrideStorage: ALSLike<BlocksOverride> = ALS
35
49
  ? new ALS()
36
50
  : { getStore: () => undefined, run: (_s: any, fn: any) => fn() };
37
51
 
@@ -39,7 +53,10 @@ const blocksOverrideStorage: ALSLike<Record<string, unknown>> = ALS
39
53
  // Change listeners
40
54
  // ---------------------------------------------------------------------------
41
55
 
42
- type ChangeListener = (blocks: Record<string, unknown>, revision: string) => void;
56
+ type ChangeListener = (
57
+ blocks: Record<string, unknown>,
58
+ revision: string,
59
+ ) => void;
43
60
  const changeListeners: ChangeListener[] = [];
44
61
 
45
62
  /** Register a callback invoked whenever setBlocks() changes the decofile. */
@@ -69,6 +86,8 @@ function computeRevision(blocks: Record<string, unknown>): string {
69
86
  * Notifies all onChange listeners and updates the revision.
70
87
  */
71
88
  export function setBlocks(blocks: Record<string, unknown>) {
89
+ // A caller may hand back the same object after mutating it in place.
90
+ pageIndexCache.delete(blocks);
72
91
  blockData = blocks;
73
92
  revision = computeRevision(blocks);
74
93
 
@@ -86,9 +105,93 @@ export function setBlocks(blocks: Record<string, unknown>) {
86
105
  }
87
106
 
88
107
  /**
89
- * Load the current blocks. If running inside a `withBlocksOverride` scope
90
- * (admin preview) or a request carrying a draft-preview override, that
91
- * override is merged on top of the base blocks.
108
+ * Canonicalise a block key so an override block matches its base twin even when
109
+ * the two decofiles disagree on percent-encoding of the key.
110
+ *
111
+ * The site's published decofile encodes special characters in block keys
112
+ * (`pages-Home%20(principal)-287364`); the Studio draft-preview sandbox emits
113
+ * them raw (`pages-Home (principal)-287364`). Decoding collapses both spellings
114
+ * to the same canonical form. Defensive: a malformed `%` sequence makes
115
+ * `decodeURIComponent` throw, so fall back to the raw key rather than 500 the
116
+ * merge.
117
+ */
118
+ function canonicalBlockKey(key: string): string {
119
+ try {
120
+ return decodeURIComponent(key);
121
+ } catch {
122
+ return key;
123
+ }
124
+ }
125
+
126
+ /**
127
+ * Merge an override decofile on top of the base blocks.
128
+ *
129
+ * An override entry REPLACES the base block of the same logical key — including
130
+ * a base twin spelled with different percent-encoding. A naive key-merge would
131
+ * instead ADD the differently-encoded override block, leaving two `pages-`
132
+ * blocks with the same `.path`; `findPageByPath` returns the first (base) one,
133
+ * so a draft-preview edit would silently never render. Canonicalising the base
134
+ * keys lets the override find and displace its twin.
135
+ *
136
+ * A `null`/`undefined` override value deletes the block (its twin too), so a
137
+ * draft that removes a block is honoured.
138
+ */
139
+ function mergeOverride(
140
+ base: Record<string, unknown>,
141
+ override: Record<string, unknown>,
142
+ ): Record<string, unknown> {
143
+ const merged = { ...base };
144
+ const baseByCanonical = new Map<string, string>();
145
+ for (const baseKey of Object.keys(merged)) {
146
+ baseByCanonical.set(canonicalBlockKey(baseKey), baseKey);
147
+ }
148
+ for (const [key, value] of Object.entries(override)) {
149
+ const twin = baseByCanonical.get(canonicalBlockKey(key));
150
+ if (twin !== undefined && twin !== key) delete merged[twin];
151
+ if (value === null || value === undefined) {
152
+ delete merged[key];
153
+ } else {
154
+ merged[key] = value;
155
+ }
156
+ }
157
+ return merged;
158
+ }
159
+
160
+ /**
161
+ * Base blocks that are NOT file-backed: synthesized by the generator (CSV
162
+ * redirect loaders, keyed `__csv_redirects__<file>`). A draft snapshot is the
163
+ * complete truth of `.deco/blocks/` but knows nothing about these, so they
164
+ * survive the snapshot instead of vanishing from the preview.
165
+ */
166
+ const SYNTHETIC_BLOCK_KEY_PREFIX = "__csv_redirects__";
167
+
168
+ /**
169
+ * Compose a draft SNAPSHOT over the base blocks: the draft is the complete
170
+ * decofile at the branch head, so it REPLACES every file-backed base block —
171
+ * a block absent from the draft was deleted and must not render. Only
172
+ * synthetic base blocks (see SYNTHETIC_BLOCK_KEY_PREFIX) survive. `null`
173
+ * draft values are tolerated as deletions for defensiveness.
174
+ */
175
+ function applyDraftSnapshot(
176
+ base: Record<string, unknown>,
177
+ draft: Record<string, unknown>,
178
+ ): Record<string, unknown> {
179
+ const out: Record<string, unknown> = {};
180
+ for (const [key, value] of Object.entries(base)) {
181
+ if (key.startsWith(SYNTHETIC_BLOCK_KEY_PREFIX)) out[key] = value;
182
+ }
183
+ for (const [key, value] of Object.entries(draft)) {
184
+ if (value === null || value === undefined) continue;
185
+ out[key] = value;
186
+ }
187
+ return out;
188
+ }
189
+
190
+ /**
191
+ * Load the current blocks. If running inside a `withBlocksOverride` /
192
+ * `withDraftBlocks` scope (admin preview / draft endpoints) or a request
193
+ * carrying an ambient draft, that override composes over the base blocks
194
+ * according to its mode.
92
195
  */
93
196
  export function loadBlocks(): Record<string, unknown> {
94
197
  // Re-sync from globalThis in case setBlocks was called in another module instance
@@ -97,21 +200,17 @@ export function loadBlocks(): Record<string, unknown> {
97
200
  revision = G.__deco.revision ?? null;
98
201
  }
99
202
 
100
- // `withBlocksOverride` (an explicit admin render of a specific payload) wins
101
- // over an ambient draft: the caller named the exact blocks to render, so a
102
- // draft pointer on the same request must not silently replace them.
103
- const override = blocksOverrideStorage.getStore() ?? getRequestDraftOverride();
104
- if (override) {
105
- const merged = { ...blockData };
106
- for (const [key, value] of Object.entries(override)) {
107
- if (value === null || value === undefined) {
108
- delete merged[key];
109
- } else {
110
- merged[key] = value;
111
- }
112
- }
113
- return merged;
203
+ // An explicit scope (the caller named the exact blocks to render) wins over
204
+ // an ambient draft: a draft pointer on the same request must not silently
205
+ // replace it.
206
+ const scoped = blocksOverrideStorage.getStore();
207
+ if (scoped) {
208
+ return scoped.mode === "merge"
209
+ ? mergeOverride(blockData, scoped.blocks)
210
+ : applyDraftSnapshot(blockData, scoped.blocks);
114
211
  }
212
+ const draft = getRequestDraftOverride();
213
+ if (draft) return applyDraftSnapshot(blockData, draft);
115
214
  return blockData;
116
215
  }
117
216
 
@@ -128,8 +227,25 @@ export function getRevision(): string | null {
128
227
  * for the duration of the render. Other concurrent requests are not
129
228
  * affected (AsyncLocalStorage is per-request scoped).
130
229
  */
131
- export function withBlocksOverride<T>(override: Record<string, unknown>, fn: () => T): T {
132
- return blocksOverrideStorage.run(override, fn);
230
+ export function withBlocksOverride<T>(
231
+ override: Record<string, unknown>,
232
+ fn: () => T,
233
+ ): T {
234
+ return blocksOverrideStorage.run({ mode: "merge", blocks: override }, fn);
235
+ }
236
+
237
+ /**
238
+ * Run a function with a COMPLETE draft decofile (snapshot semantics — see
239
+ * applyDraftSnapshot). Used by secondary endpoints (`/deco/invoke`) that
240
+ * re-resolve the page's draft from the raw request: the draft must compose
241
+ * exactly like the page render, deletions included, or a lazy section could
242
+ * render a block the page no longer has.
243
+ */
244
+ export function withDraftBlocks<T>(
245
+ draft: Record<string, unknown>,
246
+ fn: () => T,
247
+ ): T {
248
+ return blocksOverrideStorage.run({ mode: "snapshot", blocks: draft }, fn);
133
249
  }
134
250
 
135
251
  // Higher key wins. Compared lexicographically:
@@ -140,13 +256,13 @@ export function withBlocksOverride<T>(override: Record<string, unknown>, fn: ()
140
256
  // `/` (literals=0) vs the catch-all `/{prefix/}?*` (literals=0, params=1).
141
257
  // Without this, the URLPattern fix (#213/#214) inadvertently lets a
142
258
  // `/{group/}?*` catch-all out-rank an exact `/` home page because the
143
- // `{group` segment counted as a param. See deco-sites/granadobr-tanstack
144
- // where `/` was being routed to the granado PDP/PLP block's NotFound
259
+ // `{group` segment counted as a param. See a production storefront
260
+ // where `/` was being routed to a brand-prefixed PDP/PLP block's NotFound
145
261
  // fallback.
146
262
  //
147
263
  // Order produced:
148
264
  // /foo/bar (no wildcard, literals=2) > /foo/:x (no wildcard, lit=1, param=1)
149
- // /foo (no wildcard) > /{granado/}?* (has wildcard) > /*
265
+ // /foo (no wildcard) > /{acme/}?* (has wildcard) > /*
150
266
  function pathSpecificityKey(path: string): [number, number, number] {
151
267
  const parts = path.split("/").filter(Boolean);
152
268
  let literals = 0;
@@ -168,17 +284,79 @@ function pathSpecificityKey(path: string): [number, number, number] {
168
284
  return [hasWildcard ? 0 : 1, literals, params];
169
285
  }
170
286
 
171
- export function getAllPages(): Array<{ key: string; page: DecoPage }> {
172
- const blocks = loadBlocks();
173
- const pages: Array<{ key: string; page: DecoPage; key2: [number, number, number] }> = [];
287
+ // Literal rather than WELL_KNOWN_TYPES.PAGE: resolve.ts already imports from
288
+ // this module, so importing back would close a cycle.
289
+ const PAGE_RESOLVE_TYPE = "website/pages/Page.tsx";
290
+
291
+ /**
292
+ * Is this block a page?
293
+ *
294
+ * The `pages-` prefix is kept as a fast path because it is what the admin
295
+ * emits and it short-circuits the vast majority of blocks without a property
296
+ * read. But it cannot be the *only* test: a decofile carried over from Deco on
297
+ * Fresh can hold page blocks under any key — renaming one in the CMS renames
298
+ * its snapshot file, and `loadDecofileDirectory` preserves whatever key the
299
+ * filename already had.
300
+ *
301
+ * Those blocks are pages in every way that matters (`website/pages/Page.tsx`,
302
+ * a `path`, `sections`), and on Fresh they routed fine: `website/loaders/pages.ts`
303
+ * enumerated by `__resolveType`, not by key. Filtering on the prefix alone makes
304
+ * them invisible, so every one of their URLs falls through to whatever catch-all
305
+ * the site has — usually a 404 — and they disappear from the CMS sitemap too.
306
+ * One storefront in this state has 205 such blocks against 107 prefixed ones.
307
+ */
308
+ function isPageBlock(key: string, block: unknown): boolean {
309
+ if (key.startsWith("pages-")) return true;
310
+ return (
311
+ typeof block === "object" &&
312
+ block !== null &&
313
+ (block as Resolvable).__resolveType === PAGE_RESOLVE_TYPE
314
+ );
315
+ }
316
+
317
+ type PageIndexEntry = {
318
+ key: string;
319
+ page: DecoPage;
320
+ path: string;
321
+ /** `path` has no URLPattern syntax, so it only matches its own spelling. */
322
+ literal: boolean;
323
+ /** Compiled on first use; `null` when the pattern is malformed. */
324
+ matcher?: CompiledPattern | null;
325
+ };
326
+
327
+ /**
328
+ * Page list per blocks object, ranked by path specificity.
329
+ *
330
+ * `findPageByPath` runs on every CMS resolve — twice per request on a site
331
+ * that retries a lowercase path, and once more per template it resolves — and
332
+ * a request that ends on no CMS page (a catalog PLP/PDP, a search, a 404) walks
333
+ * the whole list. Rebuilding and sorting the list and compiling a URLPattern
334
+ * per page on each call made that walk the hottest frame of an uncached render
335
+ * on a 1.2k-page decofile. Keyed by the blocks object: `setBlocks()` and every
336
+ * draft/override composition produce a new one, so a published change can
337
+ * never be served from a stale index. Kept on `globalThis`, like the blocks
338
+ * themselves, so every module instance drops the same entry on `setBlocks()`.
339
+ * The compiled matchers live on the entries and go away with them.
340
+ */
341
+ const pageIndexCache: WeakMap<Record<string, unknown>, PageIndexEntry[]> =
342
+ G.__deco.pageIndexCache ?? (G.__deco.pageIndexCache = new WeakMap());
343
+
344
+ function buildPageIndex(blocks: Record<string, unknown>): PageIndexEntry[] {
345
+ const pages: Array<PageIndexEntry & { key2: [number, number, number] }> = [];
174
346
 
175
347
  for (const [key, block] of Object.entries(blocks)) {
176
- if (!key.startsWith("pages-")) continue;
348
+ if (!isPageBlock(key, block)) continue;
177
349
  const page = block as DecoPage;
178
350
  if (!page.sections) continue;
179
351
  if (!page.path) continue;
180
352
 
181
- pages.push({ key, page, key2: pathSpecificityKey(page.path) });
353
+ pages.push({
354
+ key,
355
+ page,
356
+ path: page.path,
357
+ literal: isPlainPath(page.path),
358
+ key2: pathSpecificityKey(page.path),
359
+ });
182
360
  }
183
361
 
184
362
  return pages
@@ -188,7 +366,21 @@ export function getAllPages(): Array<{ key: string; page: DecoPage }> {
188
366
  }
189
367
  return 0;
190
368
  })
191
- .map(({ key, page }) => ({ key, page }));
369
+ .map(({ key, page, path, literal }) => ({ key, page, path, literal }));
370
+ }
371
+
372
+ function getPageIndex(): PageIndexEntry[] {
373
+ const blocks = loadBlocks();
374
+ let index = pageIndexCache.get(blocks);
375
+ if (!index) {
376
+ index = buildPageIndex(blocks);
377
+ pageIndexCache.set(blocks, index);
378
+ }
379
+ return index;
380
+ }
381
+
382
+ export function getAllPages(): Array<{ key: string; page: DecoPage }> {
383
+ return getPageIndex().map(({ key, page }) => ({ key, page }));
192
384
  }
193
385
 
194
386
  // Module-scoped (NOT `declare global`) ambient declaration for the
@@ -218,6 +410,84 @@ declare const URLPattern: {
218
410
  };
219
411
  };
220
412
 
413
+ type CompiledPattern = {
414
+ exec(input: { pathname: string }): MatchPatternResult | null;
415
+ };
416
+
417
+ function compilePattern(pattern: string): CompiledPattern | null {
418
+ try {
419
+ return new URLPattern({ pathname: pattern });
420
+ } catch {
421
+ return null;
422
+ }
423
+ }
424
+
425
+ /**
426
+ * Compiled patterns for direct `matchPath()` callers, bounded: unlike the page
427
+ * index, its patterns can come from anywhere. Oldest entry evicted first.
428
+ */
429
+ const MATCH_PATH_CACHE_MAX = 256;
430
+ const matchPathCache = new Map<string, CompiledPattern | null>();
431
+
432
+ function cachedPattern(pattern: string): CompiledPattern | null {
433
+ const hit = matchPathCache.get(pattern);
434
+ if (hit !== undefined) return hit;
435
+ const compiled = compilePattern(pattern);
436
+ if (matchPathCache.size >= MATCH_PATH_CACHE_MAX) {
437
+ matchPathCache.delete(matchPathCache.keys().next().value as string);
438
+ }
439
+ matchPathCache.set(pattern, compiled);
440
+ return compiled;
441
+ }
442
+
443
+ function execPattern(
444
+ compiled: CompiledPattern | null,
445
+ urlPath: string,
446
+ ): Record<string, string> | null {
447
+ if (!compiled) return null;
448
+ let result: MatchPatternResult | null;
449
+ try {
450
+ result = compiled.exec({ pathname: urlPath });
451
+ } catch {
452
+ return null;
453
+ }
454
+ if (!result) return null;
455
+
456
+ const groups = result.pathname.groups as Record<string, string | undefined>;
457
+ const out: Record<string, string> = {};
458
+ for (const [k, v] of Object.entries(groups)) {
459
+ if (v !== undefined) out[k] = v;
460
+ }
461
+ return out;
462
+ }
463
+
464
+ /**
465
+ * Characters that are literal both in URLPattern syntax and in URL path
466
+ * canonicalization. A pattern made only of them matches exactly its own
467
+ * spelling, and an input made only of them is already canonical — so for that
468
+ * pair a string comparison gives the same answer as `URLPattern.exec`. Anything
469
+ * else (`:param`, groups, `*`, `%`-escapes, non-ASCII, dot segments) takes the
470
+ * URLPattern path.
471
+ */
472
+ const PLAIN_PATH = /^[A-Za-z0-9\-._~/]*$/;
473
+ const DOT_SEGMENT = /(^|\/)\.{1,2}(\/|$)/;
474
+
475
+ function isPlainPath(path: string): boolean {
476
+ return PLAIN_PATH.test(path) && !DOT_SEGMENT.test(path);
477
+ }
478
+
479
+ function assertURLPattern() {
480
+ if (typeof URLPattern === "undefined") {
481
+ throw new Error(
482
+ "@decocms/blocks: this runtime has no URLPattern Web API, so CMS page " +
483
+ "paths cannot be matched. URLPattern is native in browsers, " +
484
+ "Cloudflare workerd, Deno, and Node.js >= 24 — you are most likely " +
485
+ "running Node <= 22. Upgrade the runtime to Node 24+ (see this " +
486
+ 'package\'s "engines" field).',
487
+ );
488
+ }
489
+ }
490
+
221
491
  /**
222
492
  * Match a CMS page path pattern against a URL path.
223
493
  *
@@ -238,30 +508,12 @@ declare const URLPattern: {
238
508
  * `URLPattern` is native in browsers, workerd, Deno, and Node >= 24 (this
239
509
  * package's `engines` floor). Node 22 and older lack it.
240
510
  */
241
- export function matchPath(pattern: string, urlPath: string): Record<string, string> | null {
242
- if (typeof URLPattern === "undefined") {
243
- throw new Error(
244
- "@decocms/blocks: this runtime has no URLPattern Web API, so CMS page " +
245
- "paths cannot be matched. URLPattern is native in browsers, " +
246
- "Cloudflare workerd, Deno, and Node.js >= 24 — you are most likely " +
247
- "running Node <= 22. Upgrade the runtime to Node 24+ (see this " +
248
- 'package\'s "engines" field).',
249
- );
250
- }
251
- let result: MatchPatternResult | null;
252
- try {
253
- result = new URLPattern({ pathname: pattern }).exec({ pathname: urlPath });
254
- } catch {
255
- return null;
256
- }
257
- if (!result) return null;
258
-
259
- const groups = result.pathname.groups as Record<string, string | undefined>;
260
- const out: Record<string, string> = {};
261
- for (const [k, v] of Object.entries(groups)) {
262
- if (v !== undefined) out[k] = v;
263
- }
264
- return out;
511
+ export function matchPath(
512
+ pattern: string,
513
+ urlPath: string,
514
+ ): Record<string, string> | null {
515
+ assertURLPattern();
516
+ return execPattern(cachedPattern(pattern), urlPath);
265
517
  }
266
518
 
267
519
  /**
@@ -282,7 +534,7 @@ export function getSiteSeo(): {
282
534
  noIndexing?: boolean;
283
535
  } {
284
536
  const blocks = loadBlocks();
285
- const site = blocks["Site"] as Record<string, unknown> | undefined;
537
+ const site = (blocks["Site"] ?? blocks["site"]) as Record<string, unknown> | undefined;
286
538
  if (!site) return {};
287
539
  const seo = site.seo as Record<string, unknown> | undefined;
288
540
  if (!seo) return {};
@@ -292,11 +544,18 @@ export function getSiteSeo(): {
292
544
  export function findPageByPath(
293
545
  targetPath: string,
294
546
  ): { page: DecoPage; params: Record<string, string>; blockKey: string } | null {
295
- const allPages = getAllPages();
547
+ // Same loud failure as matchPath, even when every page is literal.
548
+ assertURLPattern();
549
+ const plainTarget = isPlainPath(targetPath);
296
550
 
297
- for (const { key, page } of allPages) {
298
- if (!page.path) continue;
299
- const params = matchPath(page.path, targetPath);
551
+ for (const entry of getPageIndex()) {
552
+ const { key, page, path, literal } = entry;
553
+ if (literal && plainTarget) {
554
+ if (path === targetPath) return { page, params: {}, blockKey: key };
555
+ continue;
556
+ }
557
+ if (entry.matcher === undefined) entry.matcher = compilePattern(path);
558
+ const params = execPattern(entry.matcher, targetPath);
300
559
  if (params !== null) return { page, params, blockKey: key };
301
560
  }
302
561
 
@@ -1,4 +1,5 @@
1
1
  import type { ComponentType } from "react";
2
+ import type { RenderJson } from "./renderJson";
2
3
 
3
4
  export type OnBeforeResolveProps = (props: Record<string, unknown>) => Record<string, unknown>;
4
5
 
@@ -8,6 +9,8 @@ export type SectionModule = {
8
9
  onBeforeResolveProps?: OnBeforeResolveProps;
9
10
  LoadingFallback?: ComponentType<any>;
10
11
  ErrorFallback?: ComponentType<{ error: Error }>;
12
+ /** How this section renders to JSON for the mobile app (?renderJson). */
13
+ renderJson?: RenderJson;
11
14
  };
12
15
 
13
16
  type RegistryEntry = () => Promise<SectionModule>;
@@ -17,6 +20,12 @@ export interface SectionOptions {
17
20
  loadingFallback?: ComponentType<any>;
18
21
  /** Custom error fallback component for this section. */
19
22
  errorFallback?: ComponentType<{ error: Error }>;
23
+ /**
24
+ * The section's `renderJson` export (?renderJson mobile path): `false` drops
25
+ * the section from the JSON, a function projects its props. Populated by the
26
+ * generated section conventions and, as a fallback, on module preload.
27
+ */
28
+ renderJson?: RenderJson;
20
29
  /**
21
30
  * When true, the section is wrapped in `<ClientOnly>` from TanStack Router.
22
31
  * It renders only on the client — no SSR, no hydration mismatch.
@@ -72,6 +81,15 @@ export function registerSections(
72
81
  }
73
82
  }
74
83
 
84
+ /**
85
+ * Set a section's `renderJson` option (?renderJson mobile path) without touching
86
+ * its loader/component registration. Called from the generated section
87
+ * conventions for `export const renderJson = false | (props) => ...`.
88
+ */
89
+ export function setSectionRenderJson(key: string, renderJson: RenderJson): void {
90
+ sectionOptions[key] = { ...sectionOptions[key], renderJson };
91
+ }
92
+
75
93
  export function getSection(resolveType: string): RegistryEntry | undefined {
76
94
  return registry[resolveType];
77
95
  }
@@ -99,6 +117,7 @@ export async function preloadSectionModule(
99
117
  const opts: SectionOptions = { ...existing };
100
118
  if (mod.LoadingFallback) opts.loadingFallback = mod.LoadingFallback;
101
119
  if (mod.ErrorFallback) opts.errorFallback = mod.ErrorFallback;
120
+ if (mod.renderJson !== undefined) opts.renderJson = mod.renderJson;
102
121
  sectionOptions[resolveType] = opts;
103
122
  return opts;
104
123
  } catch (e) {
@@ -146,6 +165,7 @@ export async function preloadSectionComponents(keys: string[]): Promise<void> {
146
165
  const opts: SectionOptions = { ...sectionOptions[key] };
147
166
  if (mod.LoadingFallback) opts.loadingFallback = mod.LoadingFallback;
148
167
  if (mod.ErrorFallback) opts.errorFallback = mod.ErrorFallback;
168
+ if (mod.renderJson !== undefined) opts.renderJson = mod.renderJson;
149
169
  sectionOptions[key] = opts;
150
170
  } catch (e) {
151
171
  console.warn(`[Registry] Failed to preload component "${key}":`, e);
@@ -167,6 +187,7 @@ export type SyncSectionEntry =
167
187
  default: ComponentType<any>;
168
188
  LoadingFallback?: ComponentType<any>;
169
189
  ErrorFallback?: ComponentType<{ error: Error }>;
190
+ renderJson?: RenderJson;
170
191
  };
171
192
 
172
193
  /**
@@ -205,6 +226,7 @@ export function registerSectionsSync(sections: Record<string, SyncSectionEntry>)
205
226
  const opts: SectionOptions = { ...sectionOptions[key] };
206
227
  if (entry.LoadingFallback) opts.loadingFallback = entry.LoadingFallback;
207
228
  if (entry.ErrorFallback) opts.errorFallback = entry.ErrorFallback;
229
+ if (entry.renderJson !== undefined) opts.renderJson = entry.renderJson;
208
230
  sectionOptions[key] = opts;
209
231
  }
210
232
  }