@contentstack/studio-client 1.6.0 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) 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 +170 -0
  6. package/dist/composable-studio/build-scoped-data.js.map +1 -0
  7. package/dist/composable-studio/collect-data-needs.js +270 -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/sdk.js +1677 -191
  12. package/dist/composable-studio/sdk.js.map +1 -1
  13. package/dist/composable-studio/studio-intelligence.manager.js +1 -12
  14. package/dist/composable-studio/studio-intelligence.manager.js.map +1 -1
  15. package/dist/config/default-config.js +1 -0
  16. package/dist/config/default-config.js.map +1 -1
  17. package/dist/config/stack-sdk-wrapper.js +85 -0
  18. package/dist/config/stack-sdk-wrapper.js.map +1 -1
  19. package/dist/highlight-node/highlight-node.js +4 -1
  20. package/dist/highlight-node/highlight-node.js.map +1 -1
  21. package/dist/index.d.ts +611 -39
  22. package/dist/index.js +10 -2
  23. package/dist/index.js.map +1 -1
  24. package/dist/json-rte-registry/embedded-entry-conversion.js +186 -0
  25. package/dist/json-rte-registry/embedded-entry-conversion.js.map +1 -0
  26. package/dist/json-rte-registry/index.js +73 -33
  27. package/dist/json-rte-registry/index.js.map +1 -1
  28. package/dist/json-rte-registry/stack-sdk-store.js +10 -0
  29. package/dist/json-rte-registry/stack-sdk-store.js.map +1 -0
  30. package/dist/node_modules/fflate/esm/browser.js +1 -7
  31. package/dist/node_modules/fflate/esm/browser.js.map +1 -1
  32. package/dist/packages/studio-internal/dist/utils/section-slot-walker.js +63 -0
  33. package/dist/packages/studio-internal/dist/utils/section-slot-walker.js.map +1 -0
  34. package/dist/query/query-executor.js +182 -27
  35. package/dist/query/query-executor.js.map +1 -1
  36. package/dist/url-metadata/build-template-query.js +124 -0
  37. package/dist/url-metadata/build-template-query.js.map +1 -0
  38. package/dist/url-metadata/parse-url-metadata.js +75 -0
  39. package/dist/url-metadata/parse-url-metadata.js.map +1 -0
  40. package/dist/url-metadata/rank-url-matches.js +100 -0
  41. package/dist/url-metadata/rank-url-matches.js.map +1 -0
  42. package/dist/url-metadata/select-url-winner.js +45 -0
  43. package/dist/url-metadata/select-url-winner.js.map +1 -0
  44. package/dist/url-metadata/shouldUseUrlMetadataPath.js +22 -0
  45. package/dist/url-metadata/shouldUseUrlMetadataPath.js.map +1 -0
  46. package/dist/url-metadata/types.js +50 -0
  47. package/dist/url-metadata/types.js.map +1 -0
  48. package/dist/url-metadata/url-pattern-matcher.js +311 -0
  49. package/dist/url-metadata/url-pattern-matcher.js.map +1 -0
  50. package/dist/utils/build-composition-fetch-query.js +19 -0
  51. package/dist/utils/build-composition-fetch-query.js.map +1 -0
  52. package/dist/utils/canvas.js +14 -0
  53. package/dist/utils/canvas.js.map +1 -1
  54. package/dist/utils/constants.js +19 -2
  55. package/dist/utils/constants.js.map +1 -1
  56. package/dist/utils/convertCompositionQueryInputToCompositionQuery.js +11 -1
  57. package/dist/utils/convertCompositionQueryInputToCompositionQuery.js.map +1 -1
  58. package/dist/utils/editor-utils.js +9 -0
  59. package/dist/utils/editor-utils.js.map +1 -1
  60. package/dist/utils/is-composition-being-edited.js.map +1 -1
  61. package/dist/utils/query-param.js +1 -1
  62. package/dist/utils/query-param.js.map +1 -1
  63. package/dist/utils/reference_fetcher.js +60 -5
  64. package/dist/utils/reference_fetcher.js.map +1 -1
  65. package/dist/utils/sdk.js +16 -1
  66. package/dist/utils/sdk.js.map +1 -1
  67. package/dist/utils/spec-analyzer.js +21 -4
  68. package/dist/utils/spec-analyzer.js.map +1 -1
  69. package/package.json +7 -10
  70. package/dist/get-composition-from-slug/get-composition-from-slug.js +0 -59
  71. package/dist/get-composition-from-slug/get-composition-from-slug.js.map +0 -1
  72. package/dist/utils/get-url-patterns.js +0 -40
  73. package/dist/utils/get-url-patterns.js.map +0 -1
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
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, Path, Operation, Descendant, Condition, NodeStyles } from '@contentstack/studio-internal';
3
3
  import * as _contentstack_studio_registry from '@contentstack/studio-registry';
