@contentstack/studio-client 1.4.0 → 1.5.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 (97) hide show
  1. package/dist/breakpoints/BreakpointManager.js +17 -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 +101 -0
  6. package/dist/composable-studio/build-scoped-data.js.map +1 -0
  7. package/dist/composable-studio/collect-data-needs.js +226 -0
  8. package/dist/composable-studio/collect-data-needs.js.map +1 -0
  9. package/dist/composable-studio/composition-placement.types.js +7 -0
  10. package/dist/composable-studio/composition-placement.types.js.map +1 -0
  11. package/dist/composable-studio/initializer-sdk.js +1 -9
  12. package/dist/composable-studio/initializer-sdk.js.map +1 -1
  13. package/dist/composable-studio/sdk.js +1551 -195
  14. package/dist/composable-studio/sdk.js.map +1 -1
  15. package/dist/composable-studio/studio-intelligence.manager.js +124 -0
  16. package/dist/composable-studio/studio-intelligence.manager.js.map +1 -0
  17. package/dist/config/config.schema.js +10 -0
  18. package/dist/config/config.schema.js.map +1 -1
  19. package/dist/config/default-config.js +1 -0
  20. package/dist/config/default-config.js.map +1 -1
  21. package/dist/config/process-user-config.js +6 -0
  22. package/dist/config/process-user-config.js.map +1 -1
  23. package/dist/config/stack-sdk-wrapper.js +87 -2
  24. package/dist/config/stack-sdk-wrapper.js.map +1 -1
  25. package/dist/design/handle-active-style-change.js +0 -3
  26. package/dist/design/handle-active-style-change.js.map +1 -1
  27. package/dist/dnd/dnd-manager.js +25 -7
  28. package/dist/dnd/dnd-manager.js.map +1 -1
  29. package/dist/dnd/{utils.js → scroll-utils.js} +2 -27
  30. package/dist/dnd/scroll-utils.js.map +1 -0
  31. package/dist/hidden-element-notification/hidden-element-notification-event.js +7 -0
  32. package/dist/hidden-element-notification/hidden-element-notification-event.js.map +1 -1
  33. package/dist/highlight-node/highlight-node-manager.js +7 -1
  34. package/dist/highlight-node/highlight-node-manager.js.map +1 -1
  35. package/dist/highlight-node/highlight-node.js +38 -18
  36. package/dist/highlight-node/highlight-node.js.map +1 -1
  37. package/dist/index.d.ts +618 -31
  38. package/dist/index.js +16 -5
  39. package/dist/index.js.map +1 -1
  40. package/dist/node_modules/fflate/esm/browser.js +384 -0
  41. package/dist/node_modules/fflate/esm/browser.js.map +1 -0
  42. package/dist/packages/studio-internal/dist/utils/spec-compression.js +43 -0
  43. package/dist/packages/studio-internal/dist/utils/spec-compression.js.map +1 -0
  44. package/dist/query/expression-resolver.js +124 -0
  45. package/dist/query/expression-resolver.js.map +1 -0
  46. package/dist/query/query-executor.js +482 -0
  47. package/dist/query/query-executor.js.map +1 -0
  48. package/dist/shared/dnd-events.js +39 -0
  49. package/dist/shared/dnd-events.js.map +1 -0
  50. package/dist/url-change/url-change.js +65 -0
  51. package/dist/url-change/url-change.js.map +1 -0
  52. package/dist/url-metadata/build-template-query.js +124 -0
  53. package/dist/url-metadata/build-template-query.js.map +1 -0
  54. package/dist/url-metadata/parse-url-metadata.js +75 -0
  55. package/dist/url-metadata/parse-url-metadata.js.map +1 -0
  56. package/dist/url-metadata/rank-url-matches.js +100 -0
  57. package/dist/url-metadata/rank-url-matches.js.map +1 -0
  58. package/dist/url-metadata/select-url-winner.js +45 -0
  59. package/dist/url-metadata/select-url-winner.js.map +1 -0
  60. package/dist/url-metadata/shouldUseUrlMetadataPath.js +22 -0
  61. package/dist/url-metadata/shouldUseUrlMetadataPath.js.map +1 -0
  62. package/dist/url-metadata/types.js +50 -0
  63. package/dist/url-metadata/types.js.map +1 -0
  64. package/dist/url-metadata/url-pattern-matcher.js +311 -0
  65. package/dist/url-metadata/url-pattern-matcher.js.map +1 -0
  66. package/dist/utils/build-composition-fetch-query.js +19 -0
  67. package/dist/utils/build-composition-fetch-query.js.map +1 -0
  68. package/dist/utils/composable-studio-error.js +1 -0
  69. package/dist/utils/composable-studio-error.js.map +1 -1
  70. package/dist/utils/conditionBlock.js +17 -5
  71. package/dist/utils/conditionBlock.js.map +1 -1
  72. package/dist/utils/constants.js +22 -2
  73. package/dist/utils/constants.js.map +1 -1
  74. package/dist/utils/convertCompositionQueryInputToCompositionQuery.js +11 -1
  75. package/dist/utils/convertCompositionQueryInputToCompositionQuery.js.map +1 -1
  76. package/dist/utils/editor-utils.js +9 -0
  77. package/dist/utils/editor-utils.js.map +1 -1
  78. package/dist/utils/error-messages.default.js +1 -1
  79. package/dist/utils/error-messages.default.js.map +1 -1
  80. package/dist/utils/http-error.constants.js +11 -2
  81. package/dist/utils/http-error.constants.js.map +1 -1
  82. package/dist/utils/is-inside-iframe.js +16 -0
  83. package/dist/utils/is-inside-iframe.js.map +1 -0
  84. package/dist/utils/query-param.js +1 -1
  85. package/dist/utils/query-param.js.map +1 -1
  86. package/dist/utils/reference_fetcher.js +125 -14
  87. package/dist/utils/reference_fetcher.js.map +1 -1
  88. package/dist/utils/sdk.js +6 -1
  89. package/dist/utils/sdk.js.map +1 -1
  90. package/dist/utils/spec-analyzer.js +112 -0
  91. package/dist/utils/spec-analyzer.js.map +1 -0
  92. package/package.json +11 -10
  93. package/dist/dnd/utils.js.map +0 -1
  94. package/dist/get-composition-from-slug/get-composition-from-slug.js +0 -59
  95. package/dist/get-composition-from-slug/get-composition-from-slug.js.map +0 -1
  96. package/dist/utils/get-url-patterns.js +0 -40
  97. package/dist/utils/get-url-patterns.js.map +0 -1
