@contentstack/studio-client 3.1.0 → 4.0.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 (107) hide show
  1. package/README.md +21 -0
  2. package/dist/breakpoints/BreakpointManager.js +7 -5
  3. package/dist/breakpoints/BreakpointManager.js.map +1 -1
  4. package/dist/breakpoints/breakpoint.js +3 -2
  5. package/dist/breakpoints/breakpoint.js.map +1 -1
  6. package/dist/canvas/canvas.utils.js +13 -1
  7. package/dist/canvas/canvas.utils.js.map +1 -1
  8. package/dist/composable-studio/build-scoped-data.js +53 -31
  9. package/dist/composable-studio/build-scoped-data.js.map +1 -1
  10. package/dist/composable-studio/collect-data-needs.js +22 -4
  11. package/dist/composable-studio/collect-data-needs.js.map +1 -1
  12. package/dist/composable-studio/sdk.js +1288 -453
  13. package/dist/composable-studio/sdk.js.map +1 -1
  14. package/dist/composable-studio/section-data.js +316 -0
  15. package/dist/composable-studio/section-data.js.map +1 -0
  16. package/dist/composable-studio/studio-intelligence.manager.js +5 -2
  17. package/dist/composable-studio/studio-intelligence.manager.js.map +1 -1
  18. package/dist/config/config.schema.js +45 -8
  19. package/dist/config/config.schema.js.map +1 -1
  20. package/dist/config/default-config.js +10 -3
  21. package/dist/config/default-config.js.map +1 -1
  22. package/dist/config/process-user-config.js +37 -1
  23. package/dist/config/process-user-config.js.map +1 -1
  24. package/dist/config/stack-sdk-wrapper.js +71 -2
  25. package/dist/config/stack-sdk-wrapper.js.map +1 -1
  26. package/dist/context-menu/context-menu.js +5 -2
  27. package/dist/context-menu/context-menu.js.map +1 -1
  28. package/dist/design/handle-active-style-change.js +3 -2
  29. package/dist/design/handle-active-style-change.js.map +1 -1
  30. package/dist/dnd/dnd-event.js +2 -1
  31. package/dist/dnd/dnd-event.js.map +1 -1
  32. package/dist/dnd/dnd-manager.js +3 -1
  33. package/dist/dnd/dnd-manager.js.map +1 -1
  34. package/dist/editor.d.ts +250 -0
  35. package/dist/editor.js +11 -0
  36. package/dist/editor.js.map +1 -0
  37. package/dist/get-active-node-screenshot/get-node-screenshot-event.js +2 -1
  38. package/dist/get-active-node-screenshot/get-node-screenshot-event.js.map +1 -1
  39. package/dist/hidden-element-notification/hidden-element-notification-event.js +2 -1
  40. package/dist/hidden-element-notification/hidden-element-notification-event.js.map +1 -1
  41. package/dist/highlight-node/highlight-node-manager.js +225 -15
  42. package/dist/highlight-node/highlight-node-manager.js.map +1 -1
  43. package/dist/highlight-node/highlight-node.js +42 -6
  44. package/dist/highlight-node/highlight-node.js.map +1 -1
  45. package/dist/highlight-spacing/highlight-spacing-events.js +2 -1
  46. package/dist/highlight-spacing/highlight-spacing-events.js.map +1 -1
  47. package/dist/index.d.ts +1334 -467
  48. package/dist/index.js +14 -14
  49. package/dist/index.js.map +1 -1
  50. package/dist/url-change/url-change.js +4 -3
  51. package/dist/url-change/url-change.js.map +1 -1
  52. package/dist/url-metadata/build-template-query.js +27 -6
  53. package/dist/url-metadata/build-template-query.js.map +1 -1
  54. package/dist/utils/canvas.js +2 -1
  55. package/dist/utils/canvas.js.map +1 -1
  56. package/dist/utils/check-bindings.js +233 -0
  57. package/dist/utils/check-bindings.js.map +1 -0
  58. package/dist/utils/classify-response-error.js +288 -0
  59. package/dist/utils/classify-response-error.js.map +1 -0
  60. package/dist/utils/composable-studio-error.js +36 -20
  61. package/dist/utils/composable-studio-error.js.map +1 -1
  62. package/dist/utils/composition-not-found.js +52 -0
  63. package/dist/utils/composition-not-found.js.map +1 -0
  64. package/dist/utils/conditionBlock.js +80 -3
  65. package/dist/utils/conditionBlock.js.map +1 -1
  66. package/dist/utils/constants.js +21 -2
  67. package/dist/utils/constants.js.map +1 -1
  68. package/dist/utils/degraded-finding.js +166 -0
  69. package/dist/utils/degraded-finding.js.map +1 -0
  70. package/dist/utils/editor-mode.js +1 -1
  71. package/dist/utils/http-error.constants.js +12 -46
  72. package/dist/utils/http-error.constants.js.map +1 -1
  73. package/dist/utils/include-path-rules.js +141 -0
  74. package/dist/utils/include-path-rules.js.map +1 -0
  75. package/dist/utils/is-composition-being-edited.js +1 -1
  76. package/dist/utils/is-inside-iframe.js +1 -1
  77. package/dist/utils/is-inside-visual-builder-frame.js +1 -1
  78. package/dist/utils/parse-ui.js +60 -0
  79. package/dist/utils/parse-ui.js.map +1 -0
  80. package/dist/utils/query-param.js +1 -1
  81. package/dist/utils/query-param.js.map +1 -1
  82. package/dist/utils/query-url-budget.js +79 -0
  83. package/dist/utils/query-url-budget.js.map +1 -0
  84. package/dist/utils/reference-stub.js +75 -0
  85. package/dist/utils/reference-stub.js.map +1 -0
  86. package/dist/utils/reference_fetcher.js +59 -4
  87. package/dist/utils/reference_fetcher.js.map +1 -1
  88. package/dist/utils/require-stack.js +141 -0
  89. package/dist/utils/require-stack.js.map +1 -0
  90. package/dist/utils/served-by.js +33 -0
  91. package/dist/utils/served-by.js.map +1 -0
  92. package/dist/utils/spec-analyzer.js +2 -2
  93. package/dist/utils/spec-analyzer.js.map +1 -1
  94. package/dist/utils/studio-error-codes.js +253 -0
  95. package/dist/utils/studio-error-codes.js.map +1 -0
  96. package/dist/utils/studio-error.js +122 -0
  97. package/dist/utils/studio-error.js.map +1 -0
  98. package/dist/utils/studio-messaging.js +25 -0
  99. package/dist/utils/studio-messaging.js.map +1 -0
  100. package/dist/visual-builder/composition-save-event.js +2 -1
  101. package/dist/visual-builder/composition-save-event.js.map +1 -1
  102. package/package.json +19 -7
  103. package/LICENSE +0 -21
  104. package/dist/utils/error-messages.default.js +0 -141
  105. package/dist/utils/error-messages.default.js.map +0 -1
  106. package/dist/utils/error-messages.js +0 -47
  107. package/dist/utils/error-messages.js.map +0 -1