4
4
  import { RawStaticValue, ICSEntryReference, StudioSpecData, StaticValue, BreakpointInput, Breakpoint } from '@contentstack/studio-registry';
5
5
  export { Breakpoint } from '@contentstack/studio-registry';
@@ -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,17 +636,19 @@ 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>;
387
640
  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>;
641
+ fetchData: (compositionEntry: CompositionEntry, queryOptions: _contentstack_studio_messenger.CompositionQuery, options?: CompositionQueryOptions, sectionEntries?: SectionCompositionEntry[], searchParams?: URLSearchParams) => Promise<_contentstack_studio_registry.StudioSpecData>;
389
642
  fetchTemplateEntry: (fetchOptions: {
390
643
  connected_content_type: string;
391
644
  compositionQuery: _contentstack_studio_messenger.CompositionQuery;
392
645
  includeQueries: string[];
393
646
  onlyQueries: [string, string][];
394
647
  composableUid: string;
395
- }, data: _contentstack_studio_registry.StudioSpecData, compositionEntry: CompositionEntry, compositionQueryOptions?: CompositionQueryOptions) => Promise<void>;
396
- getSeoMetadata: (ui: _contentstack_studio_internal.Node) => SeoMetadata;
648
+ }, data: _contentstack_studio_registry.StudioSpecData, compositionEntry: CompositionEntry, compositionQueryOptions?: CompositionQueryOptions, urlPatternContext?: {
649
+ matchResult: ReturnType<typeof matchCompositionUrl> | undefined;
650
+ }, searchParams?: URLSearchParams) => Promise<void>;
651
+ getSeoMetadata: (ui: _contentstack_studio_internal.Node, specData?: _contentstack_studio_registry.StudioSpecData) => SeoMetadata | null;
397
652
  };