package/dist/index.d.ts CHANGED
@@ -1,20 +1,25 @@
1
1
  import * as _contentstack_studio_internal from '@contentstack/studio-internal';
2
- import { Node, PathNode, Path, Descendant, Operation, BindingType, Condition, NodeStyles } from '@contentstack/studio-internal';
2
+ import { Node, PathNode, Path, Operation, Descendant, BindingType, Condition, NodeStyles } from '@contentstack/studio-internal';
3
3
  import * as _contentstack_studio_registry from '@contentstack/studio-registry';
4
- import { StudioSpecData, RawStaticValue, ICSEntryReference, StaticValue, BreakpointInput, Breakpoint } from '@contentstack/studio-registry';
4
+ import { RawStaticValue, ICSEntryReference, StudioSpecData, 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
- import { CompositionQueryInput, ComposableStudioQueryParams, CompositionQuery, ComposableStudioQueryParamsKeys, HiddenElementNotificationEventData, POST_MESSAGE_EVENTS } from '@contentstack/studio-messenger';
7
+ import { CompositionQuery, CompositionQueryInput, ComposableStudioQueryParams, ComposableStudioQueryParamsKeys, HiddenElementNotificationEventData, POST_MESSAGE_EVENTS } from '@contentstack/studio-messenger';
8
8
  export { IS_BROWSER } from '@contentstack/studio-messenger';
9
9
  import { z } from 'zod';
10
10
  import deliverySdk, { BaseAsset } from '@contentstack/delivery-sdk';
11
11
  import { Stack } from 'contentstack';
12
- import { InitMessage } from '@contentstack/studio-message-types/base';
13
12
  import { HitboxDetails, SerializedEvent, RefetchSpecEventData, ApplySymbolOperationEventData } from '@contentstack/studio-message-types/latest';
14
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';
15
14
  import { EventEmitter } from 'eventemitter3';
16
15
  import { IJsonToHtmlOptions } from '@contentstack/json-rte-serializer';
17
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
+
18
23
  type DeepRequired<T> = Required<{
19
24
  [K in keyof T]: T[K] extends Required<T[K]> ? T[K] : DeepRequired<T[K]>;
20
25
  }>;
@@ -43,10 +48,12 @@ declare const userConfigSchema: z.ZodObject<{
43
48
  enable?: boolean | undefined;
44
49
  position?: "top" | "top-left" | "top-right" | "top-center" | "bottom" | "bottom-left" | "bottom-right" | "bottom-center" | undefined;
45
50
  }>>;
51
+ fetchComposition: z.ZodOptional<z.ZodType<CompositionFetcher, z.ZodTypeDef, CompositionFetcher>>;
52
+ fetchTemplateEntry: z.ZodOptional<z.ZodType<TemplateEntryFetcher, z.ZodTypeDef, TemplateEntryFetcher>>;
46
53
  }, "strip", z.ZodTypeAny, {
54
+ locale?: string | undefined;
47
55
  contentTypeUid?: string | undefined;
48
56
  stackSdk?: any;
49
- locale?: string | undefined;
50
57
  cslp?: {
51
58
  appendTags?: boolean | undefined;
52
59
  } | undefined;
@@ -54,10 +61,12 @@ declare const userConfigSchema: z.ZodObject<{
54
61
  enable?: boolean | undefined;
55
62
  position?: "top" | "top-left" | "top-right" | "top-center" | "bottom" | "bottom-left" | "bottom-right" | "bottom-center" | undefined;
56
63
  } | undefined;
64
+ fetchComposition?: CompositionFetcher | undefined;
65
+ fetchTemplateEntry?: TemplateEntryFetcher | undefined;
57
66
  }, {
67
+ locale?: string | undefined;
58
68
  contentTypeUid?: string | undefined;
59
69
  stackSdk?: any;
60
- locale?: string | undefined;
61
70
  cslp?: {
62
71
  appendTags?: boolean | undefined;
63
72
  } | undefined;
@@ -65,6 +74,8 @@ declare const userConfigSchema: z.ZodObject<{
65
74
  enable?: boolean | undefined;
66
75
  position?: "top" | "top-left" | "top-right" | "top-center" | "bottom" | "bottom-left" | "bottom-right" | "bottom-center" | undefined;
67
76
  } | undefined;
77
+ fetchComposition?: CompositionFetcher | undefined;
78
+ fetchTemplateEntry?: TemplateEntryFetcher | undefined;
68
79
  }>;
69
80
 
70
81
  type JSStack = Stack;