package/dist/index.d.ts CHANGED
@@ -3,14 +3,16 @@ import { Node, BindingType, PathNode, Operation, Descendant, Path, Condition, No
3
3
  import * as _contentstack_studio_registry from '@contentstack/studio-registry';
4
4
  import { StudioStateConfig, RawStaticValue, ICSEntryReference, StudioSpecData, DataSources, SectionScopedDataSources, StaticValue, BreakpointInput, Breakpoint } from '@contentstack/studio-registry';
5
5
  export { Breakpoint } from '@contentstack/studio-registry';
6
+ import { ComposableStudioQueryParams, ComposableStudioQueryParamsKeys } from '@contentstack/studio-messenger/types';
6
7
  import * as _contentstack_studio_messenger from '@contentstack/studio-messenger';
7
- import { CompositionQuery, CompositionQueryInput, ComposableStudioQueryParams, ComposableStudioQueryParamsKeys, HiddenElementNotificationEventData } from '@contentstack/studio-messenger';
8
+ import { CompositionQuery, CompositionQueryInput, HiddenElementNotificationEventData } from '@contentstack/studio-messenger';
8
9
  export { IS_BROWSER } from '@contentstack/studio-messenger';
9
10
  import { z } from 'zod';
10
11
  import deliverySdk, { BaseAsset } from '@contentstack/delivery-sdk';
11
12
  import { Stack } from 'contentstack';
12
13
  import { HitboxDetails, SerializedEvent, RefetchSpecEventData } from '@contentstack/studio-message-types/latest';
13
- export { ActiveBreakpointEventPayload, BaseHighlightEventPayload, ChangeActiveStyleGroupPayload, ComputedStyleSection, DraggerPosition, HighlightActiveNodeEventPayload, HighlightAncestorsEventPayload, HighlightFocusedNodeEventPayload, HighlightNodeEventPayload, HighlightSlotNodeEventPayload, HighlightStyleNodeEventPayload, HitboxDetails, MouseMoveEventPayload, MouseUpEventPayload, RefetchSpecEventData, RequestHighlightNodeEventPayload, SetCursorTypeEventPayload, TARGET_NODE, UpdateStyleEventPayload, ValidatePropEventPayload, handleActiveNodePayload, handleActiveSlotNode, handleFocusedNodePayload } from '@contentstack/studio-message-types/latest';
14
+ export { ActiveBreakpointEventPayload, BaseHighlightEventPayload, ChangeActiveStyleGroupPayload, ComputedStyleSection, DraggerPosition, HighlightActiveNodeEventPayload, HighlightAncestorsEventPayload, HighlightFocusedNodeEventPayload, HighlightNodeEventPayload, HighlightSlotNodeEventPayload, HighlightStyleNodeEventPayload, HitboxDetails, MouseMoveEventPayload, MouseUpEventPayload, RefetchSpecEventData, RequestHighlightNodeEventPayload, RevealMissKind, RevealNodePayload, RevealResultPayload, SetCursorTypeEventPayload, TARGET_NODE, UpdateStyleEventPayload, ValidatePropEventPayload, handleActiveNodePayload, handleActiveSlotNode, handleFocusedNodePayload } from '@contentstack/studio-message-types/latest';
15
+ import { POST_MESSAGE_EVENTS } from '@contentstack/studio-messenger/constants';
14
16
  import { EventEmitter } from 'eventemitter3';
15
17
  import { IJsonToHtmlOptions } from '@contentstack/json-rte-serializer';
16
18
 
@@ -29,8 +31,28 @@ declare const userConfigSchema: z.ZodObject<{
29
31
  * Visual type to be used for storing the UI
30
32
  */
31
33
  contentTypeUid: z.ZodOptional<z.ZodString>;
34
+ /**
35
+ * Accepted as given. Whether a stack is usable is settled by the preflight,
36
+ * not here: a missing or malformed stack is recorded at setup and raised at
37
+ * the first call that needs it, so validating it here would throw at setup
38
+ * for a page that may never fetch a composition.
39
+ *
40
+ * The check this replaces applied `in` to the value, which throws a
41
+ * `TypeError` rather than failing validation when nothing was passed.
42
+ */
32
43
  stackSdk: z.ZodType<any, z.ZodTypeDef, any>;
33
44
  locale: z.ZodOptional<z.ZodString>;
45
+ /**
46
+ * Turns on reporting for the failures that do not stop the page — a binding
47
+ * that reads a field which is not there, a query that matched nothing, a
48
+ * reference that came back as a stub.
49
+ *
50
+ * Off by default, and that default is deliberate: those findings are reported
51
+ * in development already, and a customer's production console belongs to
52
+ * them. Switching this on is how a developer diagnoses a deployed site, which
53
+ * has no Studio chrome on it and no other way to say what went wrong.
54
+ */
55
+ debug: z.ZodOptional<z.ZodBoolean>;
34
56
  cslp: z.ZodOptional<z.ZodObject<{
35
57
  appendTags: z.ZodOptional<z.ZodBoolean>;
36
58
  }, "strip", z.ZodTypeAny, {
@@ -48,6 +70,30 @@ declare const userConfigSchema: z.ZodObject<{
48
70
  enable?: boolean | undefined;
49
71
  position?: "top" | "top-left" | "top-right" | "top-center" | "bottom" | "bottom-left" | "bottom-right" | "bottom-center" | undefined;
50
72
  }>>;
73
+ /**
74
+ * Whether this SDK works out `include[]` paths of its own, on top of the set
75
+ * the composition already carries in `data_sources[*].resolvedReferences`.
76
+ *
77
+ * Studio recomputes that set on every save and, having the content type
78
+ * schemas, keeps only paths that end at a reference (ADR 0018). This SDK has
79
+ * no schema, so what it derives cannot be filtered: measured on one page it
80
+ * added 23 paths of which 22 addressed nothing. The Delivery API refuses a
81
+ * request carrying more than 100 include[] paths, so those are not free.
82
+ *
83
+ * Leave it unset and the SDK decides per composition, from the
84
+ * `schema_version` the entry was saved with: derive for anything older than
85
+ * the point the persisted set became authoritative, skip it for anything at or
86
+ * beyond. That matters because a composition saved before the save-time derive
87
+ * existed holds only the author's ticks, and switching derivation off there
88
+ * would leave every bound-but-un-ticked reference unfetched.
89
+ *
90
+ * Set it explicitly to override that judgement in either direction.
91
+ *
92
+ * What the SDK does regardless is COMPOSE: a section's paths are stored
93
+ * relative to its own scope and only the host knows where the section sits, so
94
+ * prefixing them is the one job that cannot move.
95
+ */
96
+ deriveIncludePaths: z.ZodOptional<z.ZodBoolean>;
51
97
  fetchComposition: z.ZodOptional<z.ZodType<CompositionFetcher, z.ZodTypeDef, CompositionFetcher>>;
52
98
  fetchTemplateEntry: z.ZodOptional<z.ZodType<TemplateEntryFetcher, z.ZodTypeDef, TemplateEntryFetcher>>;
53
99
  /**
@@ -62,6 +108,7 @@ declare const userConfigSchema: z.ZodObject<{
62
108
  locale?: string | undefined;
63
109
  contentTypeUid?: string | undefined;
64
110
  stackSdk?: any;
111
+ debug?: boolean | undefined;
65
112
  cslp?: {
66
113
  appendTags?: boolean | undefined;
67
114
  } | undefined;
@@ -69,6 +116,7 @@ declare const userConfigSchema: z.ZodObject<{
69
116
  enable?: boolean | undefined;
70
117
  position?: "top" | "top-left" | "top-right" | "top-center" | "bottom" | "bottom-left" | "bottom-right" | "bottom-center" | undefined;
71
118
  } | undefined;
119
+ deriveIncludePaths?: boolean | undefined;
72
120
  fetchComposition?: CompositionFetcher | undefined;
73
121
  fetchTemplateEntry?: TemplateEntryFetcher | undefined;
74
122
  state?: StudioStateConfig | undefined;
@@ -76,6 +124,7 @@ declare const userConfigSchema: z.ZodObject<{
76
124
  locale?: string | undefined;
77
125
  contentTypeUid?: string | undefined;
78
126
  stackSdk?: any;
127
+ debug?: boolean | undefined;
79
128
  cslp?: {
80
129
  appendTags?: boolean | undefined;
81
130
  } | undefined;
@@ -83,6 +132,7 @@ declare const userConfigSchema: z.ZodObject<{
83
132
  enable?: boolean | undefined;
84
133
  position?: "top" | "top-left" | "top-right" | "top-center" | "bottom" | "bottom-left" | "bottom-right" | "bottom-center" | undefined;
85
134
  } | undefined;
135
+ deriveIncludePaths?: boolean | undefined;
86
136
  fetchComposition?: CompositionFetcher | undefined;
87
137
  fetchTemplateEntry?: TemplateEntryFetcher | undefined;
88
138
  state?: StudioStateConfig | undefined;
@@ -115,10 +165,27 @@ declare class StackSDK {
115
165
  private isJsQuery;
116
166
  where(query: ReturnType<StackSDK["ctQuery"]>, field: string, value: any): any;
117
167
  get apiKey(): string;
168
+ get deliveryToken(): string | undefined;
169
+ get environment(): string | undefined;
170
+ /**
171
+ * The host the stack will actually call. Always populated on both SDKs — the
172
+ * TS factory overwrites `config.host` with the region's resolved default, and
173
+ * the JS SDK's own defaults carry one. There is deliberately no
174
+ * `hostWasExplicit` companion: by the time a constructed stack reaches us the
175
+ * customer's original value is gone, and recovering it would mean comparing
176
+ * against a table of Contentstack hostnames, which breaks on dev and staging
177
+ * stacks and on custom CDNs.
178
+ */
179
+ get host(): string | undefined;
118
180
  get livePreviewConfig(): {
119
181
  host?: string;
120
182
  preview_token?: string;
121
183
  enable?: boolean;
184
+ /**
185
+ * The hash from the address. The runtime object carries it under this
186
+ * name and the transport routes on it; it was previously undeclared.
187
+ */
188
+ live_preview?: string;
122
189
  } | undefined;
123
190
  get locale(): string | undefined;
124
191
  /**
@@ -133,9 +200,17 @@ declare class StackSDK {
133
200
  applyTaxonomyFilters(query: any, taxonomyConstraints: Record<string, string>): any;
134
201
  }
135
202
 
136
- interface Config extends DeepRequired<Omit<UserConfig, "stackSdk" | "locale" | "fetchComposition" | "fetchTemplateEntry" | "state">> {
137
- stackSdk: StackSDK;
203
+ interface Config extends DeepRequired<Omit<UserConfig, "stackSdk" | "locale" | "fetchComposition" | "fetchTemplateEntry" | "state" | "deriveIncludePaths">> {
204
+ /** Absent when nothing usable was supplied; the guards test for it. */
205
+ stackSdk?: StackSDK;
138
206
  locale?: string;
207
+ /**
208
+ * Whether the caller passed `contentTypeUid` themselves. `contentTypeUid` is
209
+ * always populated, so the value alone cannot tell a chosen uid from the
210
+ * default — and a developer who set nothing needs a different leading cause
211
+ * from one who set the wrong thing.
212
+ */
213
+ contentTypeUidWasSupplied: boolean;
139
214
  /**
140
215
  * Variant alias the SDK should use for all data fetches. Not part of the
141
216
  * public `UserConfig` — set by Studio (when running inside a Studio iframe)
@@ -145,6 +220,12 @@ interface Config extends DeepRequired<Omit<UserConfig, "stackSdk" | "locale" | "
145
220
  variantAlias?: string;
146
221
  fetchComposition?: CompositionFetcher;
147
222
  fetchTemplateEntry?: TemplateEntryFetcher;
223
+ /**
224
+ * Override for whether the SDK derives include[] paths of its own. Left
225
+ * undefined it is decided per composition from its `schema_version`, which is
226
+ * why it stays out of `DeepRequired` — "unset" is a meaningful third state.
227
+ */
228
+ deriveIncludePaths?: boolean;
148
229
  /**
149
230
  * Bring-Your-Own-State config, passed through as-is (kept out of
150
231
  * DeepRequired so `subscribe` / `variables` stay optional).
@@ -154,6 +235,623 @@ interface Config extends DeepRequired<Omit<UserConfig, "stackSdk" | "locale" | "
154
235
  type LightConfig = Pick<Config, "openInStudioButton" | "contentTypeUid" | "cslp">;
155
236
  type UserConfig = z.infer<typeof userConfigSchema>;
156
237
 
238
+ /**
239
+ * The documented error codes, and the class each one belongs to.
240
+ *
241
+ * A code names one diagnosable case and is the only identifier on an error. It
242
+ * is printed in the log line, quoted in support conversations and sent to
243
+ * Studio, so it is stable across releases once published.
244
+ *
245
+ * The class is looked up from {@link ERROR_CLASS} rather than carried on the
246
+ * error, because a second identifier that nothing branches on is a second thing
247
+ * to keep in step.
248
+ *
249
+ * Codes land here as the cases behind them are built, not up front — a code
250
+ * with no throw site is a promise, not a contract.
251
+ */
252
+ declare const StudioErrorCode: {
253
+ /** The stack has no content type with the uid Studio queried. */
254
+ readonly CONTENT_TYPE_NOT_FOUND: "CONTENT_TYPE_NOT_FOUND";
255
+ /** No stack on this host answers to the API key the request carried. */
256
+ readonly STACK_NOT_FOUND_ON_HOST: "STACK_NOT_FOUND_ON_HOST";
257
+ /** The stack has no environment by the name the connection uses. */
258
+ readonly ENVIRONMENT_NOT_FOUND: "ENVIRONMENT_NOT_FOUND";
259
+ /** The stack has no language by the code the SDK was configured with. */
260
+ readonly LOCALE_NOT_CONFIGURED: "LOCALE_NOT_CONFIGURED";
261
+ /** The address asked for a language the stack does not have. */
262
+ readonly URL_LOCALE_NOT_FOUND: "URL_LOCALE_NOT_FOUND";
263
+ /**
264
+ * Studio was given no Contentstack stack to query, or given something that is
265
+ * not one. Raised by the first call that needs the stack, never at setup: a
266
+ * site that wires Studio into a layout and renders no composition on this
267
+ * route is legitimate.
268
+ */
269
+ readonly STACK_SDK_MISSING: "STACK_SDK_MISSING";
270
+ /**
271
+ * A stack arrived, and the api key inside it is empty.
272
+ *
273
+ * Only reachable on a JavaScript-SDK stack — the TypeScript delivery factory
274
+ * refuses to construct one without an api key, in the caller's own code. Its
275
+ * response-driven sibling is `STACK_NOT_FOUND_ON_HOST`, which is what an empty
276
+ * key used to be reported as once the request came back 412.
277
+ */
278
+ readonly API_KEY_MISSING: "API_KEY_MISSING";
279
+ /**
280
+ * A stack arrived, and the delivery token inside it is empty.
281
+ *
282
+ * JavaScript-SDK stacks only, as above. No response can report this one: the
283
+ * delivery client's retry policy consumes the 401 into an unknown error before
284
+ * anything here sees it, so the preflight is the only place it can be found.
285
+ */
286
+ readonly DELIVERY_TOKEN_MISSING: "DELIVERY_TOKEN_MISSING";
287
+ /**
288
+ * A stack arrived, and the environment inside it is empty.
289
+ *
290
+ * JavaScript-SDK stacks only, as above. The value reads as optional and is
291
+ * not — Studio queries published content per environment — which is why the
292
+ * message says so rather than only naming the gap.
293
+ */
294
+ readonly ENVIRONMENT_MISSING: "ENVIRONMENT_MISSING";
295
+ /**
296
+ * The configured Contentstack address cannot be used as written: it does not
297
+ * parse as an address, or it is `http:` on a page the browser serves over
298
+ * `https:` and will block as mixed content.
299
+ *
300
+ * States only that the value cannot work, never what it should have been. We
301
+ * have no way to know the right host, and any test for a Contentstack-shaped
302
+ * hostname breaks on dev and staging stacks and on customers' own CDNs.
303
+ */
304
+ readonly HOST_UNUSABLE: "HOST_UNUSABLE";
305
+ /**
306
+ * The call carried none of `compositionUid`, `url` or `templateContentTypeUid`,
307
+ * so there was nothing to look for.
308
+ *
309
+ * Never a not-found: the composition may well exist, the request just never
310
+ * asked for one. The fault is in the call rather than the configuration, which
311
+ * `findings.lookedIn` says so a developer does not audit a correct config file.
312
+ */
313
+ readonly COMPOSITION_IDENTIFIER_MISSING: "COMPOSITION_IDENTIFIER_MISSING";
314
+ /**
315
+ * A composition was requested before `init()` finished, and it had still not
316
+ * finished when the wait ran out.
317
+ *
318
+ * The wait is long on purpose (~30s). A shorter one fires on inits that were
319
+ * going to succeed — a cold serverless start, a slow server render — and
320
+ * reporting a working site as broken is worse than reporting a broken one late.
321
+ */
322
+ readonly INIT_NOT_COMPLETE: "INIT_NOT_COMPLETE";
323
+ /**
324
+ * The candidate scan hit its safety cap without finding a match, so we stopped
325
+ * looking rather than established that nothing matched.
326
+ *
327
+ * Never a not-found, and the distinction is the whole point: a 404 is acted on
328
+ * by crawlers, caches and link checkers, and a project that has simply grown
329
+ * past the cap would start de-indexing pages that exist. Nothing in the
330
+ * customer's project causes this and nothing there can fix it.
331
+ */
332
+ readonly SEARCH_INCOMPLETE: "SEARCH_INCOMPLETE";
333
+ /**
334
+ * Every ownership check on a tied address failed, so no candidate could be
335
+ * shown to own it — and none could be shown not to either.
336
+ *
337
+ * A single failed probe is survivable: another candidate may still answer. All
338
+ * of them failing is a delivery outage, and calling that "nothing owns this
339
+ * address" 404s a page that exists and is published.
340
+ */
341
+ readonly URL_OWNERSHIP_PROBE_FAILED: "URL_OWNERSHIP_PROBE_FAILED";
342
+ /**
343
+ * Something answered, and what came back is not a delivery response — a
344
+ * proxy's error page, a gateway's JSON, a body truncated in transit.
345
+ *
346
+ * Never a not-found, and the damage of getting it wrong is the widest of any
347
+ * case here: the entries list is simply absent, which reads as "no
348
+ * compositions", which would 404 every page on the site at once for as long as
349
+ * whatever is in the way keeps answering.
350
+ */
351
+ readonly RESPONSE_UNUSABLE: "RESPONSE_UNUSABLE";
352
+ /**
353
+ * A composition or section was found, and its stored layout will not open.
354
+ *
355
+ * Not a missing page: the composition is there and is damaged. And never
356
+ * version skew — a spec written by a newer Studio inflates and parses fine and
357
+ * fails later as an unknown component type, so offering that here sends the
358
+ * reader to upgrade something that was never in the way.
359
+ */
360
+ readonly SPEC_UNREADABLE: "SPEC_UNREADABLE";
361
+ /**
362
+ * A complete scan over a usable response found no composition set up for the
363
+ * address. The page is genuinely not there.
364
+ */
365
+ readonly NO_COMPOSITION_FOR_URL: "NO_COMPOSITION_FOR_URL";
366
+ /**
367
+ * Compositions are set up for the address, every one of them was asked for an
368
+ * entry, and none has one.
369
+ *
370
+ * Distinct from nothing being set up, because the fixes are opposite: this
371
+ * reader's routing is right and their content is missing, so sending them to
372
+ * check the URL sends them to audit something already correct.
373
+ */
374
+ readonly URL_MATCHED_NO_ENTRY: "URL_MATCHED_NO_ENTRY";
375
+ /**
376
+ * A composition uid was asked for, the query answered, and nothing in the
377
+ * project has it.
378
+ *
379
+ * The wording stops at that. Whether the composition exists at all is not
380
+ * knowable from one query — it may be published to another environment,
381
+ * mistyped, or on a different stack — and the sentence this replaces asserted
382
+ * "does not exist or has been deleted" in every one of those cases.
383
+ */
384
+ readonly COMPOSITION_UID_NOT_FOUND: "COMPOSITION_UID_NOT_FOUND";
385
+ /**
386
+ * A composition names a connected content type, the entry for it was asked
387
+ * for, and there is none.
388
+ *
389
+ * Renamed from an id that said "preview", which it never had anything to do
390
+ * with — it fires identically on published content, and the name sent people
391
+ * to check a preview setup that was not involved.
392
+ */
393
+ readonly CONNECTED_ENTRY_NOT_FOUND: "CONNECTED_ENTRY_NOT_FOUND";
394
+ /**
395
+ * A component the stored layout uses was never registered, so there is
396
+ * nothing to render it with.
397
+ *
398
+ * Setup rather than content: the composition is fine and the application did
399
+ * not tell the SDK about a component it refers to. Built-in components
400
+ * register on first import of the React package, so the usual cause is that
401
+ * the package root was never imported.
402
+ */
403
+ readonly COMPONENT_NOT_REGISTERED: "COMPONENT_NOT_REGISTERED";
404
+ /**
405
+ * The request went out and nothing came back — no response, no status.
406
+ *
407
+ * Never a not-found: a page that cannot be reached is not a page that does
408
+ * not exist, and 404ing it would have crawlers and caches de-index a working
409
+ * site over a bad minute.
410
+ */
411
+ readonly TRANSPORT_FAILED: "TRANSPORT_FAILED";
412
+ /**
413
+ * Something answered, and the answer was not one we can act on — a 5xx, or a
414
+ * status this SDK has no reading for.
415
+ *
416
+ * The terminal case, and the one that matters most: every response no other
417
+ * check recognises ends up here. It used to end up at "composition not
418
+ * found", which is how a wrong api key, a wrong environment and a delivery
419
+ * outage all came to tell a developer their page did not exist.
420
+ */
421
+ readonly UPSTREAM_ERROR: "UPSTREAM_ERROR";
422
+ /** A content type was asked for, and no composition in the project is connected to it. */
423
+ readonly NO_COMPOSITION_FOR_TEMPLATE_CONTENT_TYPE: "NO_COMPOSITION_FOR_TEMPLATE_CONTENT_TYPE";
424
+ };
425
+ type StudioErrorCodeType = (typeof StudioErrorCode)[keyof typeof StudioErrorCode];
426
+ /**
427
+ * The five classes, each named for an observable fact about the attempt rather
428
+ * than for a situation. A host reads the class to decide an HTTP status: only
429
+ * `NOT_FOUND` is a 404, everything else is a 5xx.
430
+ */
431
+ declare const StudioErrorClass: {
432
+ /** Something the SDK needed was not available when it was needed. */
433
+ readonly SETUP_INCOMPLETE: "SETUP_INCOMPLETE";
434
+ /** Something supplied is wrong. */
435
+ readonly SETUP_INVALID: "SETUP_INVALID";
436
+ /** Sent, no response. */
437
+ readonly NETWORK_ERROR: "NETWORK_ERROR";
438
+ /** We could not establish an answer. */
439
+ readonly SERVER_ERROR: "SERVER_ERROR";
440
+ /** We established that nothing matched. */
441
+ readonly NOT_FOUND: "NOT_FOUND";
442
+ };
443
+ type StudioErrorClassType = (typeof StudioErrorClass)[keyof typeof StudioErrorClass];
444
+
445
+ /**
446
+ * What each diagnosis established, keyed by the code that established it.
447
+ *
448
+ * Distinct from `context`, and the difference is enforced by the shapes rather
449
+ * than by a convention: `context` says where the request went and is identical on
450
+ * every error, which is what makes the no-token rule checkable in one place.
451
+ * These say what one particular failure found, so they differ per code.
452
+ *
453
+ * The map is closed on purpose. A receiver narrows on the error's `code`, which
454
+ * it already has, so nothing here repeats the code as a tag. And because adding a
455
+ * field means editing this file, a token can never reach a diagnosis by accident
456
+ * at some throw site — which matters, since the whole object is built to be
457
+ * pasted somewhere public.
458
+ *
459
+ * Named `findings` rather than `details` in the code because
460
+ * `ComposableStudioError.details` is the legacy metadata bag and is still public.
461
+ * The two collapse when [the legacy ids are retired].
462
+ */
463
+ interface StudioErrorFindingsByCode {
464
+ [StudioErrorCode.CONTENT_TYPE_NOT_FOUND]: {
465
+ contentTypeUid: string;
466
+ /** Whether the site named it, which decides how the causes are ordered. */
467
+ contentTypeUidWasSupplied: boolean;
468
+ };
469
+ [StudioErrorCode.STACK_NOT_FOUND_ON_HOST]: WireFacts;
470
+ [StudioErrorCode.ENVIRONMENT_NOT_FOUND]: WireFacts & {
471
+ /** The environment the request carried, when the stack reported one. */
472
+ environment?: string;
473
+ };
474
+ [StudioErrorCode.LOCALE_NOT_CONFIGURED]: WireFacts & {
475
+ locale: string;
476
+ localeSource: "configuration";
477
+ };
478
+ [StudioErrorCode.URL_LOCALE_NOT_FOUND]: WireFacts & {
479
+ locale: string;
480
+ localeSource: "url-pattern";
481
+ /** The address whose pattern supplied the locale. */
482
+ requestedUrl?: string;
483
+ };
484
+ [StudioErrorCode.HOST_UNUSABLE]: {
485
+ /** The value as configured, so the reader can find where it came from. */
486
+ host: string;
487
+ /** What was proved about it. Never a claim about what it should have been. */
488
+ reason: "unparseable" | "blocked-as-mixed-content";
489
+ };
490
+ /** Carries only where we looked: there is no value to report when none was named. */
491
+ [StudioErrorCode.COMPOSITION_IDENTIFIER_MISSING]: {
492
+ lookedIn: LookedIn;
493
+ };
494
+ [StudioErrorCode.INIT_NOT_COMPLETE]: {
495
+ lookedIn: LookedIn;
496
+ /** How long the fetch waited before giving up, in milliseconds. */
497
+ waitedMs: number;
498
+ };
499
+ /**
500
+ * Where the value was looked for, and nothing else. Which value is missing is
501
+ * the code's job, and the value itself does not exist to report — reporting the
502
+ * api key that *was* found belongs to `context`, which carries it on every
503
+ * error alike.
504
+ */
505
+ [StudioErrorCode.API_KEY_MISSING]: {
506
+ lookedIn: LookedIn;
507
+ };
508
+ /**
509
+ * Where the token was looked for. Deliberately nothing else: this is the one
510
+ * diagnosis whose subject has no field anywhere in the contract, because a
511
+ * delivery token must never reach a block built to be pasted somewhere public.
512
+ */
513
+ [StudioErrorCode.DELIVERY_TOKEN_MISSING]: {
514
+ lookedIn: LookedIn;
515
+ };
516
+ /** Where the environment was looked for; `context.environment` is empty by definition. */
517
+ [StudioErrorCode.ENVIRONMENT_MISSING]: {
518
+ lookedIn: LookedIn;
519
+ };
520
+ /**
521
+ * What was being read and how, but never the bytes themselves — the diagnosis
522
+ * is built to be pasted somewhere public, and a stored layout is the customer's
523
+ * content.
524
+ */
525
+ [StudioErrorCode.SPEC_UNREADABLE]: {
526
+ /** The composition or section the layout belongs to, when the caller knows it. */
527
+ subject?: string;
528
+ /** Whether the value claimed to be compressed, which decides where to look first. */
529
+ wasCompressed: boolean;
530
+ /** How much there was to read. A surprising length is itself a clue. */
531
+ byteLength: number;
532
+ };
533
+ /** Which address answered unreadably. There is no body here: it may be anything. */
534
+ [StudioErrorCode.RESPONSE_UNUSABLE]: {
535
+ host?: string;
536
+ };
537
+ /** The address nothing matched, and how much of the project was looked at. */
538
+ [StudioErrorCode.NO_COMPOSITION_FOR_URL]: {
539
+ url: string;
540
+ /** How many compositions were considered. The scan completed, so this is all of them. */
541
+ consideredCount: number;
542
+ };
543
+ /**
544
+ * Which compositions were in the running and what happened to each.
545
+ *
546
+ * The trace is the diagnosis here; the causes only interpret it. It is computed
547
+ * during resolution either way, so carrying it costs nothing — and without it
548
+ * the reader is told several compositions matched without being told which.
549
+ */
550
+ [StudioErrorCode.URL_MATCHED_NO_ENTRY]: {
551
+ url: string;
552
+ considered: ConsideredComposition[];
553
+ };
554
+ /** The uid asked for, and the content type it was looked for in. */
555
+ [StudioErrorCode.COMPOSITION_UID_NOT_FOUND]: {
556
+ compositionUid: string;
557
+ contentTypeUid: string;
558
+ };
559
+ /** The content type nothing is connected to. */
560
+ [StudioErrorCode.NO_COMPOSITION_FOR_TEMPLATE_CONTENT_TYPE]: {
561
+ templateContentTypeUid: string;
562
+ };
563
+ /**
564
+ * Which address could not be settled, and how many checks were attempted. The
565
+ * count is what separates "one candidate, one failure" from an outage.
566
+ */
567
+ [StudioErrorCode.URL_OWNERSHIP_PROBE_FAILED]: {
568
+ url: string;
569
+ /** How many tied candidates were checked, every one of which failed. */
570
+ probeCount: number;
571
+ };
572
+ /**
573
+ * How far the search got before giving up, and what it was looking for. The
574
+ * count is what tells a reader this is about the size of their project rather
575
+ * than about the address they asked for.
576
+ */
577
+ [StudioErrorCode.SEARCH_INCOMPLETE]: {
578
+ /** The address being resolved when the scan ran out of room. */
579
+ url: string;
580
+ /** How many compositions were considered before the cap stopped the scan. */
581
+ consideredCount: number;
582
+ };
583
+ /** The content type whose entry was looked for, and the address it was looked for at. */
584
+ [StudioErrorCode.CONNECTED_ENTRY_NOT_FOUND]: {
585
+ contentTypeUid: string;
586
+ /** Set when the entry was asked for by id rather than found by address. */
587
+ templateEntryUid?: string;
588
+ };
589
+ /** Which component types the layout uses and the registry does not have. */
590
+ [StudioErrorCode.COMPONENT_NOT_REGISTERED]: {
591
+ componentTypes: string[];
592
+ /** Whether these are ours to register or the application's. */
593
+ areBuiltIn: boolean;
594
+ };
595
+ /**
596
+ * Which address was unreachable, and what the transport said. Never a body —
597
+ * there is no body.
598
+ */
599
+ [StudioErrorCode.TRANSPORT_FAILED]: {
600
+ host?: string;
601
+ detail?: string;
602
+ };
603
+ /** The status and error code, which is everything we established about it. */
604
+ [StudioErrorCode.UPSTREAM_ERROR]: {
605
+ status?: number;
606
+ errorCode?: unknown;
607
+ host?: string;
608
+ };
609
+ /** Where the stack was looked for. A stack that never arrived has nothing else to say. */
610
+ [StudioErrorCode.STACK_SDK_MISSING]: {
611
+ /**
612
+ * Where the value was looked for. The class covers defects outside the
613
+ * configuration object too — a call that named no composition, an import
614
+ * that never ran — so naming the place saves a developer auditing the
615
+ * wrong file.
616
+ */
617
+ lookedIn: LookedIn;
618
+ };
619
+ }
620
+ /** Where a value the SDK needed was looked for and not found. */
621
+ type LookedIn = "configuration" | "call" | "registry";
622
+ /** The response facts a host reads to decide what to render in the page's place. */
623
+ interface WireFacts {
624
+ status?: number;
625
+ errorCode?: unknown;
626
+ }
627
+ /** The findings for one code. */
628
+ type StudioErrorFindings = StudioErrorFindingsByCode[StudioErrorCodeType];
629
+ /** One candidate in a URL resolution, and what became of it. */
630
+ interface ConsideredComposition {
631
+ composable_uid: string;
632
+ /** The pattern or address it is set up for. */
633
+ url?: string;
634
+ /** Literal characters matched — how the winner is chosen between ties. */
635
+ specificity?: number;
636
+ /** The content type it reads from, when it is a linked composition. */
637
+ connected_content_type?: string;
638
+ /** Whether asking it for an entry found one, found none, or never happened. */
639
+ connectedEntryResult?: string;
640
+ }
641
+
642
+ /**
643
+ * Information about a possible cause of an error and how to fix it
644
+ */
645
+ interface TroubleshootingInfo {
646
+ /**
647
+ * Description of the possible cause of the error
648
+ */
649
+ cause: string;
650
+ /**
651
+ * Suggested fix or resolution for this cause
652
+ */
653
+ fix: string;
654
+ }
655
+ /**
656
+ * Type definition for error details that can be passed to ComposableStudioError
657
+ */
658
+ interface ComposableStudioErrorDetails {
659
+ /**
660
+ * Array of troubleshooting information with causes and fixes
661
+ */
662
+ troubleshootingInfo?: TroubleshootingInfo[];
663
+ /**
664
+ * Additional error context and metadata
665
+ */
666
+ [key: string]: any;
667
+ }
668
+ declare class ComposableStudioError extends Error {
669
+ details?: ComposableStudioErrorDetails;
670
+ /**
671
+ * The case this error is, and the identifier everything new reads: the log
672
+ * line, the docs, a support conversation, and the diagnostic Studio receives.
673
+ *
674
+ * Optional while throw sites move over one at a time. Absent means the site
675
+ * that raised it has not been diagnosed yet, not that the case is unknown.
676
+ * `id` is what those sites still carry, and it goes once they have all moved.
677
+ */
678
+ code?: StudioErrorCodeType;
679
+ /**
680
+ * What to do, ordered, most likely first. One entry means we proved the
681
+ * cause; more than one means we are ranking and the reader should work down
682
+ * the list. Set together with `code`, and never empty when set.
683
+ */
684
+ causes?: Causes;
685
+ /** Where the request went and what it was made with. Never a token. */
686
+ context?: StudioErrorContext;
687
+ /**
688
+ * What this particular failure established, typed by `code`. Separate from
689
+ * `details`, which is the legacy metadata bag: these are the facts a surface
690
+ * reads, and the shape is closed so no throw site can add a token to it.
691
+ */
692
+ findings?: StudioErrorFindings;
693
+ /**
694
+ * Which of the five classes this code belongs to, looked up rather than
695
+ * stored, so it can never disagree with `code`. A surface that does not
696
+ * recognise the code can still act on the class — it is the coarse answer
697
+ * that stays true for every code added after that surface shipped.
698
+ */
699
+ get errorClass(): StudioErrorClassType | undefined;
700
+ constructor(message: string, details?: ComposableStudioErrorDetails);
701
+ }
702
+
703
+ /** The three author-facing render contexts a host app can find itself in. */
704
+ type StudioMode = "canvas" | "preview" | "visitor";
705
+ /**
706
+ * The query param Studio always appends to canvas / template-preview iframe
707
+ * URLs. Part of the stable contract — changing its value is a breaking
708
+ * change and will be release-noted as such.
709
+ */
710
+ declare const STUDIO_CANVAS_QUERY_PARAM: "cs-composable-studio";
711
+ /**
712
+ * Class the SDK bootstrap adds to `<html>` when running inside the Studio
713
+ * canvas. Available for CSS-only gating (e.g. `html.cs-studio-canvas
714
+ * #onetrust-banner-sdk { display: none }`).
715
+ */
716
+ declare const STUDIO_MODE_HTML_CLASS = "cs-studio-canvas";
717
+ declare global {
718
+ interface Window {
719
+ __CS_STUDIO_MODE__?: StudioMode;
720
+ }
721
+ }
722
+ /**
723
+ * Detects the current Studio mode.
724
+ *
725
+ * Browser: the `window.__CS_STUDIO_MODE__` marker wins when present (it
726
+ * survives client-side navigations that strip query params); otherwise the
727
+ * URL's query params decide.
728
+ *
729
+ * Server: pass the request's search params (string or URLSearchParams) to
730
+ * get a real answer; with no arguments it safely reports `"visitor"`.
731
+ */
732
+ declare function detectStudioMode(searchQuery?: string | URLSearchParams): StudioMode;
733
+ /**
734
+ * True when the host app is rendering inside the Studio canvas (or Visual
735
+ * Builder frame) — the one check to gate cookie banners, chat widgets,
736
+ * analytics, marketing pixels, and feature-flag bootstraps behind.
737
+ *
738
+ * SSR-safe: returns false on the server unless the request's search params
739
+ * are passed explicitly.
740
+ */
741
+ declare function isStudioCanvas(searchQuery?: string | URLSearchParams): boolean;
742
+ /**
743
+ * True in any Studio-driven context (canvas OR live-preview pane). Use when
744
+ * a third-party should also stay out of preview sessions — e.g. analytics.
745
+ */
746
+ declare function isStudioEditorMode(searchQuery?: string | URLSearchParams): boolean;
747
+ /**
748
+ * Bootstrap: computes the mode from the current URL, stamps
749
+ * `window.__CS_STUDIO_MODE__`, and (for canvas mode) adds
750
+ * {@link STUDIO_MODE_HTML_CLASS} to `<html>`. Idempotent; no-op on the
751
+ * server. Invoked automatically when `@contentstack/studio-react` loads in
752
+ * the browser — call it manually only if you gate scripts that run before
753
+ * the SDK's module graph is evaluated.
754
+ */
755
+ declare function markStudioMode(): StudioMode;
756
+
757
+ /** Which Contentstack service answered a request. */
758
+ type ServedBy = "cdn" | "preview" | "unknown";
759
+
760
+ /**
761
+ * The shape every diagnosable failure is raised in, and the one place it is
762
+ * rendered and logged.
763
+ *
764
+ * Each field answers one question and no field answers two: which case this is
765
+ * (`code`), what happened (`message`), what to do (`causes`), where the request
766
+ * went (`context`), and what this particular failure established (`details`).
767
+ */
768
+
769
+ /** What might be wrong, and what to do about it. */
770
+ interface Cause {
771
+ cause: string;
772
+ fix: string;
773
+ }
774
+ /**
775
+ * At least one cause, enforced by the type rather than by a runtime check.
776
+ *
777
+ * The length of the list carries our confidence: one means we proved it, more
778
+ * than one means the reader should work down the list. Zero would mean we
779
+ * raised an error and had nothing to say about it, which is worse than not
780
+ * classifying it at all.
781
+ */
782
+ type Causes = readonly [Cause, ...Cause[]];
783
+ /**
784
+ * Where the request went and what it was made with. The same shape on every
785
+ * error, which is what makes the no-secrets rule enforceable in one place:
786
+ * there is no field here for a delivery or preview token, so no throw site can
787
+ * add one by accident. A *missing* token is a finding about one failure and
788
+ * belongs in that error's `details`.
789
+ *
790
+ * One field the catalogue describes is deliberately absent. `hostWasExplicit`
791
+ * is not derivable — both stack kinds overwrite the host with a resolved
792
+ * default during construction, so by the time a stack reaches us an explicit
793
+ * host cannot be told from a defaulted one.
794
+ */
795
+ interface StudioErrorContext {
796
+ mode: StudioMode;
797
+ apiKey?: string;
798
+ environment?: string;
799
+ locale?: string;
800
+ host?: string;
801
+ /**
802
+ * Absent when there was no stack to read it from. A surface states only what
803
+ * the payload supports, and `false` here would be a claim about a
804
+ * configuration we were never given.
805
+ */
806
+ livePreviewEnabled?: boolean;
807
+ /**
808
+ * Which service answered. Captured before the request rather than read back
809
+ * afterwards, and `"unknown"` when the application fetched for itself.
810
+ */
811
+ servedBy: ServedBy;
812
+ sdkVersion: string;
813
+ }
814
+ interface StudioErrorInput<C extends StudioErrorCodeType = StudioErrorCodeType> {
815
+ code: C;
816
+ /** One sentence stating what happened. The causes are appended by the renderer. */
817
+ headline: string;
818
+ causes: Causes;
819
+ context: StudioErrorContext;
820
+ /**
821
+ * What this specific failure established, narrowed to the shape this code
822
+ * declares. Closed by {@link StudioErrorFindingsByCode}, so a token cannot be
823
+ * added to a diagnosis without editing that map.
824
+ */
825
+ findings: StudioErrorFindingsByCode[C];
826
+ }
827
+ /** Reads the facts a diagnosis prints from the config the fetch actually used. */
828
+ declare function buildStudioErrorContext(config?: Config, servedBy?: ServedBy): StudioErrorContext;
829
+ /**
830
+ * Builds the error and returns it to be thrown.
831
+ *
832
+ * **It does not log.** Whether a diagnosis reaches a console, a reporting
833
+ * service or neither is the application's decision, not ours — it is the only
834
+ * party that knows its environment, its log budget and its privacy rules. An
835
+ * SDK that writes to the console on the app's behalf takes that decision away
836
+ * and duplicates whatever the app already does with the rejection.
837
+ *
838
+ * What we owe the app in exchange is an error worth logging: the message
839
+ * carries the code and every cause, so a plain `console.error(err)` shows the
840
+ * whole diagnosis, and the structured `code`, `causes` and `context` are there
841
+ * for anything that wants to report rather than print.
842
+ */
843
+ declare function createStudioError<C extends StudioErrorCodeType>(input: StudioErrorInput<C>): ComposableStudioError;
844
+ /**
845
+ * Whether a failure is a property of the setup rather than of one attempt.
846
+ *
847
+ * Fallbacks exist to survive a request that did not work out: another candidate
848
+ * may own the url, a scan may find what a fast path missed. None of that applies
849
+ * here. The same configuration produces the same answer on every path and every
850
+ * retry, so falling back spends work to reach an identical failure — and reports
851
+ * the one diagnosis worth reading as a transient hiccup on the way.
852
+ */
853
+ declare function isSetupFault(error: unknown): boolean;
854
+
157
855
  declare function getDefaultConfig(): Config;
158
856
 
159
857
  declare const isBrowser: () => boolean;
@@ -176,9 +874,28 @@ declare const isBrowser: () => boolean;
176
874
  */
177
875
  declare const INCLUDE_DEPTH_COUNT = 3;
178
876
  declare const SDK_VERSION: string;
179
- declare const SCHEMA_VERSION = "1.0.0";
180
- declare const COMPOSABLE_DATA_ATTRIBUTES: {
181
- readonly BUILDER: "data-composable-studio-builder";
877
+ /**
878
+ * Version of the composition spec this SDK writes and reads.
879
+ *
880
+ * Studio persists whatever the canvas SDK reports here onto the composition as
881
+ * `schema_version`, so it doubles as a marker of what a saved composition can be
882
+ * trusted to contain.
883
+ *
884
+ * 1.1.0 (COMPLETE_INCLUDES_FROM_SCHEMA_VERSION) — every fetch root's
885
+ * `data_sources[*].resolvedReferences` is recomputed on save and holds exactly
886
+ * the references it needs, including what this SDK used to work out at render
887
+ * (`derivePlacementIncludePaths`), so the SDK derives nothing (ADR 0018). Below
888
+ * that the sets were accumulated by union, and before 2026-07-17 they held only
889
+ * what the author had ticked — which is why the derivation still runs for them.
890
+ *
891
+ * RELEASE ORDER: released only after Studio saves complete sets for every fetch
892
+ * root (studio-ui#1303, which calls `derivePlacementIncludePaths` at save). An SDK
893
+ * reporting 1.1.0 to a Studio that does not yet do that would mark compositions
894
+ * as trustworthy when they are not.
895
+ */
896
+ declare const SCHEMA_VERSION = "1.1.0";
897
+ declare const COMPOSABLE_DATA_ATTRIBUTES: {
898
+ readonly BUILDER: "data-composable-studio-builder";
182
899
  readonly PLACEHOLDER: "data-composable-studio-placeholder";
183
900
  readonly LEAF: "data-composable-studio-leaf";
184
901
  readonly NODE: "data-composable-studio-node";
@@ -226,6 +943,16 @@ declare const getHitboxDirection: (event: MouseEvent, nodeBoundingBox: DOMRect)
226
943
  */
227
944
  declare const toggleNodeVisible: (node: Element, visible: boolean) => void;
228
945
  declare const getComposableElement: (uid: string) => HTMLElement;
946
+ /**
947
+ * Every element a node rendered, not just the first.
948
+ *
949
+ * One composition node can reach the DOM many times: a Repeater renders its
950
+ * subtree once per item, and each copy carries the same uid, so a node inside
951
+ * a Repeater has one element per iteration. Callers that ask "where is this
952
+ * node on the page" have to reason over all of them — the first in document
953
+ * order is iteration 0, which is routinely the one that rendered nothing.
954
+ */
955
+ declare const getComposableElements: (uid: string) => HTMLElement[];
229
956
  declare const getHitboxDetails: (event: MouseEvent) => HitboxDetails;
230
957
  declare const getComputedStyles: (event: MouseEvent) => Record<string, string> | null;
231
958
  declare const serializeEvent: (event: MouseEvent) => SerializedEvent;
@@ -428,6 +1155,12 @@ interface CompositionEntry {
428
1155
  created_at: string;
429
1156
  updated_at: string;
430
1157
  url?: string;
1158
+ /**
1159
+ * Spec version the composition was last saved against — the `SCHEMA_VERSION`
1160
+ * the canvas SDK reported to Studio at the time. Absent on anything saved
1161
+ * before Studio began persisting it. Read by `compositionCarriesCompleteIncludes`.
1162
+ */
1163
+ schema_version?: string;
431
1164
  place_composition_as?: CompositionPlacement;
432
1165
  linked_schemas?: {
433
1166
  content_type_uid: string;
@@ -471,6 +1204,13 @@ interface StudioSpec {
471
1204
  urlResolution?: {
472
1205
  shortlisted: UrlMatchDiagnostic[];
473
1206
  };
1207
+ /**
1208
+ * Where this request went and what it was made with — the same block every
1209
+ * error carries. Present on success too, because a page that rendered the
1210
+ * wrong content is diagnosed by comparing these facts against what Studio
1211
+ * holds, and there is no error to carry them on. Never holds a token.
1212
+ */
1213
+ requestContext?: StudioErrorContext;
474
1214
  }
475
1215
  type SearchQueryInput = (Partial<ComposableStudioQueryParams> & {
476
1216
  [key: string]: string | string[] | undefined;
@@ -614,25 +1354,60 @@ type StudioComponentFetchOptions = {
614
1354
  */
615
1355
  type StudioComponentSpecOptions = {
616
1356
  /**
617
- * When the componen is rendered in SSR within the studio,
618
- * we get the spec as null. YOU SHOULD NOT PASS IT AS NULL.
1357
+ * The resolved composition. `null` only when a caller builds this object by
1358
+ * hand to mean "I hold no spec, fetch it from the parent window" — the
1359
+ * built-in canvas does exactly that, having no credentials to fetch with.
1360
+ * A fetch never returns `null`; it rejects instead.
619
1361
  */
620
1362
  spec: StudioSpec | null;
1363
+ /**
1364
+ * Opaque machinery for `<StudioComponent>` — pass it through, do not inspect
1365
+ * it. The renderer reads the composition query, the query options and the
1366
+ * config out of it to re-initialise and re-fetch on the client.
1367
+ */
621
1368
  fetchOptions: StudioComponentFetchOptions;
622
1369
  /**
623
- * This is used to determine whether the spec is available.
624
- * If the spec is not available, we can show a 404 page.
1370
+ * Whether the resolved spec carries a composition entry.
1371
+ *
1372
+ * **Not a 404 signal.** Every "there is no composition here" outcome rejects
1373
+ * rather than returning, so on a resolved fetch this is always `true`, and on
1374
+ * the push path it is `true` whenever Studio supplied a spec. To test for the
1375
+ * no-spec sentinel, check `spec` itself.
1376
+ *
1377
+ * @deprecated Read `spec.compositionEntry` directly, and decide 404 from the
1378
+ * rejected `ComposableStudioError`. Slated for removal in a future major.
625
1379
  */
626
1380
  hasSpec: boolean;
627
1381
  /**
628
- * This is used to determine whether the template (connected Template data)
629
- * is available.
630
- * If the template is not available, we can show a 404 page.
1382
+ * Whether the spec carries resolved data for a connected content type.
631
1383
  *
632
- * This value is false if the template is not available or the composition
633
- * is not connected to a template.
1384
+ * **Not a 404 signal.** It is `false` for every **freeform** composition, so
1385
+ * gating a 404 on it returns 404 for every freeform page, however that page
1386
+ * is published. Its exact meaning also differs between the fetch and push
1387
+ * paths, which is a second reason not to branch on it.
1388
+ *
1389
+ * @deprecated For composition kind read {@link connectedContentTypeUid}. For
1390
+ * the 404 decision use `isCompositionNotFound(error)`, which answers the
1391
+ * question directly and keeps working across two copies of the package in one
1392
+ * dependency tree. Slated for removal in a future major.
634
1393
  */
635
1394
  hasTemplate: boolean;
1395
+ /**
1396
+ * The content type this composition reads from, or `null` when it is freeform.
1397
+ *
1398
+ * The question `hasTemplate` was being misread as, spelled honestly. The value
1399
+ * already exists at `spec.compositionEntry.connected_content_type`; surfacing
1400
+ * it here saves every host reaching two levels into the raw CMS entry and
1401
+ * normalising the empty string that means "none".
1402
+ *
1403
+ * **Still not a 404 signal.** A freeform composition is a real page and a
1404
+ * connected one with no entry is a real miss, so kind cannot decide a status
1405
+ * in either direction — that is what `isCompositionNotFound` is for.
1406
+ *
1407
+ * Optional because callers construct this object by hand, and a required field
1408
+ * would break them.
1409
+ */
1410
+ connectedContentTypeUid?: string | null;
636
1411
  /**
637
1412
  * The SEO metadata for the composition. This data can be added to the head
638
1413
  * of the HTML.
@@ -695,250 +1470,6 @@ declare const NODE_TO_ELEMENT: WeakMap<any, HTMLElement>;
695
1470
  declare const NODE_TO_PATH_NODE: WeakMap<any, PathNode>;
696
1471
  declare const NODE_TO_PARENT: WeakMap<any, any>;
697
1472
 
698
- declare const findPath: (node: Descendant) => Path;
699
- declare const findPathForElement: (el: HTMLElement) => Path;
700
- declare const applyOperation: (editor: Node, operations: Operation[]) => Node;
701
-
702
- declare function isCompositionBeingEdited(compositionUid: string): boolean;
703
-
704
- declare const queryParam: {
705
- get(key: ComposableStudioQueryParamsKeys): string | null;
706
- has(key: ComposableStudioQueryParamsKeys): boolean;
707
- };
708
- declare const onlyParmasGenerator: (only: [string, string][]) => Record<string, string[]>;
709
-
710
- declare const SECTION_COMPOSITIONS_KEY = "section_compositions";
711
- declare const TEMPLATE_FULL_ENTRY_KEY = "template_full_entry";
712
- declare const setTemplateEntryInDS: (dataSources: Record<string, any>, entry: unknown) => void;
713
- declare const setStaticEntryInDS: (dataSources: Record<string, any>, ct_uid: string, _entries: unknown) => void;
714
- /**
715
- * Counterpart to setStaticEntryInDS: drop a single resolved additional entry
716
- * from the contentstack data source bucket. Called when the author removes an
717
- * entry so the pruned bucket replaces the stale one on the next UPDATE_SPEC_DATA
718
- * push (which merges at the dataSources level); without it the removed entry's
719
- * data lingers and keeps rendering.
720
- */
721
- declare const removeStaticEntryFromDS: (dataSources: Record<string, any>, ct_uid: string, uid: string) => void;
722
- declare const batchFetchEntries: (sdk: StackSDK, entries: ICSEntryReference[]) => Promise<[string, CompositionEntry[]][]>;
723
- declare const getBindingStringForCS: (binding: BindingType) => string;
724
- type EntriesResponse<T> = {
725
- entries: T[];
726
- } | [T[]];
727
- declare function entriesFromResponse<T>(response: EntriesResponse<T>): T[];
728
-
729
- declare const isInsideVisualBuilderFrame: () => boolean;
730
-
731
- /**
732
- * Checks if the current context is inside an iframe.
733
- *
734
- * @returns {boolean} True if inside an iframe, false otherwise.
735
- */
736
- declare const isInsideIframe: () => boolean;
737
-
738
- /** The three author-facing render contexts a host app can find itself in. */
739
- type StudioMode = "canvas" | "preview" | "visitor";
740
- /**
741
- * The query param Studio always appends to canvas / template-preview iframe
742
- * URLs. Part of the stable contract — changing its value is a breaking
743
- * change and will be release-noted as such.
744
- */
745
- declare const STUDIO_CANVAS_QUERY_PARAM: "cs-composable-studio";
746
- /**
747
- * Class the SDK bootstrap adds to `<html>` when running inside the Studio
748
- * canvas. Available for CSS-only gating (e.g. `html.cs-studio-canvas
749
- * #onetrust-banner-sdk { display: none }`).
750
- */
751
- declare const STUDIO_MODE_HTML_CLASS = "cs-studio-canvas";
752
- declare global {
753
- interface Window {
754
- __CS_STUDIO_MODE__?: StudioMode;
755
- }
756
- }
757
- /**
758
- * Detects the current Studio mode.
759
- *
760
- * Browser: the `window.__CS_STUDIO_MODE__` marker wins when present (it
761
- * survives client-side navigations that strip query params); otherwise the
762
- * URL's query params decide.
763
- *
764
- * Server: pass the request's search params (string or URLSearchParams) to
765
- * get a real answer; with no arguments it safely reports `"visitor"`.
766
- */
767
- declare function detectStudioMode(searchQuery?: string | URLSearchParams): StudioMode;
768
- /**
769
- * True when the host app is rendering inside the Studio canvas (or Visual
770
- * Builder frame) — the one check to gate cookie banners, chat widgets,
771
- * analytics, marketing pixels, and feature-flag bootstraps behind.
772
- *
773
- * SSR-safe: returns false on the server unless the request's search params
774
- * are passed explicitly.
775
- */
776
- declare function isStudioCanvas(searchQuery?: string | URLSearchParams): boolean;
777
- /**
778
- * True in any Studio-driven context (canvas OR live-preview pane). Use when
779
- * a third-party should also stay out of preview sessions — e.g. analytics.
780
- */
781
- declare function isStudioEditorMode(searchQuery?: string | URLSearchParams): boolean;
782
- /**
783
- * Bootstrap: computes the mode from the current URL, stamps
784
- * `window.__CS_STUDIO_MODE__`, and (for canvas mode) adds
785
- * {@link STUDIO_MODE_HTML_CLASS} to `<html>`. Idempotent; no-op on the
786
- * server. Invoked automatically when `@contentstack/studio-react` loads in
787
- * the browser — call it manually only if you gate scripts that run before
788
- * the SDK's module graph is evaluated.
789
- */
790
- declare function markStudioMode(): StudioMode;
791
-
792
- declare const ComposableStudioErrors: {
793
- readonly COMPOSITION_NOT_FOUND: "COMPOSITION_NOT_FOUND";
794
- readonly COMPOSITION_NOT_FOUND_BY_URL: "COMPOSITION_NOT_FOUND_BY_URL";
795
- readonly PREVIEW_ENTRY_NOT_FOUND: "PREVIEW_ENTRY_NOT_FOUND";
796
- readonly FETCHING_CONNECTED_DATA_FAILED: "FETCHING_CONNECTED_DATA_FAILED";
797
- readonly RESOLVING_DATA_SOURCES_FAILED: "RESOLVING_DATA_SOURCES_FAILED";
798
- readonly STACK_SDK_NOT_AVAILABLE: "STACK_SDK_NOT_AVAILABLE";
799
- readonly INVALID_FETCH_SPEC_OPTIONS: "INVALID_FETCH_SPEC_OPTIONS";
800
- readonly MISSING_COMPOSITION_IDENTIFIER: "MISSING_COMPOSITION_IDENTIFIER";
801
- readonly UI_PARSING_ERROR: "UI_PARSING_ERROR";
802
- readonly SPEC_DATA_INVALID: "SPEC_DATA_INVALID";
803
- readonly NETWORK_ERROR: "NETWORK_ERROR";
804
- readonly AUTHENTICATION_ERROR: "AUTHENTICATION_ERROR";
805
- readonly SERVER_ERROR: "SERVER_ERROR";
806
- readonly COMPONENT_NOT_FOUND: "COMPONENT_NOT_FOUND";
807
- };
808
- /**
809
- * Information about a possible cause of an error and how to fix it
810
- */
811
- interface TroubleshootingInfo {
812
- /**
813
- * Description of the possible cause of the error
814
- */
815
- cause: string;
816
- /**
817
- * Suggested fix or resolution for this cause
818
- */
819
- fix: string;
820
- }
821
- /**
822
- * Type definition for error details that can be passed to ComposableStudioError
823
- */
824
- interface ComposableStudioErrorDetails {
825
- /**
826
- * Array of troubleshooting information with causes and fixes
827
- */
828
- troubleshootingInfo?: TroubleshootingInfo[];
829
- /**
830
- * Additional error context and metadata
831
- */
832
- [key: string]: any;
833
- }
834
- declare class ComposableStudioError extends Error {
835
- id: keyof typeof ComposableStudioErrors;
836
- details?: ComposableStudioErrorDetails;
837
- constructor(id: keyof typeof ComposableStudioErrors, message: string, details?: ComposableStudioErrorDetails);
838
- }
839
-
840
- declare const evaluateCondition: (condition: Condition, data: any) => boolean;
841
-
842
- declare class RendererModeUtil {
843
- private searchParams;
844
- private isServerWithoutParams;
845
- constructor(searchParams?: URLSearchParams);
846
- /**
847
- * Checks if the current context is inside a Studio.
848
- *
849
- * @returns {boolean} True if inside a Studio, false otherwise.
850
- */
851
- isInsideStudioFrame(): boolean;
852
- /**
853
- * Checks if the current context is inside an iframe.
854
- *
855
- * @returns {boolean} True if inside an iframe, false otherwise.
856
- */
857
- isInsideIframe(): boolean;
858
- /**
859
- * Checks if the current context is inside a Visual Builder frame.
860
- *
861
- * Learn more about Visual Builder: {@link https://www.contentstack.com/docs/content-managers/visual-builder}
862
- *
863
- * @returns {boolean} True if inside a Visual Builder frame, false otherwise.
864
- */
865
- isInsideVisualBuilderFrame(): boolean;
866
- /**
867
- * Checks if the current context is editing a specific composition.
868
- *
869
- * It is useful when you have multiple compositions in a single page
870
- * and you want to know if the current context is editing a specific
871
- * composition.
872
- *
873
- * @param compositionUid - The UID of the composition to check.
874
- * @returns {boolean} True if editing the specified composition, false otherwise.
875
- */
876
- isEditingCurrentComposition(compositionUid: string): boolean;
877
- /**
878
- * Determines the current renderer mode for a given composition UID.
879
- *
880
- * - Returns "edit" if the current composition is being edited.
881
- * - Returns "show_edit_button" if inside the visual builder frame
882
- * or if the composition is not currently being edited but should show the edit button.
883
- * - Returns "preview" otherwise.
884
- *
885
- * This method is useful when you want to change the functionality of the
886
- * component based on where it is being rendered.
887
- *
888
- * @param compositionUid - The UID of the composition to check.
889
- * @returns RendererMode - The current mode (EDIT, SHOW_EDIT_BUTTON, or PREVIEW).
890
- */
891
- getMode(compositionUid: string): "preview" | "edit" | "show_edit_button";
892
- }
893
- /**
894
- * Module-level mode util backed by `window.location.search` (the browser URL).
895
- *
896
- * SSR CAUTION: this reads `window`, which does not exist on the server, so on the server
897
- * every method returns its production default (e.g. `isInsideStudioFrame()` -> false) for
898
- * ALL requests. It is correct ONLY in browser-only code (the editor render, hooks,
899
- * INIT_STUDIO). In server-reachable fetch code (studio-client's spec-fetch path) do NOT use
900
- * this: the answer is wrong on the server, and a single shared singleton cannot represent
901
- * per-request state across concurrent SSR requests anyway. There, use the request-scoped
902
- * helpers in `sdk.ts` (`isInStudio` / `isEditorFetch` / `readStudioParam`, built on
903
- * `getRequestSearchParams`), which read the forwarded request query on the server and fall
904
- * back to `window` on the client. See COMS-1554 for the AsyncLocalStorage proposal that would
905
- * remove this split and make this util correct everywhere.
906
- */
907
- declare const clientRendererModeUtil: RendererModeUtil;
908
- declare const serializeComputedStyles: (computedStyle: CSSStyleDeclaration) => Record<string, string>;
909
-
910
- /**
911
- * Analyzes a UI spec (Node tree) and extracts all component types used.
912
- * Recursively traverses the spec to find all components.
913
- *
914
- * @param spec - The root node of the UI spec
915
- * @returns Set of component types used in the spec
916
- */
917
- declare function analyzeUsedComponents(spec: Node | null | undefined): Set<string>;
918
- /**
919
- * Analyzes multiple UI specs and returns the union of all component types used.
920
- * Useful for optimizing multi-composition loading.
921
- *
922
- * @param specs - Array of UI spec root nodes
923
- * @returns Set of all unique component types used across all specs
924
- */
925
- declare function analyzeMultipleSpecs(specs: (Node | null | undefined)[]): Set<string>;
926
- /**
927
- * Checks if a spec uses a specific component type.
928
- *
929
- * @param spec - The UI spec to check
930
- * @param componentType - The component type to look for
931
- * @returns true if the component is used in the spec
932
- */
933
- declare function specUsesComponent(spec: Node | null | undefined, componentType: string): boolean;
934
- /**
935
- * Gets component usage statistics for a spec.
936
- *
937
- * @param spec - The UI spec to analyze
938
- * @returns Map of component types to their usage count
939
- */
940
- declare function getComponentUsageStats(spec: Node | null | undefined): Map<string, number>;
941
-
942
1473
  interface UrlPatternVariableInfo {
943
1474
  type: string;
944
1475
  name: string;
@@ -982,6 +1513,18 @@ interface SectionNeeds {
982
1513
  uidRemapping?: Record<string, string>;
983
1514
  cardinality?: "collection" | "single";
984
1515
  componentPropsFallback?: Record<string, unknown>;
1516
+ /**
1517
+ * The document this instance's section data lives in (ADR 0017): `"template"`,
1518
+ * a `<ct>:<uid>` pinned-entry key, or `query:<dsUid>`. Absent ⇒ template, so
1519
+ * every pre-existing composition behaves exactly as before.
1520
+ */
1521
+ fetchRootKey?: string;
1522
+ /**
1523
+ * The path WITHIN that document. For the template root this is the same thing
1524
+ * as `selectedField`; for a pinned-entry root it is the root path with the
1525
+ * `<ct>:<uid>` document segment already dropped.
1526
+ */
1527
+ fetchRootPrefix?: string[];
985
1528
  }
986
1529
  type NeedsBySection = Map<string, SectionNeeds>;
987
1530
 
@@ -1024,67 +1567,331 @@ declare function getSeoMetadataPure(ui: Node, specData?: StudioSpecData): SeoMet
1024
1567
  * Returns `{}` when there are no section compositions (e.g. a standalone
1025
1568
  * section rendered as the root reads `dataSources.template` directly).
1026
1569
  */
1027
- declare function buildSectionScopedData(compositionEntry: CompositionEntry, pageUi: Node, sectionEntries: SectionCompositionEntry[], dataSources: StudioSpecData["dataSources"]): ReturnType<typeof buildScopedDataSources>;
1028
-
1570
+ declare function buildSectionScopedData(compositionEntry: CompositionEntry, pageUi: Node, sectionEntries: SectionCompositionEntry[], dataSources: StudioSpecData["dataSources"]): ReturnType<typeof buildScopedDataSources>;
1571
+ /**
1572
+ * Every include[] path the SDK would work out on its own for a composition,
1573
+ * grouped by the fetch root whose request it belongs on — `"template"`, a
1574
+ * `<ct>:<uid>` pinned entry, or `query:<uid>` (ADR 0017, ADR 0018):
1575
+ *
1576
+ * - the composition's own reference-condition paths, on `"template"`;
1577
+ * - for every placed section, its reference-condition paths composed onto where
1578
+ * it sits, and each step of that position (`derivedIncludePathsForInstance`).
1579
+ *
1580
+ * Below COMPLETE_INCLUDES_FROM_SCHEMA_VERSION the SDK adds these at render. From
1581
+ * that version on it adds none: Studio calls this at save, keeps what the schema
1582
+ * confirms is a reference, and persists it on the matching data source, so the
1583
+ * composition carries everything its fetch roots need. The render path and the
1584
+ * save path share `derivedIncludePathsForInstance`, so they cannot drift apart.
1585
+ *
1586
+ * Paths are unvalidated — the SDK has no schema. A caller persisting them must
1587
+ * validate them first.
1588
+ */
1589
+ declare function derivePlacementIncludePaths(compositionEntry: Pick<CompositionEntry, "ui" | "connected_content_type">, sectionEntries: SectionCompositionEntry[]): Record<string, string[]>;
1590
+
1591
+ /**
1592
+ * A single, framework-neutral meta tag. `attr` distinguishes standard
1593
+ * `<meta name="...">` tags from Open Graph-style `<meta property="...">`.
1594
+ */
1595
+ interface CompositionMetaTag {
1596
+ attr: "name" | "property";
1597
+ key: string;
1598
+ content: string;
1599
+ }
1600
+ /**
1601
+ * Framework-neutral SEO metadata derived from a composition's resolved
1602
+ * `specOptions.seo`. Consumers bind this to their host's head mechanism:
1603
+ * Next.js `generateMetadata`, Remix `meta()`, TanStack `head()`, or a raw
1604
+ * HTML template via {@link renderMetadataToHtml}.
1605
+ */
1606
+ interface CompositionMetadata {
1607
+ title?: string;
1608
+ description?: string;
1609
+ ogImage?: string;
1610
+ /** Absolute canonical URL. Present only when `baseUrl` was provided and the composition has a URL. */
1611
+ canonical?: string;
1612
+ /** Every derived tag (description, og:*, twitter:*, custom metaProps) in render order. */
1613
+ tags: CompositionMetaTag[];
1614
+ }
1615
+ interface GetCompositionMetadataOptions {
1616
+ /**
1617
+ * Site origin used to absolutize the canonical URL and og:url,
1618
+ * e.g. `https://www.example.com`. No trailing slash required.
1619
+ */
1620
+ baseUrl?: string;
1621
+ }
1622
+ /**
1623
+ * Derives framework-neutral SEO metadata from a fetched composition.
1624
+ *
1625
+ * The heavy lifting (resolving field bindings for title/description/OG image)
1626
+ * already happens inside `fetchCompositionData` — this helper only shapes the
1627
+ * resolved values into standard head-tag structures.
1628
+ *
1629
+ * @example Plain Node
1630
+ * ```ts
1631
+ * const meta = getCompositionMetadata(specOptions, { baseUrl: "https://example.com" });
1632
+ * res.send(`<head><title>${meta.title}</title>${renderMetadataToHtml(meta)}</head>...`);
1633
+ * ```
1634
+ *
1635
+ * @example Next.js App Router
1636
+ * ```ts
1637
+ * export async function generateMetadata() {
1638
+ * const meta = getCompositionMetadata(await getSpecOptions());
1639
+ * return { title: meta.title, description: meta.description };
1640
+ * }
1641
+ * ```
1642
+ */
1643
+ declare function getCompositionMetadata(specOptions: Pick<StudioComponentSpecOptions, "seo" | "spec">, options?: GetCompositionMetadataOptions): CompositionMetadata;
1644
+ /**
1645
+ * Renders {@link CompositionMetadata} to a raw HTML string (meta + canonical
1646
+ * link tags — the `<title>` element is left to the caller since most hosts
1647
+ * manage it separately). For template-string SSR hosts (Express/Fastify).
1648
+ */
1649
+ declare function renderMetadataToHtml(metadata: CompositionMetadata): string;
1650
+
1651
+ /**
1652
+ * A placement's **Section data** — the binding that supplies a placed section's
1653
+ * data, i.e. what the section's own `template.*` paths resolve against.
1654
+ *
1655
+ * Persisted on the placed section-composition node as part of
1656
+ * `metadata.sectionBindingOverride`. Being a binding rather than a bare field
1657
+ * path is what lets a section root at a pinned entry, a query result or a
1658
+ * repeater item — none of which a freeform page can express as a path into a
1659
+ * page template entry it does not have. See ADR 0016.
1660
+ *
1661
+ * Three states, all distinguishable and all load-bearing:
1662
+ *
1663
+ * | value | meaning |
1664
+ * |-------------|--------------------------------------------------------|
1665
+ * | `undefined` | inherit the section's declared `selected_field` |
1666
+ * | `null` | deliberately cleared — render no bound data |
1667
+ * | a binding | the author's choice |
1668
+ *
1669
+ * `undefined` cannot be collapsed into `null`: absence has to keep meaning
1670
+ * "follow the section's declaration", so a section author's later change to
1671
+ * `linked_schemas` still propagates to placements that never opted in.
1672
+ */
1673
+ type SectionDataBinding = BindingType | null | undefined;
1674
+ interface SectionBindingOverride {
1675
+ /**
1676
+ * Legacy per-placement field path. Still READ (it is the migration source for
1677
+ * `rootBinding`), never newly written.
1678
+ */
1679
+ selectedField?: string;
1680
+ uidRemapping?: Record<string, string>;
1681
+ /** The Section data. See {@link SectionDataBinding} for the three states. */
1682
+ rootBinding?: BindingType | null;
1683
+ /**
1684
+ * Which `linked_schemas` entry the Section data matched.
1685
+ *
1686
+ * On a template the winner is found by `content_type_uid === pageCT`. A
1687
+ * freeform page has no page content type, so without this the cold-load path
1688
+ * falls back to `linked_schemas[0]` and reads `cardinality` off the wrong
1689
+ * schema — a collection section then silently renders as a single element.
1690
+ */
1691
+ matchedSchemaCt?: string;
1692
+ }
1693
+ /** Binding `type` for a path into the page's template entry. */
1694
+ declare const TEMPLATE_BINDING_TYPE = "template";
1695
+ /**
1696
+ * Split a dotted field path into binding-path segments, dropping the array
1697
+ * indices and modular-block numeric prefixes that are not data keys. Mirrors
1698
+ * `sanitizeFieldPath` in sdk.ts — kept local so this module stays dependency-free
1699
+ * and usable from Studio.
1700
+ */
1701
+ declare function splitFieldPath(path: string): string[];
1702
+ /**
1703
+ * Nest dotted path segments into the object shape a binding `value.path` uses:
1704
+ * `["a", "b"]` → `{ a: { b: {} } }`. An empty path nests to `{}`, which is what
1705
+ * a scope-root binding carries.
1706
+ */
1707
+ declare function nestPath(segments: string[]): Record<string, unknown>;
1708
+ /** The inverse of {@link nestPath}: walk the single-key chain back to segments. */
1709
+ declare function flattenPath(path: Record<string, unknown> | undefined | null): string[];
1710
+ /**
1711
+ * Build the template-typed Section data equivalent to a legacy `selectedField`.
1712
+ *
1713
+ * This is the whole migration: every placement saved before the Section data
1714
+ * existed resolves to exactly the binding it behaved as, derived on read. No
1715
+ * stored data changes.
1716
+ */
1717
+ declare function synthesizeTemplateRootBinding(selectedField: string | undefined): BindingType;
1718
+ /** Whether a resolved Section data means "deliberately cleared". */
1719
+ declare function isDataRootCleared(root: SectionDataBinding): root is null;
1720
+ /**
1721
+ * Whether a Section data points into the page's template entry — the only kind
1722
+ * that extends a page-template prefix. A contentstack / query / repeater-typed
1723
+ * root names its own document instead (see ADR 0017's fetch root).
1724
+ */
1725
+ declare function isTemplateRootBinding(root: SectionDataBinding): boolean;
1726
+ /**
1727
+ * The path a Section data addresses **within the scope its placement already
1728
+ * inherits** — the page template entry for a `template` root, the live
1729
+ * iteration item for a `repeater` one (ADR 0006).
1730
+ *
1731
+ * This is what the renderer means by `selectedField`: the provider scopes the
1732
+ * enclosing repeater item (or the template entry) by it. A root naming ANOTHER
1733
+ * document carries its path in the fetch root's `prefix` instead, so it has no
1734
+ * scope path — the two are never both in play.
1735
+ *
1736
+ * The `template`-only version of this test is what left a repeater-relative
1737
+ * root unusable: its path (`hero_card` inside the item) was dropped on the way
1738
+ * to the renderer, every iteration scoped to the whole item, and the section
1739
+ * rendered component defaults.
1740
+ */
1741
+ declare function getRootScopePath(root: SectionDataBinding): string[];
1742
+ /**
1743
+ * The dotted path a Section data addresses *within* its document.
1744
+ *
1745
+ * For a template root this is the old `selectedField`. For a contentstack root
1746
+ * the first segment is the `<ct>:<uid>` pool key, which names the **document**
1747
+ * rather than a field inside it — callers that need the in-document path must
1748
+ * drop it (`dropDocumentSegment`).
1749
+ */
1750
+ declare function getRootBindingPath(root: SectionDataBinding): string[];
1751
+ interface SectionInstanceNode {
1752
+ metadata?: {
1753
+ sectionBindingOverride?: SectionBindingOverride;
1754
+ selectedField?: string;
1755
+ compositionUID?: string;
1756
+ [key: string]: unknown;
1757
+ };
1758
+ }
1759
+ type LinkedSchemasLookup = (compositionUid: string | undefined) => Array<{
1760
+ content_type_uid: string;
1761
+ selected_field?: string;
1762
+ }>;
1763
+ /**
1764
+ * The legacy `selectedField` ladder, verbatim: per-instance override → legacy
1765
+ * `metadata.selectedField` → the `linked_schemas` default for the page content
1766
+ * type → the first schema.
1767
+ *
1768
+ * Extracted so the Section data resolver and the existing page-template
1769
+ * projection read the SAME ladder and cannot drift. Returns the path
1770
+ * **unsanitised** — callers that need CDA-safe segments sanitise at the point
1771
+ * of use, exactly as they did before the Section data existed.
1772
+ */
1773
+ declare function resolveLegacySelectedField(node: SectionInstanceNode, linkedSchemasFor: LinkedSchemasLookup, pageContentTypeUid: string): string;
1774
+ /**
1775
+ * Where a resolved `selectedField` came from — which decides whether it is
1776
+ * relative to an enclosing wrapper section or absolute from the page root.
1777
+ *
1778
+ * - `"override"` — the page composer picked it. The picker's options come from
1779
+ * `findMatchingPageFields` against the schema **scoped to the drop
1780
+ * location**, so an override is RELATIVE to the enclosing wrapper.
1781
+ * - `"declared"` — read off `linked_schemas` by matching the PAGE content
1782
+ * type, so it is rooted at the page entry: ABSOLUTE.
1783
+ * - `"legacy"` — `metadata.selectedField` from before per-instance overrides
1784
+ * existed; same origin as `declared`, so also absolute.
1785
+ *
1786
+ * This distinction is what the leading-overlap collapse in
1787
+ * `composeSectionTemplatePrefix` was approximating by string comparison. Overlap
1788
+ * catches an absolute path that happens to SHARE a leading segment with its
1789
+ * ancestor; it cannot catch one that does not, which is how a slot child ends up
1790
+ * with `author.related_block` — a path the referenced content type does not
1791
+ * have, silently dropped by CDA.
1792
+ */
1793
+ type SelectedFieldProvenance = "override" | "legacy" | "declared";
1794
+ declare function resolveLegacySelectedFieldWithProvenance(node: SectionInstanceNode, linkedSchemasFor: LinkedSchemasLookup, pageContentTypeUid: string): {
1795
+ field: string;
1796
+ provenance: SelectedFieldProvenance;
1797
+ };
1798
+ /**
1799
+ * Whether a resolved field is rooted at the page entry rather than at an
1800
+ * enclosing wrapper section. A page-absolute field must REPLACE the inherited
1801
+ * prefix, never be concatenated onto it.
1802
+ *
1803
+ * A scope-root field ("") is neither — it adds no segment either way — so it is
1804
+ * reported as not absolute to keep the inherited prefix intact.
1805
+ */
1806
+ declare function isPageAbsoluteField(field: string, provenance: SelectedFieldProvenance): boolean;
1807
+ /**
1808
+ * Resolve a section-composition node's effective **Section data**.
1809
+ *
1810
+ * Resolution order — the existing `selectedField` ladder with one tier added on
1811
+ * top, so this is strictly a superset of today's behaviour:
1812
+ *
1813
+ * 1. `sectionBindingOverride.rootBinding` when the key is PRESENT (including
1814
+ * an explicit `null`, which means cleared)
1815
+ * 2. otherwise synthesise a template-typed binding from the legacy
1816
+ * `selectedField` ladder: override → `metadata.selectedField` →
1817
+ * `linked_schemas` default for the page content type → first schema
1818
+ *
1819
+ * The caller MUST NOT write the result back onto the node. Persisted state is
1820
+ * structurally diffed against the save baseline (ADR 0007), so persisting a
1821
+ * derived value would mark every pre-existing page dirty the moment it opens,
1822
+ * and would freeze a live fallback into a copy.
1823
+ */
1824
+ declare function resolveInstanceRootBinding(node: SectionInstanceNode, linkedSchemasFor: LinkedSchemasLookup, pageContentTypeUid: string): SectionDataBinding;
1825
+ /**
1826
+ * Which `linked_schemas` entry a placement is bound to.
1827
+ *
1828
+ * Prefers the persisted `matchedSchemaCt` (the only answer available on a
1829
+ * freeform page), falling back to matching the page content type the way the
1830
+ * template path always has.
1831
+ */
1832
+ declare function resolveMatchedSchema<T extends {
1833
+ content_type_uid: string;
1834
+ selected_field?: string;
1835
+ }>(node: {
1836
+ metadata?: {
1837
+ sectionBindingOverride?: SectionBindingOverride;
1838
+ };
1839
+ }, linkedSchemas: T[] | undefined, pageContentTypeUid: string): T | undefined;
1840
+ /**
1841
+ * Deep-compare two Section datas. Used by the stamp pass, which must compare a
1842
+ * DERIVED binding against a DERIVED binding: comparing a `BindingType` object
1843
+ * against a raw `selectedField` string never matches, so every template
1844
+ * placement would stamp and every old page would go dirty on open.
1845
+ */
1846
+ declare function sectionDataEqual(a: SectionDataBinding, b: SectionDataBinding): boolean;
1029
1847
  /**
1030
- * A single, framework-neutral meta tag. `attr` distinguishes standard
1031
- * `<meta name="...">` tags from Open Graph-style `<meta property="...">`.
1848
+ * A **fetch root**: the single fetched document a set of data paths is rooted
1849
+ * at, and whose CDA `include[]` those paths are contributed to.
1850
+ *
1851
+ * `include[]` / `only[]` are properties of a *request*, not of a path — you can
1852
+ * only add an include to a document that is actually being fetched. So a path
1853
+ * is only meaningful paired with the document it counts from.
1854
+ *
1855
+ * A template page has exactly ONE fetch root (the template entry), which is why
1856
+ * the pre-existing code could accumulate every section's paths into two flat
1857
+ * arrays. A freeform page has one per Section data in play, so the destination is
1858
+ * per-instance and only knowable after resolving that instance's binding.
1032
1859
  */
1033
- interface CompositionMetaTag {
1034
- attr: "name" | "property";
1860
+ interface FetchRoot {
1861
+ /** `"template"`, a `<ct>:<uid>` pool key, or `query:<dsUid>`. */
1035
1862
  key: string;
1036
- content: string;
1863
+ /** The path *within* that document. */
1864
+ prefix: string[];
1037
1865
  }
1866
+ declare const TEMPLATE_FETCH_ROOT_KEY = "template";
1867
+ declare const templateFetchRoot: (prefix?: string[]) => FetchRoot;
1868
+ /** Whether a fetch-root key names the page template entry. */
1869
+ declare function isTemplateFetchRoot(key: string): boolean;
1038
1870
  /**
1039
- * Framework-neutral SEO metadata derived from a composition's resolved
1040
- * `specOptions.seo`. Consumers bind this to their host's head mechanism:
1041
- * Next.js `generateMetadata`, Remix `meta()`, TanStack `head()`, or a raw
1042
- * HTML template via {@link renderMetadataToHtml}.
1871
+ * Parse a `<ct>:<uid>` fetch-root key back into its parts. Returns null for the
1872
+ * template root and for query roots, neither of which is an entry.
1043
1873
  */
1044
- interface CompositionMetadata {
1045
- title?: string;
1046
- description?: string;
1047
- ogImage?: string;
1048
- /** Absolute canonical URL. Present only when `baseUrl` was provided and the composition has a URL. */
1049
- canonical?: string;
1050
- /** Every derived tag (description, og:*, twitter:*, custom metaProps) in render order. */
1051
- tags: CompositionMetaTag[];
1052
- }
1053
- interface GetCompositionMetadataOptions {
1054
- /**
1055
- * Site origin used to absolutize the canonical URL and og:url,
1056
- * e.g. `https://www.example.com`. No trailing slash required.
1057
- */
1058
- baseUrl?: string;
1059
- }
1874
+ declare function parseEntryFetchRootKey(key: string): {
1875
+ contentTypeUid: string;
1876
+ entryUid: string;
1877
+ } | null;
1060
1878
  /**
1061
- * Derives framework-neutral SEO metadata from a fetched composition.
1879
+ * Derive the fetch root a Section data addresses.
1062
1880
  *
1063
- * The heavy lifting (resolving field bindings for title/description/OG image)
1064
- * already happens inside `fetchCompositionData` — this helper only shapes the
1065
- * resolved values into standard head-tag structures.
1881
+ * The first path segment of a non-template binding names the **document**, not
1882
+ * a field inside it, so it becomes the key and is dropped from the prefix:
1066
1883
  *
1067
- * @example Plain Node
1068
- * ```ts
1069
- * const meta = getCompositionMetadata(specOptions, { baseUrl: "https://example.com" });
1070
- * res.send(`<head><title>${meta.title}</title>${renderMetadataToHtml(meta)}</head>...`);
1071
- * ```
1884
+ * { contentstack, path: { "mkt_ct:blt1": { banner: {} } } }
1885
+ * → { key: "mkt_ct:blt1", prefix: ["banner"] }
1072
1886
  *
1073
- * @example Next.js App Router
1074
- * ```ts
1075
- * export async function generateMetadata() {
1076
- * const meta = getCompositionMetadata(await getSpecOptions());
1077
- * return { title: meta.title, description: meta.description };
1078
- * }
1079
- * ```
1080
- */
1081
- declare function getCompositionMetadata(specOptions: Pick<StudioComponentSpecOptions, "seo" | "spec">, options?: GetCompositionMetadataOptions): CompositionMetadata;
1082
- /**
1083
- * Renders {@link CompositionMetadata} to a raw HTML string (meta + canonical
1084
- * link tags — the `<title>` element is left to the caller since most hosts
1085
- * manage it separately). For template-string SSR hosts (Express/Fastify).
1887
+ * A `repeater`-typed root inherits the enclosing document: the repeater re-scopes
1888
+ * per iteration at render time, but the includes still belong to whichever
1889
+ * document the repeater's own source was fetched from.
1890
+ *
1891
+ * Returns `inherited` unchanged for a cleared root — there is nothing to fetch,
1892
+ * so nothing should be re-anchored.
1086
1893
  */
1087
- declare function renderMetadataToHtml(metadata: CompositionMetadata): string;
1894
+ declare function fetchRootFromBinding(root: SectionDataBinding, inherited: FetchRoot): FetchRoot;
1088
1895
 
1089
1896
  /**
1090
1897
  * Processes the raw static values and stored them against their static value UID.
@@ -1138,142 +1945,6 @@ declare function addContextMenuEventListeners(): {
1138
1945
  removeEventListeners: () => void;
1139
1946
  } | undefined;
1140
1947
 
1141
- declare const MAX_SCROLL_SPEED = 100;
1142
- declare const SCROLL_INTERVAL = 50;
1143
- declare const EDGE_PADDING = 50;
1144
- interface MousePosition {
1145
- clientX: number;
1146
- clientY: number;
1147
- }
1148
- declare class DNDManager {
1149
- started: boolean;
1150
- dragging: boolean;
1151
- scrollContainer: HTMLElement | null;
1152
- scrollInterval: ReturnType<typeof setInterval> | undefined;
1153
- startPosition: MousePosition | null;
1154
- hasMoved: boolean;
1155
- mouseDown: boolean;
1156
- constructor();
1157
- handleMouseDown(_e: MouseEvent): void;
1158
- handleMouseUp(_e: MouseEvent): void;
1159
- handleMouseLeave(e: MouseEvent): void;
1160
- start(e: MouseEvent): void;
1161
- startParent(): void;
1162
- end(): void;
1163
- mouseMove(e: MouseEvent): void;
1164
- get isStarted(): boolean;
1165
- get isDragging(): boolean;
1166
- hasExceededTolerance(start: MousePosition, end: MousePosition): boolean;
1167
- }
1168
- declare const dndManager: DNDManager;
1169
-
1170
- declare const dndEventListener: () => {
1171
- removeEventListeners: () => void;
1172
- };
1173
-
1174
- declare const getScrollableParent: (el: HTMLElement) => HTMLElement;
1175
- declare const calculateDynamicSpeed: (distance: number, padding: number, maxSpeed: number) => number;
1176
-
1177
- declare function handleOnScroll(): void;
1178
- declare function handleResize(): void;
1179
- declare const isModKey: (e: MouseEvent | KeyboardEvent) => boolean;
1180
- declare function addHighlightNodeEventListeners(): {
1181
- removeEventListeners: () => void;
1182
- } | undefined;
1183
-
1184
- type OnStyleChangeCallback = (options: {
1185
- activeNodeUID: string;
1186
- element: HTMLElement;
1187
- componentClassName: string;
1188
- }) => void;
1189
- declare class HighlightNodeManager {
1190
- activeNodeUID: string | null;
1191
- focusedNodeUID: string | null;
1192
- activeNodePath: Path | null;
1193
- focusedNodePath: Path | null;
1194
- hoveredNodeUID: string | null;
1195
- activeSlotUID: string | null;
1196
- styleGroup: string | null;
1197
- onStyleChangeCallbacks: Set<OnStyleChangeCallback>;
1198
- onActiveNodeChangeCallbacks: Set<(uid: string, path: Path) => void>;
1199
- visible: boolean;
1200
- constructor();
1201
- private setActiveNodeUID;
1202
- private setFocusedNodeUID;
1203
- setHoveredNode(uid: string): void;
1204
- setActiveSlotUID(uid: string | null): void;
1205
- resetActiveNode(): void;
1206
- resetFocusedNode(): void;
1207
- /**
1208
- * Subscribe to changes in the active node.
1209
- *
1210
- * @param callback - Function that will be called whenever the active node changes.
1211
- * The callback receives the UID of the newly active node as a parameter.
1212
- * @param options - Configuration options
1213
- * @param options.syncToExistingValue - When true, the callback will be immediately called
1214
- * with the current active node's UID. When false, the callback will only be called on future changes.
1215
- * Defaults to false.
1216
- *
1217
- * @example
1218
- * ```ts
1219
- * highlightNodeManager.onActiveNodeChange((uid) => {
1220
- * console.log('Active node changed to:', uid);
1221
- * }, { syncToExistingValue: true });
1222
- * ```
1223
- */
1224
- onActiveNodeChange(callback: (uid: string, path: Path) => void, options: {
1225
- syncToExistingValue: boolean;
1226
- }): void;
1227
- /**
1228
- * Unsubscribe from changes in the active node.
1229
- *
1230
- * @param callback - The callback function to unsubscribe.
1231
- *
1232
- * @example
1233
- * ```ts
1234
- * const onHighlight = (uid: string) => {
1235
- * console.log('Active node changed to:', uid);
1236
- * };
1237
- *
1238
- * highlightNodeManager.onActiveNodeChange(onHighlight);
1239
- * highlightNodeManager.unsubscribeFromActiveNodeChange(onHighlight);
1240
- * ```
1241
- */
1242
- unsubscribeFromActiveNodeChange(callback: (uid: string, path: Path) => void): void;
1243
- private notifyActiveNodeChange;
1244
- removeNodeHighligher(): void;
1245
- hideActiveNode(): void;
1246
- setStyleGroup: (styleGroup: string | null) => void;
1247
- subscribeToOnStyleChange: (callback: OnStyleChangeCallback) => void;
1248
- unsubscribeFromOnStyleChange: (callback: OnStyleChangeCallback) => void;
1249
- resetStyleGroup(): void;
1250
- setAndHighlightActiveNode(uid: string): void;
1251
- setAndHighlightFocusedNode(uid: string): void;
1252
- setAndHighlightHoveredNode(uid: string): void;
1253
- setAndHighlightStyleNode(styleGroup: string, uid: string): {
1254
- styles: undefined;
1255
- } | {
1256
- styles: Partial<CSSStyleDeclaration>;
1257
- };
1258
- highlightActiveNode(): void;
1259
- highlightFocusedNode(): void;
1260
- highlightNodeOnHover(): void;
1261
- highlightStyleNode(): void;
1262
- sendStylesToClient(): {
1263
- styles: undefined;
1264
- } | {
1265
- styles: Partial<CSSStyleDeclaration>;
1266
- };
1267
- highlightSlotNode(): void;
1268
- private getStylesObject;
1269
- private getHighlightStyleNodePayload;
1270
- getBoundingRectOfDisplayContents(element: HTMLElement): DOMRect | null;
1271
- private getNodeRect;
1272
- private getNodePath;
1273
- getAncestorsElements(currEl: HTMLElement): HTMLElement[];
1274
- }
1275
- declare const highlightNodeManager: HighlightNodeManager;
1276
-
1277
1948
  /**
1278
1949
  * Listens for URL changes inside the iframe (SPA navigations, pushState, replaceState, popstate)
1279
1950
  * and sends URL_CHANGE postMessage to the parent so the studio can sync the navbar URL.
@@ -1283,10 +1954,6 @@ declare function addUrlChangeListeners(): {
1283
1954
  removeEventListeners: () => void;
1284
1955
  } | undefined;
1285
1956
 
1286
- declare function addHighlightSpacingEventListeners(): {
1287
- removeEventListeners: () => void;
1288
- } | undefined;
1289
-
1290
1957
  declare function addBreakpointEventListeners(): {
1291
1958
  removeEventListeners: () => void;
1292
1959
  } | undefined;
@@ -1316,6 +1983,220 @@ declare class BreakpointManager {
1316
1983
  private syncBreakpointsWithStudio;
1317
1984
  }
1318
1985
 
1986
+ declare const findPath: (node: Descendant) => Path;
1987
+ declare const findPathForElement: (el: HTMLElement) => Path;
1988
+ declare const applyOperation: (editor: Node, operations: Operation[]) => Node;
1989
+
1990
+ declare function isCompositionBeingEdited(compositionUid: string): boolean;
1991
+
1992
+ declare const queryParam: {
1993
+ get(key: ComposableStudioQueryParamsKeys): string | null;
1994
+ has(key: ComposableStudioQueryParamsKeys): boolean;
1995
+ };
1996
+ declare const onlyParmasGenerator: (only: [string, string][]) => Record<string, string[]>;
1997
+
1998
+ declare const SECTION_COMPOSITIONS_KEY = "section_compositions";
1999
+ declare const TEMPLATE_FULL_ENTRY_KEY = "template_full_entry";
2000
+ declare const setTemplateEntryInDS: (dataSources: Record<string, any>, entry: unknown) => void;
2001
+ declare const setStaticEntryInDS: (dataSources: Record<string, any>, ct_uid: string, _entries: unknown) => void;
2002
+ /**
2003
+ * Counterpart to setStaticEntryInDS: drop a single resolved additional entry
2004
+ * from the contentstack data source bucket. Called when the author removes an
2005
+ * entry so the pruned bucket replaces the stale one on the next UPDATE_SPEC_DATA
2006
+ * push (which merges at the dataSources level); without it the removed entry's
2007
+ * data lingers and keeps rendering.
2008
+ */
2009
+ declare const removeStaticEntryFromDS: (dataSources: Record<string, any>, ct_uid: string, uid: string) => void;
2010
+ declare const batchFetchEntries: (sdk: StackSDK, entries: ICSEntryReference[]) => Promise<[string, CompositionEntry[]][]>;
2011
+ declare const getBindingStringForCS: (binding: BindingType) => string;
2012
+ type EntriesResponse<T> = {
2013
+ entries: T[];
2014
+ } | [T[]];
2015
+ declare function entriesFromResponse<T>(response: EntriesResponse<T>): T[];
2016
+
2017
+ declare const isInsideVisualBuilderFrame: () => boolean;
2018
+
2019
+ /**
2020
+ * Checks if the current context is inside an iframe.
2021
+ *
2022
+ * @returns {boolean} True if inside an iframe, false otherwise.
2023
+ */
2024
+ declare const isInsideIframe: () => boolean;
2025
+
2026
+ /**
2027
+ * How a host tells "there is no such page" from "we could not answer".
2028
+ *
2029
+ * A host rendering a composition answers one question per request: render this,
2030
+ * return 404, or return 5xx. Only one kind of failure is a 404, and getting it
2031
+ * wrong is expensive in one direction — a 404 is acted on permanently by crawlers
2032
+ * and caches, while a 5xx is retried.
2033
+ */
2034
+
2035
+ /**
2036
+ * Whether this failure means the page is not there.
2037
+ *
2038
+ * **This is the check to write, rather than `instanceof`.** Two copies of the
2039
+ * package in one dependency tree is an ordinary outcome of a transitive install,
2040
+ * and each copy has its own class object — so a prototype check returns false for
2041
+ * an error raised by the other copy. It fails silently and in the worst direction:
2042
+ * a genuinely missing page is reported as a server error, and the host serves a
2043
+ * 500 where it meant to serve a 404.
2044
+ *
2045
+ * A code is a string. It survives the package boundary, a structured-clone, a
2046
+ * serialisation to a log and back, and a second copy of the SDK.
2047
+ */
2048
+ declare function isCompositionNotFound(error: unknown): boolean;
2049
+ /**
2050
+ * The not-found subclass, for a host that would rather catch by type.
2051
+ *
2052
+ * It ships because catching by type is a reasonable thing to want, and because an
2053
+ * error's class is what a debugger and a stack trace show. It is not the
2054
+ * documented check: see {@link isCompositionNotFound} for why.
2055
+ *
2056
+ * Nothing constructs this directly. The diagnosis factory picks it whenever the
2057
+ * code it is given belongs to the not-found class, which is what keeps the class
2058
+ * and the predicate from ever disagreeing about the same error.
2059
+ */
2060
+ declare class CompositionNotFoundError extends ComposableStudioError {
2061
+ }
2062
+
2063
+ declare const evaluateCondition: (condition: Condition, data: any) => boolean;
2064
+ /**
2065
+ * Answers both questions a ConditionBlock has to ask: does this condition pass,
2066
+ * and what data should its children see.
2067
+ *
2068
+ * When the condition binds through a repeater, the bound value is projected
2069
+ * onto the repeater's context path so descendants resolve against the matched
2070
+ * branch. Everything off that path is shared by reference — the projection must
2071
+ * not deep-copy the spec, which is large.
2072
+ *
2073
+ * Lives here, with `evaluateCondition`, because all three renderers (runtime,
2074
+ * editor and RSC) need the identical answer and previously derived it
2075
+ * separately. `shouldRender` is evaluated against the UNPROJECTED data, which
2076
+ * is what all three did.
2077
+ */
2078
+ declare const resolveConditionScope: <T>(condition: Condition, data: T) => {
2079
+ shouldRender: boolean;
2080
+ scopedData: T;
2081
+ };
2082
+
2083
+ declare class RendererModeUtil {
2084
+ private searchParams;
2085
+ private isServerWithoutParams;
2086
+ constructor(searchParams?: URLSearchParams);
2087
+ /**
2088
+ * Checks if the current context is inside a Studio.
2089
+ *
2090
+ * @returns {boolean} True if inside a Studio, false otherwise.
2091
+ */
2092
+ isInsideStudioFrame(): boolean;
2093
+ /**
2094
+ * Checks if the current context is inside an iframe.
2095
+ *
2096
+ * @returns {boolean} True if inside an iframe, false otherwise.
2097
+ */
2098
+ isInsideIframe(): boolean;
2099
+ /**
2100
+ * Checks if the current context is inside a Visual Builder frame.
2101
+ *
2102
+ * Learn more about Visual Builder: {@link https://www.contentstack.com/docs/content-managers/visual-builder}
2103
+ *
2104
+ * @returns {boolean} True if inside a Visual Builder frame, false otherwise.
2105
+ */
2106
+ isInsideVisualBuilderFrame(): boolean;
2107
+ /**
2108
+ * Checks if the current context is editing a specific composition.
2109
+ *
2110
+ * It is useful when you have multiple compositions in a single page
2111
+ * and you want to know if the current context is editing a specific
2112
+ * composition.
2113
+ *
2114
+ * @param compositionUid - The UID of the composition to check.
2115
+ * @returns {boolean} True if editing the specified composition, false otherwise.
2116
+ */
2117
+ isEditingCurrentComposition(compositionUid: string): boolean;
2118
+ /**
2119
+ * Determines the current renderer mode for a given composition UID.
2120
+ *
2121
+ * - Returns "edit" if the current composition is being edited.
2122
+ * - Returns "show_edit_button" if inside the visual builder frame
2123
+ * or if the composition is not currently being edited but should show the edit button.
2124
+ * - Returns "preview" otherwise.
2125
+ *
2126
+ * This method is useful when you want to change the functionality of the
2127
+ * component based on where it is being rendered.
2128
+ *
2129
+ * @param compositionUid - The UID of the composition to check.
2130
+ * @returns RendererMode - The current mode (EDIT, SHOW_EDIT_BUTTON, or PREVIEW).
2131
+ */
2132
+ getMode(compositionUid: string): "preview" | "edit" | "show_edit_button";
2133
+ }
2134
+ /**
2135
+ * Module-level mode util backed by `window.location.search` (the browser URL).
2136
+ *
2137
+ * SSR CAUTION: this reads `window`, which does not exist on the server, so on the server
2138
+ * every method returns its production default (e.g. `isInsideStudioFrame()` -> false) for
2139
+ * ALL requests. It is correct ONLY in browser-only code (the editor render, hooks,
2140
+ * INIT_STUDIO). In server-reachable fetch code (studio-client's spec-fetch path) do NOT use
2141
+ * this: the answer is wrong on the server, and a single shared singleton cannot represent
2142
+ * per-request state across concurrent SSR requests anyway. There, use the request-scoped
2143
+ * helpers in `sdk.ts` (`isInStudio` / `isEditorFetch` / `readStudioParam`, built on
2144
+ * `getRequestSearchParams`), which read the forwarded request query on the server and fall
2145
+ * back to `window` on the client. See COMS-1554 for the AsyncLocalStorage proposal that would
2146
+ * remove this split and make this util correct everywhere.
2147
+ */
2148
+ declare const clientRendererModeUtil: RendererModeUtil;
2149
+ declare const serializeComputedStyles: (computedStyle: CSSStyleDeclaration) => Record<string, string>;
2150
+
2151
+ /**
2152
+ * Analyzes a UI spec (Node tree) and extracts all component types used.
2153
+ * Recursively traverses the spec to find all components.
2154
+ *
2155
+ * @param spec - The root node of the UI spec
2156
+ * @returns Set of component types used in the spec
2157
+ */
2158
+ declare function analyzeUsedComponents(spec: Node | null | undefined): Set<string>;
2159
+ /**
2160
+ * Analyzes multiple UI specs and returns the union of all component types used.
2161
+ * Useful for optimizing multi-composition loading.
2162
+ *
2163
+ * @param specs - Array of UI spec root nodes
2164
+ * @returns Set of all unique component types used across all specs
2165
+ */
2166
+ declare function analyzeMultipleSpecs(specs: (Node | null | undefined)[]): Set<string>;
2167
+ /**
2168
+ * Checks if a spec uses a specific component type.
2169
+ *
2170
+ * @param spec - The UI spec to check
2171
+ * @param componentType - The component type to look for
2172
+ * @returns true if the component is used in the spec
2173
+ */
2174
+ declare function specUsesComponent(spec: Node | null | undefined, componentType: string): boolean;
2175
+ /**
2176
+ * Gets component usage statistics for a spec.
2177
+ *
2178
+ * @param spec - The UI spec to analyze
2179
+ * @returns Map of component types to their usage count
2180
+ */
2181
+ declare function getComponentUsageStats(spec: Node | null | undefined): Map<string, number>;
2182
+
2183
+ type StudioEvent = (typeof POST_MESSAGE_EVENTS)[keyof typeof POST_MESSAGE_EVENTS];
2184
+ /**
2185
+ * Fire-and-forget send to the Studio parent frame.
2186
+ *
2187
+ * The postMessage bridge (`@contentstack/studio-messenger` →
2188
+ * `@contentstack/advanced-post-message`) is imported on demand rather than at
2189
+ * module scope. Importing it statically put the whole bridge into every bundle
2190
+ * that reached one of these modules — including a published site, where the
2191
+ * event manager is `undefined` outside the Studio iframe and every one of these
2192
+ * calls is already a no-op.
2193
+ *
2194
+ * Callers are all fire-and-forget today, so resolving the bridge a microtask
2195
+ * later is not observable. Anything that needs to *receive* events keeps a
2196
+ * static import: listener registration cannot be deferred safely.
2197
+ */
2198
+ declare function sendStudioEvent<TResponse = unknown>(event: StudioEvent, payload?: unknown): Promise<TResponse | undefined>;
2199
+
1319
2200
  interface GoogleFont {
1320
2201
  family: string;
1321
2202
  variants: string[];
@@ -1555,20 +2436,6 @@ declare function getEmbeddedEntryRenderer(): ((args: EmbeddedEntryRenderArgs) =>
1555
2436
  */
1556
2437
  declare function getEmbeddedAssetRenderer(): ((args: EmbeddedAssetRenderArgs) => string) | null;
1557
2438
 
1558
- declare const compositionSaveEventListener: () => {
1559
- unregister: () => void;
1560
- } | undefined;
1561
-
1562
- declare function openHiddenElementNotification(uid: string): void;
1563
- declare function closeHiddenElementNotification(uid: string): void;
1564
- declare function hiddenElementNotificationEventEmitter(): {
1565
- unregister: () => void;
1566
- } | undefined;
1567
-
1568
- declare function getNodeScreenshotEvent(): {
1569
- unregister: () => void;
1570
- } | undefined;
1571
-
1572
2439
  interface QuerySpec {
1573
2440
  contentType: string;
1574
2441
  sourceType?: "content_type" | "contentstack" | "taxonomy";
@@ -1658,7 +2525,7 @@ type UrlMetadataQueryMode = "match" | "existence";
1658
2525
  * stringifies it and passes it to `api.cma.entry.getAll` via the `query` param.
1659
2526
  *
1660
2527
  * In `existence` mode for `legacy_url` and `content_type_url_pattern` the
1661
- * object is `{ url: { $nin: ["", null] } }` regardless of `extractedVariables`.
2528
+ * object is `{ url: { $nin: [""], $ne: null } }` regardless of `extractedVariables`.
1662
2529
  */
1663
2530
  declare function buildUrlMetadataQueryObject(context: Pick<TemplateQueryContext, "compositionQuery" | "extractedVariables" | "url_source">, mode?: UrlMetadataQueryMode): Record<string, any>;
1664
2531
  /**
@@ -1729,5 +2596,5 @@ declare function rankUrlMatches(requestUrl: string, lightweightEntries: Lightwei
1729
2596
  */
1730
2597
  declare function shouldUseUrlMetadataPath(url_metadata?: Partial<CompositionUrlMetadataSerialized>): boolean;
1731
2598
 
1732
- export { BreakpointManager, COMPOSABLE_DATA_ATTRIBUTES, COMPOSABLE_STUDIO_EMITTED_EVENTS, COMPOSITION_PLACEMENT_OPTIONS, COMPOSITION_PREVIEW_URL_SOURCES, COMPOSITION_PREVIEW_URL_SOURCES_VALUES, ComposableStudioError, ComposableStudioErrors, DEFAULT_BREAKPOINTS, DEFAULT_COMPOSITION_PREVIEW_URL_SOURCE, EDGE_PADDING, ELEMENT_TO_NODE, ExpressionResolver, GOOGLE_FONT_API, INCLUDE_DEPTH_COUNT, MAX_SCROLL_SPEED, NODE_TO_ELEMENT, NODE_TO_PARENT, NODE_TO_PATH_NODE, QueryExecutor, RendererMode, RendererModeUtil, SCHEMA_VERSION, SCROLL_INTERVAL, SDK_VERSION, SECTION_COMPOSITIONS_KEY, STUDIO_CANVAS_QUERY_PARAM, STUDIO_MODE_HTML_CLASS, TEMPLATE_FULL_ENTRY_KEY, URL_PATTERN_DATE_VARIABLES, URL_PATTERN_METADATA_FIELDS, URL_PATTERN_METADATA_FIELDS_VALUES, URL_PATTERN_VARIABLE_TYPES, addBreakpointEventListeners, addContextMenuEventListeners, addHighlightNodeEventListeners, addHighlightSpacingEventListeners, addUrlChangeListeners, analyzeMultipleSpecs, analyzeUsedComponents, applyOperation, batchFetchEntries, buildSectionScopedData, buildTemplateQuery, buildUrlMetadataQueryObject, calculateDynamicSpeed, clientRendererModeUtil, closeHiddenElementNotification, compileUrlPattern, composableStudioEventEmitter, compositionSaveEventListener, computePatternSpecificity, createClassNameUid, createEmbeddedEntryConversion, studioSdk as default, defaultAssetRender, detectStudioMode, dndEventListener, dndManager, entriesFromResponse, evaluateCondition, extractHtmlRteRefs, extractJsonRteRefs, fetchEmbeddedEntries, findNearestBuilderNode, findNearestSlotNode, findPath, findPathForElement, getBindingStringForCS, getComponentUsageStats, getComposableElement, getCompositionMetadata, getComputedStyles, getDefaultConfig, getEmbeddedAssetRenderer, getEmbeddedEntryRenderer, getHitboxDetails, getHitboxDirection, getJSONRTE, getNodeScreenshotEvent, getScrollableParent, getSeoMetadataPure, handleOnScroll, handleResize, hasSlotDropzone, hiddenElementNotificationEventEmitter, highlightNodeManager, isBrowser, isCompositionBeingEdited, isInsideIframe, isInsideVisualBuilderFrame, isModKey, isStudioCanvas, isStudioEditorMode, loadGoogleFont, markStudioMode, matchCompositionUrl, matchUrlPattern, onlyParmasGenerator, openHiddenElementNotification, parseStringValue, parseUrlMetadata, preProcessStaticValues, queryParam, rankUrlMatches, registerEmbeddedEntryRenderer, registerJSONRTE, registerRTERenderer, removeStaticEntryFromDS, renderMetadataToHtml, resolveByUrlSource, serializeComputedStyles, serializeEvent, setStaticEntryInDS, setTemplateEntryInDS, shouldExtractTaxonomies, shouldUseUrlMetadataPath, specUsesComponent, studioSdk, toggleNodeVisible, updateStyleOnStyleNodeChange };
1733
- export type { ClientEditableNodeInternalAttributes, ClientPreviewNodeInternalAttributes, ComposableStudioErrorDetails, ComposableStudioLightSdk, CompositionEntry, CompositionEntryIncompleteUi, CompositionFetcher, CompositionMetaTag, CompositionMetadata, CompositionPlacement, CompositionPreviewUrlSource, CompositionPreviewUrlSourceValues, CompositionQueryForSSR, CompositionQueryForSSRInput, CompositionQueryOptions, CompositionUrlMetadata, CompositionUrlMetadataSerialized, CompositionUrlQueries, Config, ConnectedEntryResult, DateVariableKey, EmbeddedAssetRenderArgs, EmbeddedEntryConversionOptions, EmbeddedEntryRenderArgs, EmittedEvents, ExtractedUrlPatternVariables, ExtractedUrlVariables, FetchCompositionContext, FetchTemplateEntryContext, FieldValue, FontVariants, GetCompositionMetadataOptions, GoogleFont, HiddenElementNotificationHandler, LightConfig, LightweightCompositionEntry, MetaProp, ParsedStringResult, PatternMatchResult, QueryExecutionOptions, QueryResult, QuerySpec, QueryState, RTEConfig, RankingResult, ReferenceFieldValue, RenderableCompositionEntry, ResolvedEmbeddedEntry, ResolvedQueryOptions, RuntimeContext, SearchQueryInput, SectionCompositionEntry, SeoMetadata, StudioComponentFetchOptions, StudioComponentSpecOptions, StudioMode, StudioSdk, StudioSpec, TemplateEntryFetcher, TemplateQueryContext, TroubleshootingInfo, URLSearchParamsString, UrlMatchDiagnostic, UrlMetadataQueryMode, UrlPatternMetadataField, UrlPatternMetadataFieldValue, UserConfig };
2599
+ export { BreakpointManager, COMPOSABLE_DATA_ATTRIBUTES, COMPOSABLE_STUDIO_EMITTED_EVENTS, COMPOSITION_PLACEMENT_OPTIONS, COMPOSITION_PREVIEW_URL_SOURCES, COMPOSITION_PREVIEW_URL_SOURCES_VALUES, ComposableStudioError, CompositionNotFoundError, DEFAULT_BREAKPOINTS, DEFAULT_COMPOSITION_PREVIEW_URL_SOURCE, ELEMENT_TO_NODE, ExpressionResolver, GOOGLE_FONT_API, INCLUDE_DEPTH_COUNT, NODE_TO_ELEMENT, NODE_TO_PARENT, NODE_TO_PATH_NODE, QueryExecutor, RendererMode, RendererModeUtil, SCHEMA_VERSION, SDK_VERSION, SECTION_COMPOSITIONS_KEY, STUDIO_CANVAS_QUERY_PARAM, STUDIO_MODE_HTML_CLASS, StudioErrorClass, StudioErrorCode, TEMPLATE_BINDING_TYPE, TEMPLATE_FETCH_ROOT_KEY, TEMPLATE_FULL_ENTRY_KEY, URL_PATTERN_DATE_VARIABLES, URL_PATTERN_METADATA_FIELDS, URL_PATTERN_METADATA_FIELDS_VALUES, URL_PATTERN_VARIABLE_TYPES, addBreakpointEventListeners, addContextMenuEventListeners, addUrlChangeListeners, analyzeMultipleSpecs, analyzeUsedComponents, applyOperation, batchFetchEntries, buildSectionScopedData, buildStudioErrorContext, buildTemplateQuery, buildUrlMetadataQueryObject, clientRendererModeUtil, compileUrlPattern, composableStudioEventEmitter, computePatternSpecificity, createClassNameUid, createEmbeddedEntryConversion, createStudioError, studioSdk as default, defaultAssetRender, derivePlacementIncludePaths, detectStudioMode, entriesFromResponse, evaluateCondition, extractHtmlRteRefs, extractJsonRteRefs, fetchEmbeddedEntries, fetchRootFromBinding, findNearestBuilderNode, findNearestSlotNode, findPath, findPathForElement, flattenPath, getBindingStringForCS, getComponentUsageStats, getComposableElement, getComposableElements, getCompositionMetadata, getComputedStyles, getDefaultConfig, getEmbeddedAssetRenderer, getEmbeddedEntryRenderer, getHitboxDetails, getHitboxDirection, getJSONRTE, getRootBindingPath, getRootScopePath, getSeoMetadataPure, hasSlotDropzone, isBrowser, isCompositionBeingEdited, isCompositionNotFound, isDataRootCleared, isInsideIframe, isInsideVisualBuilderFrame, isPageAbsoluteField, isSetupFault, isStudioCanvas, isStudioEditorMode, isTemplateFetchRoot, isTemplateRootBinding, loadGoogleFont, markStudioMode, matchCompositionUrl, matchUrlPattern, nestPath, onlyParmasGenerator, parseEntryFetchRootKey, parseStringValue, parseUrlMetadata, preProcessStaticValues, queryParam, rankUrlMatches, registerEmbeddedEntryRenderer, registerJSONRTE, registerRTERenderer, removeStaticEntryFromDS, renderMetadataToHtml, resolveByUrlSource, resolveConditionScope, resolveInstanceRootBinding, resolveLegacySelectedField, resolveLegacySelectedFieldWithProvenance, resolveMatchedSchema, sectionDataEqual, sendStudioEvent, serializeComputedStyles, serializeEvent, setStaticEntryInDS, setTemplateEntryInDS, shouldExtractTaxonomies, shouldUseUrlMetadataPath, specUsesComponent, splitFieldPath, studioSdk, synthesizeTemplateRootBinding, templateFetchRoot, toggleNodeVisible, updateStyleOnStyleNodeChange };
2600
+ export type { ClientEditableNodeInternalAttributes, ClientPreviewNodeInternalAttributes, ComposableStudioErrorDetails, ComposableStudioLightSdk, CompositionEntry, CompositionEntryIncompleteUi, CompositionFetcher, CompositionMetaTag, CompositionMetadata, CompositionPlacement, CompositionPreviewUrlSource, CompositionPreviewUrlSourceValues, CompositionQueryForSSR, CompositionQueryForSSRInput, CompositionQueryOptions, CompositionUrlMetadata, CompositionUrlMetadataSerialized, CompositionUrlQueries, Config, ConnectedEntryResult, DateVariableKey, EmbeddedAssetRenderArgs, EmbeddedEntryConversionOptions, EmbeddedEntryRenderArgs, EmittedEvents, ExtractedUrlPatternVariables, ExtractedUrlVariables, FetchCompositionContext, FetchRoot, FetchTemplateEntryContext, FieldValue, FontVariants, GetCompositionMetadataOptions, GoogleFont, HiddenElementNotificationHandler, LightConfig, LightweightCompositionEntry, LinkedSchemasLookup, MetaProp, ParsedStringResult, PatternMatchResult, QueryExecutionOptions, QueryResult, QuerySpec, QueryState, RTEConfig, RankingResult, ReferenceFieldValue, RenderableCompositionEntry, ResolvedEmbeddedEntry, ResolvedQueryOptions, RuntimeContext, SearchQueryInput, SectionBindingOverride, SectionCompositionEntry, SectionDataBinding, SectionInstanceNode, SelectedFieldProvenance, SeoMetadata, StudioComponentFetchOptions, StudioComponentSpecOptions, StudioMode, StudioSdk, StudioSpec, TemplateEntryFetcher, TemplateQueryContext, TroubleshootingInfo, URLSearchParamsString, UrlMatchDiagnostic, UrlMetadataQueryMode, UrlPatternMetadataField, UrlPatternMetadataFieldValue, UserConfig };