398
653
  public: {
399
654
  fetchCompositionData: (queryOptions: CompositionQueryForSSRInput, options?: CompositionQueryOptions) => Promise<StudioComponentSpecOptions>;
@@ -620,11 +875,20 @@ declare function addBreakpointEventListeners(): {
620
875
  declare const DEFAULT_BREAKPOINTS: BreakpointInput;
621
876
 
622
877
  declare class BreakpointManager {
623
- private static instance;
624
878
  private activeBreakpoint;
625
879
  private breakpointRegistry;
626
880
  private constructor();
881
+ /**
882
+ * Returns the singleton `BreakpointManager` instance from the SDK's
883
+ * versioned `globalThis` slot. See
884
+ * `@contentstack/studio-registry/common/global-store.ts` for why singletons
885
+ * live on globalThis instead of a class-static field.
886
+ */
627
887
  static getInstance(): BreakpointManager;
888
+ /**
889
+ * Resets the singleton. For tests only.
890
+ */
891
+ static resetInstance(): void;
628
892
  setActiveBreakpoint(breakpoint: Breakpoint): void;
629
893
  getActiveBreakpoint(): Breakpoint | null;
630
894
  findMatchingBreakpoint(): Breakpoint;
@@ -643,10 +907,20 @@ declare const queryParam: {
643
907
  get(key: ComposableStudioQueryParamsKeys): string | null;
644
908
  has(key: ComposableStudioQueryParamsKeys): boolean;
645
909
  };
646
- declare const onlyParmasGenerator: (only: [string, string][]) => Record<string, string>;
910
+ declare const onlyParmasGenerator: (only: [string, string][]) => Record<string, string[]>;
647
911
 
912
+ declare const SECTION_COMPOSITIONS_KEY = "section_compositions";
913
+ declare const TEMPLATE_FULL_ENTRY_KEY = "template_full_entry";
648
914
  declare const setTemplateEntryInDS: (dataSources: Record<string, any>, entry: unknown) => void;
649
915
  declare const setStaticEntryInDS: (dataSources: Record<string, any>, ct_uid: string, _entries: unknown) => void;
916
+ /**
917
+ * Counterpart to setStaticEntryInDS: drop a single resolved additional entry
918
+ * from the contentstack data source bucket. Called when the author removes an
919
+ * entry so the pruned bucket replaces the stale one on the next UPDATE_SPEC_DATA
920
+ * push (which merges at the dataSources level); without it the removed entry's
921
+ * data lingers and keeps rendering.
922
+ */
923
+ declare const removeStaticEntryFromDS: (dataSources: Record<string, any>, ct_uid: string, uid: string) => void;
650
924
  declare const batchFetchEntries: (sdk: StackSDK, entries: ICSEntryReference[]) => Promise<[string, CompositionEntry[]][]>;
651
925
  declare const getBindingStringForCS: (binding: BindingType) => string;
652
926
  type EntriesResponse<T> = {
@@ -764,6 +1038,20 @@ declare class RendererModeUtil {
764
1038
  */
765
1039
  getMode(compositionUid: string): "preview" | "edit" | "show_edit_button";
766
1040
  }
1041
+ /**
1042
+ * Module-level mode util backed by `window.location.search` (the browser URL).
1043
+ *
1044
+ * SSR CAUTION: this reads `window`, which does not exist on the server, so on the server
1045
+ * every method returns its production default (e.g. `isInsideStudioFrame()` -> false) for
1046
+ * ALL requests. It is correct ONLY in browser-only code (the editor render, hooks,
1047
+ * INIT_STUDIO). In server-reachable fetch code (studio-client's spec-fetch path) do NOT use
1048
+ * this: the answer is wrong on the server, and a single shared singleton cannot represent
1049
+ * per-request state across concurrent SSR requests anyway. There, use the request-scoped
1050
+ * helpers in `sdk.ts` (`isInStudio` / `isEditorFetch` / `readStudioParam`, built on
1051
+ * `getRequestSearchParams`), which read the forwarded request query on the server and fall
1052
+ * back to `window` on the client. See COMS-1554 for the AsyncLocalStorage proposal that would
1053
+ * remove this split and make this util correct everywhere.
1054
+ */
767
1055
  declare const clientRendererModeUtil: RendererModeUtil;
768
1056
  declare const serializeComputedStyles: (computedStyle: CSSStyleDeclaration) => Record<string, string>;
769
1057
 
@@ -844,40 +1132,201 @@ interface EmittedEvents {
844
1132
 
845
1133
  declare const composableStudioEventEmitter: EventEmitter<EmittedEvents, any>;
846
1134
 
1135
+ interface EmbeddedEntryRenderArgs {
1136
+ entryUid: string;
1137
+ contentTypeUid: string;
1138
+ displayType: string;
1139
+ title: string;
1140
+ /** Full resolved entry object — every field the delivery API returned. */
1141
+ entry: ResolvedEmbeddedEntry;
1142
+ }
847
1143
  /**
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
1144
+ * Args passed to the user-registered `embeddedAsset` renderer.
1145
+ *
1146
+ * Asset metadata travels inline in the RTE markup — no fetch needed:
1147
+ * HTML RTE: `<figure class="embedded-asset" data-sys-asset-uid="…"
1148
+ * data-sys-asset-filelink="…" data-sys-asset-contenttype="…"
1149
+ * data-sys-asset-filename="…" data-sys-asset-alt="…"
1150
+ * sys-style-type="display"></figure>`
1151
+ * JSON RTE: `{ type:"reference", attrs:{ type:"asset", "asset-uid":"…",
1152
+ * "asset-link":"…", "asset-type":"image/png", "asset-name":"…",
1153
+ * alt:"…", "display-type":"display" } }`
1154
+ */
1155
+ interface EmbeddedAssetRenderArgs {
1156
+ assetUid: string;
1157
+ /** Direct CDN URL — use as `<img src>` / `<video src>` etc. */
1158
+ url: string;
1159
+ /** MIME type, e.g. `image/png`, `video/mp4`. Drives default renderer's tag choice. */
1160
+ contentType: string;
1161
+ /** Original filename, useful for download links. */
1162
+ filename: string;
1163
+ /** Alt text from the RTE editor — empty string when unset. */
1164
+ alt: string;
1165
+ /** Layout hint from the editor: `display` (block), `inline`, `link`, etc. */
1166
+ displayType: string;
1167
+ }
1168
+ /**
1169
+ * Default asset renderer used when the user hasn't registered an
1170
+ * `embeddedAsset` callback via `registerRTERenderer`. Branches on MIME type:
1171
+ * image/* → `<img src>` (with alt + class for styling hooks)
1172
+ * video/* → `<video src controls>`
1173
+ * audio/* → `<audio src controls>`
1174
+ * other → `<a href download>` fallback link
1175
+ *
1176
+ * Unsafe URL schemes (`javascript:`, `vbscript:`, non-image `data:` etc.) are
1177
+ * blocked and render as plain text placeholder to prevent XSS.
1178
+ */
1179
+ declare function defaultAssetRender({ assetUid, url, contentType, filename, alt, }: EmbeddedAssetRenderArgs): string;
1180
+ interface EmbeddedEntryConversionOptions {
1181
+ /**
1182
+ * Pre-resolved entry map. Keys are entry UIDs. Each value is the full entry
1183
+ * object (any fields). The `title` field is used as the display label unless
1184
+ * your `render` function overrides it.
1185
+ *
1186
+ * When omitted the SDK fetches entries automatically via `fetchEmbeddedEntries`.
1187
+ */
1188
+ entries?: Record<string, ResolvedEmbeddedEntry>;
1189
+ render?: (args: EmbeddedEntryRenderArgs) => string;
1190
+ /**
1191
+ * Custom element type renderers for JSON RTE plugins (e.g. table, social-embed,
1192
+ * code-block). Merged with the built-in `reference` handler. Keyed by the
1193
+ * node `type` value produced by the RTE plugin.
1194
+ *
1195
+ * @example
1196
+ * createEmbeddedEntryConversion({
1197
+ * customElementTypes: {
1198
+ * table: (attrs, child) => `<table>${child}</table>`,
1199
+ * "social-embed": (attrs, child, block) =>
1200
+ * `<div class="embed" data-url="${block?.attrs?.url ?? ""}">${child}</div>`,
1201
+ * },
1202
+ * });
1203
+ */
1204
+ customElementTypes?: IJsonToHtmlOptions["customElementTypes"];
1205
+ }
1206
+ interface ResolvedEmbeddedEntry {
1207
+ uid: string;
1208
+ title?: string;
1209
+ _content_type_uid?: string;
1210
+ [key: string]: any;
1211
+ }
1212
+ /** Walk a JSON RTE doc and collect all entry-reference {entryUid, contentTypeUid} pairs. */
1213
+ declare function extractJsonRteRefs(node: any): Array<{
1214
+ entryUid: string;
1215
+ contentTypeUid: string;
1216
+ }>;
1217
+ /** Extract {entryUid, contentTypeUid} pairs from an HTML RTE string via regex. */
1218
+ declare function extractHtmlRteRefs(html: string): Array<{
1219
+ entryUid: string;
1220
+ contentTypeUid: string;
1221
+ }>;
1222
+ /**
1223
+ * Fetch embedded entries from the registered stack SDK.
1224
+ * Groups refs by content type and issues one query per group in parallel.
1225
+ * Returns a uid→entry map.
1226
+ */
1227
+ declare function fetchEmbeddedEntries(refs: Array<{
1228
+ entryUid: string;
1229
+ contentTypeUid: string;
1230
+ }>): Promise<Record<string, ResolvedEmbeddedEntry>>;
1231
+ declare function createEmbeddedEntryConversion(options?: EmbeddedEntryConversionOptions & {
1232
+ /** Asset renderer — defaults to `defaultAssetRender` (img/video/audio/link by MIME). */
1233
+ renderAsset?: (args: EmbeddedAssetRenderArgs) => string;
1234
+ }): IJsonToHtmlOptions;
1235
+
1236
+ /**
1237
+ * Unified RTE configuration. Extends the JSON RTE serializer options with
1238
+ * an `embeddedEntry` renderer so users configure everything in one call.
1239
+ *
860
1240
  * @example
861
- * registerJSONRTE({
1241
+ * registerRTERenderer({
1242
+ * // Embedded entry rendering
1243
+ * embeddedEntry: ({ entry, contentTypeUid, displayType }) => {
1244
+ * if (displayType === "block") return `<h1>${entry.title}</h1>`;
1245
+ * return `<span>${entry.title}</span>`;
1246
+ * },
1247
+ * // Custom JSON RTE node types
1248
+ * customElementTypes: {
1249
+ * "code-block": (attrs, child) => `<pre><code>${child}</code></pre>`,
1250
+ * },
1251
+ * allowNonStandardTypes: true,
1252
+ * });
1253
+ */
1254
+ interface RTEConfig extends IJsonToHtmlOptions {
1255
+ embeddedEntry?: (args: EmbeddedEntryRenderArgs) => string;
1256
+ /**
1257
+ * Renderer for embedded ASSETS in RTE fields (images / videos / audio /
1258
+ * file links inserted via the editor's "Insert Asset" button). Both JSON
1259
+ * RTE (`{ attrs.type: "asset" }`) and HTML RTE (`<figure
1260
+ * class="embedded-asset" data-sys-asset-uid="…">`) paths invoke this.
1261
+ *
1262
+ * Omit to use the built-in default (img for image/*, video/audio with
1263
+ * controls for those MIMEs, `<a download>` fallback otherwise).
1264
+ */
1265
+ embeddedAsset?: (args: EmbeddedAssetRenderArgs) => string;
1266
+ }
1267
+ /**
1268
+ * Unified RTE registration. Covers both embedded entry rendering and custom
1269
+ * JSON RTE node types in a single call. Replaces the full config on each call.
1270
+ *
1271
+ * @example — embedded entries only
1272
+ * registerRTERenderer({
1273
+ * embeddedEntry: ({ entry, contentTypeUid, displayType }) => {
1274
+ * if (displayType === "block") return `<div><h3>${entry.full_name ?? entry.title}</h3></div>`;
1275
+ * if (displayType === "link") return `<a href="${entry.url}">${entry.title}</a>`;
1276
+ * return `<span>${entry.title}</span>`;
1277
+ * },
1278
+ * });
1279
+ *
1280
+ * @example — JSON RTE custom node types only
1281
+ * registerRTERenderer({
1282
+ * customElementTypes: {
1283
+ * "code-block": (attrs, child) => `<pre><code>${child}</code></pre>`,
1284
+ * "my-table": (attrs, child) => `<table>${child}</table>`,
1285
+ * },
1286
+ * allowNonStandardTypes: true,
1287
+ * });
1288
+ *
1289
+ * @example — both together
1290
+ * registerRTERenderer({
1291
+ * embeddedEntry: ({ entry, contentTypeUid, displayType }) => {
1292
+ * const label = entry.full_name ?? entry.title ?? entry.uid;
1293
+ * if (displayType === "block") return `<div><h1>${label}</h1><p>${entry.short_bio ?? ""}</p></div>`;
1294
+ * if (displayType === "link") return `<a href="${entry.url ?? "#"}">${label}</a>`;
1295
+ * return `<span>${label}</span>`;
1296
+ * },
862
1297
  * 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
- * },
1298
+ * "code-block": (attrs, child) => `<pre><code>${child}</code></pre>`,
872
1299
  * },
873
1300
  * });
874
1301
  */
1302
+ declare function registerRTERenderer(config: RTEConfig): void;
1303
+ /**
1304
+ * @deprecated Use `registerRTERenderer` instead. Preserves any previously
1305
+ * registered `embeddedEntry` / `embeddedAsset` renderers; only replaces the
1306
+ * JSON RTE serializer options.
1307
+ */
875
1308
  declare function registerJSONRTE(config: IJsonToHtmlOptions): void;
876
1309
  /**
877
- * Gets the current config for JSON RTE
878
- * @returns The current config for JSON RTE
1310
+ * @deprecated Use `registerRTERenderer` instead. Registers embedded entry
1311
+ * renderer only — does not clear existing `customElementTypes` or `embeddedAsset`.
1312
+ */
1313
+ declare function registerEmbeddedEntryRenderer(render: (args: EmbeddedEntryRenderArgs) => string): void;
1314
+ /**
1315
+ * Returns the current JSON RTE serializer options (without embeddedEntry / embeddedAsset).
1316
+ * Used internally by the RichText / CollapsibleText hooks.
879
1317
  */
880
1318
  declare function getJSONRTE(): IJsonToHtmlOptions;
1319
+ /**
1320
+ * Returns the registered embedded entry renderer, or null if none registered.
1321
+ * Used internally by the RichText / CollapsibleText hooks.
1322
+ */
1323
+ declare function getEmbeddedEntryRenderer(): ((args: EmbeddedEntryRenderArgs) => string) | null;
1324
+ /**
1325
+ * Returns the registered embedded asset renderer, or null if none registered.
1326
+ * Used internally by the RichText / CollapsibleText hooks. When null, the
1327
+ * hook falls back to `defaultAssetRender` so canvas never shows blank assets.
1328
+ */
1329
+ declare function getEmbeddedAssetRenderer(): ((args: EmbeddedAssetRenderArgs) => string) | null;
881
1330
 
882
1331
  declare const compositionSaveEventListener: () => {
883
1332
  unregister: () => void;
@@ -895,7 +1344,7 @@ declare function getNodeScreenshotEvent(): {
895
1344
 
896
1345
  interface QuerySpec {
897
1346
  contentType: string;
898
- sourceType?: "content_type" | "taxonomy";
1347
+ sourceType?: "content_type" | "contentstack" | "taxonomy";
899
1348
  query: Record<string, any>;
900
1349
  params: Record<string, any>;
901
1350
  }
@@ -965,5 +1414,128 @@ declare class QueryExecutor {
965
1414
  private resolveExpressionsInQuery;
966
1415
  }
967
1416
 
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 };
1417
+ /**
1418
+ * Query-building mode.
1419
+ * - `match`: predicates equal the captured value (production composition lookup).
1420
+ * - `existence`: predicates require the field to be present and non-empty (Studio
1421
+ * iframe-URL flow — we have no URL to match against; we only need an entry
1422
+ * that has values for every variable in the pattern).
1423
+ */
1424
+ type UrlMetadataQueryMode = "match" | "existence";
1425
+ /**
1426
+ * Build the plain JSON query object for a composition's URL metadata.
1427
+ *
1428
+ * Shared between the SDK (production composition resolution) and the Studio
1429
+ * UI (iframe-URL preview-entry fetch). The SDK passes the returned object (possibly
1430
+ * wrapped in an `$or` by `buildTemplateQuery`) to `ctQuery({ query })`; the UI
1431
+ * stringifies it and passes it to `api.cma.entry.getAll` via the `query` param.
1432
+ *
1433
+ * In `existence` mode for `legacy_url` and `content_type_url_pattern` the
1434
+ * object is `{ url: { $nin: ["", null] } }` regardless of `extractedVariables`.
1435
+ */
1436
+ declare function buildUrlMetadataQueryObject(context: Pick<TemplateQueryContext, "compositionQuery" | "extractedVariables" | "url_source">, mode?: UrlMetadataQueryMode): Record<string, any>;
1437
+ /**
1438
+ * Build the full template-entry query as a single raw query object and hand it
1439
+ * to `ctQuery({ query })`.
1440
+ *
1441
+ * Unlike the old per-field `where()` chaining, this builds one object so it can
1442
+ * express a top-level `$or` and embed `taxonomies.<uid>` directly (the dedicated
1443
+ * `applyTaxonomyFilters`/`Taxonomies()` path cannot compose inside an `$or`).
1444
+ *
1445
+ * For `{{entry.url}}` in a pattern-based source (match mode), the query becomes
1446
+ * `{ $or: [ <per-field decomposition>, { url: <full request path> } ] }` so the
1447
+ * `url` field matches the whole request path as well as the captured segment —
1448
+ * the prefix-duplication / bare-`/{{entry.url}}` case. Other sources and modes
1449
+ * pass the per-field object unchanged.
1450
+ */
1451
+ declare function buildTemplateQuery(stackSdk: StackSDK, context: TemplateQueryContext, queryOptions: {
1452
+ references: string[];
1453
+ only?: [string, string][];
1454
+ variantAlias?: string;
1455
+ locale?: string;
1456
+ branch?: string;
1457
+ environment?: string;
1458
+ }, mode?: UrlMetadataQueryMode): any;
1459
+ /**
1460
+ * Resolve template entry based on url_source type and query context
1461
+ */
1462
+ declare function resolveByUrlSource(stackSdk: StackSDK, url_source: string, compositionQuery: {
1463
+ url?: string;
1464
+ }, extractedVariables: ExtractedUrlPatternVariables, parsedUrlQueries: CompositionUrlQueries, connectedContentType: string, queryOptions: {
1465
+ references: string[];
1466
+ only?: [string, string][];
1467
+ variantAlias?: string;
1468
+ locale?: string;
1469
+ branch?: string;
1470
+ environment?: string;
1471
+ }): any;
1472
+
1473
+ /**
1474
+ * Parse and validate url_metadata field from a composition entry
1475
+ * Returns parsed metadata or legacy object if metadata is missing, malformed, or legacy
1476
+ */
1477
+ declare function parseUrlMetadata(url_metadata?: Partial<CompositionUrlMetadataSerialized>): CompositionUrlMetadata;
1478
+ /**
1479
+ * Check if a composition entry has taxonomy extraction enabled
1480
+ * Returns true if only.BASE includes "taxonomies"
1481
+ */
1482
+ declare function shouldExtractTaxonomies(parsedMetadata: CompositionUrlMetadata): boolean;
1483
+
1484
+ /**
1485
+ * Rank URL matches across multiple composition entries
1486
+ * Returns all composable_uid strings tied at the highest specificity score
1487
+ *
1488
+ * @param requestUrl The incoming URL to match against
1489
+ * @param lightweightEntries Composition entries with url and composable_uid
1490
+ * @returns Ranking result with all entries at max specificity tier
1491
+ */
1492
+ declare function rankUrlMatches(requestUrl: string, lightweightEntries: LightweightCompositionEntry[]): RankingResult;
1493
+
1494
+ /**
1495
+ * Determine if the metadata-driven path should be used
1496
+ * It means whether we want to fallback to the wildcard routes
1497
+ * or parse the URL for variables and determine the composition
1498
+ * Returns false if metadata is missing, invalid JSON, or url_source is legacy_url
1499
+ *
1500
+ * @param url_metadata Raw url_metadata from composition entry
1501
+ * @returns true if metadata path should be used, false for legacy path
1502
+ */
1503
+ declare function shouldUseUrlMetadataPath(url_metadata?: Partial<CompositionUrlMetadataSerialized>): boolean;
1504
+
1505
+ interface UrlPatternVariableInfo {
1506
+ type: string;
1507
+ name: string;
1508
+ category: (typeof URL_PATTERN_VARIABLE_TYPES)[keyof typeof URL_PATTERN_VARIABLE_TYPES];
1509
+ referenceName?: string;
1510
+ referenceField?: string;
1511
+ }
1512
+ /**
1513
+ * Compile a URL pattern into a regex that can match and extract variables
1514
+ * Handles arbitrary patterns like: "lsefj{{entry.url}}assefs{{content_type_uid}}/{{taxonomy:ola}}"
1515
+ */
1516
+ declare function compileUrlPattern(pattern: string, includeReferences?: string[]): {
1517
+ regex: RegExp;
1518
+ variableOrder: Array<UrlPatternVariableInfo>;
1519
+ literalCharCount: number;
1520
+ };
1521
+ /**
1522
+ * Match a request URL against a compiled pattern and extract variables
1523
+ */
1524
+ declare function matchUrlPattern(requestUrl: string, compiledPattern: ReturnType<typeof compileUrlPattern>): ExtractedUrlPatternVariables | null;
1525
+ /**
1526
+ * Compute pattern specificity score for ranking
1527
+ * Primary: literal character count (more specific)
1528
+ * Secondary: total pattern length
1529
+ */
1530
+ declare function computePatternSpecificity(pattern: string): number;
1531
+ interface MatchCompositionOptions {
1532
+ includeReferences?: string[];
1533
+ connected_content_type?: string;
1534
+ }
1535
+ /**
1536
+ * Match a single composition entry against a request URL
1537
+ */
1538
+ declare function matchCompositionUrl(requestUrl: string, compositionUrl: string, composable_uid: string, options?: MatchCompositionOptions): PatternMatchResult;
1539
+
1540
+ 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, createEmbeddedEntryConversion, studioSdk as default, defaultAssetRender, dndEventListener, dndManager, entriesFromResponse, evaluateCondition, extractHtmlRteRefs, extractJsonRteRefs, fetchEmbeddedEntries, findNearestBuilderNode, findNearestSlotNode, findPath, findPathForElement, getBindingStringForCS, getComponentUsageStats, getComposableElement, getComputedStyles, getDefaultConfig, getEmbeddedAssetRenderer, getEmbeddedEntryRenderer, 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, registerEmbeddedEntryRenderer, registerJSONRTE, registerRTERenderer, removeStaticEntryFromDS, resolveByUrlSource, serializeComputedStyles, serializeEvent, setStaticEntryInDS, setTemplateEntryInDS, shouldExtractTaxonomies, shouldUseUrlMetadataPath, specUsesComponent, studioSdk, toggleNodeVisible, updateStyleOnStyleNodeChange };
1541
+ export type { ClientEditableNodeInternalAttributes, ClientPreviewNodeInternalAttributes, ComposableStudioErrorDetails, ComposableStudioLightSdk, CompositionEntry, CompositionEntryIncompleteUi, CompositionFetcher, CompositionPlacement, CompositionPreviewUrlSource, CompositionPreviewUrlSourceValues, CompositionQueryForSSR, CompositionQueryForSSRInput, CompositionQueryOptions, CompositionUrlMetadata, CompositionUrlMetadataSerialized, CompositionUrlQueries, Config, ConnectedEntryResult, DateVariableKey, EmbeddedAssetRenderArgs, EmbeddedEntryConversionOptions, EmbeddedEntryRenderArgs, EmittedEvents, ExtractedUrlPatternVariables, ExtractedUrlVariables, FetchCompositionContext, FetchTemplateEntryContext, FieldValue, FontVariants, GoogleFont, HiddenElementNotificationHandler, LightConfig, LightweightCompositionEntry, MetaProp, ParsedStringResult, PatternMatchResult, QueryExecutionOptions, QueryResult, QuerySpec, QueryState, RTEConfig, RankingResult, ReferenceFieldValue, RenderableCompositionEntry, ResolvedEmbeddedEntry, ResolvedQueryOptions, RuntimeContext, SearchQueryInput, SectionCompositionEntry, SeoMetadata, StudioComponentFetchOptions, StudioComponentSpecOptions, StudioSdk, StudioSpec, SymbolEntry, TemplateEntryFetcher, TemplateQueryContext, TroubleshootingInfo, URLSearchParamsString, UrlMatchDiagnostic, UrlMetadataQueryMode, UrlPatternMetadataField, UrlPatternMetadataFieldValue, UserConfig };