@@ -73,7 +84,7 @@ declare class StackSDK {
73
84
  sdk: JSStack | TSStack;
74
85
  private _locale?;
75
86
  constructor(sdk: JSStack | TSStack, locale?: string);
76
- isJavaScriptSDK(sdk: Stack | ReturnType<(typeof deliverySdk)["stack"]>): sdk is Stack;
87
+ isJavaScriptSDK(_sdk: Stack | ReturnType<(typeof deliverySdk)["stack"]>): _sdk is Stack;
77
88
  livePreviewQuery(livePreviewHash: string): void;
78
89
  ctQuery(contentTypeUid: string, options?: {
79
90
  includeAll?: boolean;
@@ -82,6 +93,8 @@ declare class StackSDK {
82
93
  only?: [string, string][];
83
94
  variantAlias?: string;
84
95
  locale?: string;
96
+ branch?: string;
97
+ environment?: string;
85
98
  query?: Record<string, any>;
86
99
  }): any;
87
100
  entryQuery(contentTypeUid: string, entryUID: string, options?: {
@@ -98,11 +111,30 @@ declare class StackSDK {
98
111
  enable?: boolean;
99
112
  } | undefined;
100
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;
101
124
  }
102
125
 
103
- interface Config extends DeepRequired<Omit<UserConfig, "stackSdk" | "locale">> {
126
+ interface Config extends DeepRequired<Omit<UserConfig, "stackSdk" | "locale" | "fetchComposition" | "fetchTemplateEntry">> {
104
127
  stackSdk: StackSDK;
105
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;
136
+ fetchComposition?: CompositionFetcher;
137
+ fetchTemplateEntry?: TemplateEntryFetcher;
106
138
  }
107
139
  type LightConfig = Pick<Config, "openInStudioButton" | "contentTypeUid" | "cslp">;
108
140
  type UserConfig = z.infer<typeof userConfigSchema>;
@@ -110,7 +142,26 @@ type UserConfig = z.infer<typeof userConfigSchema>;
110
142
  declare function getDefaultConfig(): Config;
111
143
 
112
144
  declare const isBrowser: () => boolean;
113
- 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;
163
+ declare const SDK_VERSION: string;
164
+ declare const SCHEMA_VERSION = "1.0.0";
114
165
  declare const COMPOSABLE_DATA_ATTRIBUTES: {
115
166
  readonly BUILDER: "data-composable-studio-builder";
116
167
  readonly PLACEHOLDER: "data-composable-studio-placeholder";
@@ -147,6 +198,186 @@ declare const getHitboxDetails: (event: MouseEvent) => HitboxDetails;
147
198
  declare const getComputedStyles: (event: MouseEvent) => Record<string, string> | null;
148
199
  declare const serializeEvent: (event: MouseEvent) => SerializedEvent;
149
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
+
150
381
  type StudioSdk = ReturnType<typeof studioSdk.init>;
151
382
  type ComposableStudioLightSdk = ReturnType<typeof studioSdk.lightInit>;
152
383
  /**
@@ -165,17 +396,34 @@ interface CompositionEntry {
165
396
  created_at: string;
166
397
  updated_at: string;
167
398
  url?: string;
168
- 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
+ }[];
169
405
  ui: CompositionEntryIncompleteUi;
170
406
  data_sources: string;
171
407
  static_value?: RawStaticValue;
172
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[];
173
416
  }
174
417
  interface SymbolEntry extends Omit<CompositionEntry, "ui"> {
175
418
  ui_preview?: BaseAsset;
176
419
  ui: Node;
177
420
  tags: ["symbol"];
178
421
  }
422
+ interface SectionCompositionEntry extends Omit<CompositionEntry, "ui"> {
423
+ ui_preview?: BaseAsset;
424
+ ui: Node;
425
+ }
426
+ type RenderableCompositionEntry = CompositionEntry | SectionCompositionEntry;
179
427
  /**
180
428
  * This spec is the one we get from our `fetchSpec()` method.
181
429
  * It contains all the information we can derive from the compositionEntry.
@@ -184,9 +432,19 @@ interface SymbolEntry extends Omit<CompositionEntry, "ui"> {
184
432
  interface StudioSpec {
185
433
  data: StudioSpecData;
186
434
  ui: Node;
187
- compositionEntry: CompositionEntry;
435
+ compositionEntry: RenderableCompositionEntry;
188
436
  symbols?: SymbolEntry[];
437
+ sectionCompositions?: SectionCompositionEntry[];
189
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
+ };
190
448
  }
191
449
  type SearchQueryInput = (Partial<ComposableStudioQueryParams> & {
192
450
  [key: string]: string | string[] | undefined;
@@ -228,7 +486,91 @@ type CompositionQueryOptions = {
228
486
  only?: (string | [string, string])[];
229
487
  };
230
488
  };
489
+ /**
490
+ * UID of a specific entry in the connected content type to use
491
+ * as the template/preview entry.
492
+ *
493
+ * When provided, the SDK fetches this exact entry instead of
494
+ * resolving by URL or grabbing the first available entry.
495
+ *
496
+ * Resolution priority: templateEntryUid > url > first entry (limit 1)
497
+ */
498
+ templateEntryUid?: string;
499
+ /**
500
+ * Per-query composition fetcher override. Takes precedence over global.
501
+ * Return the composition entry, null for not-found, or call `defaultFetch()`.
502
+ */
503
+ fetchComposition?: CompositionFetcher;
504
+ /**
505
+ * Per-query template entry fetcher override. Takes precedence over global.
506
+ * Return the entry, null for not-found, or call `defaultFetch()`.
507
+ */
508
+ fetchTemplateEntry?: TemplateEntryFetcher;
231
509
  };
510
+ /**
511
+ * CompositionQueryOptions with fetcher callbacks stripped.
512
+ * Passed to custom fetchers via the `options` field.
513
+ * Automatically picks up any future additions to CompositionQueryOptions.
514
+ */
515
+ type ResolvedQueryOptions = Omit<CompositionQueryOptions, "fetchComposition" | "fetchTemplateEntry">;
516
+ /**
517
+ * Context provided to a custom composition fetcher.
518
+ */
519
+ interface FetchCompositionContext {
520
+ /** The query input — has composableUid, url, or both */
521
+ compositionQuery: CompositionQuery;
522
+ /** The content type UID where compositions are stored */
523
+ contentTypeUid: string;
524
+ /** All query options (locale, variantAlias, extendQuery, templateEntryUid, + future) */
525
+ options: ResolvedQueryOptions;
526
+ /** The raw Contentstack SDK instance passed to studioSdk.init() */
527
+ stackSdk: any;
528
+ /**
529
+ * Calls the SDK's default composition fetching logic.
530
+ * Use this to: conditionally fall through, wrap/decorate, inspect/transform.
531
+ */
532
+ defaultFetch: () => Promise<CompositionEntry>;
533
+ }
534
+ /**
535
+ * Context provided to a custom template entry fetcher.
536
+ */
537
+ interface FetchTemplateEntryContext {
538
+ /** The already-fetched composition entry */
539
+ compositionEntry: CompositionEntry;
540
+ /** The original query (has composableUid, url, or both) */
541
+ compositionQuery: CompositionQuery;
542
+ /** The content type UID that this composition is linked to */
543
+ connectedContentType: string;
544
+ /** All query options (locale, variantAlias, extendQuery, templateEntryUid, + future) */
545
+ options: ResolvedQueryOptions;
546
+ /**
547
+ * SDK-computed reference field paths from UI tree bindings + options.extendQuery.
548
+ * e.g., ["author", "categories", "related_posts.author"]
549
+ */
550
+ includeReferences: string[];
551
+ /**
552
+ * SDK-computed field projections from UI tree bindings + options.extendQuery.
553
+ * Empty when inside Visual Builder (all fields fetched).
554
+ */
555
+ only: [string, string][];
556
+ /** The raw Contentstack SDK instance passed to studioSdk.init() */
557
+ stackSdk: any;
558
+ /**
559
+ * Calls the SDK's default template entry fetching logic.
560
+ * Uses templateEntryUid > url > first entry resolution.
561
+ */
562
+ defaultFetch: () => Promise<any>;
563
+ }
564
+ /**
565
+ * User-provided fetcher for compositions.
566
+ * Return the composition entry, null for not-found, or call defaultFetch().
567
+ */
568
+ type CompositionFetcher = (context: FetchCompositionContext) => Promise<CompositionEntry | null>;
569
+ /**
570
+ * User-provided fetcher for template entries.
571
+ * Return the entry, null for not-found, or call defaultFetch().
572
+ */
573
+ type TemplateEntryFetcher = (context: FetchTemplateEntryContext) => Promise<any | null>;
232
574
  /**
233
575
  * The query string we get after running URLSearchParams.toString()
234
576
  */
@@ -290,17 +632,16 @@ declare const studioSdk: {
290
632
  internal: {
291
633
  getConfig(): Config;
292
634
  isInsideStudioFrame: () => boolean;
293
- fetchSpec: (queryOptions: _contentstack_studio_messenger.CompositionQuery, options?: CompositionQueryOptions) => Promise<StudioSpec>;
294
- fetchData: (compositionEntry: CompositionEntry, queryOptions: _contentstack_studio_messenger.CompositionQuery, options?: CompositionQueryOptions) => Promise<_contentstack_studio_registry.StudioSpecData>;
295
- fetchTemplateEntry: (options: {
635
+ fetchSpec: (queryOptions: _contentstack_studio_messenger.CompositionQuery, options?: CompositionQueryOptions, skipComponentLoading?: boolean) => Promise<StudioSpec>;
636
+ fetchMultipleSpecs: (queries: _contentstack_studio_messenger.CompositionQuery[], options?: CompositionQueryOptions) => Promise<StudioSpec[]>;
637
+ fetchData: (compositionEntry: CompositionEntry, queryOptions: _contentstack_studio_messenger.CompositionQuery, options?: CompositionQueryOptions, sectionEntries?: SectionCompositionEntry[]) => Promise<_contentstack_studio_registry.StudioSpecData>;
638
+ fetchTemplateEntry: (fetchOptions: {
296
639
  connected_content_type: string;
297
640
  compositionQuery: _contentstack_studio_messenger.CompositionQuery;
298
641
  includeQueries: string[];
299
642
  onlyQueries: [string, string][];
300
643
  composableUid: string;
301
- variantAlias?: string;
302
- locale?: string;
303
- }, data: _contentstack_studio_registry.StudioSpecData) => Promise<void>;
644
+ }, data: _contentstack_studio_registry.StudioSpecData, compositionEntry: CompositionEntry, compositionQueryOptions?: CompositionQueryOptions) => Promise<void>;
304
645
  getSeoMetadata: (ui: _contentstack_studio_internal.Node) => SeoMetadata;
305
646
  };
306
647
  public: {
@@ -314,7 +655,6 @@ declare const studioSdk: {
314
655
  };
315
656
  };
316
657
  };
317
- declare const sendInitMessage: (message: InitMessage) => void;
318
658
 
319
659
  declare const ELEMENT_TO_NODE: WeakMap<HTMLElement, any>;
320
660
  declare const NODE_TO_ELEMENT: WeakMap<any, HTMLElement>;
@@ -407,19 +747,11 @@ declare const dndEventListener: () => {
407
747
  };
408
748
 
409
749
  declare const getScrollableParent: (el: HTMLElement) => HTMLElement;
410
- declare const getScrollContainerRect: () => DOMRect | {
411
- top: number;
412
- left: number;
413
- right: number;
414
- bottom: number;
415
- width: number;
416
- height: number;
417
- } | null;
418
- declare const getScrollContainer: () => HTMLElement | (Window & typeof globalThis) | null;
419
750
  declare const calculateDynamicSpeed: (distance: number, padding: number, maxSpeed: number) => number;
420
751
 
421
752
  declare function handleOnScroll(): void;
422
753
  declare function handleResize(): void;
754
+ declare const isModKey: (e: MouseEvent | KeyboardEvent) => boolean;
423
755
  declare function addHighlightNodeEventListeners(): {
424
756
  removeEventListeners: () => void;
425
757
  } | undefined;
@@ -517,6 +849,15 @@ declare class HighlightNodeManager {
517
849
  }
518
850
  declare const highlightNodeManager: HighlightNodeManager;
519
851
 
852
+ /**
853
+ * Listens for URL changes inside the iframe (SPA navigations, pushState, replaceState, popstate)
854
+ * and sends URL_CHANGE postMessage to the parent so the studio can sync the navbar URL.
855
+ * Uses Navigation API when available, with popstate + history monkey-patch fallback.
856
+ */
857
+ declare function addUrlChangeListeners(): {
858
+ removeEventListeners: () => void;
859
+ } | undefined;
860
+
520
861
  declare function addHighlightSpacingEventListeners(): {
521
862
  removeEventListeners: () => void;
522
863
  } | undefined;
@@ -528,11 +869,20 @@ declare function addBreakpointEventListeners(): {
528
869
  declare const DEFAULT_BREAKPOINTS: BreakpointInput;
529
870
 
530
871
  declare class BreakpointManager {
531
- private static instance;
532
872
  private activeBreakpoint;
533
873
  private breakpointRegistry;
534
874
  private constructor();
875
+ /**
876
+ * Returns the singleton `BreakpointManager` instance from the SDK's
877
+ * versioned `globalThis` slot. See
878
+ * `@contentstack/studio-registry/common/global-store.ts` for why singletons
879
+ * live on globalThis instead of a class-static field.
880
+ */
535
881
  static getInstance(): BreakpointManager;
882
+ /**
883
+ * Resets the singleton. For tests only.
884
+ */
885
+ static resetInstance(): void;
536
886
  setActiveBreakpoint(breakpoint: Breakpoint): void;
537
887
  getActiveBreakpoint(): Breakpoint | null;
538
888
  findMatchingBreakpoint(): Breakpoint;
@@ -551,8 +901,10 @@ declare const queryParam: {
551
901
  get(key: ComposableStudioQueryParamsKeys): string | null;
552
902
  has(key: ComposableStudioQueryParamsKeys): boolean;
553
903
  };
554
- declare const onlyParmasGenerator: (only: [string, string][]) => Record<string, string>;
904
+ declare const onlyParmasGenerator: (only: [string, string][]) => Record<string, string[]>;
555
905
 
906
+ declare const SECTION_COMPOSITIONS_KEY = "section_compositions";
907
+ declare const TEMPLATE_FULL_ENTRY_KEY = "template_full_entry";
556
908
  declare const setTemplateEntryInDS: (dataSources: Record<string, any>, entry: unknown) => void;
557
909
  declare const setStaticEntryInDS: (dataSources: Record<string, any>, ct_uid: string, _entries: unknown) => void;
558
910
  declare const batchFetchEntries: (sdk: StackSDK, entries: ICSEntryReference[]) => Promise<[string, CompositionEntry[]][]>;
@@ -564,6 +916,13 @@ declare function entriesFromResponse<T>(response: EntriesResponse<T>): T[];
564
916
 
565
917
  declare const isInsideVisualBuilderFrame: () => boolean;
566
918
 
919
+ /**
920
+ * Checks if the current context is inside an iframe.
921
+ *
922
+ * @returns {boolean} True if inside an iframe, false otherwise.
923
+ */
924
+ declare const isInsideIframe: () => boolean;
925
+
567
926
  declare const ComposableStudioErrors: {
568
927
  readonly COMPOSITION_NOT_FOUND: "COMPOSITION_NOT_FOUND";
569
928
  readonly COMPOSITION_NOT_FOUND_BY_URL: "COMPOSITION_NOT_FOUND_BY_URL";
@@ -578,6 +937,7 @@ declare const ComposableStudioErrors: {
578
937
  readonly NETWORK_ERROR: "NETWORK_ERROR";
579
938
  readonly AUTHENTICATION_ERROR: "AUTHENTICATION_ERROR";
580
939
  readonly SERVER_ERROR: "SERVER_ERROR";
940
+ readonly COMPONENT_NOT_FOUND: "COMPONENT_NOT_FOUND";
581
941
  };
582
942
  /**
583
943
  * Information about a possible cause of an error and how to fix it
@@ -667,6 +1027,38 @@ declare class RendererModeUtil {
667
1027
  declare const clientRendererModeUtil: RendererModeUtil;
668
1028
  declare const serializeComputedStyles: (computedStyle: CSSStyleDeclaration) => Record<string, string>;
669
1029
 
1030
+ /**
1031
+ * Analyzes a UI spec (Node tree) and extracts all component types used.
1032
+ * Recursively traverses the spec to find all components.
1033
+ *
1034
+ * @param spec - The root node of the UI spec
1035
+ * @returns Set of component types used in the spec
1036
+ */
1037
+ declare function analyzeUsedComponents(spec: Node | null | undefined): Set<string>;
1038
+ /**
1039
+ * Analyzes multiple UI specs and returns the union of all component types used.
1040
+ * Useful for optimizing multi-composition loading.
1041
+ *
1042
+ * @param specs - Array of UI spec root nodes
1043
+ * @returns Set of all unique component types used across all specs
1044
+ */
1045
+ declare function analyzeMultipleSpecs(specs: (Node | null | undefined)[]): Set<string>;
1046
+ /**
1047
+ * Checks if a spec uses a specific component type.
1048
+ *
1049
+ * @param spec - The UI spec to check
1050
+ * @param componentType - The component type to look for
1051
+ * @returns true if the component is used in the spec
1052
+ */
1053
+ declare function specUsesComponent(spec: Node | null | undefined, componentType: string): boolean;
1054
+ /**
1055
+ * Gets component usage statistics for a spec.
1056
+ *
1057
+ * @param spec - The UI spec to analyze
1058
+ * @returns Map of component types to their usage count
1059
+ */
1060
+ declare function getComponentUsageStats(spec: Node | null | undefined): Map<string, number>;
1061
+
670
1062
  interface GoogleFont {
671
1063
  family: string;
672
1064
  variants: string[];
@@ -761,5 +1153,200 @@ declare function getNodeScreenshotEvent(): {
761
1153
  unregister: () => void;
762
1154
  } | undefined;
763
1155
 
764
- export { BreakpointManager, COMPOSABLE_DATA_ATTRIBUTES, COMPOSABLE_STUDIO_EMITTED_EVENTS, ComposableStudioError, ComposableStudioErrors, DEFAULT_BREAKPOINTS, EDGE_PADDING, ELEMENT_TO_NODE, GOOGLE_FONT_API, INCLUDE_DEPTH_COUNT, MAX_SCROLL_SPEED, NODE_TO_ELEMENT, NODE_TO_PARENT, NODE_TO_PATH_NODE, RendererMode, RendererModeUtil, SCROLL_INTERVAL, addBreakpointEventListeners, addContextMenuEventListeners, addHighlightNodeEventListeners, addHighlightSpacingEventListeners, applyOperation, batchFetchEntries, calculateDynamicSpeed, clientRendererModeUtil, closeHiddenElementNotification, composableStudioEventEmitter, compositionSaveEventListener, createClassNameUid, studioSdk as default, dndEventListener, dndManager, entriesFromResponse, evaluateCondition, findNearestBuilderNode, findNearestSlotNode, findPath, findPathForElement, getBindingStringForCS, getComposableElement, getComputedStyles, getDefaultConfig, getHitboxDetails, getHitboxDirection, getJSONRTE, getNodeScreenshotEvent, getScrollContainer, getScrollContainerRect, getScrollableParent, handleOnScroll, handleResize, hasSlotDropzone, hiddenElementNotificationEventEmitter, highlightNodeManager, isBrowser, isCompositionBeingEdited, isInsideVisualBuilderFrame, loadGoogleFont, onlyParmasGenerator, openHiddenElementNotification, parseStringValue, preProcessStaticValues, queryParam, registerJSONRTE, sendInitMessage, serializeComputedStyles, serializeEvent, setStaticEntryInDS, setTemplateEntryInDS, studioSdk, toggleNodeVisible, updateStyleOnStyleNodeChange };
765
- export type { ClientEditableNodeInternalAttributes, ClientPreviewNodeInternalAttributes, ComposableStudioErrorDetails, ComposableStudioLightSdk, CompositionEntry, CompositionEntryIncompleteUi, CompositionQueryForSSR, CompositionQueryForSSRInput, CompositionQueryOptions, Config, EmittedEvents, FontVariants, GoogleFont, HiddenElementNotificationHandler, LightConfig, MetaProp, ParsedStringResult, SearchQueryInput, SeoMetadata, StudioComponentFetchOptions, StudioComponentSpecOptions, StudioSdk, StudioSpec, SymbolEntry, TroubleshootingInfo, URLSearchParamsString, UserConfig };
1156
+ interface QuerySpec {
1157
+ contentType: string;
1158
+ sourceType?: "content_type" | "contentstack" | "taxonomy";
1159
+ query: Record<string, any>;
1160
+ params: Record<string, any>;
1161
+ }
1162
+ interface QueryResult {
1163
+ entries: any[];
1164
+ count: number;
1165
+ currentPage: number;
1166
+ pageSize: number;
1167
+ hasNextPage: boolean;
1168
+ hasPreviousPage: boolean;
1169
+ }
1170
+ interface QueryState extends QueryResult {
1171
+ isLoading: boolean;
1172
+ error: Error | null;
1173
+ }
1174
+ interface QueryExecutionOptions {
1175
+ variantAlias?: string;
1176
+ locale?: string;
1177
+ }
1178
+ interface RuntimeContext {
1179
+ url?: {
1180
+ params: Record<string, string>;
1181
+ path: Record<string, string>;
1182
+ hash?: string;
1183
+ };
1184
+ componentProps?: Record<string, any>;
1185
+ user?: {
1186
+ id?: string;
1187
+ email?: string;
1188
+ name?: string;
1189
+ role?: string;
1190
+ preferences?: Record<string, any>;
1191
+ };
1192
+ environment?: {
1193
+ locale?: string;
1194
+ region?: string;
1195
+ timezone?: string;
1196
+ };
1197
+ }
1198
+
1199
+ declare class ExpressionResolver {
1200
+ resolve(expression: any, context: RuntimeContext): any;
1201
+ private resolveTimeExpression;
1202
+ private resolveUrlExpression;
1203
+ private resolvePropsExpression;
1204
+ private resolveUserExpression;
1205
+ private resolveEnvExpression;
1206
+ private getNestedValue;
1207
+ }
1208
+
1209
+ declare class QueryExecutor {
1210
+ private sdk;
1211
+ private expressionResolver;
1212
+ constructor(sdk: any);
1213
+ /**
1214
+ * Detection logic:
1215
+ * 1. If 'contentType' (lowercase) exists in object or prototype, it's likely TS SDK or CMA SDK.
1216
+ * 2. If 'ContentType' (uppercase) exists AND 'contentType' doesn't, it's likely legacy JS Delivery SDK.
1217
+ */
1218
+ private isJavaScriptSDK;
1219
+ /** TS @contentstack/delivery-sdk: Mongo filter must be sent via addParams({ query }), not .query(obj) */
1220
+ private usesTsContentTypeEntryQuery;
1221
+ execute(querySpec: QuerySpec, page?: number, context?: RuntimeContext, options?: QueryExecutionOptions): Promise<QueryResult>;
1222
+ /**
1223
+ * Helper to resolve expressions in nested query objects
1224
+ */
1225
+ private resolveExpressionsInQuery;
1226
+ }
1227
+
1228
+ /**
1229
+ * Query-building mode.
1230
+ * - `match`: predicates equal the captured value (production composition lookup).
1231
+ * - `existence`: predicates require the field to be present and non-empty (Studio
1232
+ * iframe-URL flow — we have no URL to match against; we only need an entry
1233
+ * that has values for every variable in the pattern).
1234
+ */
1235
+ type UrlMetadataQueryMode = "match" | "existence";
1236
+ /**
1237
+ * Build the plain JSON query object for a composition's URL metadata.
1238
+ *
1239
+ * Shared between the SDK (production composition resolution) and the Studio
1240
+ * UI (iframe-URL preview-entry fetch). The SDK passes the returned object (possibly
1241
+ * wrapped in an `$or` by `buildTemplateQuery`) to `ctQuery({ query })`; the UI
1242
+ * stringifies it and passes it to `api.cma.entry.getAll` via the `query` param.
1243
+ *
1244
+ * In `existence` mode for `legacy_url` and `content_type_url_pattern` the
1245
+ * object is `{ url: { $nin: ["", null] } }` regardless of `extractedVariables`.
1246
+ */
1247
+ declare function buildUrlMetadataQueryObject(context: Pick<TemplateQueryContext, "compositionQuery" | "extractedVariables" | "url_source">, mode?: UrlMetadataQueryMode): Record<string, any>;
1248
+ /**
1249
+ * Build the full template-entry query as a single raw query object and hand it
1250
+ * to `ctQuery({ query })`.
1251
+ *
1252
+ * Unlike the old per-field `where()` chaining, this builds one object so it can
1253
+ * express a top-level `$or` and embed `taxonomies.<uid>` directly (the dedicated
1254
+ * `applyTaxonomyFilters`/`Taxonomies()` path cannot compose inside an `$or`).
1255
+ *
1256
+ * For `{{entry.url}}` in a pattern-based source (match mode), the query becomes
1257
+ * `{ $or: [ <per-field decomposition>, { url: <full request path> } ] }` so the
1258
+ * `url` field matches the whole request path as well as the captured segment —
1259
+ * the prefix-duplication / bare-`/{{entry.url}}` case. Other sources and modes
1260
+ * pass the per-field object unchanged.
1261
+ */
1262
+ declare function buildTemplateQuery(stackSdk: StackSDK, context: TemplateQueryContext, queryOptions: {
1263
+ references: string[];
1264
+ only?: [string, string][];
1265
+ variantAlias?: string;
1266
+ locale?: string;
1267
+ branch?: string;
1268
+ environment?: string;
1269
+ }, mode?: UrlMetadataQueryMode): any;
1270
+ /**
1271
+ * Resolve template entry based on url_source type and query context
1272
+ */
1273
+ declare function resolveByUrlSource(stackSdk: StackSDK, url_source: string, compositionQuery: {
1274
+ url?: string;
1275
+ }, extractedVariables: ExtractedUrlPatternVariables, parsedUrlQueries: CompositionUrlQueries, connectedContentType: string, queryOptions: {
1276
+ references: string[];
1277
+ only?: [string, string][];
1278
+ variantAlias?: string;
1279
+ locale?: string;
1280
+ branch?: string;
1281
+ environment?: string;
1282
+ }): any;
1283
+
1284
+ /**
1285
+ * Parse and validate url_metadata field from a composition entry
1286
+ * Returns parsed metadata or legacy object if metadata is missing, malformed, or legacy
1287
+ */
1288
+ declare function parseUrlMetadata(url_metadata?: Partial<CompositionUrlMetadataSerialized>): CompositionUrlMetadata;
1289
+ /**
1290
+ * Check if a composition entry has taxonomy extraction enabled
1291
+ * Returns true if only.BASE includes "taxonomies"
1292
+ */
1293
+ declare function shouldExtractTaxonomies(parsedMetadata: CompositionUrlMetadata): boolean;
1294
+
1295
+ /**
1296
+ * Rank URL matches across multiple composition entries
1297
+ * Returns all composable_uid strings tied at the highest specificity score
1298
+ *
1299
+ * @param requestUrl The incoming URL to match against
1300
+ * @param lightweightEntries Composition entries with url and composable_uid
1301
+ * @returns Ranking result with all entries at max specificity tier
1302
+ */
1303
+ declare function rankUrlMatches(requestUrl: string, lightweightEntries: LightweightCompositionEntry[]): RankingResult;
1304
+
1305
+ /**
1306
+ * Determine if the metadata-driven path should be used
1307
+ * It means whether we want to fallback to the wildcard routes
1308
+ * or parse the URL for variables and determine the composition
1309
+ * Returns false if metadata is missing, invalid JSON, or url_source is legacy_url
1310
+ *
1311
+ * @param url_metadata Raw url_metadata from composition entry
1312
+ * @returns true if metadata path should be used, false for legacy path
1313
+ */
1314
+ declare function shouldUseUrlMetadataPath(url_metadata?: Partial<CompositionUrlMetadataSerialized>): boolean;
1315
+
1316
+ interface UrlPatternVariableInfo {
1317
+ type: string;
1318
+ name: string;
1319
+ category: (typeof URL_PATTERN_VARIABLE_TYPES)[keyof typeof URL_PATTERN_VARIABLE_TYPES];
1320
+ referenceName?: string;
1321
+ referenceField?: string;
1322
+ }
1323
+ /**
1324
+ * Compile a URL pattern into a regex that can match and extract variables
1325
+ * Handles arbitrary patterns like: "lsefj{{entry.url}}assefs{{content_type_uid}}/{{taxonomy:ola}}"
1326
+ */
1327
+ declare function compileUrlPattern(pattern: string, includeReferences?: string[]): {
1328
+ regex: RegExp;
1329
+ variableOrder: Array<UrlPatternVariableInfo>;
1330
+ literalCharCount: number;
1331
+ };
1332
+ /**
1333
+ * Match a request URL against a compiled pattern and extract variables
1334
+ */
1335
+ declare function matchUrlPattern(requestUrl: string, compiledPattern: ReturnType<typeof compileUrlPattern>): ExtractedUrlPatternVariables | null;
1336
+ /**
1337
+ * Compute pattern specificity score for ranking
1338
+ * Primary: literal character count (more specific)
1339
+ * Secondary: total pattern length
1340
+ */
1341
+ declare function computePatternSpecificity(pattern: string): number;
1342
+ interface MatchCompositionOptions {
1343
+ includeReferences?: string[];
1344
+ connected_content_type?: string;
1345
+ }
1346
+ /**
1347
+ * Match a single composition entry against a request URL
1348
+ */
1349
+ declare function matchCompositionUrl(requestUrl: string, compositionUrl: string, composable_uid: string, options?: MatchCompositionOptions): PatternMatchResult;
1350
+
1351
+ 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, 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, buildTemplateQuery, buildUrlMetadataQueryObject, calculateDynamicSpeed, clientRendererModeUtil, closeHiddenElementNotification, compileUrlPattern, composableStudioEventEmitter, compositionSaveEventListener, computePatternSpecificity, 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, matchCompositionUrl, matchUrlPattern, onlyParmasGenerator, openHiddenElementNotification, parseStringValue, parseUrlMetadata, preProcessStaticValues, queryParam, rankUrlMatches, registerJSONRTE, resolveByUrlSource, serializeComputedStyles, serializeEvent, setStaticEntryInDS, setTemplateEntryInDS, shouldExtractTaxonomies, shouldUseUrlMetadataPath, specUsesComponent, studioSdk, toggleNodeVisible, updateStyleOnStyleNodeChange };
1352
+ export type { ClientEditableNodeInternalAttributes, ClientPreviewNodeInternalAttributes, ComposableStudioErrorDetails, ComposableStudioLightSdk, CompositionEntry, CompositionEntryIncompleteUi, CompositionFetcher, CompositionPlacement, CompositionPreviewUrlSource, CompositionPreviewUrlSourceValues, CompositionQueryForSSR, CompositionQueryForSSRInput, CompositionQueryOptions, CompositionUrlMetadata, CompositionUrlMetadataSerialized, CompositionUrlQueries, Config, ConnectedEntryResult, DateVariableKey, EmittedEvents, ExtractedUrlPatternVariables, ExtractedUrlVariables, FetchCompositionContext, FetchTemplateEntryContext, FieldValue, FontVariants, GoogleFont, HiddenElementNotificationHandler, LightConfig, LightweightCompositionEntry, MetaProp, ParsedStringResult, PatternMatchResult, QueryExecutionOptions, QueryResult, QuerySpec, QueryState, RankingResult, ReferenceFieldValue, RenderableCompositionEntry, ResolvedQueryOptions, RuntimeContext, SearchQueryInput, SectionCompositionEntry, SeoMetadata, StudioComponentFetchOptions, StudioComponentSpecOptions, StudioSdk, StudioSpec, SymbolEntry, TemplateEntryFetcher, TemplateQueryContext, TroubleshootingInfo, URLSearchParamsString, UrlMatchDiagnostic, UrlMetadataQueryMode, UrlPatternMetadataField, UrlPatternMetadataFieldValue, UserConfig };