@contentstack/studio-client 4.0.0 → 4.2.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 (124) hide show
  1. package/dist/breakpoints/BreakpointManager.js +3 -2
  2. package/dist/breakpoints/BreakpointManager.js.map +1 -1
  3. package/dist/breakpoints/breakpoint-origin.js +30 -0
  4. package/dist/breakpoints/breakpoint-origin.js.map +1 -0
  5. package/dist/canvas/canvas.type.js +1 -1
  6. package/dist/canvas/canvas.utils.js +213 -9
  7. package/dist/canvas/canvas.utils.js.map +1 -1
  8. package/dist/composable-studio/binding-defect-report.js +106 -0
  9. package/dist/composable-studio/binding-defect-report.js.map +1 -0
  10. package/dist/composable-studio/build-scoped-data.js +21 -11
  11. package/dist/composable-studio/build-scoped-data.js.map +1 -1
  12. package/dist/composable-studio/collect-data-needs.js +1 -1
  13. package/dist/composable-studio/data/pre-process-static-values.js +89 -19
  14. package/dist/composable-studio/data/pre-process-static-values.js.map +1 -1
  15. package/dist/composable-studio/delivery-setup-check.js +92 -0
  16. package/dist/composable-studio/delivery-setup-check.js.map +1 -0
  17. package/dist/composable-studio/resolution-failure-spec.js +53 -0
  18. package/dist/composable-studio/resolution-failure-spec.js.map +1 -0
  19. package/dist/composable-studio/resolution-telemetry.js +68 -0
  20. package/dist/composable-studio/resolution-telemetry.js.map +1 -0
  21. package/dist/composable-studio/sdk.js +683 -551
  22. package/dist/composable-studio/sdk.js.map +1 -1
  23. package/dist/composable-studio/section-binding/compute-all-section-auto-bindings.js +146 -0
  24. package/dist/composable-studio/section-binding/compute-all-section-auto-bindings.js.map +1 -0
  25. package/dist/composable-studio/section-binding/constants.js +27 -0
  26. package/dist/composable-studio/section-binding/constants.js.map +1 -0
  27. package/dist/composable-studio/section-binding/index.js +20 -0
  28. package/dist/composable-studio/section-binding/index.js.map +1 -0
  29. package/dist/composable-studio/section-binding/schema-path.js +112 -0
  30. package/dist/composable-studio/section-binding/schema-path.js.map +1 -0
  31. package/dist/composable-studio/section-binding/section-composition-auto-binding.js +815 -0
  32. package/dist/composable-studio/section-binding/section-composition-auto-binding.js.map +1 -0
  33. package/dist/composable-studio/section-binding/section-compositions.js +349 -0
  34. package/dist/composable-studio/section-binding/section-compositions.js.map +1 -0
  35. package/dist/composable-studio/section-binding/section-internal-ref-introspection.js +72 -0
  36. package/dist/composable-studio/section-binding/section-internal-ref-introspection.js.map +1 -0
  37. package/dist/composable-studio/section-binding/self-describe-section-bindings.js +132 -0
  38. package/dist/composable-studio/section-binding/self-describe-section-bindings.js.map +1 -0
  39. package/dist/composable-studio/section-binding/serialization.js +33 -0
  40. package/dist/composable-studio/section-binding/serialization.js.map +1 -0
  41. package/dist/composable-studio/section-data.js +5 -1
  42. package/dist/composable-studio/section-data.js.map +1 -1
  43. package/dist/composable-studio/setup-check-signal.js +48 -0
  44. package/dist/composable-studio/setup-check-signal.js.map +1 -0
  45. package/dist/composable-studio/studio-intelligence.manager.js +6 -2
  46. package/dist/composable-studio/studio-intelligence.manager.js.map +1 -1
  47. package/dist/composable-studio/weak-maps.js +3 -1
  48. package/dist/composable-studio/weak-maps.js.map +1 -1
  49. package/dist/config/config.schema.js +97 -104
  50. package/dist/config/config.schema.js.map +1 -1
  51. package/dist/config/process-user-config.js +41 -24
  52. package/dist/config/process-user-config.js.map +1 -1
  53. package/dist/config/stack-sdk-wrapper.js +22 -4
  54. package/dist/config/stack-sdk-wrapper.js.map +1 -1
  55. package/dist/context-menu/context-menu.js +1 -0
  56. package/dist/context-menu/context-menu.js.map +1 -1
  57. package/dist/dnd/dnd-manager.js +29 -0
  58. package/dist/dnd/dnd-manager.js.map +1 -1
  59. package/dist/editor.d.ts +42 -1
  60. package/dist/highlight-node/highlight-node-manager.js +89 -14
  61. package/dist/highlight-node/highlight-node-manager.js.map +1 -1
  62. package/dist/highlight-node/highlight-node.js +16 -4
  63. package/dist/highlight-node/highlight-node.js.map +1 -1
  64. package/dist/highlight-node/history-shortcut.js +78 -0
  65. package/dist/highlight-node/history-shortcut.js.map +1 -0
  66. package/dist/index.d.ts +1099 -353
  67. package/dist/index.js +19 -7
  68. package/dist/index.js.map +1 -1
  69. package/dist/query/query-executor.js +51 -9
  70. package/dist/query/query-executor.js.map +1 -1
  71. package/dist/renderer-mode.d.ts +68 -0
  72. package/dist/renderer-mode.js +2 -0
  73. package/dist/renderer-mode.js.map +1 -0
  74. package/dist/url-metadata/entry-check-key.js +14 -0
  75. package/dist/url-metadata/entry-check-key.js.map +1 -0
  76. package/dist/url-metadata/select-url-winner.js +64 -12
  77. package/dist/url-metadata/select-url-winner.js.map +1 -1
  78. package/dist/url-metadata/types.js +10 -1
  79. package/dist/url-metadata/types.js.map +1 -1
  80. package/dist/url-metadata/url-pattern-matcher.js +11 -2
  81. package/dist/url-metadata/url-pattern-matcher.js.map +1 -1
  82. package/dist/utils/canvas.js +0 -1
  83. package/dist/utils/canvas.js.map +1 -1
  84. package/dist/utils/check-bindings.js +5 -3
  85. package/dist/utils/check-bindings.js.map +1 -1
  86. package/dist/utils/classify-response-error.js +243 -33
  87. package/dist/utils/classify-response-error.js.map +1 -1
  88. package/dist/utils/composable-studio-error.js +7 -0
  89. package/dist/utils/composable-studio-error.js.map +1 -1
  90. package/dist/utils/conditionBlock.js +19 -6
  91. package/dist/utils/conditionBlock.js.map +1 -1
  92. package/dist/utils/constants.js +11 -2
  93. package/dist/utils/constants.js.map +1 -1
  94. package/dist/utils/http-error.constants.js +24 -1
  95. package/dist/utils/http-error.constants.js.map +1 -1
  96. package/dist/utils/include-path-rules.js +3 -2
  97. package/dist/utils/include-path-rules.js.map +1 -1
  98. package/dist/utils/load-error-classifier.js +18 -0
  99. package/dist/utils/load-error-classifier.js.map +1 -0
  100. package/dist/utils/parse-ui.js +27 -5
  101. package/dist/utils/parse-ui.js.map +1 -1
  102. package/dist/utils/preview-hash-refused.js +75 -0
  103. package/dist/utils/preview-hash-refused.js.map +1 -0
  104. package/dist/utils/reference_fetcher.js +79 -12
  105. package/dist/utils/reference_fetcher.js.map +1 -1
  106. package/dist/utils/require-stack.js +83 -20
  107. package/dist/utils/require-stack.js.map +1 -1
  108. package/dist/utils/serialize-for-inline-script.js +19 -0
  109. package/dist/utils/serialize-for-inline-script.js.map +1 -0
  110. package/dist/utils/served-by.js +32 -13
  111. package/dist/utils/served-by.js.map +1 -1
  112. package/dist/utils/spec-analyzer.js +24 -1
  113. package/dist/utils/spec-analyzer.js.map +1 -1
  114. package/dist/utils/studio-error-codes.js +34 -2
  115. package/dist/utils/studio-error-codes.js.map +1 -1
  116. package/dist/utils/studio-error.js +68 -7
  117. package/dist/utils/studio-error.js.map +1 -1
  118. package/dist/visual-builder/composition-save-event.js +36 -5
  119. package/dist/visual-builder/composition-save-event.js.map +1 -1
  120. package/package.json +12 -8
  121. package/dist/studio-internal/dist/utils/section-slot-walker.js +0 -63
  122. package/dist/studio-internal/dist/utils/section-slot-walker.js.map +0 -1
  123. package/dist/studio-internal/dist/utils/spec-compression.js +0 -43
  124. package/dist/studio-internal/dist/utils/spec-compression.js.map +0 -1
package/dist/index.d.ts CHANGED
@@ -1,18 +1,19 @@
1
1
  import * as _contentstack_studio_internal from '@contentstack/studio-internal';
2
2
  import { Node, BindingType, PathNode, Operation, Descendant, Path, Condition, NodeStyles } from '@contentstack/studio-internal';
3
+ export { COMPOSABLE_UID_MAX_LENGTH, COMPOSABLE_UID_PATTERN, ComposableUidProblem, HTML_ATTRIBUTE_NAME_PATTERN, HtmlAttributeNameProblem, STUDIO_HTML_ATTRIBUTE_PREFIX, STYLE_HTML_ATTRIBUTES, composableUidFromName, composableUidInvalidCharacters, composableUidProblem, htmlAttributeNameProblem } from '@contentstack/studio-internal';
3
4
  import * as _contentstack_studio_registry from '@contentstack/studio-registry';
4
- import { StudioStateConfig, RawStaticValue, ICSEntryReference, StudioSpecData, DataSources, SectionScopedDataSources, StaticValue, BreakpointInput, Breakpoint } from '@contentstack/studio-registry';
5
+ import { StudioStateConfig, StudioSpecData, RawStaticValue, ICSEntryReference, DataSources, SectionScopedDataSources, StaticValue, BreakpointInput, Breakpoint } from '@contentstack/studio-registry';
5
6
  export { Breakpoint } from '@contentstack/studio-registry';
6
7
  import { ComposableStudioQueryParams, ComposableStudioQueryParamsKeys } from '@contentstack/studio-messenger/types';
7
8
  import * as _contentstack_studio_messenger from '@contentstack/studio-messenger';
8
- import { CompositionQuery, CompositionQueryInput, HiddenElementNotificationEventData } from '@contentstack/studio-messenger';
9
- export { IS_BROWSER } from '@contentstack/studio-messenger';
10
- import { z } from 'zod';
11
- import deliverySdk, { BaseAsset } from '@contentstack/delivery-sdk';
9
+ import { CompositionResolutionDiagnosticEventData, UrlWinner, CompositionQueryInput, CompositionQuery, HiddenElementNotificationEventData } from '@contentstack/studio-messenger';
10
+ export { UrlWinner } from '@contentstack/studio-messenger';
12
11
  import { Stack } from 'contentstack';
12
+ import deliverySdk, { BaseAsset } from '@contentstack/delivery-sdk';
13
13
  import { HitboxDetails, SerializedEvent, RefetchSpecEventData } from '@contentstack/studio-message-types/latest';
14
- export { ActiveBreakpointEventPayload, BaseHighlightEventPayload, ChangeActiveStyleGroupPayload, ComputedStyleSection, DraggerPosition, HighlightActiveNodeEventPayload, HighlightAncestorsEventPayload, HighlightFocusedNodeEventPayload, HighlightNodeEventPayload, HighlightSlotNodeEventPayload, HighlightStyleNodeEventPayload, HitboxDetails, MouseMoveEventPayload, MouseUpEventPayload, RefetchSpecEventData, RequestHighlightNodeEventPayload, RevealMissKind, RevealNodePayload, RevealResultPayload, SetCursorTypeEventPayload, TARGET_NODE, UpdateStyleEventPayload, ValidatePropEventPayload, handleActiveNodePayload, handleActiveSlotNode, handleFocusedNodePayload } from '@contentstack/studio-message-types/latest';
14
+ export { ActiveBreakpointEventPayload, BaseHighlightEventPayload, ChangeActiveStyleGroupPayload, ComputedStyleSection, DraggerPosition, HighlightActiveNodeEventPayload, HighlightAncestorsEventPayload, HighlightFocusedNodeEventPayload, HighlightNodeEventPayload, HighlightSlotNodeEventPayload, HighlightStyleNodeEventPayload, HistoryShortcutPayload, HitboxDetails, MouseMoveEventPayload, MouseUpEventPayload, PermanentDropZoneDirection, PermanentDropZoneHitboxDetails, RefetchSpecEventData, RequestHighlightNodeEventPayload, RevealMissKind, RevealNodePayload, RevealResultPayload, SetCursorTypeEventPayload, TARGET_NODE, UpdateStyleEventPayload, ValidatePropEventPayload, handleActiveNodePayload, handleActiveSlotNode, handleFocusedNodePayload } from '@contentstack/studio-message-types/latest';
15
15
  import { POST_MESSAGE_EVENTS } from '@contentstack/studio-messenger/constants';
16
+ export { IS_BROWSER } from '@contentstack/studio-messenger/constants';
16
17
  import { EventEmitter } from 'eventemitter3';
17
18
  import { IJsonToHtmlOptions } from '@contentstack/json-rte-serializer';
18
19
 
@@ -26,117 +27,15 @@ type DeepRequired<T> = Required<{
26
27
  [K in keyof T]: T[K] extends Required<T[K]> ? T[K] : DeepRequired<T[K]>;
27
28
  }>;
28
29
 
