@contentstack/studio-client 1.6.0 → 1.7.1

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 (86) hide show
  1. package/dist/breakpoints/BreakpointManager.js +18 -5
  2. package/dist/breakpoints/BreakpointManager.js.map +1 -1
  3. package/dist/canvas/canvas.utils.js +1 -1
  4. package/dist/canvas/canvas.utils.js.map +1 -1
  5. package/dist/composable-studio/build-scoped-data.js +170 -0
  6. package/dist/composable-studio/build-scoped-data.js.map +1 -0
  7. package/dist/composable-studio/collect-data-needs.js +344 -0
  8. package/dist/composable-studio/collect-data-needs.js.map +1 -0
  9. package/dist/composable-studio/composition-metadata.js +75 -0
  10. package/dist/composable-studio/composition-metadata.js.map +1 -0
  11. package/dist/composable-studio/composition-placement.types.js +7 -0
  12. package/dist/composable-studio/composition-placement.types.js.map +1 -0
  13. package/dist/composable-studio/sdk.js +2169 -192
  14. package/dist/composable-studio/sdk.js.map +1 -1
  15. package/dist/composable-studio/studio-intelligence.manager.js +2 -12
  16. package/dist/composable-studio/studio-intelligence.manager.js.map +1 -1
  17. package/dist/config/default-config.js +1 -0
  18. package/dist/config/default-config.js.map +1 -1
  19. package/dist/config/stack-sdk-wrapper.js +86 -0
  20. package/dist/config/stack-sdk-wrapper.js.map +1 -1
  21. package/dist/context-menu/context-menu.js +1 -0
  22. package/dist/context-menu/context-menu.js.map +1 -1
  23. package/dist/dnd/dnd-manager.js +1 -0
  24. package/dist/dnd/dnd-manager.js.map +1 -1
  25. package/dist/highlight-node/highlight-node-manager.js +1 -0
  26. package/dist/highlight-node/highlight-node-manager.js.map +1 -1
  27. package/dist/highlight-node/highlight-node.js +5 -1
  28. package/dist/highlight-node/highlight-node.js.map +1 -1
  29. package/dist/index.d.ts +1033 -294
  30. package/dist/index.js +13 -2
  31. package/dist/index.js.map +1 -1
  32. package/dist/json-rte-registry/embedded-entry-conversion.js +186 -0
  33. package/dist/json-rte-registry/embedded-entry-conversion.js.map +1 -0
  34. package/dist/json-rte-registry/index.js +73 -33
  35. package/dist/json-rte-registry/index.js.map +1 -1
  36. package/dist/json-rte-registry/stack-sdk-store.js +10 -0
  37. package/dist/json-rte-registry/stack-sdk-store.js.map +1 -0
  38. package/dist/query/query-executor.js +182 -27
  39. package/dist/query/query-executor.js.map +1 -1
  40. package/dist/studio-internal/dist/utils/section-slot-walker.js +63 -0
  41. package/dist/studio-internal/dist/utils/section-slot-walker.js.map +1 -0
  42. package/dist/{packages/studio-internal → studio-internal}/dist/utils/spec-compression.js +1 -1
  43. package/dist/studio-internal/dist/utils/spec-compression.js.map +1 -0
  44. package/dist/url-metadata/build-template-query.js +124 -0
  45. package/dist/url-metadata/build-template-query.js.map +1 -0
  46. package/dist/url-metadata/parse-url-metadata.js +75 -0
  47. package/dist/url-metadata/parse-url-metadata.js.map +1 -0
  48. package/dist/url-metadata/rank-url-matches.js +100 -0
  49. package/dist/url-metadata/rank-url-matches.js.map +1 -0
  50. package/dist/url-metadata/select-url-winner.js +45 -0
  51. package/dist/url-metadata/select-url-winner.js.map +1 -0
  52. package/dist/url-metadata/shouldUseUrlMetadataPath.js +22 -0
  53. package/dist/url-metadata/shouldUseUrlMetadataPath.js.map +1 -0
  54. package/dist/url-metadata/types.js +50 -0
  55. package/dist/url-metadata/types.js.map +1 -0
  56. package/dist/url-metadata/url-pattern-matcher.js +311 -0
  57. package/dist/url-metadata/url-pattern-matcher.js.map +1 -0
  58. package/dist/utils/build-composition-fetch-query.js +19 -0
  59. package/dist/utils/build-composition-fetch-query.js.map +1 -0
  60. package/dist/utils/canvas.js +14 -0
  61. package/dist/utils/canvas.js.map +1 -1
  62. package/dist/utils/constants.js +19 -2
  63. package/dist/utils/constants.js.map +1 -1
  64. package/dist/utils/convertCompositionQueryInputToCompositionQuery.js +11 -1
  65. package/dist/utils/convertCompositionQueryInputToCompositionQuery.js.map +1 -1
  66. package/dist/utils/editor-mode.js +142 -0
  67. package/dist/utils/editor-mode.js.map +1 -0
  68. package/dist/utils/editor-utils.js +9 -0
  69. package/dist/utils/editor-utils.js.map +1 -1
  70. package/dist/utils/is-composition-being-edited.js.map +1 -1
  71. package/dist/utils/query-param.js +1 -1
  72. package/dist/utils/query-param.js.map +1 -1
  73. package/dist/utils/reference_fetcher.js +61 -6
  74. package/dist/utils/reference_fetcher.js.map +1 -1
  75. package/dist/utils/sdk.js +16 -1
  76. package/dist/utils/sdk.js.map +1 -1
  77. package/dist/utils/spec-analyzer.js +21 -4
  78. package/dist/utils/spec-analyzer.js.map +1 -1
  79. package/package.json +8 -10
  80. package/dist/get-composition-from-slug/get-composition-from-slug.js +0 -59
  81. package/dist/get-composition-from-slug/get-composition-from-slug.js.map +0 -1
  82. package/dist/node_modules/fflate/esm/browser.js +0 -384
  83. package/dist/node_modules/fflate/esm/browser.js.map +0 -1
  84. package/dist/packages/studio-internal/dist/utils/spec-compression.js.map +0 -1
  85. package/dist/utils/get-url-patterns.js +0 -40
  86. package/dist/utils/get-url-patterns.js.map +0 -1
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import * as _contentstack_studio_internal from '@contentstack/studio-internal';
2
- import { Node, PathNode, Path, Operation, Descendant, BindingType, Condition, NodeStyles } from '@contentstack/studio-internal';
2
+ import { Node, BindingType, PathNode, Operation, Descendant, Path, Condition, NodeStyles } from '@contentstack/studio-internal';
3
3
  import * as _contentstack_studio_registry from '@contentstack/studio-registry';
4
- import { RawStaticValue, ICSEntryReference, StudioSpecData, StaticValue, BreakpointInput, Breakpoint } from '@contentstack/studio-registry';
4
+ import { RawStaticValue, ICSEntryReference, StudioSpecData, DataSources, SectionScopedDataSources, StaticValue, BreakpointInput, Breakpoint } from '@contentstack/studio-registry';
5
5
  export { Breakpoint } from '@contentstack/studio-registry';
6
6
  import * as _contentstack_studio_messenger from '@contentstack/studio-messenger';
7
7
  import { CompositionQuery, CompositionQueryInput, ComposableStudioQueryParams, ComposableStudioQueryParamsKeys, HiddenElementNotificationEventData, POST_MESSAGE_EVENTS } from '@contentstack/studio-messenger';