29
- declare const userConfigSchema: z.ZodObject<{
30
- /**
31
- * Visual type to be used for storing the UI
32
- */
33
- contentTypeUid: z.ZodOptional<z.ZodString>;
34
- /**
35
- * Accepted as given. Whether a stack is usable is settled by the preflight,
36
- * not here: a missing or malformed stack is recorded at setup and raised at
37
- * the first call that needs it, so validating it here would throw at setup
38
- * for a page that may never fetch a composition.
39
- *
40
- * The check this replaces applied `in` to the value, which throws a
41
- * `TypeError` rather than failing validation when nothing was passed.
42
- */
43
- stackSdk: z.ZodType<any, z.ZodTypeDef, any>;
44
- locale: z.ZodOptional<z.ZodString>;
45
- /**
46
- * Turns on reporting for the failures that do not stop the page — a binding
47
- * that reads a field which is not there, a query that matched nothing, a
48
- * reference that came back as a stub.
49
- *
50
- * Off by default, and that default is deliberate: those findings are reported
51
- * in development already, and a customer's production console belongs to
52
- * them. Switching this on is how a developer diagnoses a deployed site, which
53
- * has no Studio chrome on it and no other way to say what went wrong.
54
- */
55
- debug: z.ZodOptional<z.ZodBoolean>;
56
- cslp: z.ZodOptional<z.ZodObject<{
57
- appendTags: z.ZodOptional<z.ZodBoolean>;
58
- }, "strip", z.ZodTypeAny, {
59
- appendTags?: boolean | undefined;
60
- }, {
61
- appendTags?: boolean | undefined;
62
- }>>;
63
- openInStudioButton: z.ZodOptional<z.ZodObject<{
64
- enable: z.ZodOptional<z.ZodBoolean>;
65
- position: z.ZodOptional<z.ZodEnum<["top", "top-left", "top-right", "top-center", "bottom", "bottom-left", "bottom-right", "bottom-center"]>>;
66
- }, "strip", z.ZodTypeAny, {
67
- enable?: boolean | undefined;
68
- position?: "top" | "top-left" | "top-right" | "top-center" | "bottom" | "bottom-left" | "bottom-right" | "bottom-center" | undefined;
69
- }, {
70
- enable?: boolean | undefined;
71
- position?: "top" | "top-left" | "top-right" | "top-center" | "bottom" | "bottom-left" | "bottom-right" | "bottom-center" | undefined;
72
- }>>;
73
- /**
74
- * Whether this SDK works out `include[]` paths of its own, on top of the set
75
- * the composition already carries in `data_sources[*].resolvedReferences`.
76
- *
77
- * Studio recomputes that set on every save and, having the content type
78
- * schemas, keeps only paths that end at a reference (ADR 0018). This SDK has
79
- * no schema, so what it derives cannot be filtered: measured on one page it
80
- * added 23 paths of which 22 addressed nothing. The Delivery API refuses a
81
- * request carrying more than 100 include[] paths, so those are not free.
82
- *
83
- * Leave it unset and the SDK decides per composition, from the
84
- * `schema_version` the entry was saved with: derive for anything older than
85
- * the point the persisted set became authoritative, skip it for anything at or
86
- * beyond. That matters because a composition saved before the save-time derive
87
- * existed holds only the author's ticks, and switching derivation off there
88
- * would leave every bound-but-un-ticked reference unfetched.
89
- *
90
- * Set it explicitly to override that judgement in either direction.
91
- *
92
- * What the SDK does regardless is COMPOSE: a section's paths are stored
93
- * relative to its own scope and only the host knows where the section sits, so
94
- * prefixing them is the one job that cannot move.
95
- */
96
- deriveIncludePaths: z.ZodOptional<z.ZodBoolean>;
97
- fetchComposition: z.ZodOptional<z.ZodType<CompositionFetcher, z.ZodTypeDef, CompositionFetcher>>;
98
- fetchTemplateEntry: z.ZodOptional<z.ZodType<TemplateEntryFetcher, z.ZodTypeDef, TemplateEntryFetcher>>;
99
- /**
100
- * Shared-state integration. Storage options: `"local"` / `"session"` use
101
- * built-in web-storage stores; `"custom"` (or providing getState/setState
102
- * with no `storage`) delegates to the user's own store. `state` present
103
- * with neither → built-in SESSION store. Omit `state` entirely to keep the
104
- * SDK's internal in-memory Map (fully backward compatible).
105
- */
106
- state: z.ZodOptional<z.ZodType<StudioStateConfig, z.ZodTypeDef, StudioStateConfig>>;
107
- }, "strip", z.ZodTypeAny, {
108
- locale?: string | undefined;
109
- contentTypeUid?: string | undefined;
110
- stackSdk?: any;
111
- debug?: boolean | undefined;
112
- cslp?: {
113
- appendTags?: boolean | undefined;
114
- } | undefined;
115
- openInStudioButton?: {
116
- enable?: boolean | undefined;
117
- position?: "top" | "top-left" | "top-right" | "top-center" | "bottom" | "bottom-left" | "bottom-right" | "bottom-center" | undefined;
118
- } | undefined;
119
- deriveIncludePaths?: boolean | undefined;
120
- fetchComposition?: CompositionFetcher | undefined;
121
- fetchTemplateEntry?: TemplateEntryFetcher | undefined;
122
- state?: StudioStateConfig | undefined;
123
- }, {
124
- locale?: string | undefined;
125
- contentTypeUid?: string | undefined;
126
- stackSdk?: any;
127
- debug?: boolean | undefined;
128
- cslp?: {
129
- appendTags?: boolean | undefined;
130
- } | undefined;
131
- openInStudioButton?: {
132
- enable?: boolean | undefined;
133
- position?: "top" | "top-left" | "top-right" | "top-center" | "bottom" | "bottom-left" | "bottom-right" | "bottom-center" | undefined;
134
- } | undefined;
135
- deriveIncludePaths?: boolean | undefined;
136
- fetchComposition?: CompositionFetcher | undefined;
137
- fetchTemplateEntry?: TemplateEntryFetcher | undefined;
138
- state?: StudioStateConfig | undefined;
139
- }>;
30
+ /**
31
+ * Checks the config a developer passes to the SDK. Hand-written rather than a
32
+ * schema library: this runs on every page that sets the SDK up, visitor pages
33
+ * included, and zod put ~16KB gzipped into every one of those bundles to check
34
+ * a dozen fields. The messages match the ones zod produced, so a developer sees
35
+ * the same text as before.
36
+ */
37
+ declare const EDIT_BUTTON_POSITIONS: readonly ["top", "top-left", "top-right", "top-center", "bottom", "bottom-left", "bottom-right", "bottom-center"];
38
+ type EditButtonPosition = (typeof EDIT_BUTTON_POSITIONS)[number];
140
39
 
141
40
  type JSStack = Stack;
142
41
  type TSStack = ReturnType<(typeof deliverySdk)["stack"]>;