@@ -14,6 +14,12 @@ export { ActiveBreakpointEventPayload, BaseHighlightEventPayload, ChangeActiveSt
14
14
  import { EventEmitter } from 'eventemitter3';
15
15
  import { IJsonToHtmlOptions } from '@contentstack/json-rte-serializer';
16
16
 
17
+ declare const COMPOSITION_PLACEMENT_OPTIONS: {
18
+ readonly PAGE: "page";
19
+ readonly SECTION: "section";
20
+ };
21
+ type CompositionPlacement = (typeof COMPOSITION_PLACEMENT_OPTIONS)[keyof typeof COMPOSITION_PLACEMENT_OPTIONS];
22
+
17
23
  type DeepRequired<T> = Required<{
18
24
  [K in keyof T]: T[K] extends Required<T[K]> ? T[K] : DeepRequired<T[K]>;
19
25
  }>;
@@ -45,9 +51,9 @@ declare const userConfigSchema: z.ZodObject<{
45
51
  fetchComposition: z.ZodOptional<z.ZodType<CompositionFetcher, z.ZodTypeDef, CompositionFetcher>>;
46
52
  fetchTemplateEntry: z.ZodOptional<z.ZodType<TemplateEntryFetcher, z.ZodTypeDef, TemplateEntryFetcher>>;
47
53
  }, "strip", z.ZodTypeAny, {
54
+ locale?: string | undefined;
48
55
  contentTypeUid?: string | undefined;
49
56
  stackSdk?: any;
50
- locale?: string | undefined;
51
57
  cslp?: {
52
58
  appendTags?: boolean | undefined;
53
59
  } | undefined;
@@ -58,9 +64,9 @@ declare const userConfigSchema: z.ZodObject<{
58
64
  fetchComposition?: CompositionFetcher | undefined;
59
65
  fetchTemplateEntry?: TemplateEntryFetcher | undefined;
60
66
  }, {
67
+ locale?: string | undefined;
61
68
  contentTypeUid?: string | undefined;
62
69
  stackSdk?: any;
63
- locale?: string | undefined;
64
70
  cslp?: {
65
71
  appendTags?: boolean | undefined;
66
72
  } | undefined;
@@ -87,6 +93,8 @@ declare class StackSDK {
87
93
  only?: [string, string][];
88
94
  variantAlias?: string;
89
95
  locale?: string;
96
+ branch?: string;
97
+ environment?: string;
90
98
  query?: Record<string, any>;
91
99
  }): any;
92
100
  entryQuery(contentTypeUid: string, entryUID: string, options?: {
@@ -103,11 +111,28 @@ declare class StackSDK {
103
111
  enable?: boolean;
104
112
  } | undefined;
105
113
  get locale(): string | undefined;
114
+ /**
115
+ * Create a taxonomy query - mirrors ctQuery style for consistency
116
+ * Prefers stack.Taxonomies() but falls back to ctQuery approach
117
+ */
118
+ taxonomies(): any;
119
+ /**
120
+ * Apply taxonomy filters to a query using taxonomy methods when available,
121
+ * otherwise fall back to ctQuery + where approach
122
+ */
123
+ applyTaxonomyFilters(query: any, taxonomyConstraints: Record<string, string>): any;
106
124
  }
107
125
 
108
126
  interface Config extends DeepRequired<Omit<UserConfig, "stackSdk" | "locale" | "fetchComposition" | "fetchTemplateEntry">> {
109
127
  stackSdk: StackSDK;
110
128
  locale?: string;
129
+ /**
130
+ * Variant alias the SDK should use for all data fetches. Not part of the
131
+ * public `UserConfig` — set by Studio (when running inside a Studio iframe)
132
+ * via the `cs-variant-alias` URL search param so the SDK can render and
133
+ * fetch references in the variant Studio picked.
134
+ */
135
+ variantAlias?: string;
111
136
  fetchComposition?: CompositionFetcher;
112
137
  fetchTemplateEntry?: TemplateEntryFetcher;
113
138
  }
@@ -117,7 +142,24 @@ type UserConfig = z.infer<typeof userConfigSchema>;
117
142
  declare function getDefaultConfig(): Config;
118
143
 
119
144
  declare const isBrowser: () => boolean;
120
- declare const INCLUDE_DEPTH_COUNT = 4;
145
+ /**
146
+ * Depth used for `includeAllDepth` when fetching entries with referenced content.
147
+ *
148
+ * NOTE: This is currently a workaround, not a real fix.
149
+ *
150
+ * The CDA enforces a hard limit of 100 on the number of include reference paths
151
+ * it will process. Exceeding it returns:
152
+ * { error_code: 141, error_message: "The include reference paths processing
153
+ * limit has been exceeded", errors: { include: ["should not be greater than 100"] } }
154
+ *
155
+ * History: started at 5 (worked), hit the 141 error, dropped to 4 (worked again),
156
+ * hit the same error, now at 3. Each step only treats the symptom — the real cause
157
+ * (why our reference path count blows past 100 at higher depths) is still unknown.
158
+ *
159
+ * TODO(COMS-1520): investigate the root cause and replace this magic number with a
160
+ * proper fix instead of lowering the depth each time the limit is hit.
161
+ */
162
+ declare const INCLUDE_DEPTH_COUNT = 3;
121
163
  declare const SDK_VERSION: string;
122
164
  declare const SCHEMA_VERSION = "1.0.0";
123
165
  declare const COMPOSABLE_DATA_ATTRIBUTES: {
@@ -156,6 +198,186 @@ declare const getHitboxDetails: (event: MouseEvent) => HitboxDetails;
156
198
  declare const getComputedStyles: (event: MouseEvent) => Record<string, string> | null;
157
199
  declare const serializeEvent: (event: MouseEvent) => SerializedEvent;
158
200
 
201
+ /**
202
+ * Composition preview URL source types for CMS field `url_metadata.url_source`
203
+ *
204
+ * These constants define how the composition's preview URL is derived:
205
+ * - From custom preview URLs
206
+ * - From content type URL patterns
207
+ * - From default URL patterns
208
+ * - From user-specified patterns
209
+ * - From legacy URL configuration
210
+ */
211
+ declare const COMPOSITION_PREVIEW_URL_SOURCES: {
212
+ readonly CUSTOM_PREVIEW_URL: "custom_preview_url";
213
+ readonly CONTENT_TYPE_URL_PATTERN: "content_type_url_pattern";
214
+ readonly DEFAULT_URL_PATTERN: "default_url_pattern";
215
+ readonly USER_SPECIFIED_PATTERN: "user_specified_pattern";
216
+ readonly LEGACY_URL: "legacy_url";
217
+ };
218
+ declare const COMPOSITION_PREVIEW_URL_SOURCES_VALUES: ("custom_preview_url" | "content_type_url_pattern" | "default_url_pattern" | "user_specified_pattern" | "legacy_url")[];
219
+ type CompositionPreviewUrlSource = typeof COMPOSITION_PREVIEW_URL_SOURCES;
220
+ type CompositionPreviewUrlSourceValues = CompositionPreviewUrlSource[keyof CompositionPreviewUrlSource];
221
+ declare const DEFAULT_COMPOSITION_PREVIEW_URL_SOURCE: "legacy_url";
222
+ /**
223
+ * URL queries structure - mirrors UI CompositionUrlQueries but excludes 'where' at runtime
224
+ * 'where' is present in the UI type but explicitly ignored in the SDK implementation
225
+ */
226
+ interface CompositionUrlQueries {
227
+ include: string[];
228
+ only: Record<string, string[]>;
229
+ where: Record<string, any>;
230
+ }
231
+ /**
232
+ * URL metadata structure - mirrors UI CompositionUrlMetadata
233
+ */
234
+ interface CompositionUrlMetadata {
235
+ url_source: CompositionPreviewUrlSourceValues;
236
+ url_queries: CompositionUrlQueries;
237
+ }
238
+ /** URL metadata as stored on CMS entries — `url_queries` is a JSON string */
239
+ type CompositionUrlMetadataSerialized = Omit<CompositionUrlMetadata, "url_queries"> & {
240
+ url_queries: string;
241
+ };
242
+ declare const URL_PATTERN_VARIABLE_TYPES: {
243
+ readonly ENTRY: "entry";
244
+ readonly TAXONOMY: "taxonomy";
245
+ readonly METADATA: "metadata";
246
+ readonly DATE: "date";
247
+ readonly WILDCARD: "wildcard";
248
+ };
249
+ declare const URL_PATTERN_METADATA_FIELDS: {
250
+ readonly COMPOSITION_UID: "composition_uid";
251
+ readonly CONTENT_TYPE_UID: "content_type_uid";
252
+ readonly ENVIRONMENT: "environment";
253
+ readonly LOCALE: "locale";
254
+ readonly BRANCH: "branch";
255
+ };
256
+ declare const URL_PATTERN_METADATA_FIELDS_VALUES: ("composition_uid" | "content_type_uid" | "environment" | "locale" | "branch")[];
257
+ type UrlPatternMetadataField = typeof URL_PATTERN_METADATA_FIELDS;
258
+ type UrlPatternMetadataFieldValue = (typeof URL_PATTERN_METADATA_FIELDS_VALUES)[number];
259
+ declare const URL_PATTERN_DATE_VARIABLES: {
260
+ readonly YEAR: "entry_created_date:year";
261
+ readonly YEAR_SHORT: "entry_created_date:year_short";
262
+ readonly MONTH: "entry_created_date:month";
263
+ readonly MONTH_NAME: "entry_created_date:monthname";
264
+ readonly MONTH_NAME_SHORT: "entry_created_date:monthname_short";
265
+ readonly DAY: "entry_created_date:day";
266
+ };
267
+ type DateVariableKey = (typeof URL_PATTERN_DATE_VARIABLES)[keyof typeof URL_PATTERN_DATE_VARIABLES];
268
+ /**
269
+ * Reference field value structure for nested reference objects
270
+ * Used when URL patterns contain reference fields like {{entry.reference.title}}
271
+ */
272
+ type ReferenceFieldValue = Record<string, string | number | boolean>;
273
+ /**
274
+ * Union type for field values - supports both simple values and reference objects
275
+ * - Simple values: "My Title", 123, true
276
+ * - Reference values: { "title": "Ref Title", "group.field": "value" }
277
+ */
278
+ type FieldValue = string | number | boolean | ReferenceFieldValue;
279
+ /**
280
+ * Variables extracted from URL pattern matching
281
+ */
282
+ interface ExtractedUrlPatternVariables {
283
+ /** Entry field variables - supports both simple values and reference objects */
284
+ fields: Record<string, FieldValue>;
285
+ /** Taxonomy variables like { category: "tech", tags: "javascript" } */
286
+ taxonomies: Record<string, string>;
287
+ /** Fixed metadata variables (not used for querying but tracked for future) */
288
+ metadata: {
289
+ composition_uid?: string;
290
+ content_type_uid?: string;
291
+ environment?: string;
292
+ locale?: string;
293
+ branch?: string;
294
+ };
295
+ /** Date pattern variables from content type URL patterns - strongly typed */
296
+ dateVariables: Partial<Record<DateVariableKey, string>>;
297
+ /** Count of literal (non-placeholder) characters for specificity scoring */
298
+ literalCharCount: number;
299
+ /**
300
+ * The full decoded request path that matched this pattern. Used to build the
301
+ * `{{entry.url}}` full-path `$or` branch (match the `url` field against the
302
+ * whole path, not just the captured segment).
303
+ */
304
+ requestPath?: string;
305
+ }
306
+ /**
307
+ * @deprecated Use ExtractedUrlPatternVariables instead
308
+ * Kept for backward compatibility during migration
309
+ */
310
+ type ExtractedUrlVariables = ExtractedUrlPatternVariables;
311
+ /**
312
+ * Result from pattern matching a single URL against a composition URL pattern
313
+ */
314
+ interface PatternMatchResult {
315
+ matched: boolean;
316
+ composable_uid: string;
317
+ /** Only present if matched is true */
318
+ variables?: ExtractedUrlPatternVariables;
319
+ connected_content_type?: string;
320
+ }
321
+ /**
322
+ * Result from ranking multiple patterns against a request URL
323
+ */
324
+ interface RankingResult {
325
+ /** Array of composable_uid strings tied at the highest specificity */
326
+ composableUids: string[];
327
+ /** Array of freeform composition UIDs tied at highest specificity */
328
+ freeformComposableUids: string[];
329
+ /** Array of templated composition UIDs tied at highest specificity */
330
+ templatedComposableUids: string[];
331
+ /** The highest specificity score achieved */
332
+ specificity: number;
333
+ /** All pattern match results for potential future tie-breaking */
334
+ matches: PatternMatchResult[];
335
+ /**
336
+ * Every match across ALL specificity tiers (not just the top tier), each with
337
+ * its score — used for Studio resolution diagnostics so a lower-specificity
338
+ * match of the edited composition is still reported.
339
+ */
340
+ allMatches: UrlMatchDiagnostic[];
341
+ }
342
+ /**
343
+ * Outcome of the entry-existence probe for a candidate during URL resolution
344
+ * (top-tier tie disambiguation):
345
+ * - "found": the connected content type owns a matching entry (a valid winner).
346
+ * - "absent": the content type was queried but owns no matching entry.
347
+ * - "not-checked": no probe ran — not a tie, or a freeform/lower-tier candidate.
348
+ */
349
+ type ConnectedEntryResult = "found" | "absent" | "not-checked";
350
+ /** A single URL match surfaced for diagnostics — lightweight, includes specificity. */
351
+ interface UrlMatchDiagnostic {
352
+ composable_uid: string;
353
+ url?: string;
354
+ specificity: number;
355
+ connected_content_type?: string;
356
+ /** Entry-existence probe outcome; undefined until the probe stamps it. */
357
+ connectedEntryResult?: ConnectedEntryResult;
358
+ }
359
+ /**
360
+ * Lightweight composition entry used in the metadata query phase.
361
+ */
362
+ interface LightweightCompositionEntry {
363
+ composable_uid: string;
364
+ url: string;
365
+ url_metadata?: Partial<CompositionUrlMetadataSerialized>;
366
+ connected_content_type?: string;
367
+ }
368
+ /**
369
+ * Query building context for template entry resolution
370
+ */
371
+ interface TemplateQueryContext {
372
+ compositionQuery: {
373
+ url?: string;
374
+ };
375
+ extractedVariables: ExtractedUrlPatternVariables;
376
+ parsedUrlQueries: CompositionUrlQueries;
377
+ connectedContentType: string;
378
+ url_source: CompositionPreviewUrlSourceValues;
379
+ }
380
+
159
381
  type StudioSdk = ReturnType<typeof studioSdk.init>;
160
382
  type ComposableStudioLightSdk = ReturnType<typeof studioSdk.lightInit>;
161
383
  /**
@@ -174,17 +396,34 @@ interface CompositionEntry {
174
396
  created_at: string;
175
397
  updated_at: string;
176
398
  url?: string;
177
- place_composition_as?: "page" | "section";
399
+ place_composition_as?: CompositionPlacement;
400
+ linked_schemas?: {
401
+ content_type_uid: string;
402
+ selected_field?: string;
403
+ display_name?: string;
404
+ }[];
178
405
  ui: CompositionEntryIncompleteUi;
179
406
  data_sources: string;
180
407
  static_value?: RawStaticValue;
181
408
  symbols?: ICSEntryReference[];
409
+ url_metadata?: CompositionUrlMetadataSerialized;
410
+ /**
411
+ * CMA-level references to section composition entries placed inside this
412
+ * composition's UI. When fetched with `include[]=linked_sections`, this
413
+ * carries the resolved section entries inline.
414
+ */
415
+ linked_sections?: ICSEntryReference[] | CompositionEntry[];
182
416
  }
183
417
  interface SymbolEntry extends Omit<CompositionEntry, "ui"> {
184
418
  ui_preview?: BaseAsset;
185
419
  ui: Node;
186
420
  tags: ["symbol"];
187
421
  }
422
+ interface SectionCompositionEntry extends Omit<CompositionEntry, "ui"> {
423
+ ui_preview?: BaseAsset;
424
+ ui: Node;
425
+ }
426
+ type RenderableCompositionEntry = CompositionEntry | SectionCompositionEntry;
188
427
  /**
189
428
  * This spec is the one we get from our `fetchSpec()` method.
190
429
  * It contains all the information we can derive from the compositionEntry.
@@ -193,9 +432,19 @@ interface SymbolEntry extends Omit<CompositionEntry, "ui"> {
193
432
  interface StudioSpec {
194
433
  data: StudioSpecData;
195
434
  ui: Node;
196
- compositionEntry: CompositionEntry;
435
+ compositionEntry: RenderableCompositionEntry;
197
436
  symbols?: SymbolEntry[];
437
+ sectionCompositions?: SectionCompositionEntry[];
198
438
  config?: LightConfig;
439
+ /**
440
+ * Studio-only resolution diagnostics for the URL metadata path. Present when
441
+ * the composition was resolved by URL ranking; carries every candidate
442
+ * considered with its specificity. Consumed by the React hook to build the
443
+ * `SDK_DIAGNOSTICS` post-message. Not part of the rendered output.
444
+ */
445
+ urlResolution?: {
446
+ shortlisted: UrlMatchDiagnostic[];
447
+ };
199
448
  }
200
449
  type SearchQueryInput = (Partial<ComposableStudioQueryParams> & {
201
450
  [key: string]: string | string[] | undefined;
@@ -368,6 +617,9 @@ interface SeoMetadata {
368
617
  pageTitle: string;
369
618
  pageDescription: string;
370
619
  openGraphImage: string;
620
+ pageTitleBinding?: BindingType;
621
+ pageDescriptionBinding?: BindingType;
622
+ openGraphImageBinding?: BindingType;
371
623
  metaProps: MetaProp[];
372
624
  }
373
625
  interface MetaProp {
@@ -376,6 +628,7 @@ interface MetaProp {
376
628
  type: "text" | "number";
377
629
  defaultValue: string;
378
630
  previewValue: string;
631
+ binding?: BindingType;
379
632
  }
380
633
 
381
634
  declare const studioSdk: {
@@ -383,20 +636,24 @@ declare const studioSdk: {
383
636
  internal: {
384
637
  getConfig(): Config;
385
638
  isInsideStudioFrame: () => boolean;
386
- fetchSpec: (queryOptions: _contentstack_studio_messenger.CompositionQuery, options?: CompositionQueryOptions, skipComponentLoading?: boolean) => Promise<StudioSpec>;
639
+ fetchSpec: (queryOptions: _contentstack_studio_messenger.CompositionQuery, options?: CompositionQueryOptions, skipComponentLoading?: boolean, searchParams?: URLSearchParams) => Promise<StudioSpec>;
640
+ fetchCompositionSpecOnly: (queryOptions: _contentstack_studio_messenger.CompositionQuery, options?: CompositionQueryOptions, skipComponentLoading?: boolean) => Promise<StudioSpec>;
387
641
  fetchMultipleSpecs: (queries: _contentstack_studio_messenger.CompositionQuery[], options?: CompositionQueryOptions) => Promise<StudioSpec[]>;
388
- fetchData: (compositionEntry: CompositionEntry, queryOptions: _contentstack_studio_messenger.CompositionQuery, options?: CompositionQueryOptions) => Promise<_contentstack_studio_registry.StudioSpecData>;
642
+ fetchData: (compositionEntry: CompositionEntry, queryOptions: _contentstack_studio_messenger.CompositionQuery, options?: CompositionQueryOptions, sectionEntries?: SectionCompositionEntry[], searchParams?: URLSearchParams) => Promise<_contentstack_studio_registry.StudioSpecData>;
389
643
  fetchTemplateEntry: (fetchOptions: {
390
644
  connected_content_type: string;
391
645
  compositionQuery: _contentstack_studio_messenger.CompositionQuery;
392
646
  includeQueries: string[];
393
647
  onlyQueries: [string, string][];
394
648
  composableUid: string;
395
- }, data: _contentstack_studio_registry.StudioSpecData, compositionEntry: CompositionEntry, compositionQueryOptions?: CompositionQueryOptions) => Promise<void>;
396
- getSeoMetadata: (ui: _contentstack_studio_internal.Node) => SeoMetadata;
649
+ }, data: _contentstack_studio_registry.StudioSpecData, compositionEntry: CompositionEntry, compositionQueryOptions?: CompositionQueryOptions, urlPatternContext?: {
650
+ matchResult: ReturnType<typeof matchCompositionUrl> | undefined;
651
+ }, searchParams?: URLSearchParams) => Promise<void>;
652
+ getSeoMetadata: (ui: _contentstack_studio_internal.Node, specData?: _contentstack_studio_registry.StudioSpecData) => SeoMetadata | null;
397
653
  };
398
654
  public: {
399
655
  fetchCompositionData: (queryOptions: CompositionQueryForSSRInput, options?: CompositionQueryOptions) => Promise<StudioComponentSpecOptions>;
656
+ fetchComposition: (queryOptions: CompositionQueryForSSRInput, options?: CompositionQueryOptions) => Promise<StudioSpec>;
400
657
  getConfig: () => Pick<Config, "contentTypeUid" | "cslp" | "openInStudioButton">;
401
658
  };
402
659
  };
@@ -412,108 +669,498 @@ declare const NODE_TO_ELEMENT: WeakMap<any, HTMLElement>;
412
669
  declare const NODE_TO_PATH_NODE: WeakMap<any, PathNode>;
413
670
  declare const NODE_TO_PARENT: WeakMap<any, any>;
414
671
 
672
+ declare const findPath: (node: Descendant) => Path;
673
+ declare const findPathForElement: (el: HTMLElement) => Path;
674
+ declare const applyOperation: (editor: Node, operations: Operation[]) => Node;
675
+
676
+ declare function isCompositionBeingEdited(compositionUid: string): boolean;
677
+
678
+ declare const queryParam: {
679
+ get(key: ComposableStudioQueryParamsKeys): string | null;
680
+ has(key: ComposableStudioQueryParamsKeys): boolean;
681
+ };
682
+ declare const onlyParmasGenerator: (only: [string, string][]) => Record<string, string[]>;
683
+
684
+ declare const SECTION_COMPOSITIONS_KEY = "section_compositions";
685
+ declare const TEMPLATE_FULL_ENTRY_KEY = "template_full_entry";
686
+ declare const setTemplateEntryInDS: (dataSources: Record<string, any>, entry: unknown) => void;
687
+ declare const setStaticEntryInDS: (dataSources: Record<string, any>, ct_uid: string, _entries: unknown) => void;
415
688
  /**
416
- * Processes the raw static values and stored them against their static value UID.
417
- *
418
- * @param rawStaticValues It converts the raw static values to the required format.
419
- * @returns The processed static values.
420
- *
421
- * @example
422
- * const data = {
423
- * text: [{
424
- * key: "some-unique-key",
425
- * value: "Some text value"
426
- * }, {
427
- * key: "another-unique-key",
428
- * value: "Another text value"
429
- * }]
689
+ * Counterpart to setStaticEntryInDS: drop a single resolved additional entry
690
+ * from the contentstack data source bucket. Called when the author removes an
691
+ * entry so the pruned bucket replaces the stale one on the next UPDATE_SPEC_DATA
692
+ * push (which merges at the dataSources level); without it the removed entry's
693
+ * data lingers and keeps rendering.
694
+ */
695
+ declare const removeStaticEntryFromDS: (dataSources: Record<string, any>, ct_uid: string, uid: string) => void;
696
+ declare const batchFetchEntries: (sdk: StackSDK, entries: ICSEntryReference[]) => Promise<[string, CompositionEntry[]][]>;
697
+ declare const getBindingStringForCS: (binding: BindingType) => string;
698
+ type EntriesResponse<T> = {
699
+ entries: T[];
700
+ } | [T[]];
701
+ declare function entriesFromResponse<T>(response: EntriesResponse<T>): T[];
702
+
703
+ declare const isInsideVisualBuilderFrame: () => boolean;
704
+
705
+ /**
706
+ * Checks if the current context is inside an iframe.
430
707
  *
431
- * console.log(preProcessStaticValues(data));
708
+ * @returns {boolean} True if inside an iframe, false otherwise.
709
+ */
710
+ declare const isInsideIframe: () => boolean;
711
+
712
+ /** The three author-facing render contexts a host app can find itself in. */
713
+ type StudioMode = "canvas" | "preview" | "visitor";
714
+ /**
715
+ * The query param Studio always appends to canvas / template-preview iframe
716
+ * URLs. Part of the stable contract — changing its value is a breaking
717
+ * change and will be release-noted as such.
718
+ */
719
+ declare const STUDIO_CANVAS_QUERY_PARAM: "cs-composable-studio";
720
+ /**
721
+ * Class the SDK bootstrap adds to `<html>` when running inside the Studio
722
+ * canvas. Available for CSS-only gating (e.g. `html.cs-studio-canvas
723
+ * #onetrust-banner-sdk { display: none }`).
724
+ */
725
+ declare const STUDIO_MODE_HTML_CLASS = "cs-studio-canvas";
726
+ declare global {
727
+ interface Window {
728
+ __CS_STUDIO_MODE__?: StudioMode;
729
+ }
730
+ }
731
+ /**
732
+ * Detects the current Studio mode.
432
733
  *
433
- * // Output
434
- * // {
435
- * // "some-unique-key": "Some text value",
436
- * // "another-unique-key": "Another text value"
437
- * // }
734
+ * Browser: the `window.__CS_STUDIO_MODE__` marker wins when present (it
735
+ * survives client-side navigations that strip query params); otherwise the
736
+ * URL's query params decide.
438
737
  *
439
- * }
738
+ * Server: pass the request's search params (string or URLSearchParams) to
739
+ * get a real answer; with no arguments it safely reports `"visitor"`.
440
740
  */
441
- declare function preProcessStaticValues(rawStaticValues: RawStaticValue): StaticValue;
442
- type ParsedStringResult = {
443
- value: any;
444
- } & ({
445
- isValid: false;
446
- error: string;
447
- } | {
448
- isValid: true;
449
- });
741
+ declare function detectStudioMode(searchQuery?: string | URLSearchParams): StudioMode;
450
742
  /**
451
- * Parses a string value and returns its parsed representation.
743
+ * True when the host app is rendering inside the Studio canvas (or Visual
744
+ * Builder frame) — the one check to gate cookie banners, chat widgets,
745
+ * analytics, marketing pixels, and feature-flag bootstraps behind.
452
746
  *
453
- * @param input The string input to parse.
454
- * @returns An object containing the parsed value, validity status, and optional error message.
455
- *
456
- * @example
457
- * const result = parseStringValue('{"key": "value"}');
458
- * console.log(result);
459
- * // Output: { value: { key: 'value' }, isValid: true }
747
+ * SSR-safe: returns false on the server unless the request's search params
748
+ * are passed explicitly.
460
749
  */
461
- declare function parseStringValue(input: string): ParsedStringResult;
462
-
463
- declare function addContextMenuEventListeners(): {
464
- removeEventListeners: () => void;
465
- } | undefined;
750
+ declare function isStudioCanvas(searchQuery?: string | URLSearchParams): boolean;
751
+ /**
752
+ * True in any Studio-driven context (canvas OR live-preview pane). Use when
753
+ * a third-party should also stay out of preview sessions — e.g. analytics.
754
+ */
755
+ declare function isStudioEditorMode(searchQuery?: string | URLSearchParams): boolean;
756
+ /**
757
+ * Bootstrap: computes the mode from the current URL, stamps
758
+ * `window.__CS_STUDIO_MODE__`, and (for canvas mode) adds
759
+ * {@link STUDIO_MODE_HTML_CLASS} to `<html>`. Idempotent; no-op on the
760
+ * server. Invoked automatically when `@contentstack/studio-react` loads in
761
+ * the browser — call it manually only if you gate scripts that run before
762
+ * the SDK's module graph is evaluated.
763
+ */
764
+ declare function markStudioMode(): StudioMode;
466
765
 
467
- declare const MAX_SCROLL_SPEED = 100;
468
- declare const SCROLL_INTERVAL = 50;
469
- declare const EDGE_PADDING = 50;
470
- interface MousePosition {
471
- clientX: number;
472
- clientY: number;
766
+ declare const ComposableStudioErrors: {
767
+ readonly COMPOSITION_NOT_FOUND: "COMPOSITION_NOT_FOUND";
768
+ readonly COMPOSITION_NOT_FOUND_BY_URL: "COMPOSITION_NOT_FOUND_BY_URL";
769
+ readonly PREVIEW_ENTRY_NOT_FOUND: "PREVIEW_ENTRY_NOT_FOUND";
770
+ readonly FETCHING_CONNECTED_DATA_FAILED: "FETCHING_CONNECTED_DATA_FAILED";
771
+ readonly RESOLVING_DATA_SOURCES_FAILED: "RESOLVING_DATA_SOURCES_FAILED";
772
+ readonly STACK_SDK_NOT_AVAILABLE: "STACK_SDK_NOT_AVAILABLE";
773
+ readonly INVALID_FETCH_SPEC_OPTIONS: "INVALID_FETCH_SPEC_OPTIONS";
774
+ readonly MISSING_COMPOSITION_IDENTIFIER: "MISSING_COMPOSITION_IDENTIFIER";
775
+ readonly UI_PARSING_ERROR: "UI_PARSING_ERROR";
776
+ readonly SPEC_DATA_INVALID: "SPEC_DATA_INVALID";
777
+ readonly NETWORK_ERROR: "NETWORK_ERROR";
778
+ readonly AUTHENTICATION_ERROR: "AUTHENTICATION_ERROR";
779
+ readonly SERVER_ERROR: "SERVER_ERROR";
780
+ readonly COMPONENT_NOT_FOUND: "COMPONENT_NOT_FOUND";
781
+ };
782
+ /**
783
+ * Information about a possible cause of an error and how to fix it
784
+ */
785
+ interface TroubleshootingInfo {
786
+ /**
787
+ * Description of the possible cause of the error
788
+ */
789
+ cause: string;
790
+ /**
791
+ * Suggested fix or resolution for this cause
792
+ */
793
+ fix: string;
473
794
  }
474
- declare class DNDManager {
475
- started: boolean;
476
- dragging: boolean;
477
- scrollContainer: HTMLElement | null;
478
- scrollInterval: ReturnType<typeof setInterval> | undefined;
479
- startPosition: MousePosition | null;
480
- hasMoved: boolean;
481
- mouseDown: boolean;
482
- constructor();
483
- handleMouseDown(_e: MouseEvent): void;
484
- handleMouseUp(_e: MouseEvent): void;
485
- handleMouseLeave(e: MouseEvent): void;
486
- start(e: MouseEvent): void;
487
- startParent(): void;
488
- end(): void;
489
- mouseMove(e: MouseEvent): void;
490
- get isStarted(): boolean;
491
- get isDragging(): boolean;
492
- hasExceededTolerance(start: MousePosition, end: MousePosition): boolean;
795
+ /**
796
+ * Type definition for error details that can be passed to ComposableStudioError
797
+ */
798
+ interface ComposableStudioErrorDetails {
799
+ /**
800
+ * Array of troubleshooting information with causes and fixes
801
+ */
802
+ troubleshootingInfo?: TroubleshootingInfo[];
803
+ /**
804
+ * Additional error context and metadata
805
+ */
806
+ [key: string]: any;
807
+ }
808
+ declare class ComposableStudioError extends Error {
809
+ id: keyof typeof ComposableStudioErrors;
810
+ details?: ComposableStudioErrorDetails;
811
+ constructor(id: keyof typeof ComposableStudioErrors, message: string, details?: ComposableStudioErrorDetails);
493
812
  }
494
- declare const dndManager: DNDManager;
495
-
496
- declare const dndEventListener: () => {
497
- removeEventListeners: () => void;
498
- };
499
-
500
- declare const getScrollableParent: (el: HTMLElement) => HTMLElement;
501
- declare const calculateDynamicSpeed: (distance: number, padding: number, maxSpeed: number) => number;
502
813
 
503
- declare function handleOnScroll(): void;
504
- declare function handleResize(): void;
505
- declare const isModKey: (e: MouseEvent | KeyboardEvent) => boolean;
506
- declare function addHighlightNodeEventListeners(): {
507
- removeEventListeners: () => void;
508
- } | undefined;
814
+ declare const evaluateCondition: (condition: Condition, data: any) => boolean;
509
815
 
510
- type OnStyleChangeCallback = (options: {
511
- activeNodeUID: string;
512
- element: HTMLElement;
513
- componentClassName: string;
514
- }) => void;
515
- declare class HighlightNodeManager {
516
- activeNodeUID: string | null;
816
+ declare class RendererModeUtil {
817
+ private searchParams;
818
+ private isServerWithoutParams;
819
+ constructor(searchParams?: URLSearchParams);
820
+ /**
821
+ * Checks if the current context is inside a Studio.
822
+ *
823
+ * @returns {boolean} True if inside a Studio, false otherwise.
824
+ */
825
+ isInsideStudioFrame(): boolean;
826
+ /**
827
+ * Checks if the current context is inside an iframe.
828
+ *
829
+ * @returns {boolean} True if inside an iframe, false otherwise.
830
+ */
831
+ isInsideIframe(): boolean;
832
+ /**
833
+ * Checks if the current context is inside a Visual Builder frame.
834
+ *
835
+ * Learn more about Visual Builder: {@link https://www.contentstack.com/docs/content-managers/visual-builder}
836
+ *
837
+ * @returns {boolean} True if inside a Visual Builder frame, false otherwise.
838
+ */
839
+ isInsideVisualBuilderFrame(): boolean;
840
+ /**
841
+ * Checks if the current context is editing a specific composition.
842
+ *
843
+ * It is useful when you have multiple compositions in a single page
844
+ * and you want to know if the current context is editing a specific
845
+ * composition.
846
+ *
847
+ * @param compositionUid - The UID of the composition to check.
848
+ * @returns {boolean} True if editing the specified composition, false otherwise.
849
+ */
850
+ isEditingCurrentComposition(compositionUid: string): boolean;
851
+ /**
852
+ * Determines the current renderer mode for a given composition UID.
853
+ *
854
+ * - Returns "edit" if the current composition is being edited.
855
+ * - Returns "show_edit_button" if inside the visual builder frame
856
+ * or if the composition is not currently being edited but should show the edit button.
857
+ * - Returns "preview" otherwise.
858
+ *
859
+ * This method is useful when you want to change the functionality of the
860
+ * component based on where it is being rendered.
861
+ *
862
+ * @param compositionUid - The UID of the composition to check.
863
+ * @returns RendererMode - The current mode (EDIT, SHOW_EDIT_BUTTON, or PREVIEW).
864
+ */
865
+ getMode(compositionUid: string): "preview" | "edit" | "show_edit_button";
866
+ }
867
+ /**
868
+ * Module-level mode util backed by `window.location.search` (the browser URL).
869
+ *
870
+ * SSR CAUTION: this reads `window`, which does not exist on the server, so on the server
871
+ * every method returns its production default (e.g. `isInsideStudioFrame()` -> false) for
872
+ * ALL requests. It is correct ONLY in browser-only code (the editor render, hooks,
873
+ * INIT_STUDIO). In server-reachable fetch code (studio-client's spec-fetch path) do NOT use
874
+ * this: the answer is wrong on the server, and a single shared singleton cannot represent
875
+ * per-request state across concurrent SSR requests anyway. There, use the request-scoped
876
+ * helpers in `sdk.ts` (`isInStudio` / `isEditorFetch` / `readStudioParam`, built on
877
+ * `getRequestSearchParams`), which read the forwarded request query on the server and fall
878
+ * back to `window` on the client. See COMS-1554 for the AsyncLocalStorage proposal that would
879
+ * remove this split and make this util correct everywhere.
880
+ */
881
+ declare const clientRendererModeUtil: RendererModeUtil;
882
+ declare const serializeComputedStyles: (computedStyle: CSSStyleDeclaration) => Record<string, string>;
883
+
884
+ /**
885
+ * Analyzes a UI spec (Node tree) and extracts all component types used.
886
+ * Recursively traverses the spec to find all components.
887
+ *
888
+ * @param spec - The root node of the UI spec
889
+ * @returns Set of component types used in the spec
890
+ */
891
+ declare function analyzeUsedComponents(spec: Node | null | undefined): Set<string>;
892
+ /**
893
+ * Analyzes multiple UI specs and returns the union of all component types used.
894
+ * Useful for optimizing multi-composition loading.
895
+ *
896
+ * @param specs - Array of UI spec root nodes
897
+ * @returns Set of all unique component types used across all specs
898
+ */
899
+ declare function analyzeMultipleSpecs(specs: (Node | null | undefined)[]): Set<string>;
900
+ /**
901
+ * Checks if a spec uses a specific component type.
902
+ *
903
+ * @param spec - The UI spec to check
904
+ * @param componentType - The component type to look for
905
+ * @returns true if the component is used in the spec
906
+ */
907
+ declare function specUsesComponent(spec: Node | null | undefined, componentType: string): boolean;
908
+ /**
909
+ * Gets component usage statistics for a spec.
910
+ *
911
+ * @param spec - The UI spec to analyze
912
+ * @returns Map of component types to their usage count
913
+ */
914
+ declare function getComponentUsageStats(spec: Node | null | undefined): Map<string, number>;
915
+
916
+ interface UrlPatternVariableInfo {
917
+ type: string;
918
+ name: string;
919
+ category: (typeof URL_PATTERN_VARIABLE_TYPES)[keyof typeof URL_PATTERN_VARIABLE_TYPES];
920
+ referenceName?: string;
921
+ referenceField?: string;
922
+ }
923
+ /**
924
+ * Compile a URL pattern into a regex that can match and extract variables
925
+ * Handles arbitrary patterns like: "lsefj{{entry.url}}assefs{{content_type_uid}}/{{taxonomy:ola}}"
926
+ */
927
+ declare function compileUrlPattern(pattern: string, includeReferences?: string[]): {
928
+ regex: RegExp;
929
+ variableOrder: Array<UrlPatternVariableInfo>;
930
+ literalCharCount: number;
931
+ };
932
+ /**
933
+ * Match a request URL against a compiled pattern and extract variables
934
+ */
935
+ declare function matchUrlPattern(requestUrl: string, compiledPattern: ReturnType<typeof compileUrlPattern>): ExtractedUrlPatternVariables | null;
936
+ /**
937
+ * Compute pattern specificity score for ranking
938
+ * Primary: literal character count (more specific)
939
+ * Secondary: total pattern length
940
+ */
941
+ declare function computePatternSpecificity(pattern: string): number;
942
+ interface MatchCompositionOptions {
943
+ includeReferences?: string[];
944
+ connected_content_type?: string;
945
+ }
946
+ /**
947
+ * Match a single composition entry against a request URL
948
+ */
949
+ declare function matchCompositionUrl(requestUrl: string, compositionUrl: string, composable_uid: string, options?: MatchCompositionOptions): PatternMatchResult;
950
+
951
+ interface SectionNeeds {
952
+ entryKeys: string[];
953
+ queryKeys: string[];
954
+ parentRepeaterUID?: string;
955
+ selectedField?: string;
956
+ uidRemapping?: Record<string, string>;
957
+ componentPropsFallback?: Record<string, unknown>;
958
+ }
959
+ type NeedsBySection = Map<string, SectionNeeds>;
960
+
961
+ interface ResolvedPool {
962
+ entriesByKey: Map<string, any>;
963
+ queriesByKey: Map<string, any>;
964
+ /** instanceUid -> (section's data_source uid -> pool entry key) */
965
+ sectionEntryDsToPoolKey: Map<string, Map<string, string>>;
966
+ /** instanceUid -> (section's query data_source uid -> pool query key) */
967
+ sectionQueryDsToPoolKey: Map<string, Map<string, string>>;
968
+ /**
969
+ * instanceUid -> the SECTION composition entry's preprocessed `static_value`
970
+ * (key -> value). Mirrors the page-level static_value path in sdk.ts but per
971
+ * section instance, so static_value bindings authored inside a section
972
+ * subtree resolve at runtime as well as in the editor.
973
+ */
974
+ sectionStaticValueByInstance?: Map<string, Record<string, unknown>>;
975
+ }
976
+ declare function buildScopedDataSources(pool: ResolvedPool, needsBySection: NeedsBySection, pageDataSources: DataSources): Record<string, SectionScopedDataSources>;
977
+
978
+ /**
979
+ * Pure SEO resolver. Merges the composition's saved SEO metadata
980
+ * (`ui.metadata.seo`) with resolved values from `specData` (bound title /
981
+ * description / OG image / meta props read from the template entry). Shared by
982
+ * the SDK's `getSeoMetadata` and exposed for BYO-data callers who resolve SEO
983
+ * against data they supply themselves — see `resolveSeoMetadata` in
984
+ * `@contentstack/studio-react`.
985
+ */
986
+ declare function getSeoMetadataPure(ui: Node, specData?: StudioSpecData): SeoMetadata | null;
987
+ /**
988
+ * Pure per-instance section scoping. Given a composition's `pageUi` + its
989
+ * section composition entries + an ALREADY-RESOLVED `dataSources` pool, derive
990
+ * the `section_scoped_data` map (per section-instance uid). No network.
991
+ *
992
+ * Reused in two places:
993
+ * 1. `fetchData` — after the CDA fetch has populated `data.dataSources`.
994
+ * 2. BYO-data rendering (`StudioComposition`) — the caller supplies
995
+ * `dataSources`; embedded sections scope without any refetch.
996
+ *
997
+ * Returns `{}` when there are no section compositions (e.g. a standalone
998
+ * section rendered as the root reads `dataSources.template` directly).
999
+ */
1000
+ declare function buildSectionScopedData(compositionEntry: CompositionEntry, pageUi: Node, sectionEntries: SectionCompositionEntry[], dataSources: StudioSpecData["dataSources"]): ReturnType<typeof buildScopedDataSources>;
1001
+
1002
+ /**
1003
+ * A single, framework-neutral meta tag. `attr` distinguishes standard
1004
+ * `<meta name="...">` tags from Open Graph-style `<meta property="...">`.
1005
+ */
1006
+ interface CompositionMetaTag {
1007
+ attr: "name" | "property";
1008
+ key: string;
1009
+ content: string;
1010
+ }
1011
+ /**
1012
+ * Framework-neutral SEO metadata derived from a composition's resolved
1013
+ * `specOptions.seo`. Consumers bind this to their host's head mechanism:
1014
+ * Next.js `generateMetadata`, Remix `meta()`, TanStack `head()`, or a raw
1015
+ * HTML template via {@link renderMetadataToHtml}.
1016
+ */
1017
+ interface CompositionMetadata {
1018
+ title?: string;
1019
+ description?: string;
1020
+ ogImage?: string;
1021
+ /** Absolute canonical URL. Present only when `baseUrl` was provided and the composition has a URL. */
1022
+ canonical?: string;
1023
+ /** Every derived tag (description, og:*, twitter:*, custom metaProps) in render order. */
1024
+ tags: CompositionMetaTag[];
1025
+ }
1026
+ interface GetCompositionMetadataOptions {
1027
+ /**
1028
+ * Site origin used to absolutize the canonical URL and og:url,
1029
+ * e.g. `https://www.example.com`. No trailing slash required.
1030
+ */
1031
+ baseUrl?: string;
1032
+ }
1033
+ /**
1034
+ * Derives framework-neutral SEO metadata from a fetched composition.
1035
+ *
1036
+ * The heavy lifting (resolving field bindings for title/description/OG image)
1037
+ * already happens inside `fetchCompositionData` — this helper only shapes the
1038
+ * resolved values into standard head-tag structures.
1039
+ *
1040
+ * @example Plain Node
1041
+ * ```ts
1042
+ * const meta = getCompositionMetadata(specOptions, { baseUrl: "https://example.com" });
1043
+ * res.send(`<head><title>${meta.title}</title>${renderMetadataToHtml(meta)}</head>...`);
1044
+ * ```
1045
+ *
1046
+ * @example Next.js App Router
1047
+ * ```ts
1048
+ * export async function generateMetadata() {
1049
+ * const meta = getCompositionMetadata(await getSpecOptions());
1050
+ * return { title: meta.title, description: meta.description };
1051
+ * }
1052
+ * ```
1053
+ */
1054
+ declare function getCompositionMetadata(specOptions: Pick<StudioComponentSpecOptions, "seo" | "spec">, options?: GetCompositionMetadataOptions): CompositionMetadata;
1055
+ /**
1056
+ * Renders {@link CompositionMetadata} to a raw HTML string (meta + canonical
1057
+ * link tags — the `<title>` element is left to the caller since most hosts
1058
+ * manage it separately). For template-string SSR hosts (Express/Fastify).
1059
+ */
1060
+ declare function renderMetadataToHtml(metadata: CompositionMetadata): string;
1061
+
1062
+ /**
1063
+ * Processes the raw static values and stored them against their static value UID.
1064
+ *
1065
+ * @param rawStaticValues It converts the raw static values to the required format.
1066
+ * @returns The processed static values.
1067
+ *
1068
+ * @example
1069
+ * const data = {
1070
+ * text: [{
1071
+ * key: "some-unique-key",
1072
+ * value: "Some text value"
1073
+ * }, {
1074
+ * key: "another-unique-key",
1075
+ * value: "Another text value"
1076
+ * }]
1077
+ *
1078
+ * console.log(preProcessStaticValues(data));
1079
+ *
1080
+ * // Output
1081
+ * // {
1082
+ * // "some-unique-key": "Some text value",
1083
+ * // "another-unique-key": "Another text value"
1084
+ * // }
1085
+ *
1086
+ * }
1087
+ */
1088
+ declare function preProcessStaticValues(rawStaticValues: RawStaticValue): StaticValue;
1089
+ type ParsedStringResult = {
1090
+ value: any;
1091
+ } & ({
1092
+ isValid: false;
1093
+ error: string;
1094
+ } | {
1095
+ isValid: true;
1096
+ });
1097
+ /**
1098
+ * Parses a string value and returns its parsed representation.
1099
+ *
1100
+ * @param input The string input to parse.
1101
+ * @returns An object containing the parsed value, validity status, and optional error message.
1102
+ *
1103
+ * @example
1104
+ * const result = parseStringValue('{"key": "value"}');
1105
+ * console.log(result);
1106
+ * // Output: { value: { key: 'value' }, isValid: true }
1107
+ */
1108
+ declare function parseStringValue(input: string): ParsedStringResult;
1109
+
1110
+ declare function addContextMenuEventListeners(): {
1111
+ removeEventListeners: () => void;
1112
+ } | undefined;
1113
+
1114
+ declare const MAX_SCROLL_SPEED = 100;
1115
+ declare const SCROLL_INTERVAL = 50;
1116
+ declare const EDGE_PADDING = 50;
1117
+ interface MousePosition {
1118
+ clientX: number;
1119
+ clientY: number;
1120
+ }
1121
+ declare class DNDManager {
1122
+ started: boolean;
1123
+ dragging: boolean;
1124
+ scrollContainer: HTMLElement | null;
1125
+ scrollInterval: ReturnType<typeof setInterval> | undefined;
1126
+ startPosition: MousePosition | null;
1127
+ hasMoved: boolean;
1128
+ mouseDown: boolean;
1129
+ constructor();
1130
+ handleMouseDown(_e: MouseEvent): void;
1131
+ handleMouseUp(_e: MouseEvent): void;
1132
+ handleMouseLeave(e: MouseEvent): void;
1133
+ start(e: MouseEvent): void;
1134
+ startParent(): void;
1135
+ end(): void;
1136
+ mouseMove(e: MouseEvent): void;
1137
+ get isStarted(): boolean;
1138
+ get isDragging(): boolean;
1139
+ hasExceededTolerance(start: MousePosition, end: MousePosition): boolean;
1140
+ }
1141
+ declare const dndManager: DNDManager;
1142
+
1143
+ declare const dndEventListener: () => {
1144
+ removeEventListeners: () => void;
1145
+ };
1146
+
1147
+ declare const getScrollableParent: (el: HTMLElement) => HTMLElement;
1148
+ declare const calculateDynamicSpeed: (distance: number, padding: number, maxSpeed: number) => number;
1149
+
1150
+ declare function handleOnScroll(): void;
1151
+ declare function handleResize(): void;
1152
+ declare const isModKey: (e: MouseEvent | KeyboardEvent) => boolean;
1153
+ declare function addHighlightNodeEventListeners(): {
1154
+ removeEventListeners: () => void;
1155
+ } | undefined;
1156
+
1157
+ type OnStyleChangeCallback = (options: {
1158
+ activeNodeUID: string;
1159
+ element: HTMLElement;
1160
+ componentClassName: string;
1161
+ }) => void;
1162
+ declare class HighlightNodeManager {
1163
+ activeNodeUID: string | null;
517
1164
  focusedNodeUID: string | null;
518
1165
  activeNodePath: Path | null;
519
1166
  focusedNodePath: Path | null;
@@ -620,11 +1267,20 @@ declare function addBreakpointEventListeners(): {
620
1267
  declare const DEFAULT_BREAKPOINTS: BreakpointInput;
621
1268
 
622
1269
  declare class BreakpointManager {
623
- private static instance;
624
1270
  private activeBreakpoint;
625
1271
  private breakpointRegistry;
626
1272
  private constructor();
1273
+ /**
1274
+ * Returns the singleton `BreakpointManager` instance from the SDK's
1275
+ * versioned `globalThis` slot. See
1276
+ * `@contentstack/studio-registry/common/global-store.ts` for why singletons
1277
+ * live on globalThis instead of a class-static field.
1278
+ */
627
1279
  static getInstance(): BreakpointManager;
1280
+ /**
1281
+ * Resets the singleton. For tests only.
1282
+ */
1283
+ static resetInstance(): void;
628
1284
  setActiveBreakpoint(breakpoint: Breakpoint): void;
629
1285
  getActiveBreakpoint(): Breakpoint | null;
630
1286
  findMatchingBreakpoint(): Breakpoint;
@@ -633,172 +1289,6 @@ declare class BreakpointManager {
633
1289
  private syncBreakpointsWithStudio;
634
1290
  }
635
1291
 
636
- declare const findPath: (node: Descendant) => Path;
637
- declare const findPathForElement: (el: HTMLElement) => Path;
638
- declare const applyOperation: (editor: Node, operations: Operation[]) => Node;
639
-
640
- declare function isCompositionBeingEdited(compositionUid: string): boolean;
641
-
642
- declare const queryParam: {
643
- get(key: ComposableStudioQueryParamsKeys): string | null;
644
- has(key: ComposableStudioQueryParamsKeys): boolean;
645
- };
646
- declare const onlyParmasGenerator: (only: [string, string][]) => Record<string, string>;
647
-
648
- declare const setTemplateEntryInDS: (dataSources: Record<string, any>, entry: unknown) => void;
649
- declare const setStaticEntryInDS: (dataSources: Record<string, any>, ct_uid: string, _entries: unknown) => void;
650
- declare const batchFetchEntries: (sdk: StackSDK, entries: ICSEntryReference[]) => Promise<[string, CompositionEntry[]][]>;
651
- declare const getBindingStringForCS: (binding: BindingType) => string;
652
- type EntriesResponse<T> = {
653
- entries: T[];
654
- } | [T[]];
655
- declare function entriesFromResponse<T>(response: EntriesResponse<T>): T[];
656
-
657
- declare const isInsideVisualBuilderFrame: () => boolean;
658
-
659
- /**
660
- * Checks if the current context is inside an iframe.
661
- *
662
- * @returns {boolean} True if inside an iframe, false otherwise.
663
- */
664
- declare const isInsideIframe: () => boolean;
665
-
666
- declare const ComposableStudioErrors: {
667
- readonly COMPOSITION_NOT_FOUND: "COMPOSITION_NOT_FOUND";
668
- readonly COMPOSITION_NOT_FOUND_BY_URL: "COMPOSITION_NOT_FOUND_BY_URL";
669
- readonly PREVIEW_ENTRY_NOT_FOUND: "PREVIEW_ENTRY_NOT_FOUND";
670
- readonly FETCHING_CONNECTED_DATA_FAILED: "FETCHING_CONNECTED_DATA_FAILED";
671
- readonly RESOLVING_DATA_SOURCES_FAILED: "RESOLVING_DATA_SOURCES_FAILED";
672
- readonly STACK_SDK_NOT_AVAILABLE: "STACK_SDK_NOT_AVAILABLE";
673
- readonly INVALID_FETCH_SPEC_OPTIONS: "INVALID_FETCH_SPEC_OPTIONS";
674
- readonly MISSING_COMPOSITION_IDENTIFIER: "MISSING_COMPOSITION_IDENTIFIER";
675
- readonly UI_PARSING_ERROR: "UI_PARSING_ERROR";
676
- readonly SPEC_DATA_INVALID: "SPEC_DATA_INVALID";
677
- readonly NETWORK_ERROR: "NETWORK_ERROR";
678
- readonly AUTHENTICATION_ERROR: "AUTHENTICATION_ERROR";
679
- readonly SERVER_ERROR: "SERVER_ERROR";
680
- readonly COMPONENT_NOT_FOUND: "COMPONENT_NOT_FOUND";
681
- };
682
- /**
683
- * Information about a possible cause of an error and how to fix it
684
- */
685
- interface TroubleshootingInfo {
686
- /**
687
- * Description of the possible cause of the error
688
- */
689
- cause: string;
690
- /**
691
- * Suggested fix or resolution for this cause
692
- */
693
- fix: string;
694
- }
695
- /**
696
- * Type definition for error details that can be passed to ComposableStudioError
697
- */
698
- interface ComposableStudioErrorDetails {
699
- /**
700
- * Array of troubleshooting information with causes and fixes
701
- */
702
- troubleshootingInfo?: TroubleshootingInfo[];
703
- /**
704
- * Additional error context and metadata
705
- */
706
- [key: string]: any;
707
- }
708
- declare class ComposableStudioError extends Error {
709
- id: keyof typeof ComposableStudioErrors;
710
- details?: ComposableStudioErrorDetails;
711
- constructor(id: keyof typeof ComposableStudioErrors, message: string, details?: ComposableStudioErrorDetails);
712
- }
713
-
714
- declare const evaluateCondition: (condition: Condition, data: any) => boolean;
715
-
716
- declare class RendererModeUtil {
717
- private searchParams;
718
- private isServerWithoutParams;
719
- constructor(searchParams?: URLSearchParams);
720
- /**
721
- * Checks if the current context is inside a Studio.
722
- *
723
- * @returns {boolean} True if inside a Studio, false otherwise.
724
- */
725
- isInsideStudioFrame(): boolean;
726
- /**
727
- * Checks if the current context is inside an iframe.
728
- *
729
- * @returns {boolean} True if inside an iframe, false otherwise.
730
- */
731
- isInsideIframe(): boolean;
732
- /**
733
- * Checks if the current context is inside a Visual Builder frame.
734
- *
735
- * Learn more about Visual Builder: {@link https://www.contentstack.com/docs/content-managers/visual-builder}
736
- *
737
- * @returns {boolean} True if inside a Visual Builder frame, false otherwise.
738
- */
739
- isInsideVisualBuilderFrame(): boolean;
740
- /**
741
- * Checks if the current context is editing a specific composition.
742
- *
743
- * It is useful when you have multiple compositions in a single page
744
- * and you want to know if the current context is editing a specific
745
- * composition.
746
- *
747
- * @param compositionUid - The UID of the composition to check.
748
- * @returns {boolean} True if editing the specified composition, false otherwise.
749
- */
750
- isEditingCurrentComposition(compositionUid: string): boolean;
751
- /**
752
- * Determines the current renderer mode for a given composition UID.
753
- *
754
- * - Returns "edit" if the current composition is being edited.
755
- * - Returns "show_edit_button" if inside the visual builder frame
756
- * or if the composition is not currently being edited but should show the edit button.
757
- * - Returns "preview" otherwise.
758
- *
759
- * This method is useful when you want to change the functionality of the
760
- * component based on where it is being rendered.
761
- *
762
- * @param compositionUid - The UID of the composition to check.
763
- * @returns RendererMode - The current mode (EDIT, SHOW_EDIT_BUTTON, or PREVIEW).
764
- */
765
- getMode(compositionUid: string): "preview" | "edit" | "show_edit_button";
766
- }
767
- declare const clientRendererModeUtil: RendererModeUtil;
768
- declare const serializeComputedStyles: (computedStyle: CSSStyleDeclaration) => Record<string, string>;
769
-
770
- /**
771
- * Analyzes a UI spec (Node tree) and extracts all component types used.
772
- * Recursively traverses the spec to find all components.
773
- *
774
- * @param spec - The root node of the UI spec
775
- * @returns Set of component types used in the spec
776
- */
777
- declare function analyzeUsedComponents(spec: Node | null | undefined): Set<string>;
778
- /**
779
- * Analyzes multiple UI specs and returns the union of all component types used.
780
- * Useful for optimizing multi-composition loading.
781
- *
782
- * @param specs - Array of UI spec root nodes
783
- * @returns Set of all unique component types used across all specs
784
- */
785
- declare function analyzeMultipleSpecs(specs: (Node | null | undefined)[]): Set<string>;
786
- /**
787
- * Checks if a spec uses a specific component type.
788
- *
789
- * @param spec - The UI spec to check
790
- * @param componentType - The component type to look for
791
- * @returns true if the component is used in the spec
792
- */
793
- declare function specUsesComponent(spec: Node | null | undefined, componentType: string): boolean;
794
- /**
795
- * Gets component usage statistics for a spec.
796
- *
797
- * @param spec - The UI spec to analyze
798
- * @returns Map of component types to their usage count
799
- */
800
- declare function getComponentUsageStats(spec: Node | null | undefined): Map<string, number>;
801
-
802
1292
  interface GoogleFont {
803
1293
  family: string;
804
1294
  variants: string[];
@@ -844,40 +1334,201 @@ interface EmittedEvents {
844
1334
 
845
1335
  declare const composableStudioEventEmitter: EventEmitter<EmittedEvents, any>;
846
1336
 
1337
+ interface EmbeddedEntryRenderArgs {
1338
+ entryUid: string;
1339
+ contentTypeUid: string;
1340
+ displayType: string;
1341
+ title: string;
1342
+ /** Full resolved entry object — every field the delivery API returned. */
1343
+ entry: ResolvedEmbeddedEntry;
1344
+ }
847
1345
  /**
848
- * Registers a config for JSON RTE
849
- * @param config - The config to register. This should have the following format:
850
- * {
851
- * customElementTypes: {
852
- * [elementName]: {
853
- * parse: (node: any) => any,
854
- * render: (node: any) => any,
855
- * },
856
- * },
857
- * }
858
- * For more details, check the docs here: https://github.com/contentstack/json-rte-serializer/blob/main/README.md#custom-element-types
859
- * @throws If the config is not provided
1346
+ * Args passed to the user-registered `embeddedAsset` renderer.
1347
+ *
1348
+ * Asset metadata travels inline in the RTE markup — no fetch needed:
1349
+ * HTML RTE: `<figure class="embedded-asset" data-sys-asset-uid="…"
1350
+ * data-sys-asset-filelink="…" data-sys-asset-contenttype="…"
1351
+ * data-sys-asset-filename="…" data-sys-asset-alt="…"
1352
+ * sys-style-type="display"></figure>`
1353
+ * JSON RTE: `{ type:"reference", attrs:{ type:"asset", "asset-uid":"…",
1354
+ * "asset-link":"…", "asset-type":"image/png", "asset-name":"…",
1355
+ * alt:"…", "display-type":"display" } }`
1356
+ */
1357
+ interface EmbeddedAssetRenderArgs {
1358
+ assetUid: string;
1359
+ /** Direct CDN URL — use as `<img src>` / `<video src>` etc. */
1360
+ url: string;
1361
+ /** MIME type, e.g. `image/png`, `video/mp4`. Drives default renderer's tag choice. */
1362
+ contentType: string;
1363
+ /** Original filename, useful for download links. */
1364
+ filename: string;
1365
+ /** Alt text from the RTE editor — empty string when unset. */
1366
+ alt: string;
1367
+ /** Layout hint from the editor: `display` (block), `inline`, `link`, etc. */
1368
+ displayType: string;
1369
+ }
1370
+ /**
1371
+ * Default asset renderer used when the user hasn't registered an
1372
+ * `embeddedAsset` callback via `registerRTERenderer`. Branches on MIME type:
1373
+ * image/* → `<img src>` (with alt + class for styling hooks)
1374
+ * video/* → `<video src controls>`
1375
+ * audio/* → `<audio src controls>`
1376
+ * other → `<a href download>` fallback link
1377
+ *
1378
+ * Unsafe URL schemes (`javascript:`, `vbscript:`, non-image `data:` etc.) are
1379
+ * blocked and render as plain text placeholder to prevent XSS.
1380
+ */
1381
+ declare function defaultAssetRender({ assetUid, url, contentType, filename, alt, }: EmbeddedAssetRenderArgs): string;
1382
+ interface EmbeddedEntryConversionOptions {
1383
+ /**
1384
+ * Pre-resolved entry map. Keys are entry UIDs. Each value is the full entry
1385
+ * object (any fields). The `title` field is used as the display label unless
1386
+ * your `render` function overrides it.
1387
+ *
1388
+ * When omitted the SDK fetches entries automatically via `fetchEmbeddedEntries`.
1389
+ */
1390
+ entries?: Record<string, ResolvedEmbeddedEntry>;
1391
+ render?: (args: EmbeddedEntryRenderArgs) => string;
1392
+ /**
1393
+ * Custom element type renderers for JSON RTE plugins (e.g. table, social-embed,
1394
+ * code-block). Merged with the built-in `reference` handler. Keyed by the
1395
+ * node `type` value produced by the RTE plugin.
1396
+ *
1397
+ * @example
1398
+ * createEmbeddedEntryConversion({
1399
+ * customElementTypes: {
1400
+ * table: (attrs, child) => `<table>${child}</table>`,
1401
+ * "social-embed": (attrs, child, block) =>
1402
+ * `<div class="embed" data-url="${block?.attrs?.url ?? ""}">${child}</div>`,
1403
+ * },
1404
+ * });
1405
+ */
1406
+ customElementTypes?: IJsonToHtmlOptions["customElementTypes"];
1407
+ }
1408
+ interface ResolvedEmbeddedEntry {
1409
+ uid: string;
1410
+ title?: string;
1411
+ _content_type_uid?: string;
1412
+ [key: string]: any;
1413
+ }
1414
+ /** Walk a JSON RTE doc and collect all entry-reference {entryUid, contentTypeUid} pairs. */
1415
+ declare function extractJsonRteRefs(node: any): Array<{
1416
+ entryUid: string;
1417
+ contentTypeUid: string;
1418
+ }>;
1419
+ /** Extract {entryUid, contentTypeUid} pairs from an HTML RTE string via regex. */
1420
+ declare function extractHtmlRteRefs(html: string): Array<{
1421
+ entryUid: string;
1422
+ contentTypeUid: string;
1423
+ }>;
1424
+ /**
1425
+ * Fetch embedded entries from the registered stack SDK.
1426
+ * Groups refs by content type and issues one query per group in parallel.
1427
+ * Returns a uid→entry map.
1428
+ */
1429
+ declare function fetchEmbeddedEntries(refs: Array<{
1430
+ entryUid: string;
1431
+ contentTypeUid: string;
1432
+ }>): Promise<Record<string, ResolvedEmbeddedEntry>>;
1433
+ declare function createEmbeddedEntryConversion(options?: EmbeddedEntryConversionOptions & {
1434
+ /** Asset renderer — defaults to `defaultAssetRender` (img/video/audio/link by MIME). */
1435
+ renderAsset?: (args: EmbeddedAssetRenderArgs) => string;
1436
+ }): IJsonToHtmlOptions;
1437
+
1438
+ /**
1439
+ * Unified RTE configuration. Extends the JSON RTE serializer options with
1440
+ * an `embeddedEntry` renderer so users configure everything in one call.
1441
+ *
860
1442
  * @example
861
- * registerJSONRTE({
1443
+ * registerRTERenderer({
1444
+ * // Embedded entry rendering
1445
+ * embeddedEntry: ({ entry, contentTypeUid, displayType }) => {
1446
+ * if (displayType === "block") return `<h1>${entry.title}</h1>`;
1447
+ * return `<span>${entry.title}</span>`;
1448
+ * },
1449
+ * // Custom JSON RTE node types
862
1450
  * customElementTypes: {
863
- * myComponent: {
864
- * parse: (node) => node,
865
- * render: (node) => (
866
- * <div>
867
- * <h3>My Component</h3>
868
- * <p>{node.children[0].text}</p>
869
- * </div>
870
- * ),
871
- * },
1451
+ * "code-block": (attrs, child) => `<pre><code>${child}</code></pre>`,
872
1452
  * },
1453
+ * allowNonStandardTypes: true,
873
1454
  * });
874
1455
  */
1456
+ interface RTEConfig extends IJsonToHtmlOptions {
1457
+ embeddedEntry?: (args: EmbeddedEntryRenderArgs) => string;
1458
+ /**
1459
+ * Renderer for embedded ASSETS in RTE fields (images / videos / audio /
1460
+ * file links inserted via the editor's "Insert Asset" button). Both JSON
1461
+ * RTE (`{ attrs.type: "asset" }`) and HTML RTE (`<figure
1462
+ * class="embedded-asset" data-sys-asset-uid="…">`) paths invoke this.
1463
+ *
1464
+ * Omit to use the built-in default (img for image/*, video/audio with
1465
+ * controls for those MIMEs, `<a download>` fallback otherwise).
1466
+ */
1467
+ embeddedAsset?: (args: EmbeddedAssetRenderArgs) => string;
1468
+ }
1469
+ /**
1470
+ * Unified RTE registration. Covers both embedded entry rendering and custom
1471
+ * JSON RTE node types in a single call. Replaces the full config on each call.
1472
+ *
1473
+ * @example — embedded entries only
1474
+ * registerRTERenderer({
1475
+ * embeddedEntry: ({ entry, contentTypeUid, displayType }) => {
1476
+ * if (displayType === "block") return `<div><h3>${entry.full_name ?? entry.title}</h3></div>`;
1477
+ * if (displayType === "link") return `<a href="${entry.url}">${entry.title}</a>`;
1478
+ * return `<span>${entry.title}</span>`;
1479
+ * },
1480
+ * });
1481
+ *
1482
+ * @example — JSON RTE custom node types only
1483
+ * registerRTERenderer({
1484
+ * customElementTypes: {
1485
+ * "code-block": (attrs, child) => `<pre><code>${child}</code></pre>`,
1486
+ * "my-table": (attrs, child) => `<table>${child}</table>`,
1487
+ * },
1488
+ * allowNonStandardTypes: true,
1489
+ * });
1490
+ *
1491
+ * @example — both together
1492
+ * registerRTERenderer({
1493
+ * embeddedEntry: ({ entry, contentTypeUid, displayType }) => {
1494
+ * const label = entry.full_name ?? entry.title ?? entry.uid;
1495
+ * if (displayType === "block") return `<div><h1>${label}</h1><p>${entry.short_bio ?? ""}</p></div>`;
1496
+ * if (displayType === "link") return `<a href="${entry.url ?? "#"}">${label}</a>`;
1497
+ * return `<span>${label}</span>`;
1498
+ * },
1499
+ * customElementTypes: {
1500
+ * "code-block": (attrs, child) => `<pre><code>${child}</code></pre>`,
1501
+ * },
1502
+ * });
1503
+ */
1504
+ declare function registerRTERenderer(config: RTEConfig): void;
1505
+ /**
1506
+ * @deprecated Use `registerRTERenderer` instead. Preserves any previously
1507
+ * registered `embeddedEntry` / `embeddedAsset` renderers; only replaces the
1508
+ * JSON RTE serializer options.
1509
+ */
875
1510
  declare function registerJSONRTE(config: IJsonToHtmlOptions): void;
876
1511
  /**
877
- * Gets the current config for JSON RTE
878
- * @returns The current config for JSON RTE
1512
+ * @deprecated Use `registerRTERenderer` instead. Registers embedded entry
1513
+ * renderer only — does not clear existing `customElementTypes` or `embeddedAsset`.
1514
+ */
1515
+ declare function registerEmbeddedEntryRenderer(render: (args: EmbeddedEntryRenderArgs) => string): void;
1516
+ /**
1517
+ * Returns the current JSON RTE serializer options (without embeddedEntry / embeddedAsset).
1518
+ * Used internally by the RichText / CollapsibleText hooks.
879
1519
  */
880
1520
  declare function getJSONRTE(): IJsonToHtmlOptions;
1521
+ /**
1522
+ * Returns the registered embedded entry renderer, or null if none registered.
1523
+ * Used internally by the RichText / CollapsibleText hooks.
1524
+ */
1525
+ declare function getEmbeddedEntryRenderer(): ((args: EmbeddedEntryRenderArgs) => string) | null;
1526
+ /**
1527
+ * Returns the registered embedded asset renderer, or null if none registered.
1528
+ * Used internally by the RichText / CollapsibleText hooks. When null, the
1529
+ * hook falls back to `defaultAssetRender` so canvas never shows blank assets.
1530
+ */
1531
+ declare function getEmbeddedAssetRenderer(): ((args: EmbeddedAssetRenderArgs) => string) | null;
881
1532
 
882
1533
  declare const compositionSaveEventListener: () => {
883
1534
  unregister: () => void;
@@ -895,7 +1546,7 @@ declare function getNodeScreenshotEvent(): {
895
1546
 
896
1547
  interface QuerySpec {
897
1548
  contentType: string;
898
- sourceType?: "content_type" | "taxonomy";
1549
+ sourceType?: "content_type" | "contentstack" | "taxonomy";
899
1550
  query: Record<string, any>;
900
1551
  params: Record<string, any>;
901
1552
  }
@@ -965,5 +1616,93 @@ declare class QueryExecutor {
965
1616
  private resolveExpressionsInQuery;
966
1617
  }
967
1618
 
968
- export { BreakpointManager, COMPOSABLE_DATA_ATTRIBUTES, COMPOSABLE_STUDIO_EMITTED_EVENTS, ComposableStudioError, ComposableStudioErrors, DEFAULT_BREAKPOINTS, 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, addBreakpointEventListeners, addContextMenuEventListeners, addHighlightNodeEventListeners, addHighlightSpacingEventListeners, addUrlChangeListeners, analyzeMultipleSpecs, analyzeUsedComponents, applyOperation, batchFetchEntries, calculateDynamicSpeed, clientRendererModeUtil, closeHiddenElementNotification, composableStudioEventEmitter, compositionSaveEventListener, createClassNameUid, studioSdk as default, dndEventListener, dndManager, entriesFromResponse, evaluateCondition, findNearestBuilderNode, findNearestSlotNode, findPath, findPathForElement, getBindingStringForCS, getComponentUsageStats, getComposableElement, getComputedStyles, getDefaultConfig, getHitboxDetails, getHitboxDirection, getJSONRTE, getNodeScreenshotEvent, getScrollableParent, handleOnScroll, handleResize, hasSlotDropzone, hiddenElementNotificationEventEmitter, highlightNodeManager, isBrowser, isCompositionBeingEdited, isInsideIframe, isInsideVisualBuilderFrame, isModKey, loadGoogleFont, onlyParmasGenerator, openHiddenElementNotification, parseStringValue, preProcessStaticValues, queryParam, registerJSONRTE, serializeComputedStyles, serializeEvent, setStaticEntryInDS, setTemplateEntryInDS, specUsesComponent, studioSdk, toggleNodeVisible, updateStyleOnStyleNodeChange };
969
- export type { ClientEditableNodeInternalAttributes, ClientPreviewNodeInternalAttributes, ComposableStudioErrorDetails, ComposableStudioLightSdk, CompositionEntry, CompositionEntryIncompleteUi, CompositionFetcher, CompositionQueryForSSR, CompositionQueryForSSRInput, CompositionQueryOptions, Config, EmittedEvents, FetchCompositionContext, FetchTemplateEntryContext, FontVariants, GoogleFont, HiddenElementNotificationHandler, LightConfig, MetaProp, ParsedStringResult, QueryExecutionOptions, QueryResult, QuerySpec, QueryState, ResolvedQueryOptions, RuntimeContext, SearchQueryInput, SeoMetadata, StudioComponentFetchOptions, StudioComponentSpecOptions, StudioSdk, StudioSpec, SymbolEntry, TemplateEntryFetcher, TroubleshootingInfo, URLSearchParamsString, UserConfig };
1619
+ /**
1620
+ * Query-building mode.
1621
+ * - `match`: predicates equal the captured value (production composition lookup).
1622
+ * - `existence`: predicates require the field to be present and non-empty (Studio
1623
+ * iframe-URL flow — we have no URL to match against; we only need an entry
1624
+ * that has values for every variable in the pattern).
1625
+ */
1626
+ type UrlMetadataQueryMode = "match" | "existence";
1627
+ /**
1628
+ * Build the plain JSON query object for a composition's URL metadata.
1629
+ *
1630
+ * Shared between the SDK (production composition resolution) and the Studio
1631
+ * UI (iframe-URL preview-entry fetch). The SDK passes the returned object (possibly
1632
+ * wrapped in an `$or` by `buildTemplateQuery`) to `ctQuery({ query })`; the UI
1633
+ * stringifies it and passes it to `api.cma.entry.getAll` via the `query` param.
1634
+ *
1635
+ * In `existence` mode for `legacy_url` and `content_type_url_pattern` the
1636
+ * object is `{ url: { $nin: ["", null] } }` regardless of `extractedVariables`.
1637
+ */
1638
+ declare function buildUrlMetadataQueryObject(context: Pick<TemplateQueryContext, "compositionQuery" | "extractedVariables" | "url_source">, mode?: UrlMetadataQueryMode): Record<string, any>;
1639
+ /**
1640
+ * Build the full template-entry query as a single raw query object and hand it
1641
+ * to `ctQuery({ query })`.
1642
+ *
1643
+ * Unlike the old per-field `where()` chaining, this builds one object so it can
1644
+ * express a top-level `$or` and embed `taxonomies.<uid>` directly (the dedicated
1645
+ * `applyTaxonomyFilters`/`Taxonomies()` path cannot compose inside an `$or`).
1646
+ *
1647
+ * For `{{entry.url}}` in a pattern-based source (match mode), the query becomes
1648
+ * `{ $or: [ <per-field decomposition>, { url: <full request path> } ] }` so the
1649
+ * `url` field matches the whole request path as well as the captured segment —
1650
+ * the prefix-duplication / bare-`/{{entry.url}}` case. Other sources and modes
1651
+ * pass the per-field object unchanged.
1652
+ */
1653
+ declare function buildTemplateQuery(stackSdk: StackSDK, context: TemplateQueryContext, queryOptions: {
1654
+ references: string[];
1655
+ only?: [string, string][];
1656
+ variantAlias?: string;
1657
+ locale?: string;
1658
+ branch?: string;
1659
+ environment?: string;
1660
+ }, mode?: UrlMetadataQueryMode): any;
1661
+ /**
1662
+ * Resolve template entry based on url_source type and query context
1663
+ */
1664
+ declare function resolveByUrlSource(stackSdk: StackSDK, url_source: string, compositionQuery: {
1665
+ url?: string;
1666
+ }, extractedVariables: ExtractedUrlPatternVariables, parsedUrlQueries: CompositionUrlQueries, connectedContentType: string, queryOptions: {
1667
+ references: string[];
1668
+ only?: [string, string][];
1669
+ variantAlias?: string;
1670
+ locale?: string;
1671
+ branch?: string;
1672
+ environment?: string;
1673
+ }): any;
1674
+
1675
+ /**
1676
+ * Parse and validate url_metadata field from a composition entry
1677
+ * Returns parsed metadata or legacy object if metadata is missing, malformed, or legacy
1678
+ */
1679
+ declare function parseUrlMetadata(url_metadata?: Partial<CompositionUrlMetadataSerialized>): CompositionUrlMetadata;
1680
+ /**
1681
+ * Check if a composition entry has taxonomy extraction enabled
1682
+ * Returns true if only.BASE includes "taxonomies"
1683
+ */
1684
+ declare function shouldExtractTaxonomies(parsedMetadata: CompositionUrlMetadata): boolean;
1685
+
1686
+ /**
1687
+ * Rank URL matches across multiple composition entries
1688
+ * Returns all composable_uid strings tied at the highest specificity score
1689
+ *
1690
+ * @param requestUrl The incoming URL to match against
1691
+ * @param lightweightEntries Composition entries with url and composable_uid
1692
+ * @returns Ranking result with all entries at max specificity tier
1693
+ */
1694
+ declare function rankUrlMatches(requestUrl: string, lightweightEntries: LightweightCompositionEntry[]): RankingResult;
1695
+
1696
+ /**
1697
+ * Determine if the metadata-driven path should be used
1698
+ * It means whether we want to fallback to the wildcard routes
1699
+ * or parse the URL for variables and determine the composition
1700
+ * Returns false if metadata is missing, invalid JSON, or url_source is legacy_url
1701
+ *
1702
+ * @param url_metadata Raw url_metadata from composition entry
1703
+ * @returns true if metadata path should be used, false for legacy path
1704
+ */
1705
+ declare function shouldUseUrlMetadataPath(url_metadata?: Partial<CompositionUrlMetadataSerialized>): boolean;
1706
+
1707
+ 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 };
1708
+ 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, SymbolEntry, TemplateEntryFetcher, TemplateQueryContext, TroubleshootingInfo, URLSearchParamsString, UrlMatchDiagnostic, UrlMetadataQueryMode, UrlPatternMetadataField, UrlPatternMetadataFieldValue, UserConfig };