@@ -177,6 +76,8 @@ declare class StackSDK {
177
76
  * stacks and on custom CDNs.
178
77
  */
179
78
  get host(): string | undefined;
79
+ /** The branch the stack was built for, sent as the `branch` header. */
80
+ get branch(): string | undefined;
180
81
  get livePreviewConfig(): {
181
82
  host?: string;
182
83
  preview_token?: string;
@@ -200,41 +101,6 @@ declare class StackSDK {
200
101
  applyTaxonomyFilters(query: any, taxonomyConstraints: Record<string, string>): any;
201
102
  }
202
103
 
203
- interface Config extends DeepRequired<Omit<UserConfig, "stackSdk" | "locale" | "fetchComposition" | "fetchTemplateEntry" | "state" | "deriveIncludePaths">> {
204
- /** Absent when nothing usable was supplied; the guards test for it. */
205
- stackSdk?: StackSDK;
206
- locale?: string;
207
- /**
208
- * Whether the caller passed `contentTypeUid` themselves. `contentTypeUid` is
209
- * always populated, so the value alone cannot tell a chosen uid from the
210
- * default — and a developer who set nothing needs a different leading cause
211
- * from one who set the wrong thing.
212
- */
213
- contentTypeUidWasSupplied: boolean;
214
- /**
215
- * Variant alias the SDK should use for all data fetches. Not part of the
216
- * public `UserConfig` — set by Studio (when running inside a Studio iframe)
217
- * via the `cs-variant-alias` URL search param so the SDK can render and
218
- * fetch references in the variant Studio picked.
219
- */
220
- variantAlias?: string;
221
- fetchComposition?: CompositionFetcher;
222
- fetchTemplateEntry?: TemplateEntryFetcher;
223
- /**
224
- * Override for whether the SDK derives include[] paths of its own. Left
225
- * undefined it is decided per composition from its `schema_version`, which is
226
- * why it stays out of `DeepRequired` — "unset" is a meaningful third state.
227
- */
228
- deriveIncludePaths?: boolean;
229
- /**
230
- * Bring-Your-Own-State config, passed through as-is (kept out of
231
- * DeepRequired so `subscribe` / `variables` stay optional).
232
- */
233
- state?: StudioStateConfig;
234
- }
235
- type LightConfig = Pick<Config, "openInStudioButton" | "contentTypeUid" | "cslp">;
236
- type UserConfig = z.infer<typeof userConfigSchema>;
237
-
238
104
  /**
239
105
  * The documented error codes, and the class each one belongs to.
240
106
  *
@@ -254,12 +120,30 @@ declare const StudioErrorCode: {
254
120
  readonly CONTENT_TYPE_NOT_FOUND: "CONTENT_TYPE_NOT_FOUND";
255
121
  /** No stack on this host answers to the API key the request carried. */
256
122
  readonly STACK_NOT_FOUND_ON_HOST: "STACK_NOT_FOUND_ON_HOST";
123
+ /** The stack was found, and it refused the delivery token the request carried. */
124
+ readonly DELIVERY_TOKEN_INVALID: "DELIVERY_TOKEN_INVALID";
125
+ /**
126
+ * The live preview session belongs to a different stack from the API key the
127
+ * request carried. Only a preview request can get this, so in practice only a
128
+ * page opened in Studio or the Visual Editor sees it.
129
+ */
130
+ readonly PREVIEW_STACK_MISMATCH: "PREVIEW_STACK_MISMATCH";
131
+ /**
132
+ * The preview host refused the request's preview hash: it has expired, was
133
+ * made up, or belongs to a session that has ended. A visitor's request that
134
+ * carried one (an old or copied preview link) never sees this: the SDK
135
+ * fetches the published composition instead. It reaches a host only from
136
+ * inside Studio's canvas, or when that published fetch fails too.
137
+ */
138
+ readonly PREVIEW_HASH_REFUSED: "PREVIEW_HASH_REFUSED";
257
139
  /** The stack has no environment by the name the connection uses. */
258
140
  readonly ENVIRONMENT_NOT_FOUND: "ENVIRONMENT_NOT_FOUND";
259
141
  /** The stack has no language by the code the SDK was configured with. */
260
142
  readonly LOCALE_NOT_CONFIGURED: "LOCALE_NOT_CONFIGURED";
261
143
  /** The address asked for a language the stack does not have. */
262
144
  readonly URL_LOCALE_NOT_FOUND: "URL_LOCALE_NOT_FOUND";
145
+ /** The stack has no branch by the name the site's stack was given. */
146
+ readonly BRANCH_NOT_FOUND: "BRANCH_NOT_FOUND";
263
147
  /**
264
148
  * Studio was given no Contentstack stack to query, or given something that is
265
149
  * not one. Raised by the first call that needs the stack, never at setup: a
@@ -292,10 +176,19 @@ declare const StudioErrorCode: {
292
176
  * message says so rather than only naming the gap.
293
177
  */
294
178
  readonly ENVIRONMENT_MISSING: "ENVIRONMENT_MISSING";
179
+ /**
180
+ * The site passed `contentTypeUid`, and it is empty or blank.
181
+ *
182
+ * What a deploy produces when the variable exists and holds nothing: `??` keeps
183
+ * the `""`, so the default never applies. Before this was named, the empty uid
184
+ * built a query the delivery SDK cannot use, the call threw before any request,
185
+ * and that throw was reported as `TRANSPORT_FAILED`.
186
+ */
187
+ readonly CONTENT_TYPE_UID_EMPTY: "CONTENT_TYPE_UID_EMPTY";
295
188
  /**
296
189
  * The configured Contentstack address cannot be used as written: it does not
297
- * parse as an address, or it is `http:` on a page the browser serves over
298
- * `https:` and will block as mixed content.
190
+ * parse as an address, or it carries a scheme (`https://cdn…`), which both
191
+ * delivery SDKs prefix with their own and so send nowhere.
299
192
  *
300
193
  * States only that the value cannot work, never what it should have been. We
301
194
  * have no way to know the right host, and any test for a Contentstack-shaped
@@ -467,6 +360,9 @@ interface StudioErrorFindingsByCode {
467
360
  contentTypeUidWasSupplied: boolean;
468
361
  };
469
362
  [StudioErrorCode.STACK_NOT_FOUND_ON_HOST]: WireFacts;
363
+ [StudioErrorCode.DELIVERY_TOKEN_INVALID]: WireFacts;
364
+ [StudioErrorCode.PREVIEW_STACK_MISMATCH]: WireFacts;
365
+ [StudioErrorCode.PREVIEW_HASH_REFUSED]: WireFacts;
470
366
  [StudioErrorCode.ENVIRONMENT_NOT_FOUND]: WireFacts & {
471
367
  /** The environment the request carried, when the stack reported one. */
472
368
  environment?: string;
@@ -475,6 +371,10 @@ interface StudioErrorFindingsByCode {
475
371
  locale: string;
476
372
  localeSource: "configuration";
477
373
  };
374
+ [StudioErrorCode.BRANCH_NOT_FOUND]: WireFacts & {
375
+ /** The branch Contentstack named in its refusal. */
376
+ branch: string;
377
+ };
478
378
  [StudioErrorCode.URL_LOCALE_NOT_FOUND]: WireFacts & {
479
379
  locale: string;
480
380
  localeSource: "url-pattern";
@@ -485,7 +385,7 @@ interface StudioErrorFindingsByCode {
485
385
  /** The value as configured, so the reader can find where it came from. */
486
386
  host: string;
487
387
  /** What was proved about it. Never a claim about what it should have been. */
488
- reason: "unparseable" | "blocked-as-mixed-content";
388
+ reason: "unparseable" | "carries-scheme";
489
389
  };
490
390
  /** Carries only where we looked: there is no value to report when none was named. */
491
391
  [StudioErrorCode.COMPOSITION_IDENTIFIER_MISSING]: {
@@ -517,6 +417,10 @@ interface StudioErrorFindingsByCode {
517
417
  [StudioErrorCode.ENVIRONMENT_MISSING]: {
518
418
  lookedIn: LookedIn;
519
419
  };
420
+ /** Where the uid was looked for; the empty value itself says nothing more. */
421
+ [StudioErrorCode.CONTENT_TYPE_UID_EMPTY]: {
422
+ lookedIn: LookedIn;
423
+ };
520
424
  /**
521
425
  * What was being read and how, but never the bytes themselves — the diagnosis
522
426
  * is built to be pasted somewhere public, and a stored layout is the customer's
@@ -598,6 +502,17 @@ interface StudioErrorFindingsByCode {
598
502
  */
599
503
  [StudioErrorCode.TRANSPORT_FAILED]: {
600
504
  host?: string;
505
+ /**
506
+ * The transport's own code: `ENOTFOUND`, `ECONNREFUSED` and the like on a
507
+ * server, `ERR_NETWORK` in a browser. What tells a name that does not
508
+ * resolve from a connection that was refused.
509
+ */
510
+ transportCode?: string;
511
+ /**
512
+ * Where the request was made. A server request is never the author's own
513
+ * connection, and a browser one may be.
514
+ */
515
+ requestedFrom: "server" | "browser";
601
516
  detail?: string;
602
517
  };
603
518
  /** The status and error code, which is everything we established about it. */
@@ -615,8 +530,19 @@ interface StudioErrorFindingsByCode {
615
530
  * wrong file.
616
531
  */
617
532
  lookedIn: LookedIn;
533
+ /**
534
+ * What the site passed instead of a stack, so the reader is pointed at the
535
+ * line they actually wrote. A kind, never the value: `stack.config` carries
536
+ * the delivery token.
537
+ */
538
+ received?: ReceivedStack;
618
539
  };
619
540
  }
541
+ /**
542
+ * What arrived as `stackSdk` when it was not a usable stack. `nothing` is also
543
+ * what a stack built after init, or one whose construction failed, looks like.
544
+ */
545
+ type ReceivedStack = "nothing" | "stack-config" | "promise" | "delivery-sdk" | "other";
620
546
  /** Where a value the SDK needed was looked for and not found. */
621
547
  type LookedIn = "configuration" | "call" | "registry";
622
548
  /** The response facts a host reads to decide what to render in the page's place. */
@@ -639,6 +565,111 @@ interface ConsideredComposition {
639
565
  connectedEntryResult?: string;
640
566
  }
641
567
 
568
+ interface Config extends DeepRequired<Omit<UserConfig, "stackSdk" | "locale" | "state" | "deriveIncludePaths">> {
569
+ /** Absent when nothing usable was supplied; the guards test for it. */
570
+ stackSdk?: StackSDK;
571
+ /**
572
+ * What was passed as `stackSdk` when it was not a usable stack, recorded at
573
+ * setup because the value itself is dropped. Absent when the stack is usable.
574
+ */
575
+ stackSdkReceived?: ReceivedStack;
576
+ locale?: string;
577
+ /**
578
+ * Whether the caller passed `contentTypeUid` themselves. `contentTypeUid` is
579
+ * always populated, so the value alone cannot tell a chosen uid from the
580
+ * default — and a developer who set nothing needs a different leading cause
581
+ * from one who set the wrong thing.
582
+ */
583
+ contentTypeUidWasSupplied: boolean;
584
+ /**
585
+ * Variant alias the SDK should use for all data fetches. Not part of the
586
+ * public `UserConfig` — set by Studio (when running inside a Studio iframe)
587
+ * via the `cs-variant-alias` URL search param so the SDK can render and
588
+ * fetch references in the variant Studio picked.
589
+ */
590
+ variantAlias?: string;
591
+ /**
592
+ * Override for whether the SDK derives include[] paths of its own. Left
593
+ * undefined it is decided per composition from its `schema_version`, which is
594
+ * why it stays out of `DeepRequired` — "unset" is a meaningful third state.
595
+ */
596
+ deriveIncludePaths?: boolean;
597
+ /**
598
+ * Bring-Your-Own-State config, passed through as-is (kept out of
599
+ * DeepRequired so `subscribe` / `variables` stay optional).
600
+ */
601
+ state?: StudioStateConfig;
602
+ }
603
+ type LightConfig = Pick<Config, "openInStudioButton" | "contentTypeUid" | "cslp">;
604
+ /** The config a developer passes to the SDK. Checked by `validateUserConfig`. */
605
+ interface UserConfig {
606
+ /**
607
+ * Visual type to be used for storing the UI
608
+ */
609
+ contentTypeUid?: string;
610
+ /**
611
+ * Accepted as given. Whether a stack is usable is settled by the preflight,
612
+ * not here: a missing or malformed stack is recorded at setup and raised at
613
+ * the first call that needs it, so validating it here would throw at setup
614
+ * for a page that may never fetch a composition.
615
+ *
616
+ * The check this replaces applied `in` to the value, which throws a
617
+ * `TypeError` rather than failing validation when nothing was passed.
618
+ */
619
+ stackSdk?: Stack | any;
620
+ locale?: string;
621
+ /**
622
+ * Turns on reporting for the failures that do not stop the page — a binding
623
+ * that reads a field which is not there, a query that matched nothing, a
624
+ * reference that came back as a stub.
625
+ *
626
+ * Off by default, and that default is deliberate: those findings are reported
627
+ * in development already, and a customer's production console belongs to
628
+ * them. Switching this on is how a developer diagnoses a deployed site, which
629
+ * has no Studio chrome on it and no other way to say what went wrong.
630
+ */
631
+ debug?: boolean;
632
+ cslp?: {
633
+ appendTags?: boolean;
634
+ };
635
+ openInStudioButton?: {
636
+ enable?: boolean;
637
+ position?: EditButtonPosition;
638
+ };
639
+ /**
640
+ * Whether this SDK works out `include[]` paths of its own, on top of the set
641
+ * the composition already carries in `data_sources[*].resolvedReferences`.
642
+ *
643
+ * Studio recomputes that set on every save and, having the content type
644
+ * schemas, keeps only paths that end at a reference (ADR 0018). This SDK has
645
+ * no schema, so what it derives cannot be filtered: measured on one page it
646
+ * added 23 paths of which 22 addressed nothing. The Delivery API refuses a
647
+ * request carrying more than 100 include[] paths, so those are not free.
648
+ *
649
+ * Leave it unset and the SDK decides per composition, from the
650
+ * `schema_version` the entry was saved with: derive for anything older than
651
+ * the point the persisted set became authoritative, skip it for anything at or
652
+ * beyond. That matters because a composition saved before the save-time derive
653
+ * existed holds only the author's ticks, and switching derivation off there
654
+ * would leave every bound-but-un-ticked reference unfetched.
655
+ *
656
+ * Set it explicitly to override that judgement in either direction.
657
+ *
658
+ * What the SDK does regardless is COMPOSE: a section's paths are stored
659
+ * relative to its own scope and only the host knows where the section sits, so
660
+ * prefixing them is the one job that cannot move.
661
+ */
662
+ deriveIncludePaths?: boolean;
663
+ /**
664
+ * Shared-state integration. Storage options: `"local"` / `"session"` use
665
+ * built-in web-storage stores; `"custom"` (or providing getState/setState
666
+ * with no `storage`) delegates to the user's own store. `state` present
667
+ * with neither → built-in SESSION store. Omit `state` entirely to keep the
668
+ * SDK's internal in-memory Map (fully backward compatible).
669
+ */
670
+ state?: StudioStateConfig;
671
+ }
672
+
642
673
  /**
643
674
  * Information about a possible cause of an error and how to fix it
644
675
  */
@@ -676,6 +707,13 @@ declare class ComposableStudioError extends Error {
676
707
  * `id` is what those sites still carry, and it goes once they have all moved.
677
708
  */
678
709
  code?: StudioErrorCodeType;
710
+ /**
711
+ * The one sentence stating what happened, without the code or the causes the
712
+ * message wraps around it. Kept apart so a surface can lay the diagnosis out
713
+ * from its parts instead of cutting the logged text back up. Set together
714
+ * with `code`.
715
+ */
716
+ headline?: string;
679
717
  /**
680
718
  * What to do, ordered, most likely first. One entry means we proved the
681
719
  * cause; more than one means we are ranking and the reader should work down
@@ -756,6 +794,18 @@ declare function markStudioMode(): StudioMode;
756
794
 
757
795
  /** Which Contentstack service answered a request. */
758
796
  type ServedBy = "cdn" | "preview" | "unknown";
797
+ /**
798
+ * Where one request went, captured in one read immediately before it was made.
799
+ *
800
+ * `servedBy` alone cannot say *why* published content came back — live preview
801
+ * switched off and a hash that never arrived both read as "cdn" — so the hash is
802
+ * carried as a fact of its own rather than inferred from it.
803
+ */
804
+ interface RequestRoute {
805
+ servedBy: ServedBy;
806
+ /** Whether a usable preview hash reached this request. Absent when there was no stack. */
807
+ hasPreviewHash?: boolean;
808
+ }
759
809
 
760
810
  /**
761
811
  * The shape every diagnosable failure is raised in, and the one place it is
@@ -804,6 +854,20 @@ interface StudioErrorContext {
804
854
  * configuration we were never given.
805
855
  */
806
856
  livePreviewEnabled?: boolean;
857
+ /**
858
+ * Whether the stack that made this request had a preview token — a boolean,
859
+ * never the token. Read where the request ran, so on a server-rendered site it
860
+ * describes the server's stack, which the browser's handshake cannot.
861
+ */
862
+ hasPreviewToken?: boolean;
863
+ /** The address live preview is pointed at, on the stack that made this request. */
864
+ previewHost?: string;
865
+ /**
866
+ * Whether a usable preview hash reached this request, captured with `servedBy`
867
+ * before it went out. Its own fact because `servedBy` cannot say why published
868
+ * content came back. Absent when the route was not captured.
869
+ */
870
+ hasPreviewHash?: boolean;
807
871
  /**
808
872
  * Which service answered. Captured before the request rather than read back
809
873
  * afterwards, and `"unknown"` when the application fetched for itself.
@@ -824,8 +888,23 @@ interface StudioErrorInput<C extends StudioErrorCodeType = StudioErrorCodeType>
824
888
  */
825
889
  findings: StudioErrorFindingsByCode[C];
826
890
  }
827
- /** Reads the facts a diagnosis prints from the config the fetch actually used. */
828
- declare function buildStudioErrorContext(config?: Config, servedBy?: ServedBy): StudioErrorContext;
891
+ /**
892
+ * Reads the facts a diagnosis prints from the config the fetch actually used.
893
+ *
894
+ * `route` is what the caller captured immediately before the request. The rest is
895
+ * configuration, safe to read here even after an await; the hash is not, which is
896
+ * why it arrives with the route instead of being read from the stack.
897
+ */
898
+ declare function buildStudioErrorContext(config?: Config, route?: Partial<RequestRoute>): StudioErrorContext;
899
+ /** What every SDK message starts with, so it can be found in a shared console. */
900
+ declare const STUDIO_LOG_PREFIX = "[Contentstack Studio]";
901
+ /**
902
+ * The heading over the causes, shared so the log and the canvas failure card
903
+ * cannot drift apart.
904
+ */
905
+ declare const STUDIO_NEXT_STEPS_HEADING = "What to do, most likely first:";
906
+ /** One step under that heading, as both the log and the card word it. */
907
+ declare function formatStudioErrorCause({ cause, fix }: Cause): string;
829
908
  /**
830
909
  * Builds the error and returns it to be thrown.
831
910
  *
@@ -852,6 +931,24 @@ declare function createStudioError<C extends StudioErrorCodeType>(input: StudioE
852
931
  */
853
932
  declare function isSetupFault(error: unknown): boolean;
854
933
 
934
+ /**
935
+ * The plain-data copy of an error that resolution telemetry carries, so it can
936
+ * cross from a server render to the browser and on to Studio.
937
+ */
938
+ type SerializedStudioError = NonNullable<CompositionResolutionDiagnosticEventData["error"]>;
939
+ /**
940
+ * An error as plain data, the inverse of `rebuildStudioError`. Both directions
941
+ * live here so a field added to the error is carried both ways or neither.
942
+ * An error the SDK did not diagnose keeps only its message.
943
+ */
944
+ declare function serializeStudioError(error: unknown): SerializedStudioError;
945
+ /**
946
+ * The error rebuilt from its plain-data copy, for code that only has the copy —
947
+ * a browser rendering what the server diagnosed. Same subclass rule as
948
+ * `createStudioError`.
949
+ */
950
+ declare function rebuildStudioError(serializedError: SerializedStudioError): ComposableStudioError;
951
+
855
952
  declare function getDefaultConfig(): Config;
856
953
 
857
954
  declare const isBrowser: () => boolean;
@@ -903,6 +1000,12 @@ declare const COMPOSABLE_DATA_ATTRIBUTES: {
903
1000
  readonly ID: "data-composable-studio-id";
904
1001
  readonly SLOT_UID: "data-composable-studio-slot-uid";
905
1002
  readonly CSLP: "data-cslp";
1003
+ /** Marks a permanent drop zone; the value is its `PermanentDropZoneDirection`. */
1004
+ readonly PERMANENT_DROP_ZONE_DIRECTION: "data-composable-studio-permanent-drop-zone-direction";
1005
+ /** Marks the permanent drop zone a drag is currently targeting. */
1006
+ readonly PERMANENT_DROP_ZONE_TARGETED: "data-composable-studio-permanent-drop-zone-targeted";
1007
+ /** Marks an empty slot's placeholder while the slot or its owner is selected. */
1008
+ readonly SLOT_SELECTED: "data-composable-studio-slot-selected";
906
1009
  };
907
1010
 
908
1011
  declare const RendererMode: {
@@ -923,7 +1026,13 @@ type ClientEditableNodeInternalAttributes = {
923
1026
  declare const findNearestBuilderNode: (ele: HTMLElement) => HTMLElement | null;
924
1027
  declare const findNearestSlotNode: (ele: HTMLElement) => HTMLElement | null;
925
1028
  declare const hasSlotDropzone: (event: MouseEvent) => boolean;
926
- declare const getHitboxDirection: (event: MouseEvent, nodeBoundingBox: DOMRect) => "top" | "bottom" | "left" | "right";
1029
+ /**
1030
+ * The permanent drop zone a drag at this point targets: the one the point is
1031
+ * in, or within the edge threshold above or below. Zones claim that band so no
1032
+ * other target's drop line lands on their border.
1033
+ */
1034
+ declare const findTargetedPermanentDropZone: (clientX: number, clientY: number) => HTMLElement | null;
1035
+ declare const getHitboxDirection: (event: MouseEvent, nodeBoundingBox: DOMRect) => "left" | "right" | "top" | "bottom";
927
1036
  /**
928
1037
  * Give a `display: contents` node a real box so it can be measured and captured,
929
1038
  * and put it back afterwards.
@@ -954,6 +1063,40 @@ declare const getComposableElement: (uid: string) => HTMLElement;
954
1063
  */
955
1064
  declare const getComposableElements: (uid: string) => HTMLElement[];
956
1065
  declare const getHitboxDetails: (event: MouseEvent) => HitboxDetails;
1066
+ /**
1067
+ * A drag above, below or beside the page's top-level components.
1068
+ *
1069
+ * The page node is `display: contents`, so the space around its children
1070
+ * belongs to no node: the hit test finds nothing there and the author got no
1071
+ * drop line until they dragged right onto a component. That space is often the
1072
+ * customer's own page around the composition — a site header above it, a
1073
+ * footer below it, a sidebar beside it — so:
1074
+ *
1075
+ * - above the topmost top-level component drops before it (start of the page);
1076
+ * - below the lowest drops after it (end of the page);
1077
+ * - beside the components, level with one, drops on that component's left or
1078
+ * right edge (whichever side the pointer is on), which Studio turns into a
1079
+ * side-by-side Columns wrap, like a drop on that edge itself. That covers a
1080
+ * customer sidebar or page margin outside the box the composition renders
1081
+ * into, and the blank space beside a narrower component (a Button) inside it;
1082
+ * - outside that box but level with a gap between rows, the side drop goes to
1083
+ * the nearest component vertically.
1084
+ *
1085
+ * Each is the same drop as that component's edge, so Studio draws the usual
1086
+ * line. Positions are where components sit on screen, not document order, and
1087
+ * every rendered copy of a Repeater counts.
1088
+ *
1089
+ * Gaps between rows inside the composition's own column (margins) are
1090
+ * deliberately not covered.
1091
+ */
1092
+ declare const getOutsideComponentsHitboxDetails: (event: MouseEvent) => HitboxDetails;
1093
+ /**
1094
+ * Where a drag at this event would drop. Same as `getHitboxDetails`, except a
1095
+ * permanent drop zone also wins in the edge band around it, and a drag above,
1096
+ * below or beside the components drops next to the right one. Presses use
1097
+ * `getHitboxDetails`, so a click near a zone still selects what it lands on.
1098
+ */
1099
+ declare const getDropTargetHitboxDetails: (event: MouseEvent) => HitboxDetails;
957
1100
  declare const getComputedStyles: (event: MouseEvent) => Record<string, string> | null;
958
1101
  declare const serializeEvent: (event: MouseEvent) => SerializedEvent;
959
1102
 
@@ -1106,6 +1249,16 @@ interface RankingResult {
1106
1249
  * - "not-checked": no probe ran — not a tie, or a freeform/lower-tier candidate.
1107
1250
  */
1108
1251
  type ConnectedEntryResult = "found" | "absent" | "not-checked";
1252
+
1253
+ /** The `kind` of each {@link UrlWinner}. */
1254
+ declare const URL_WINNER_KIND: {
1255
+ /** Nothing at this URL has an entry. */
1256
+ readonly NONE: "none";
1257
+ /** The template production renders here. */
1258
+ readonly PRODUCTION: "production";
1259
+ /** The template the render asked for, preferred over production's pick. */
1260
+ readonly PREFERRED_COMPOSITION: "preferred-composition";
1261
+ };
1109
1262
  /** A single URL match surfaced for diagnostics — lightweight, includes specificity. */
1110
1263
  interface UrlMatchDiagnostic {
1111
1264
  composable_uid: string;
@@ -1198,11 +1351,13 @@ interface StudioSpec {
1198
1351
  /**
1199
1352
  * Studio-only resolution diagnostics for the URL metadata path. Present when
1200
1353
  * the composition was resolved by URL ranking; carries every candidate
1201
- * considered with its specificity. Consumed by the React hook to build the
1202
- * `SDK_DIAGNOSTICS` post-message. Not part of the rendered output.
1354
+ * considered with its specificity, and how the winner was picked. Consumed by
1355
+ * the React hook to build the `SDK_DIAGNOSTICS` post-message. Not part of the
1356
+ * rendered output.
1203
1357
  */
1204
1358
  urlResolution?: {
1205
- shortlisted: UrlMatchDiagnostic[];
1359
+ readonly shortlisted: UrlMatchDiagnostic[];
1360
+ readonly winner: UrlWinner;
1206
1361
  };
1207
1362
  /**
1208
1363
  * Where this request went and what it was made with — the same block every
@@ -1246,6 +1401,17 @@ type CompositionQueryOptions = {
1246
1401
  * ```
1247
1402
  */
1248
1403
  locale?: string;
1404
+ /**
1405
+ * Extra reference paths (`includeReferences`) and fields (`only`) to add to
1406
+ * the entry fetch for a content type.
1407
+ *
1408
+ * @deprecated Tick the references in Studio instead: they are saved with
1409
+ * the composition and sent with the request for the entry they belong to.
1410
+ * `only` needs no replacement: the SDK already fetches just the fields the
1411
+ * composition binds (plus `locale` when edit tags are on), and `only` here
1412
+ * could only add fields to that, never remove them. Still applied until it
1413
+ * is removed in the next major; logs a one-time warning in development.
1414
+ */
1249
1415
  extendQuery?: {
1250
1416
  [ct_uid: string]: {
1251
1417
  includeReferences?: string[];
@@ -1262,87 +1428,13 @@ type CompositionQueryOptions = {
1262
1428
  * Resolution priority: templateEntryUid > url > first entry (limit 1)
1263
1429
  */
1264
1430
  templateEntryUid?: string;
1265
- /**
1266
- * Per-query composition fetcher override. Takes precedence over global.
1267
- * Return the composition entry, null for not-found, or call `defaultFetch()`.
1268
- */
1269
- fetchComposition?: CompositionFetcher;
1270
- /**
1271
- * Per-query template entry fetcher override. Takes precedence over global.
1272
- * Return the entry, null for not-found, or call `defaultFetch()`.
1273
- */
1274
- fetchTemplateEntry?: TemplateEntryFetcher;
1275
1431
  };
1276
1432
  /**
1277
- * CompositionQueryOptions with fetcher callbacks stripped.
1278
- * Passed to custom fetchers via the `options` field.
1279
- * Automatically picks up any future additions to CompositionQueryOptions.
1280
- */
1281
- type ResolvedQueryOptions = Omit<CompositionQueryOptions, "fetchComposition" | "fetchTemplateEntry">;
1282
- /**
1283
- * Context provided to a custom composition fetcher.
1433
+ * The query string we get after running URLSearchParams.toString()
1284
1434
  */
1285
- interface FetchCompositionContext {
1286
- /** The query input — has composableUid, url, or both */
1287
- compositionQuery: CompositionQuery;
1288
- /** The content type UID where compositions are stored */
1289
- contentTypeUid: string;
1290
- /** All query options (locale, variantAlias, extendQuery, templateEntryUid, + future) */
1291
- options: ResolvedQueryOptions;
1292
- /** The raw Contentstack SDK instance passed to studioSdk.init() */
1293
- stackSdk: any;
1294
- /**
1295
- * Calls the SDK's default composition fetching logic.
1296
- * Use this to: conditionally fall through, wrap/decorate, inspect/transform.
1297
- */
1298
- defaultFetch: () => Promise<CompositionEntry>;
1299
- }
1300
- /**
1301
- * Context provided to a custom template entry fetcher.
1302
- */
1303
- interface FetchTemplateEntryContext {
1304
- /** The already-fetched composition entry */
1305
- compositionEntry: CompositionEntry;
1306
- /** The original query (has composableUid, url, or both) */
1307
- compositionQuery: CompositionQuery;
1308
- /** The content type UID that this composition is linked to */
1309
- connectedContentType: string;
1310
- /** All query options (locale, variantAlias, extendQuery, templateEntryUid, + future) */
1311
- options: ResolvedQueryOptions;
1312
- /**
1313
- * SDK-computed reference field paths from UI tree bindings + options.extendQuery.
1314
- * e.g., ["author", "categories", "related_posts.author"]
1315
- */
1316
- includeReferences: string[];
1317
- /**
1318
- * SDK-computed field projections from UI tree bindings + options.extendQuery.
1319
- * Empty when inside Visual Builder (all fields fetched).
1320
- */
1321
- only: [string, string][];
1322
- /** The raw Contentstack SDK instance passed to studioSdk.init() */
1323
- stackSdk: any;
1324
- /**
1325
- * Calls the SDK's default template entry fetching logic.
1326
- * Uses templateEntryUid > url > first entry resolution.
1327
- */
1328
- defaultFetch: () => Promise<any>;
1329
- }
1330
- /**
1331
- * User-provided fetcher for compositions.
1332
- * Return the composition entry, null for not-found, or call defaultFetch().
1333
- */
1334
- type CompositionFetcher = (context: FetchCompositionContext) => Promise<CompositionEntry | null>;
1335
- /**
1336
- * User-provided fetcher for template entries.
1337
- * Return the entry, null for not-found, or call defaultFetch().
1338
- */
1339
- type TemplateEntryFetcher = (context: FetchTemplateEntryContext) => Promise<any | null>;
1340
- /**
1341
- * The query string we get after running URLSearchParams.toString()
1342
- */
1343
- type URLSearchParamsString = string;
1344
- type StudioComponentFetchOptions = {
1345
- searchQuery: URLSearchParamsString;
1435
+ type URLSearchParamsString = string;
1436
+ type StudioComponentFetchOptions = {
1437
+ searchQuery: URLSearchParamsString;
1346
1438
  compositionQuery: CompositionQuery;
1347
1439
  config: LightConfig;
1348
1440
  options?: CompositionQueryOptions;
@@ -1369,10 +1461,12 @@ type StudioComponentSpecOptions = {
1369
1461
  /**
1370
1462
  * Whether the resolved spec carries a composition entry.
1371
1463
  *
1372
- * **Not a 404 signal.** Every "there is no composition here" outcome rejects
1373
- * rather than returning, so on a resolved fetch this is always `true`, and on
1374
- * the push path it is `true` whenever Studio supplied a spec. To test for the
1375
- * no-spec sentinel, check `spec` itself.
1464
+ * **Not a 404 signal.** For a visitor every "there is no composition here"
1465
+ * outcome rejects rather than returning, and inside Studio's canvas it
1466
+ * resolves with a spec that renders the failure, so on a resolved fetch this
1467
+ * is always `true`; read `resolutionTelemetry.error` to tell a failure apart.
1468
+ * On the push path it is `true` whenever Studio supplied a spec. To test for
1469
+ * the no-spec sentinel, check `spec` itself.
1376
1470
  *
1377
1471
  * @deprecated Read `spec.compositionEntry` directly, and decide 404 from the
1378
1472
  * rejected `ComposableStudioError`. Slated for removal in a future major.
@@ -1413,6 +1507,13 @@ type StudioComponentSpecOptions = {
1413
1507
  * of the HTML.
1414
1508
  */
1415
1509
  seo: SeoMetadata | null;
1510
+ /**
1511
+ * What this fetch resolved, or why it could not, for Studio's diagnostics.
1512
+ * Set inside Studio's canvas only, where a failed fetch resolves instead of
1513
+ * rejecting: `error` is then set, and `isCompositionNotFound(error)` works
1514
+ * on it. Plain data — the error itself goes to the server log.
1515
+ */
1516
+ resolutionTelemetry?: CompositionResolutionDiagnosticEventData;
1416
1517
  };
1417
1518
  interface SeoMetadata {
1418
1519
  pageTitle: string;
@@ -1437,9 +1538,8 @@ declare const studioSdk: {
1437
1538
  internal: {
1438
1539
  getConfig(): Config;
1439
1540
  isInsideStudioFrame: () => boolean;
1440
- fetchSpec: (queryOptions: _contentstack_studio_messenger.CompositionQuery, options?: CompositionQueryOptions, skipComponentLoading?: boolean, searchParams?: URLSearchParams) => Promise<StudioSpec>;
1441
- fetchCompositionSpecOnly: (queryOptions: _contentstack_studio_messenger.CompositionQuery, options?: CompositionQueryOptions, skipComponentLoading?: boolean) => Promise<StudioSpec>;
1442
- fetchMultipleSpecs: (queries: _contentstack_studio_messenger.CompositionQuery[], options?: CompositionQueryOptions) => Promise<StudioSpec[]>;
1541
+ fetchSpec: (queryOptions: _contentstack_studio_messenger.CompositionQuery, options?: CompositionQueryOptions, searchParams?: URLSearchParams) => Promise<StudioSpec>;
1542
+ fetchCompositionSpecOnly: (queryOptions: _contentstack_studio_messenger.CompositionQuery, options?: CompositionQueryOptions, skipComponentLoading?: boolean, searchParams?: URLSearchParams) => Promise<StudioSpec>;
1443
1543
  fetchData: (compositionEntry: CompositionEntry, queryOptions: _contentstack_studio_messenger.CompositionQuery, options?: CompositionQueryOptions, sectionEntries?: SectionCompositionEntry[], searchParams?: URLSearchParams) => Promise<_contentstack_studio_registry.StudioSpecData>;
1444
1544
  fetchTemplateEntry: (fetchOptions: {
1445
1545
  connected_content_type: string;
@@ -1455,12 +1555,12 @@ declare const studioSdk: {
1455
1555
  public: {
1456
1556
  fetchCompositionData: (queryOptions: CompositionQueryForSSRInput, options?: CompositionQueryOptions) => Promise<StudioComponentSpecOptions>;
1457
1557
  fetchComposition: (queryOptions: CompositionQueryForSSRInput, options?: CompositionQueryOptions) => Promise<StudioSpec>;
1458
- getConfig: () => Pick<Config, "contentTypeUid" | "cslp" | "openInStudioButton">;
1558
+ getConfig: () => Pick<Config, "openInStudioButton" | "contentTypeUid" | "cslp">;
1459
1559
  };
1460
1560
  };
1461
1561
  lightInit(userConfig: LightConfig): {
1462
1562
  internal: {
1463
- getConfig: () => Pick<LightConfig, "contentTypeUid" | "cslp" | "openInStudioButton">;
1563
+ getConfig: () => Pick<LightConfig, "openInStudioButton" | "contentTypeUid" | "cslp">;
1464
1564
  };
1465
1565
  };
1466
1566
  };
@@ -1469,6 +1569,8 @@ declare const ELEMENT_TO_NODE: WeakMap<HTMLElement, any>;
1469
1569
  declare const NODE_TO_ELEMENT: WeakMap<any, HTMLElement>;
1470
1570
  declare const NODE_TO_PATH_NODE: WeakMap<any, PathNode>;
1471
1571
  declare const NODE_TO_PARENT: WeakMap<any, any>;
1572
+ /** Every permanent drop zone on the canvas, so a drag can find the one it is near. */
1573
+ declare const PERMANENT_DROP_ZONE_ELEMENTS: Set<HTMLElement>;
1472
1574
 
1473
1575
  interface UrlPatternVariableInfo {
1474
1576
  type: string;
@@ -1545,109 +1647,6 @@ interface ResolvedPool {
1545
1647
  }
1546
1648
  declare function buildScopedDataSources(pool: ResolvedPool, needsBySection: NeedsBySection, pageDataSources: DataSources): Record<string, SectionScopedDataSources>;
1547
1649
 
1548
- /**
1549
- * Pure SEO resolver. Merges the composition's saved SEO metadata
1550
- * (`ui.metadata.seo`) with resolved values from `specData` (bound title /
1551
- * description / OG image / meta props read from the template entry). Shared by
1552
- * the SDK's `getSeoMetadata` and exposed for BYO-data callers who resolve SEO
1553
- * against data they supply themselves — see `resolveSeoMetadata` in
1554
- * `@contentstack/studio-react`.
1555
- */
1556
- declare function getSeoMetadataPure(ui: Node, specData?: StudioSpecData): SeoMetadata | null;
1557
- /**
1558
- * Pure per-instance section scoping. Given a composition's `pageUi` + its
1559
- * section composition entries + an ALREADY-RESOLVED `dataSources` pool, derive
1560
- * the `section_scoped_data` map (per section-instance uid). No network.
1561
- *
1562
- * Reused in two places:
1563
- * 1. `fetchData` — after the CDA fetch has populated `data.dataSources`.
1564
- * 2. BYO-data rendering (`StudioComposition`) — the caller supplies
1565
- * `dataSources`; embedded sections scope without any refetch.
1566
- *
1567
- * Returns `{}` when there are no section compositions (e.g. a standalone
1568
- * section rendered as the root reads `dataSources.template` directly).
1569
- */
1570
- declare function buildSectionScopedData(compositionEntry: CompositionEntry, pageUi: Node, sectionEntries: SectionCompositionEntry[], dataSources: StudioSpecData["dataSources"]): ReturnType<typeof buildScopedDataSources>;
1571
- /**
1572
- * Every include[] path the SDK would work out on its own for a composition,
1573
- * grouped by the fetch root whose request it belongs on — `"template"`, a
1574
- * `<ct>:<uid>` pinned entry, or `query:<uid>` (ADR 0017, ADR 0018):
1575
- *
1576
- * - the composition's own reference-condition paths, on `"template"`;
1577
- * - for every placed section, its reference-condition paths composed onto where
1578
- * it sits, and each step of that position (`derivedIncludePathsForInstance`).
1579
- *
1580
- * Below COMPLETE_INCLUDES_FROM_SCHEMA_VERSION the SDK adds these at render. From
1581
- * that version on it adds none: Studio calls this at save, keeps what the schema
1582
- * confirms is a reference, and persists it on the matching data source, so the
1583
- * composition carries everything its fetch roots need. The render path and the
1584
- * save path share `derivedIncludePathsForInstance`, so they cannot drift apart.
1585
- *
1586
- * Paths are unvalidated — the SDK has no schema. A caller persisting them must
1587
- * validate them first.
1588
- */
1589
- declare function derivePlacementIncludePaths(compositionEntry: Pick<CompositionEntry, "ui" | "connected_content_type">, sectionEntries: SectionCompositionEntry[]): Record<string, string[]>;
1590
-
1591
- /**
1592
- * A single, framework-neutral meta tag. `attr` distinguishes standard
1593
- * `<meta name="...">` tags from Open Graph-style `<meta property="...">`.
1594
- */
1595
- interface CompositionMetaTag {
1596
- attr: "name" | "property";
1597
- key: string;
1598
- content: string;
1599
- }
1600
- /**
1601
- * Framework-neutral SEO metadata derived from a composition's resolved
1602
- * `specOptions.seo`. Consumers bind this to their host's head mechanism:
1603
- * Next.js `generateMetadata`, Remix `meta()`, TanStack `head()`, or a raw
1604
- * HTML template via {@link renderMetadataToHtml}.
1605
- */
1606
- interface CompositionMetadata {
1607
- title?: string;
1608
- description?: string;
1609
- ogImage?: string;
1610
- /** Absolute canonical URL. Present only when `baseUrl` was provided and the composition has a URL. */
1611
- canonical?: string;
1612
- /** Every derived tag (description, og:*, twitter:*, custom metaProps) in render order. */
1613
- tags: CompositionMetaTag[];
1614
- }
1615
- interface GetCompositionMetadataOptions {
1616
- /**
1617
- * Site origin used to absolutize the canonical URL and og:url,
1618
- * e.g. `https://www.example.com`. No trailing slash required.
1619
- */
1620
- baseUrl?: string;
1621
- }
1622
- /**
1623
- * Derives framework-neutral SEO metadata from a fetched composition.
1624
- *
1625
- * The heavy lifting (resolving field bindings for title/description/OG image)
1626
- * already happens inside `fetchCompositionData` — this helper only shapes the
1627
- * resolved values into standard head-tag structures.
1628
- *
1629
- * @example Plain Node
1630
- * ```ts
1631
- * const meta = getCompositionMetadata(specOptions, { baseUrl: "https://example.com" });
1632
- * res.send(`<head><title>${meta.title}</title>${renderMetadataToHtml(meta)}</head>...`);
1633
- * ```
1634
- *
1635
- * @example Next.js App Router
1636
- * ```ts
1637
- * export async function generateMetadata() {
1638
- * const meta = getCompositionMetadata(await getSpecOptions());
1639
- * return { title: meta.title, description: meta.description };
1640
- * }
1641
- * ```
1642
- */
1643
- declare function getCompositionMetadata(specOptions: Pick<StudioComponentSpecOptions, "seo" | "spec">, options?: GetCompositionMetadataOptions): CompositionMetadata;
1644
- /**
1645
- * Renders {@link CompositionMetadata} to a raw HTML string (meta + canonical
1646
- * link tags — the `<title>` element is left to the caller since most hosts
1647
- * manage it separately). For template-string SSR hosts (Express/Fastify).
1648
- */
1649
- declare function renderMetadataToHtml(metadata: CompositionMetadata): string;
1650
-
1651
1650
  /**
1652
1651
  * A placement's **Section data** — the binding that supplies a placed section's
1653
1652
  * data, i.e. what the section's own `template.*` paths resolve against.
@@ -1893,6 +1892,715 @@ declare function parseEntryFetchRootKey(key: string): {
1893
1892
  */
1894
1893
  declare function fetchRootFromBinding(root: SectionDataBinding, inherited: FetchRoot): FetchRoot;
1895
1894
 
1895
+ /**
1896
+ * Pure SEO resolver. Merges the composition's saved SEO metadata
1897
+ * (`ui.metadata.seo`) with resolved values from `specData` (bound title /
1898
+ * description / OG image / meta props read from the template entry). Shared by
1899
+ * the SDK's `getSeoMetadata` and exposed for BYO-data callers who resolve SEO
1900
+ * against data they supply themselves — see `resolveSeoMetadata` in
1901
+ * `@contentstack/studio-react`.
1902
+ */
1903
+ declare function getSeoMetadataPure(ui: Node, specData?: StudioSpecData): SeoMetadata | null;
1904
+ /**
1905
+ * Pure per-instance section scoping. Given a composition's `pageUi` + its
1906
+ * section composition entries + an ALREADY-RESOLVED `dataSources` pool, derive
1907
+ * the `section_scoped_data` map (per section-instance uid). No network.
1908
+ *
1909
+ * Reused in two places:
1910
+ * 1. `fetchData` — after the CDA fetch has populated `data.dataSources`.
1911
+ * 2. BYO-data rendering (`StudioComposition`) — the caller supplies
1912
+ * `dataSources`; embedded sections scope without any refetch.
1913
+ *
1914
+ * Returns `{}` when there are no section compositions (e.g. a standalone
1915
+ * section rendered as the root reads `dataSources.template` directly).
1916
+ */
1917
+ declare function buildSectionScopedData(compositionEntry: CompositionEntry, pageUi: Node, sectionEntries: SectionCompositionEntry[], dataSources: StudioSpecData["dataSources"]): ReturnType<typeof buildScopedDataSources>;
1918
+ /**
1919
+ * Every include[] path the SDK would work out on its own for a composition,
1920
+ * grouped by the fetch root whose request it belongs on — `"template"`, a
1921
+ * `<ct>:<uid>` pinned entry, or `query:<uid>` (ADR 0017, ADR 0018):
1922
+ *
1923
+ * - the composition's own reference-condition paths, on `"template"`;
1924
+ * - for every placed section, its reference-condition paths composed onto where
1925
+ * it sits, and each step of that position (`derivedIncludePathsForInstance`).
1926
+ *
1927
+ * Below COMPLETE_INCLUDES_FROM_SCHEMA_VERSION the SDK adds these at render. From
1928
+ * that version on it adds none: Studio calls this at save, keeps what the schema
1929
+ * confirms is a reference, and persists it on the matching data source, so the
1930
+ * composition carries everything its fetch roots need. The render path and the
1931
+ * save path share `derivedIncludePathsForInstance`, so they cannot drift apart.
1932
+ *
1933
+ * Paths are unvalidated — the SDK has no schema. A caller persisting them must
1934
+ * validate them first.
1935
+ */
1936
+ declare function derivePlacementIncludePaths(compositionEntry: Pick<CompositionEntry, "ui" | "connected_content_type">, sectionEntries: SectionCompositionEntry[]): Record<string, string[]>;
1937
+ /**
1938
+ * Where a node placed in a section instance's slot resolves its bindings: the
1939
+ * fetch root its paths go to and the prefix they hang off — the section's
1940
+ * position on the host plus the Repeater / Condition Block context that wraps
1941
+ * the slot inside the section (ADR 0017).
1942
+ */
1943
+ interface SlotChildScope {
1944
+ /** `"template"`, `<ct>:<entryUid>`, or `query:<queryUid>` — the request the paths join. */
1945
+ fetchRootKey: string;
1946
+ /** Unsanitized: may hold numeric segments and, on a query root, `entries`. */
1947
+ prefix: string[];
1948
+ }
1949
+ /**
1950
+ * The scope every node placed directly in a section instance's slot resolves its
1951
+ * bindings in, keyed by that node's uid. Its descendants share it until another
1952
+ * section instance starts a scope of its own.
1953
+ *
1954
+ * A slot child is authored on the page but binds inside the section's data — a
1955
+ * text in an Author Card's slot bound to `company.name` needs `author.company` on
1956
+ * the page request, not `company`. This is the scope the render path roots those
1957
+ * paths at; a caller computing include[] paths at save uses it so the two cannot
1958
+ * drift apart. Like `derivePlacementIncludePaths`, it needs every placed section
1959
+ * in `sectionEntries`, with `ui` parsed.
1960
+ */
1961
+ declare function collectSlotChildScopes(compositionEntry: Pick<CompositionEntry, "ui" | "connected_content_type">, sectionEntries: SectionCompositionEntry[]): Record<string, SlotChildScope>;
1962
+ /**
1963
+ * Where a placed section instance sits: the fetch root its paths go to, the
1964
+ * position its own (section-relative) paths hang off — the same prefix the render
1965
+ * path composes a section's paths onto (`derivedIncludePathsForInstance`) — and the
1966
+ * first-segment remapping its bindings get when the section is placed against a
1967
+ * different content type.
1968
+ */
1969
+ interface SectionPlacementScope {
1970
+ /** The placed node's uid (synthesized for a slot-default placement). */
1971
+ instanceUid: string;
1972
+ compositionUid: string;
1973
+ /** `"template"`, `<ct>:<entryUid>`, or `query:<queryUid>`. */
1974
+ fetchRootKey: string;
1975
+ /** Unsanitized: may hold numeric segments and, on a query root, `entries`. */
1976
+ prefix: string[];
1977
+ uidRemapping: Record<string, string>;
1978
+ }
1979
+ /**
1980
+ * Every section instance on the page (placed, nested in a slot, or defaulted into
1981
+ * one) with the scope its own bindings resolve in. A caller computing include[]
1982
+ * paths at save composes a section's section-relative binding paths onto
1983
+ * `prefix` (after `uidRemapping`) and files them under `fetchRootKey`, so a
1984
+ * reference the section reads lands on the request that fetches its data. Like
1985
+ * `derivePlacementIncludePaths`, it needs every placed section in
1986
+ * `sectionEntries`, with `ui` parsed.
1987
+ */
1988
+ declare function collectSectionPlacementScopes(compositionEntry: Pick<CompositionEntry, "ui" | "connected_content_type">, sectionEntries: SectionCompositionEntry[]): SectionPlacementScope[];
1989
+
1990
+ /**
1991
+ * Minimal local copies of the Studio types the section auto-binder reads.
1992
+ *
1993
+ * Ported from Studio's `src/types/contentstack.types.ts`, `src/types/cma.ts`
1994
+ * (`ContentType`) and `src/types/composition.ts` (`SchemaLink`). Only the
1995
+ * fields the binder touches are kept; everything is structurally compatible
1996
+ * with the Studio originals so the same objects can be passed either way.
1997
+ */
1998
+ declare enum FieldTypes {
1999
+ MODULAR_BLOCK = "blocks",
2000
+ GROUP = "group",
2001
+ GLOBAL_FIELD = "global_field"
2002
+ }
2003
+ interface CTGenericField {
2004
+ data_type: string;
2005
+ uid: string;
2006
+ display_name?: string;
2007
+ multiple?: boolean;
2008
+ field_metadata?: Record<string, unknown>;
2009
+ }
2010
+ interface GlobalField extends CTGenericField {
2011
+ data_type: FieldTypes.GLOBAL_FIELD;
2012
+ schema: CTSchema;
2013
+ }
2014
+ interface Group extends CTGenericField {
2015
+ data_type: FieldTypes.GROUP;
2016
+ schema: CTSchema;
2017
+ }
2018
+ interface ModularBlock extends CTGenericField {
2019
+ data_type: FieldTypes.MODULAR_BLOCK;
2020
+ blocks: {
2021
+ uid: string;
2022
+ title?: string;
2023
+ display_name?: string;
2024
+ schema: CTSchema;
2025
+ }[];
2026
+ }
2027
+ interface ReferenceField extends CTGenericField {
2028
+ data_type: "reference";
2029
+ reference_to: string[];
2030
+ }
2031
+ type CTField = CTGenericField | GlobalField | Group | ModularBlock | ReferenceField;
2032
+ type CTSchema = CTField[];
2033
+ /**
2034
+ * A content type as the binder reads it (CMA shape, minimal). No index
2035
+ * signature: callers pass their own fuller content-type interfaces, which an
2036
+ * index signature would reject.
2037
+ */
2038
+ interface ContentType {
2039
+ uid: string;
2040
+ schema: CTSchema;
2041
+ title?: string;
2042
+ }
2043
+ type SectionCardinality = "collection" | "single";
2044
+ /** A section composition's `linked_schemas[]` item. */
2045
+ interface SchemaLink {
2046
+ content_type_uid: string;
2047
+ selected_field?: string;
2048
+ display_name?: string;
2049
+ uid_remapping?: Record<string, string>;
2050
+ cardinality?: SectionCardinality;
2051
+ }
2052
+ /** The section composition fields the binder reads. */
2053
+ interface SectionCompositionLike {
2054
+ uid: string;
2055
+ title?: string;
2056
+ /** Parsed `Node`; a compressed string is decompressed by `normalizeSectionComposition`. */
2057
+ ui: unknown;
2058
+ linked_schemas?: SchemaLink[];
2059
+ }
2060
+
2061
+ /**
2062
+ * Ported verbatim from Studio `src/utilities/sectionCompositionAutoBinding.ts`.
2063
+ * Only the imports differ (local types/helpers instead of Studio modules).
2064
+ */
2065
+
2066
+ /**
2067
+ * Sentinel for `selectedField` meaning "the surrounding scope itself is the
2068
+ * section's binding target". Used when a section sits inside a repeater whose
2069
+ * item shape structurally IS the section's Global Field (no inner wrapper
2070
+ * field to descend into). The SDK's getScopedData() already treats an empty
2071
+ * string as "use the scope as-is".
2072
+ */
2073
+ declare const SECTION_BINDING_SCOPE_ROOT: "";
2074
+ interface SectionAutoBindingResult {
2075
+ /**
2076
+ * The active field path within the page's content type.
2077
+ * Defaults to the section's configured selected_field.
2078
+ * Updated when the user switches via the dropdown.
2079
+ *
2080
+ * May be `SECTION_BINDING_SCOPE_ROOT` ("") to signal that the section binds
2081
+ * to the repeater item itself (case B — see scopeMatchesSectionField).
2082
+ */
2083
+ selectedField: string;
2084
+ /**
2085
+ * Other structural matches in the page's content type that the user can switch to.
2086
+ * Excludes the currently active selectedField.
2087
+ */
2088
+ alternativeFields: string[];
2089
+ /**
2090
+ * Maps section schema child UIDs → page field child UIDs.
2091
+ * Empty when selectedField matches the section's original selected_field
2092
+ * (same content type, same UIDs — no remapping needed).
2093
+ * Populated when the user explicitly switches to an alternative field with different UIDs.
2094
+ */
2095
+ uidRemapping: Record<string, string>;
2096
+ /**
2097
+ * Set when the binding IS the page composer's explicit Section data
2098
+ * (`metadata.sectionBindingOverride.rootBinding`, ADR 0016). Authoritative:
2099
+ * neither the legacy field-list validation nor the store merge replaces it.
2100
+ */
2101
+ explicitRoot?: boolean;
2102
+ /**
2103
+ * Fetch root of an explicit Section data (ADR 0017): `"template"`, a
2104
+ * `<ct>:<uid>` pool key, or `query:<uid>`, plus the path within it. Carried so
2105
+ * the full-map context push agrees with the targeted push that preceded it.
2106
+ */
2107
+ fetchRootKey?: string;
2108
+ fetchRootPrefix?: string[];
2109
+ rootBinding?: BindingType | null;
2110
+ /**
2111
+ * Set when the fetch root came from the ENCLOSING wrapper rather than from
2112
+ * this placement (ADR 0017 slot rebasing). The distinction matters to the
2113
+ * context push: an inherited root carries no `rootBinding` of its own, so the
2114
+ * picker still reads "no Section data set" on the child while its data
2115
+ * resolves against the wrapper's document.
2116
+ */
2117
+ inheritedRoot?: boolean;
2118
+ }
2119
+ /** The per-instance override as `findSectionCompositionInstances` reads it off the node. */
2120
+ interface InstanceBindingOverrideLike {
2121
+ selectedField: string;
2122
+ uidRemapping?: Record<string, string>;
2123
+ hasExplicitRoot?: boolean;
2124
+ rootBinding?: BindingType | null;
2125
+ fetchRootKey?: string;
2126
+ fetchRootPrefix?: string[];
2127
+ }
2128
+ /**
2129
+ * What a placement's persisted `sectionBindingOverride` means for the binding
2130
+ * this pass computes.
2131
+ *
2132
+ * Two generations of override live on that key. The retired "Data source"
2133
+ * dropdown wrote a bare `selectedField`, chosen from THIS auto-binder's own
2134
+ * match list, so re-validating it against the fresh list was the right
2135
+ * staleness check (the page CT may have changed since it was saved). The
2136
+ * Section data picker (ADR 0016) writes a `rootBinding`, validated by its own
2137
+ * structural matcher, which accepts what this binder never lists: containment
2138
+ * matches, nested fields, pinned entries, query results. Re-validating those
2139
+ * here silently reverted every such pick — the row read "Navigation Menu 3",
2140
+ * the canvas rendered the declared field — so an explicit root is taken as
2141
+ * authoritative, exactly as `stampSelfDescribingSectionBindings` already does,
2142
+ * and applies even when the auto-binder has no answer of its own (otherwise
2143
+ * `resolveSectionBinding` falls back to the declared field and clobbers it).
2144
+ */
2145
+ declare function applyInstanceBindingOverride(computed: SectionAutoBindingResult | null, override: InstanceBindingOverrideLike | undefined): SectionAutoBindingResult | null;
2146
+ /**
2147
+ * Rebase a placement that pinned NO root onto the fetch root of the nearest
2148
+ * enclosing section that did (ADR 0017).
2149
+ *
2150
+ * A wrapper with a pinned-entry root changes which document everything in its
2151
+ * slots resolves against. The SDK's cold-load seeder has always applied this
2152
+ * (`walkSectionInstances` threads `inheritedRoot`), but the live editor map did
2153
+ * not — so a slot child scoped from the page template in the canvas while a
2154
+ * reload and the deployed site resolved it against the wrapper's document
2155
+ * (E2E DR7.4). A placement with a root of its own is left alone: its own root
2156
+ * wins outright rather than concatenating with the inherited prefix (DR7.5).
2157
+ */
2158
+ declare function applyInheritedFetchRoot(binding: SectionAutoBindingResult | null, inherited: {
2159
+ fetchRootKey: string;
2160
+ fetchRootPrefix: string[];
2161
+ } | undefined): SectionAutoBindingResult | null;
2162
+ declare function getNestedSchemaForScope(schema: CTSchema, scopePath?: string | null, contentTypeMap?: Map<string, ContentType>): CTSchema | null;
2163
+ declare function mergeSectionAutoBindings(computedBindings: Record<string, SectionAutoBindingResult>, existingBindings?: Record<string, SectionAutoBindingResult>): Record<string, SectionAutoBindingResult>;
2164
+ /**
2165
+ * Returns a sorted list of first-level child identifiers for a field.
2166
+ * For groups/global_fields: sorted data_types of immediate children.
2167
+ * For blocks: sorted block UIDs.
2168
+ * For references: sorted reference_to content type UIDs.
2169
+ * For simple fields: empty array.
2170
+ */
2171
+ declare function getFirstLevelFieldTypes(field: CTField): string[];
2172
+ /**
2173
+ * Returns true if two fields have the same data_type, multiple flag,
2174
+ * and compatible first-level child structure.
2175
+ *
2176
+ * For `blocks` (modular blocks) fields the rule is intentionally loose:
2177
+ * a match is declared if the two blocks fields share AT LEAST ONE
2178
+ * common block uid in their unions. Rationale — sections typically wrap
2179
+ * their Repeater in a ConditionBlock that narrows to ONE specific block
2180
+ * uid, so they don't care whether the page's blocks union is a strict
2181
+ * superset or subset of the section's; they just need the targeted
2182
+ * block to be present on both sides. Strict-set equality would refuse
2183
+ * obviously-correct pairings (page's nested modular_blocks allows only
2184
+ * the inner block type while the section's modular_blocks allows
2185
+ * several at root) and force manual overrides on the common recursive-
2186
+ * shape pattern.
2187
+ *
2188
+ * `reference` fields follow the same loose rule for the same reason: when
2189
+ * a section's schema is reference-typed, the picker auto-injects a
2190
+ * Repeater + ConditionBlock at the section root, and the ConditionBlock
2191
+ * narrows by `_content_type_uid` per iteration. So the section only needs
2192
+ * ONE of its `reference_to` target CTs to overlap with the page field's
2193
+ * `reference_to` for the binding to be useful — non-matching iterations
2194
+ * simply don't render under their CB, exactly like blocks. Strict
2195
+ * equality here would refuse pairings such as a section that handles
2196
+ * `[hero, banner]` dropped on a page whose ref points to `[hero]` only.
2197
+ *
2198
+ * Other field types (group/global_field) still require exact first-level
2199
+ * shape equality — those don't have ConditionBlock narrowing semantics,
2200
+ * so the looser rule wouldn't be safe.
2201
+ */
2202
+ declare function doFieldStructuresMatch(sectionField: CTField, pageField: CTField): boolean;
2203
+ /**
2204
+ * Case B match: the section's Global Field has no wrapper field within the
2205
+ * surrounding scope, because the scope itself (e.g. a modular block whose
2206
+ * schema mirrors the GF, or a list-of-Global-Field repeater item) IS the
2207
+ * section's binding shape.
2208
+ *
2209
+ * Compares the section field's *children* against the entire scoped schema
2210
+ * using the same shallow tolerance as `doFieldStructuresMatch` (sorted
2211
+ * first-level data_types, same length).
2212
+ */
2213
+ declare function scopeMatchesSectionField(sectionField: CTField, scopedPageSchema: CTSchema): boolean;
2214
+ /**
2215
+ * Finds all top-level fields in pageSchema whose structure matches sectionField.
2216
+ * Returns their UIDs as the matching field paths. Strict matching first; if
2217
+ * sectionField is a list (multiple) and strict yields nothing, falls back to
2218
+ * lenient subset matching so a structurally-compatible nested list inside the
2219
+ * scope (e.g. inner_group) is preferred over the single-iteration scope-root
2220
+ * fallback. For non-multiple section fields the behavior is unchanged.
2221
+ */
2222
+ declare function findMatchingPageFields(sectionField: CTField, pageSchema: CTSchema): string[];
2223
+ /**
2224
+ * Builds a positional UID remapping from section child UIDs to page child UIDs.
2225
+ * Matches children by index within the same data_type sequence.
2226
+ * Only applies to group/global_field fields with nested schemas.
2227
+ *
2228
+ * Example:
2229
+ * section schema: [{uid: "heading", data_type: "text"}, {uid: "body", data_type: "textarea"}]
2230
+ * page schema: [{uid: "title", data_type: "text"}, {uid: "desc", data_type: "textarea"}]
2231
+ * result: { heading: "title", body: "desc" }
2232
+ *
2233
+ * IMPORTANT — this remap is SHALLOW (one level of children only); it does NOT
2234
+ * recurse into nested groups/blocks. Consequence for nested data:
2235
+ * - NESTED GROUPS (a group inside a group): the inner group must use the SAME
2236
+ * uid as the outer group (e.g. outer `grp1` → inner `grp1`). The inner level
2237
+ * isn't remapped, so a section repeater bound to that group only resolves the
2238
+ * inner items when the inner uid matches; differing uids → data won't render.
2239
+ * - MODULAR BLOCKS: the page block's id must match the section's block id
2240
+ * (the ConditionBlock condition value is the block uid, compared as-is) —
2241
+ * differing block ids → the per-block iteration won't resolve.
2242
+ * If recursive nested remapping is ever needed, this function must walk child
2243
+ * schemas instead of relying on matching uids at each nested level.
2244
+ */
2245
+ declare function buildFieldUidRemapping(sectionField: CTField, pageField: CTField): Record<string, string>;
2246
+ /**
2247
+ * Computes the auto-binding for a section against the page's connected content type.
2248
+ *
2249
+ * The section's configured selected_field is ALWAYS used as the active binding
2250
+ * (preserving the section author's intent and avoiding wrong-field substitution).
2251
+ * Structural matching only discovers ALTERNATIVE fields for the dropdown.
2252
+ *
2253
+ * Algorithm:
2254
+ * 1. Find the linked schema whose content_type_uid matches the page's connected CT.
2255
+ * 2. Resolve the field at selected_field within that CT's schema.
2256
+ * 3. Find all top-level fields in the PAGE's CT that structurally match.
2257
+ * 4. Return selected_field unchanged as the active binding; other matches as alternatives.
2258
+ *
2259
+ * Returns null if the page CT doesn't match any linked schema, or if selected_field
2260
+ * is not set on the matching schema.
2261
+ * Skips computation if the SchemaLink already has uid_remapping set (user override).
2262
+ */
2263
+ declare function computeSectionAutoBinding(linkedSchemas: SchemaLink[] | undefined, pageConnectedContentTypeUid: string | null | undefined, contentTypeMap: Map<string, ContentType>, contextSchemaPath?: string | null,
2264
+ /**
2265
+ * Section composition's authored UI tree. Optional — when provided, enables
2266
+ * Case 3 introspection: a CT-anchored section (no `selected_field`) whose
2267
+ * linked CT differs from the page CT can still auto-bind by remapping its
2268
+ * internal Repeater reference bindings onto overlapping page ref fields.
2269
+ * Callers that don't have the section UI in scope can omit this; Case 3
2270
+ * simply doesn't fire.
2271
+ */
2272
+ sectionUi?: Node | null): SectionAutoBindingResult | null;
2273
+ /**
2274
+ * Computes a new binding result when the user explicitly switches to a different field
2275
+ * via the dropdown. The override field may come from a DIFFERENT position in the page's
2276
+ * content type schema, requiring UID remapping so the section's bindings still resolve.
2277
+ */
2278
+ declare function computeAutoBindingForField(linkedSchemas: SchemaLink[] | undefined, pageConnectedContentTypeUid: string | null | undefined, contentTypeMap: Map<string, ContentType>, overrideSelectedField: string, contextSchemaPath?: string | null): SectionAutoBindingResult | null;
2279
+
2280
+ /**
2281
+ * The pure tree walk behind Studio's section auto-binding, ported verbatim from
2282
+ * Studio `src/utilities/sectionCompositions.ts`: `findSectionCompositionInstances`
2283
+ * plus the helpers it needs (`indexSectionSlotsContext`,
2284
+ * `getSlotDefaultSectionUids`) and `normalizeSectionComposition`. Editor-only
2285
+ * helpers (mode toggles, Slate path lookups, slot whitelists) are not ported.
2286
+ */
2287
+
2288
+ type NormalizedSectionComposition = Omit<SectionCompositionLike, "ui"> & {
2289
+ ui: Node;
2290
+ };
2291
+ interface SectionInstanceBindingOverride {
2292
+ selectedField: string;
2293
+ uidRemapping?: Record<string, string>;
2294
+ /**
2295
+ * True when the node stores an explicit Section data — the `rootBinding` key
2296
+ * is PRESENT on `sectionBindingOverride` (ADR 0016), `null` included. Such an
2297
+ * override is authoritative; see `applyInstanceBindingOverride`. The three
2298
+ * fields below are set only in that case.
2299
+ */
2300
+ hasExplicitRoot?: boolean;
2301
+ rootBinding?: BindingType | null;
2302
+ /** Where the placement's data comes from (ADR 0017); `"template"` ⇒ page entry. */
2303
+ fetchRootKey?: string;
2304
+ fetchRootPrefix?: string[];
2305
+ }
2306
+ /**
2307
+ * The fetch root a placement INHERITS from the nearest enclosing section that
2308
+ * pinned one (ADR 0017's slot rebasing) — set only when the placement has no
2309
+ * root of its own.
2310
+ */
2311
+ interface SectionInheritedFetchRoot {
2312
+ fetchRootKey: string;
2313
+ fetchRootPrefix: string[];
2314
+ }
2315
+ interface SectionCompositionInstance {
2316
+ nodeUid: string;
2317
+ compositionUid: string;
2318
+ parentRepeaterUid: string | null;
2319
+ contextSchemaPath: string;
2320
+ /**
2321
+ * Per-instance auto-binding override persisted on the section-composition
2322
+ * node's `metadata.sectionBindingOverride`. Written by the SectionFieldBinding
2323
+ * dropdown when the user picks a non-default page field; read by
2324
+ * `computeAllSectionAutoBindings` to restore the choice across save/reload.
2325
+ * Absent when the user has never switched (or has switched back to the
2326
+ * auto-detected default).
2327
+ */
2328
+ overrideBinding?: SectionInstanceBindingOverride;
2329
+ /**
2330
+ * The enclosing wrapper's fetch root, for a placement that pinned none of its
2331
+ * own. A wrapper with a pinned-entry root rebases everything in its slots:
2332
+ * inside it, paths count from THAT document, not from the page entry
2333
+ * (ADR 0017). The SDK's cold-load seeder has always done this
2334
+ * (`walkSectionInstances`), so before this the live editor and a reload
2335
+ * disagreed — the slot child scoped from the page template in the canvas
2336
+ * while the deployed site resolved it correctly (E2E DR7.4).
2337
+ */
2338
+ inheritedFetchRoot?: SectionInheritedFetchRoot;
2339
+ }
2340
+ /**
2341
+ * Map of `section-slot` uid → its authored `defaultSection` uid for every slot
2342
+ * in a section that declares one (COMS-1659). Used by the binding walker to emit
2343
+ * a virtual instance for an empty slot's default so the default resolves data.
2344
+ */
2345
+ declare function getSlotDefaultSectionUids(ui: Node | null | undefined): Record<string, string>;
2346
+ /**
2347
+ * Auto-binder projection of `indexSectionSlotContexts`: for each section-slot,
2348
+ * collect the nearest ancestor Repeater uid plus the cumulative schema-path
2349
+ * segments contributed by ancestor Repeaters (items binding) and
2350
+ * ConditionBlocks (dataBinding). Used by `findSectionCompositionInstances`
2351
+ * to compute `parentRepeaterUid` / `contextSchemaPath` for nested
2352
+ * section-composition instances dropped inside a section's slot.
2353
+ *
2354
+ * Exported so `getIncludeQueries` (include-path analyzer) can compute the same
2355
+ * slot-context prefix when it descends into a section-composition's slot
2356
+ * children — keeping CMA include[] paths in lockstep with the binding context.
2357
+ */
2358
+ declare function indexSectionSlotsContext(sectionUI: Node): Record<string, {
2359
+ parentRepeaterUid: string | null;
2360
+ segments: string[];
2361
+ }>;
2362
+ declare function findSectionCompositionInstances(ui: Node, compositionUID?: string, sectionsByUid?: Record<string, Node>, sectionEntriesByUid?: Record<string, {
2363
+ linked_schemas?: any[];
2364
+ }>,
2365
+ /**
2366
+ * Per-instance map from `node.uid` → the RESOLVED `selectedField` of the
2367
+ * outer section as computed by the auto-binder (which may differ from the
2368
+ * section's authored `linked_schemas[0].selected_field` in cross-CT
2369
+ * reference-target matches, or when the user has switched via the
2370
+ * SectionFieldBinding dropdown). When provided, the walker prefers this
2371
+ * map for the slot-recursion path prefix so inner sections dropped inside
2372
+ * a section-slot see a `contextSchemaPath` anchored to the page-CT field
2373
+ * the OUTER actually binds against. Callers that don't have resolved
2374
+ * bindings yet (e.g. first pass of a two-pass compute) can omit this and
2375
+ * fall back to the authored path.
2376
+ */
2377
+ resolvedSelectedFieldByNodeUid?: Record<string, string>): SectionCompositionInstance[];
2378
+
2379
+ /**
2380
+ * Ported verbatim from Studio `src/utilities/selfDescribeSectionBindings.ts`.
2381
+ */
2382
+
2383
+ interface SectionLike {
2384
+ uid?: string;
2385
+ linked_schemas?: Array<{
2386
+ content_type_uid?: string;
2387
+ selected_field?: string;
2388
+ }>;
2389
+ }
2390
+ /**
2391
+ * Make a PAGE composition self-describing for standalone rendering.
2392
+ *
2393
+ * The editor resolves each section instance's binding with a schema-aware
2394
+ * auto-binder (matching the section's reference target against the page CT's
2395
+ * reference fields) and keeps the result in `store.canvas.sectionAutoBindings`.
2396
+ * The SDK/cold-load path has no page CT schema and cannot run the auto-binder —
2397
+ * it only has `sectionBindingOverride ?? linked_schemas-fallback`. The editor
2398
+ * also *clears* the override when it equals the auto-default, and a freshly
2399
+ * dropped section never writes one — so a cross-CT reference-target binding
2400
+ * (e.g. a section authored against `section_ct`/`article_ct`, dropped on a
2401
+ * `page_ct1` page and bound to `related_articles`) lives only in transient
2402
+ * editor state. Standalone then falls back to the section's own-CT field
2403
+ * (`section_ref`), which doesn't exist on the page CT, and renders nothing.
2404
+ *
2405
+ * This pass walks the page UI and stamps `metadata.sectionBindingOverride` with
2406
+ * the editor's resolved binding for every instance the SDK could NOT reproduce
2407
+ * from `linked_schemas` alone (different `selectedField`, or any non-empty
2408
+ * `uidRemapping`). Same-CT / scope-root instances the SDK already reproduces are
2409
+ * left untouched. Returns a new UI tree (input is not mutated).
2410
+ */
2411
+ declare function stampSelfDescribingSectionBindings(ui: Node, sectionAutoBindings: Record<string, SectionAutoBindingResult>, sectionsByUid: Map<string, SectionLike>, pageContentTypeUid: string): Node;
2412
+
2413
+ /**
2414
+ * Ported verbatim from Studio `src/utilities/sectionInternalRefIntrospection.ts`.
2415
+ */
2416
+
2417
+ interface SectionInternalReferenceBinding {
2418
+ /** The section CT's reference field uid that the internal Repeater binds to. */
2419
+ sectionRefUid: string;
2420
+ /** `reference_to` array of that section CT field — the set of target CTs. */
2421
+ targetCTs: string[];
2422
+ }
2423
+ /**
2424
+ * Walks a section composition's authored UI and collects every Repeater whose
2425
+ * `items` binding resolves to a top-level reference field on the section's
2426
+ * content type.
2427
+ *
2428
+ * Used by Case 3 of the auto-binder: a CT-anchored section (no `selected_field`
2429
+ * on linked_schemas) authored against CT-X but dropped on a page whose CT
2430
+ * differs needs each internal `template.<sectionRefUid>` Repeater binding to
2431
+ * remap onto a page ref field with an overlapping `reference_to` target.
2432
+ *
2433
+ * Scope of this v1 introspection:
2434
+ * - Only TEMPLATE-typed Repeater bindings are considered (the auto-binder
2435
+ * remap targets page CT fields, which the SDK applies via uidRemapping
2436
+ * against the scoped `template`).
2437
+ * - Only TOP-LEVEL field uids are extracted (the first segment of the
2438
+ * binding path). Nested ref paths (e.g. `group.inner_ref`) are out of
2439
+ * scope — the remap helper only handles shallow rename.
2440
+ * - Walks every slot recursively but does NOT descend into nested
2441
+ * section-composition nodes (those have their own internal-ref
2442
+ * extraction performed by their own auto-binding pass).
2443
+ */
2444
+ declare function extractSectionInternalReferenceBindings(sectionUi: Node | undefined | null, sectionCT: ContentType | undefined | null): SectionInternalReferenceBinding[];
2445
+
2446
+ /**
2447
+ * Store-free port of Studio `src/services/deriveSectionScoping.ts`
2448
+ * (`computeAllSectionAutoBindings` + `getAbsentSectionBindings`).
2449
+ *
2450
+ * Deviations from Studio, all forced by having no editor store:
2451
+ * - The content-type map is a parameter (Studio reads
2452
+ * `store.canvas.contentTypeUIDToCT()`); build it with `buildContentTypeMap`,
2453
+ * which replicates that selector exactly.
2454
+ * - The result is merged with `existingBindings` (default `{}`) instead of
2455
+ * `store.canvas.sectionAutoBindings()`. With `{}` the merge is a shallow
2456
+ * copy — identical to Studio's save path, which resets the store bindings to
2457
+ * `{}` before computing.
2458
+ * - The absent-section bindings are computed per call unless the caller
2459
+ * passes them (`absentBindings`) — Studio memoises them across calls on
2460
+ * their real inputs, which a store-free function cannot do safely.
2461
+ */
2462
+
2463
+ /**
2464
+ * Studio's `store.canvas.contentTypeUIDToCT()` selector, verbatim: later
2465
+ * entries with the same uid overwrite earlier ones.
2466
+ */
2467
+ declare function buildContentTypeMap(contentTypes: ReadonlyArray<ContentType> | null | undefined): Map<string, ContentType>;
2468
+ /**
2469
+ * Auto-bindings for catalog sections that are NOT on the page. Reads only the
2470
+ * section catalog, the page's connected content type and the content-type map —
2471
+ * never the tree, so a caller can memoise it on those three inputs and pass the
2472
+ * result to `computeAllSectionAutoBindings`.
2473
+ */
2474
+ declare function getAbsentSectionBindings(normalizedSections: NormalizedSectionComposition[], pageConnectedContentTypeUid: string | null, contentTypeMap: Map<string, ContentType>): Record<string, SectionAutoBindingResult>;
2475
+ /**
2476
+ * The canonical section auto-binding computation — Studio's
2477
+ * `computeAllSectionAutoBindings` with the store reads lifted to parameters.
2478
+ *
2479
+ * `absentBindings` must be `getAbsentSectionBindings` of the same sections,
2480
+ * page content type and content-type map; omitted, it is computed here.
2481
+ */
2482
+ declare function computeAllSectionAutoBindings(normalizedSections: NormalizedSectionComposition[], pageConnectedContentTypeUid: string | null, contentTypeMap: Map<string, ContentType>, editorUI?: any, existingBindings?: Record<string, SectionAutoBindingResult>, absentBindings?: Record<string, SectionAutoBindingResult>): Record<string, SectionAutoBindingResult>;
2483
+
2484
+ interface ComputeSectionAutoBindingsParams {
2485
+ /** The PAGE composition's ui, parsed (`Node`). Falsy ⇒ catalog-level bindings only. */
2486
+ ui: unknown;
2487
+ /** Section compositions in the catalog. `ui` parsed (a compressed string is decompressed). */
2488
+ sections: Array<{
2489
+ uid: string;
2490
+ ui: unknown;
2491
+ linked_schemas?: unknown[];
2492
+ title?: string;
2493
+ }>;
2494
+ /** The page's `connected_content_type`; `""`/`null` ⇒ no connected CT. */
2495
+ pageContentTypeUid: string | null | undefined;
2496
+ /** Every content type of the stack (CMA shape). Same input as Studio's `contentTypes` store slice. */
2497
+ contentTypes: Array<{
2498
+ uid: string;
2499
+ schema?: unknown[];
2500
+ [k: string]: unknown;
2501
+ }>;
2502
+ }
2503
+ /**
2504
+ * Studio's `computeAllSectionAutoBindings`, store-free: identical inputs yield
2505
+ * identical results. Keyed by section-composition NODE uid for placed sections
2506
+ * and by section composition uid for catalog sections not on the page.
2507
+ */
2508
+ declare function computeSectionAutoBindings(params: ComputeSectionAutoBindingsParams): Record<string, SectionAutoBindingResult>;
2509
+
2510
+ /**
2511
+ * Remove the `include[]` paths a longer path already covers.
2512
+ *
2513
+ * The longest path brings in the ones above it. Asking for `a.ref.nested_ref`
2514
+ * resolves `a.ref` too, so a path that is just the start of a longer one is
2515
+ * asking twice. We checked this against the live API rather than assuming it:
2516
+ * the two requests came back byte for byte the same.
2517
+ *
2518
+ * This has to run once everything has been merged. Whether a path is the start
2519
+ * of a longer one depends on paths that other sections, the page itself, and
2520
+ * the caller's own extra references have yet to add.
2521
+ */
2522
+ declare function dropImpliedParents(paths: readonly string[]): string[];
2523
+
2524
+ /**
2525
+ * A single, framework-neutral meta tag. `attr` distinguishes standard
2526
+ * `<meta name="...">` tags from Open Graph-style `<meta property="...">`.
2527
+ */
2528
+ interface CompositionMetaTag {
2529
+ attr: "name" | "property";
2530
+ key: string;
2531
+ content: string;
2532
+ }
2533
+ /**
2534
+ * Framework-neutral SEO metadata derived from a composition's resolved
2535
+ * `specOptions.seo`. Consumers bind this to their host's head mechanism:
2536
+ * Next.js `generateMetadata`, Remix `meta()`, TanStack `head()`, or a raw
2537
+ * HTML template via {@link renderMetadataToHtml}.
2538
+ */
2539
+ interface CompositionMetadata {
2540
+ title?: string;
2541
+ description?: string;
2542
+ ogImage?: string;
2543
+ /** Absolute canonical URL. Present only when `baseUrl` was provided and the composition has a URL. */
2544
+ canonical?: string;
2545
+ /** Every derived tag (description, og:*, twitter:*, custom metaProps) in render order. */
2546
+ tags: CompositionMetaTag[];
2547
+ }
2548
+ interface GetCompositionMetadataOptions {
2549
+ /**
2550
+ * Site origin used to absolutize the canonical URL and og:url,
2551
+ * e.g. `https://www.example.com`. No trailing slash required.
2552
+ */
2553
+ baseUrl?: string;
2554
+ }
2555
+ /**
2556
+ * Derives framework-neutral SEO metadata from a fetched composition.
2557
+ *
2558
+ * The heavy lifting (resolving field bindings for title/description/OG image)
2559
+ * already happens inside `fetchCompositionData` — this helper only shapes the
2560
+ * resolved values into standard head-tag structures.
2561
+ *
2562
+ * @example Plain Node
2563
+ * ```ts
2564
+ * const meta = getCompositionMetadata(specOptions, { baseUrl: "https://example.com" });
2565
+ * res.send(`<head><title>${meta.title}</title>${renderMetadataToHtml(meta)}</head>...`);
2566
+ * ```
2567
+ *
2568
+ * @example Next.js App Router
2569
+ * ```ts
2570
+ * export async function generateMetadata() {
2571
+ * const meta = getCompositionMetadata(await getSpecOptions());
2572
+ * return { title: meta.title, description: meta.description };
2573
+ * }
2574
+ * ```
2575
+ */
2576
+ declare function getCompositionMetadata(specOptions: Pick<StudioComponentSpecOptions, "seo" | "spec">, options?: GetCompositionMetadataOptions): CompositionMetadata;
2577
+ /**
2578
+ * Renders {@link CompositionMetadata} to a raw HTML string (meta + canonical
2579
+ * link tags — the `<title>` element is left to the caller since most hosts
2580
+ * manage it separately). For template-string SSR hosts (Express/Fastify).
2581
+ */
2582
+ declare function renderMetadataToHtml(metadata: CompositionMetadata): string;
2583
+
2584
+ /** Whether a spec renders a failed fetch rather than a composition. */
2585
+ declare function isResolutionFailureSpec(spec: StudioSpec | null | undefined): boolean;
2586
+
2587
+ /** What one fetch asked for, and what it got back: the spec, or the error. */
2588
+ interface ResolutionTelemetryInput {
2589
+ query: CompositionQuery;
2590
+ options?: CompositionQueryOptions;
2591
+ /** True for `StudioCanvas`, which renders the edited composition by uid. */
2592
+ isCanvasComponent?: boolean;
2593
+ spec?: StudioSpec;
2594
+ error?: unknown;
2595
+ }
2596
+ /**
2597
+ * The resolution telemetry for one fetch: what was asked for, the candidates,
2598
+ * the winner, or why it failed. One builder for every surface, so Studio reads
2599
+ * the same shape wherever the fetch ran. Plain data, because a server render
2600
+ * carries it to the browser inside the page.
2601
+ */
2602
+ declare function buildResolutionTelemetry({ query, options, isCanvasComponent, spec, error, }: ResolutionTelemetryInput): CompositionResolutionDiagnosticEventData;
2603
+
1896
2604
  /**
1897
2605
  * Processes the raw static values and stored them against their static value UID.
1898
2606
  *
@@ -2060,6 +2768,31 @@ declare function isCompositionNotFound(error: unknown): boolean;
2060
2768
  declare class CompositionNotFoundError extends ComposableStudioError {
2061
2769
  }
2062
2770
 
2771
+ /**
2772
+ * What happens when the preview host refuses a request's preview hash.
2773
+ *
2774
+ * One deployment usually serves both editors and visitors, and the only thing
2775
+ * that puts a request on the preview path is a query parameter
2776
+ * (`?live_preview=<hash>`). So a visitor reaches it too: a preview link copied
2777
+ * into a chat, an editor's old bookmark, a crawled preview URL, or a bot adding
2778
+ * parameters. Once the hash has expired the preview host refuses it, and without
2779
+ * a fallback every such request became a failed page — a 500 on any site that
2780
+ * rightly rethrows what it cannot answer.
2781
+ *
2782
+ * The SDK answers it the way a visitor without the link would be answered: the
2783
+ * published composition. Only Studio's canvas still gets the refusal, because
2784
+ * there the hash is the editor's own session and the author needs to see it.
2785
+ */
2786
+ /**
2787
+ * Whether this failure is the preview host refusing the request's preview hash.
2788
+ *
2789
+ * A code check rather than `instanceof`, for the reason given on
2790
+ * `isCompositionNotFound`: a second copy of the SDK has its own error class.
2791
+ * A host rarely needs it — a visitor's request is answered with the published
2792
+ * composition instead — but it is what to check when it does reach one.
2793
+ */
2794
+ declare function isPreviewHashRefused(error: unknown): boolean;
2795
+
2063
2796
  declare const evaluateCondition: (condition: Condition, data: any) => boolean;
2064
2797
  /**
2065
2798
  * Answers both questions a ConditionBlock has to ask: does this condition pass,
@@ -2179,6 +2912,19 @@ declare function specUsesComponent(spec: Node | null | undefined, componentType:
2179
2912
  * @returns Map of component types to their usage count
2180
2913
  */
2181
2914
  declare function getComponentUsageStats(spec: Node | null | undefined): Map<string, number>;
2915
+ /**
2916
+ * The `compositionUID` of every placed section in a layout — the types
2917
+ * analyzeUsedComponents reports for section-composition nodes, so a check can
2918
+ * tell a section that did not load from a component that is not registered.
2919
+ */
2920
+ declare function analyzePlacedSectionUids(spec: Node | null | undefined): Set<string>;
2921
+
2922
+ /**
2923
+ * JSON for a server that writes spec options into an inline `<script>` itself,
2924
+ * with no framework to do it. Escapes what would let a hostile value, such as a
2925
+ * URL containing `</script>`, break out of the tag. Parses back to the same value.
2926
+ */
2927
+ declare function serializeForInlineScript(value: unknown): string;
2182
2928
 
2183
2929
  type StudioEvent = (typeof POST_MESSAGE_EVENTS)[keyof typeof POST_MESSAGE_EVENTS];
2184
2930
  /**
@@ -2596,5 +3342,5 @@ declare function rankUrlMatches(requestUrl: string, lightweightEntries: Lightwei
2596
3342
  */
2597
3343
  declare function shouldUseUrlMetadataPath(url_metadata?: Partial<CompositionUrlMetadataSerialized>): boolean;
2598
3344
 
2599
- export { BreakpointManager, COMPOSABLE_DATA_ATTRIBUTES, COMPOSABLE_STUDIO_EMITTED_EVENTS, COMPOSITION_PLACEMENT_OPTIONS, COMPOSITION_PREVIEW_URL_SOURCES, COMPOSITION_PREVIEW_URL_SOURCES_VALUES, ComposableStudioError, CompositionNotFoundError, DEFAULT_BREAKPOINTS, DEFAULT_COMPOSITION_PREVIEW_URL_SOURCE, ELEMENT_TO_NODE, ExpressionResolver, GOOGLE_FONT_API, INCLUDE_DEPTH_COUNT, NODE_TO_ELEMENT, NODE_TO_PARENT, NODE_TO_PATH_NODE, QueryExecutor, RendererMode, RendererModeUtil, SCHEMA_VERSION, SDK_VERSION, SECTION_COMPOSITIONS_KEY, STUDIO_CANVAS_QUERY_PARAM, STUDIO_MODE_HTML_CLASS, StudioErrorClass, StudioErrorCode, TEMPLATE_BINDING_TYPE, TEMPLATE_FETCH_ROOT_KEY, TEMPLATE_FULL_ENTRY_KEY, URL_PATTERN_DATE_VARIABLES, URL_PATTERN_METADATA_FIELDS, URL_PATTERN_METADATA_FIELDS_VALUES, URL_PATTERN_VARIABLE_TYPES, addBreakpointEventListeners, addContextMenuEventListeners, addUrlChangeListeners, analyzeMultipleSpecs, analyzeUsedComponents, applyOperation, batchFetchEntries, buildSectionScopedData, buildStudioErrorContext, buildTemplateQuery, buildUrlMetadataQueryObject, clientRendererModeUtil, compileUrlPattern, composableStudioEventEmitter, computePatternSpecificity, createClassNameUid, createEmbeddedEntryConversion, createStudioError, studioSdk as default, defaultAssetRender, derivePlacementIncludePaths, detectStudioMode, entriesFromResponse, evaluateCondition, extractHtmlRteRefs, extractJsonRteRefs, fetchEmbeddedEntries, fetchRootFromBinding, findNearestBuilderNode, findNearestSlotNode, findPath, findPathForElement, flattenPath, getBindingStringForCS, getComponentUsageStats, getComposableElement, getComposableElements, getCompositionMetadata, getComputedStyles, getDefaultConfig, getEmbeddedAssetRenderer, getEmbeddedEntryRenderer, getHitboxDetails, getHitboxDirection, getJSONRTE, getRootBindingPath, getRootScopePath, getSeoMetadataPure, hasSlotDropzone, isBrowser, isCompositionBeingEdited, isCompositionNotFound, isDataRootCleared, isInsideIframe, isInsideVisualBuilderFrame, isPageAbsoluteField, isSetupFault, isStudioCanvas, isStudioEditorMode, isTemplateFetchRoot, isTemplateRootBinding, loadGoogleFont, markStudioMode, matchCompositionUrl, matchUrlPattern, nestPath, onlyParmasGenerator, parseEntryFetchRootKey, parseStringValue, parseUrlMetadata, preProcessStaticValues, queryParam, rankUrlMatches, registerEmbeddedEntryRenderer, registerJSONRTE, registerRTERenderer, removeStaticEntryFromDS, renderMetadataToHtml, resolveByUrlSource, resolveConditionScope, resolveInstanceRootBinding, resolveLegacySelectedField, resolveLegacySelectedFieldWithProvenance, resolveMatchedSchema, sectionDataEqual, sendStudioEvent, serializeComputedStyles, serializeEvent, setStaticEntryInDS, setTemplateEntryInDS, shouldExtractTaxonomies, shouldUseUrlMetadataPath, specUsesComponent, splitFieldPath, studioSdk, synthesizeTemplateRootBinding, templateFetchRoot, toggleNodeVisible, updateStyleOnStyleNodeChange };
2600
- export type { ClientEditableNodeInternalAttributes, ClientPreviewNodeInternalAttributes, ComposableStudioErrorDetails, ComposableStudioLightSdk, CompositionEntry, CompositionEntryIncompleteUi, CompositionFetcher, CompositionMetaTag, CompositionMetadata, CompositionPlacement, CompositionPreviewUrlSource, CompositionPreviewUrlSourceValues, CompositionQueryForSSR, CompositionQueryForSSRInput, CompositionQueryOptions, CompositionUrlMetadata, CompositionUrlMetadataSerialized, CompositionUrlQueries, Config, ConnectedEntryResult, DateVariableKey, EmbeddedAssetRenderArgs, EmbeddedEntryConversionOptions, EmbeddedEntryRenderArgs, EmittedEvents, ExtractedUrlPatternVariables, ExtractedUrlVariables, FetchCompositionContext, FetchRoot, FetchTemplateEntryContext, FieldValue, FontVariants, GetCompositionMetadataOptions, GoogleFont, HiddenElementNotificationHandler, LightConfig, LightweightCompositionEntry, LinkedSchemasLookup, MetaProp, ParsedStringResult, PatternMatchResult, QueryExecutionOptions, QueryResult, QuerySpec, QueryState, RTEConfig, RankingResult, ReferenceFieldValue, RenderableCompositionEntry, ResolvedEmbeddedEntry, ResolvedQueryOptions, RuntimeContext, SearchQueryInput, SectionBindingOverride, SectionCompositionEntry, SectionDataBinding, SectionInstanceNode, SelectedFieldProvenance, SeoMetadata, StudioComponentFetchOptions, StudioComponentSpecOptions, StudioMode, StudioSdk, StudioSpec, TemplateEntryFetcher, TemplateQueryContext, TroubleshootingInfo, URLSearchParamsString, UrlMatchDiagnostic, UrlMetadataQueryMode, UrlPatternMetadataField, UrlPatternMetadataFieldValue, UserConfig };
3345
+ export { BreakpointManager, COMPOSABLE_DATA_ATTRIBUTES, COMPOSABLE_STUDIO_EMITTED_EVENTS, COMPOSITION_PLACEMENT_OPTIONS, COMPOSITION_PREVIEW_URL_SOURCES, COMPOSITION_PREVIEW_URL_SOURCES_VALUES, ComposableStudioError, CompositionNotFoundError, DEFAULT_BREAKPOINTS, DEFAULT_COMPOSITION_PREVIEW_URL_SOURCE, ELEMENT_TO_NODE, ExpressionResolver, GOOGLE_FONT_API, INCLUDE_DEPTH_COUNT, NODE_TO_ELEMENT, NODE_TO_PARENT, NODE_TO_PATH_NODE, PERMANENT_DROP_ZONE_ELEMENTS, QueryExecutor, RendererMode, RendererModeUtil, SCHEMA_VERSION, SDK_VERSION, SECTION_BINDING_SCOPE_ROOT, SECTION_COMPOSITIONS_KEY, STUDIO_CANVAS_QUERY_PARAM, STUDIO_LOG_PREFIX, STUDIO_MODE_HTML_CLASS, STUDIO_NEXT_STEPS_HEADING, StudioErrorClass, StudioErrorCode, TEMPLATE_BINDING_TYPE, TEMPLATE_FETCH_ROOT_KEY, TEMPLATE_FULL_ENTRY_KEY, URL_PATTERN_DATE_VARIABLES, URL_PATTERN_METADATA_FIELDS, URL_PATTERN_METADATA_FIELDS_VALUES, URL_PATTERN_VARIABLE_TYPES, URL_WINNER_KIND, addBreakpointEventListeners, addContextMenuEventListeners, addUrlChangeListeners, analyzeMultipleSpecs, analyzePlacedSectionUids, analyzeUsedComponents, applyInheritedFetchRoot, applyInstanceBindingOverride, applyOperation, batchFetchEntries, buildContentTypeMap, buildFieldUidRemapping, buildResolutionTelemetry, buildSectionScopedData, buildStudioErrorContext, buildTemplateQuery, buildUrlMetadataQueryObject, clientRendererModeUtil, collectSectionPlacementScopes, collectSlotChildScopes, compileUrlPattern, composableStudioEventEmitter, computeAllSectionAutoBindings, computeAutoBindingForField, computePatternSpecificity, computeSectionAutoBinding, computeSectionAutoBindings, createClassNameUid, createEmbeddedEntryConversion, createStudioError, studioSdk as default, defaultAssetRender, derivePlacementIncludePaths, detectStudioMode, doFieldStructuresMatch, dropImpliedParents, entriesFromResponse, evaluateCondition, extractHtmlRteRefs, extractJsonRteRefs, extractSectionInternalReferenceBindings, fetchEmbeddedEntries, fetchRootFromBinding, findMatchingPageFields, findNearestBuilderNode, findNearestSlotNode, findPath, findPathForElement, findSectionCompositionInstances, findTargetedPermanentDropZone, flattenPath, formatStudioErrorCause, getAbsentSectionBindings, getBindingStringForCS, getComponentUsageStats, getComposableElement, getComposableElements, getCompositionMetadata, getComputedStyles, getDefaultConfig, getDropTargetHitboxDetails, getEmbeddedAssetRenderer, getEmbeddedEntryRenderer, getFirstLevelFieldTypes, getHitboxDetails, getHitboxDirection, getJSONRTE, getNestedSchemaForScope, getOutsideComponentsHitboxDetails, getRootBindingPath, getRootScopePath, getSeoMetadataPure, getSlotDefaultSectionUids, hasSlotDropzone, indexSectionSlotsContext, isBrowser, isCompositionBeingEdited, isCompositionNotFound, isDataRootCleared, isInsideIframe, isInsideVisualBuilderFrame, isPageAbsoluteField, isPreviewHashRefused, isResolutionFailureSpec, isSetupFault, isStudioCanvas, isStudioEditorMode, isTemplateFetchRoot, isTemplateRootBinding, loadGoogleFont, markStudioMode, matchCompositionUrl, matchUrlPattern, mergeSectionAutoBindings, nestPath, onlyParmasGenerator, parseEntryFetchRootKey, parseStringValue, parseUrlMetadata, preProcessStaticValues, queryParam, rankUrlMatches, rebuildStudioError, registerEmbeddedEntryRenderer, registerJSONRTE, registerRTERenderer, removeStaticEntryFromDS, renderMetadataToHtml, resolveByUrlSource, resolveConditionScope, resolveInstanceRootBinding, resolveLegacySelectedField, resolveLegacySelectedFieldWithProvenance, resolveMatchedSchema, scopeMatchesSectionField, sectionDataEqual, sendStudioEvent, serializeComputedStyles, serializeEvent, serializeForInlineScript, serializeStudioError, setStaticEntryInDS, setTemplateEntryInDS, shouldExtractTaxonomies, shouldUseUrlMetadataPath, specUsesComponent, splitFieldPath, stampSelfDescribingSectionBindings, studioSdk, synthesizeTemplateRootBinding, templateFetchRoot, toggleNodeVisible, updateStyleOnStyleNodeChange };
3346
+ export type { ClientEditableNodeInternalAttributes, ClientPreviewNodeInternalAttributes, ComposableStudioErrorDetails, ComposableStudioLightSdk, CompositionEntry, CompositionEntryIncompleteUi, CompositionMetaTag, CompositionMetadata, CompositionPlacement, CompositionPreviewUrlSource, CompositionPreviewUrlSourceValues, CompositionQueryForSSR, CompositionQueryForSSRInput, CompositionQueryOptions, CompositionUrlMetadata, CompositionUrlMetadataSerialized, CompositionUrlQueries, ComputeSectionAutoBindingsParams, Config, ConnectedEntryResult, DateVariableKey, EmbeddedAssetRenderArgs, EmbeddedEntryConversionOptions, EmbeddedEntryRenderArgs, EmittedEvents, ExtractedUrlPatternVariables, ExtractedUrlVariables, FetchRoot, FieldValue, FontVariants, GetCompositionMetadataOptions, GoogleFont, HiddenElementNotificationHandler, InstanceBindingOverrideLike, LightConfig, LightweightCompositionEntry, LinkedSchemasLookup, MetaProp, NormalizedSectionComposition, ParsedStringResult, PatternMatchResult, QueryExecutionOptions, QueryResult, QuerySpec, QueryState, RTEConfig, RankingResult, ReferenceFieldValue, RenderableCompositionEntry, ResolutionTelemetryInput, ResolvedEmbeddedEntry, RuntimeContext, SearchQueryInput, SectionAutoBindingResult, SectionBindingOverride, SectionCompositionEntry, SectionCompositionInstance, SectionDataBinding, SectionInheritedFetchRoot, SectionInstanceBindingOverride, SectionInstanceNode, SectionInternalReferenceBinding, SectionLike, SectionPlacementScope, SelectedFieldProvenance, SeoMetadata, SerializedStudioError, SlotChildScope, StudioComponentFetchOptions, StudioComponentSpecOptions, StudioMode, StudioSdk, StudioSpec, TemplateQueryContext, TroubleshootingInfo, URLSearchParamsString, UrlMatchDiagnostic, UrlMetadataQueryMode, UrlPatternMetadataField, UrlPatternMetadataFieldValue, UserConfig };