@contentstack/studio-client 3.2.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. package/dist/breakpoints/BreakpointManager.js +7 -5
  2. package/dist/breakpoints/BreakpointManager.js.map +1 -1
  3. package/dist/breakpoints/breakpoint.js +3 -2
  4. package/dist/breakpoints/breakpoint.js.map +1 -1
  5. package/dist/canvas/canvas.utils.js +13 -1
  6. package/dist/canvas/canvas.utils.js.map +1 -1
  7. package/dist/composable-studio/build-scoped-data.js +12 -35
  8. package/dist/composable-studio/build-scoped-data.js.map +1 -1
  9. package/dist/composable-studio/sdk.js +1064 -430
  10. package/dist/composable-studio/sdk.js.map +1 -1
  11. package/dist/composable-studio/studio-intelligence.manager.js +5 -2
  12. package/dist/composable-studio/studio-intelligence.manager.js.map +1 -1
  13. package/dist/config/config.schema.js +45 -8
  14. package/dist/config/config.schema.js.map +1 -1
  15. package/dist/config/default-config.js +10 -3
  16. package/dist/config/default-config.js.map +1 -1
  17. package/dist/config/process-user-config.js +37 -1
  18. package/dist/config/process-user-config.js.map +1 -1
  19. package/dist/config/stack-sdk-wrapper.js +36 -1
  20. package/dist/config/stack-sdk-wrapper.js.map +1 -1
  21. package/dist/context-menu/context-menu.js +5 -2
  22. package/dist/context-menu/context-menu.js.map +1 -1
  23. package/dist/design/handle-active-style-change.js +3 -2
  24. package/dist/design/handle-active-style-change.js.map +1 -1
  25. package/dist/dnd/dnd-event.js +2 -1
  26. package/dist/dnd/dnd-event.js.map +1 -1
  27. package/dist/dnd/dnd-manager.js +3 -1
  28. package/dist/dnd/dnd-manager.js.map +1 -1
  29. package/dist/editor.d.ts +250 -0
  30. package/dist/editor.js +11 -0
  31. package/dist/editor.js.map +1 -0
  32. package/dist/get-active-node-screenshot/get-node-screenshot-event.js +2 -1
  33. package/dist/get-active-node-screenshot/get-node-screenshot-event.js.map +1 -1
  34. package/dist/hidden-element-notification/hidden-element-notification-event.js +2 -1
  35. package/dist/hidden-element-notification/hidden-element-notification-event.js.map +1 -1
  36. package/dist/highlight-node/highlight-node-manager.js +225 -15
  37. package/dist/highlight-node/highlight-node-manager.js.map +1 -1
  38. package/dist/highlight-node/highlight-node.js +42 -6
  39. package/dist/highlight-node/highlight-node.js.map +1 -1
  40. package/dist/highlight-spacing/highlight-spacing-events.js +2 -1
  41. package/dist/highlight-spacing/highlight-spacing-events.js.map +1 -1
  42. package/dist/index.d.ts +1006 -436
  43. package/dist/index.js +12 -13
  44. package/dist/index.js.map +1 -1
  45. package/dist/url-change/url-change.js +4 -3
  46. package/dist/url-change/url-change.js.map +1 -1
  47. package/dist/url-metadata/build-template-query.js +14 -3
  48. package/dist/url-metadata/build-template-query.js.map +1 -1
  49. package/dist/utils/canvas.js +2 -1
  50. package/dist/utils/canvas.js.map +1 -1
  51. package/dist/utils/check-bindings.js +233 -0
  52. package/dist/utils/check-bindings.js.map +1 -0
  53. package/dist/utils/classify-response-error.js +288 -0
  54. package/dist/utils/classify-response-error.js.map +1 -0
  55. package/dist/utils/composable-studio-error.js +36 -20
  56. package/dist/utils/composable-studio-error.js.map +1 -1
  57. package/dist/utils/composition-not-found.js +52 -0
  58. package/dist/utils/composition-not-found.js.map +1 -0
  59. package/dist/utils/constants.js +21 -2
  60. package/dist/utils/constants.js.map +1 -1
  61. package/dist/utils/degraded-finding.js +166 -0
  62. package/dist/utils/degraded-finding.js.map +1 -0
  63. package/dist/utils/editor-mode.js +1 -1
  64. package/dist/utils/http-error.constants.js +12 -46
  65. package/dist/utils/http-error.constants.js.map +1 -1
  66. package/dist/utils/include-path-rules.js +40 -1
  67. package/dist/utils/include-path-rules.js.map +1 -1
  68. package/dist/utils/is-composition-being-edited.js +1 -1
  69. package/dist/utils/is-inside-iframe.js +1 -1
  70. package/dist/utils/is-inside-visual-builder-frame.js +1 -1
  71. package/dist/utils/parse-ui.js +60 -0
  72. package/dist/utils/parse-ui.js.map +1 -0
  73. package/dist/utils/query-param.js +1 -1
  74. package/dist/utils/query-param.js.map +1 -1
  75. package/dist/utils/reference-stub.js +75 -0
  76. package/dist/utils/reference-stub.js.map +1 -0
  77. package/dist/utils/reference_fetcher.js +44 -3
  78. package/dist/utils/reference_fetcher.js.map +1 -1
  79. package/dist/utils/require-stack.js +141 -0
  80. package/dist/utils/require-stack.js.map +1 -0
  81. package/dist/utils/served-by.js +33 -0
  82. package/dist/utils/served-by.js.map +1 -0
  83. package/dist/utils/studio-error-codes.js +253 -0
  84. package/dist/utils/studio-error-codes.js.map +1 -0
  85. package/dist/utils/studio-error.js +122 -0
  86. package/dist/utils/studio-error.js.map +1 -0
  87. package/dist/utils/studio-messaging.js +25 -0
  88. package/dist/utils/studio-messaging.js.map +1 -0
  89. package/dist/visual-builder/composition-save-event.js +2 -1
  90. package/dist/visual-builder/composition-save-event.js.map +1 -1
  91. package/package.json +19 -6
  92. package/dist/utils/error-messages.default.js +0 -141
  93. package/dist/utils/error-messages.default.js.map +0 -1
  94. package/dist/utils/error-messages.js +0 -47
  95. package/dist/utils/error-messages.js.map +0 -1
@@ -1,18 +1,28 @@
1
- import { COMPOSABLE_STUDIO_QUERY_PARAM, composableStudioEventManager, POST_MESSAGE_EVENTS } from '@contentstack/studio-messenger';
1
+ import { COMPOSABLE_STUDIO_QUERY_PARAM, POST_MESSAGE_EVENTS } from '@contentstack/studio-messenger/constants';
2
+ import { sendStudioEvent } from '../utils/studio-messaging.js';
2
3
  import { INTERNAL_COMPONENTS_NAMES, DATA_SOURCES, getStateStoreInstance, getComponentRegistryInstance, DATA_SOURCES_PREFIX } from '@contentstack/studio-registry';
3
4
  import { get, pick, uniq, uniqBy, chunk, range } from 'lodash-es';
4
5
  import { processUserConfig } from '../config/process-user-config.js';
5
6
  import { setStackSdkInstance } from '../json-rte-registry/stack-sdk-store.js';
7
+ import { requireStack } from '../utils/require-stack.js';
8
+ import { parseUI } from '../utils/parse-ui.js';
6
9
  import { SCHEMA_VERSION, SDK_VERSION, INCLUDE_DEPTH_COUNT } from '../utils/constants.js';
7
10
  import { isCompositionBeingEdited } from '../utils/is-composition-being-edited.js';
8
- import { setTemplateEntryInDS, setStaticEntryInDS, entriesFromResponse, getBindingStringForCS } from '../utils/sdk.js';
11
+ import { setTemplateEntryInDS, setStaticEntryInDS, getBindingStringForCS, entriesFromResponse } from '../utils/sdk.js';
9
12
  import '../utils/editor-mode.js';
10
- import { ComposableStudioError, ComposableStudioErrors } from '../utils/composable-studio-error.js';
13
+ import { ComposableStudioError } from '../utils/composable-studio-error.js';
14
+ import '../utils/composition-not-found.js';
15
+ import { createStudioError, buildStudioErrorContext, isSetupFault } from '../utils/studio-error.js';
16
+ import { StudioErrorCode } from '../utils/studio-error-codes.js';
11
17
  import '../utils/conditionBlock.js';
12
18
  import { clientRendererModeUtil, RendererModeUtil } from '../utils/canvas.js';
13
19
  import { analyzeUsedComponents } from '../utils/spec-analyzer.js';
14
20
  import { convertCompositionQueryInputToCompositionQuery } from '../utils/convertCompositionQueryInputToCompositionQuery.js';
15
- import { getErrorMessage, getTroubleshootingInfo } from '../utils/error-messages.js';
21
+ import { classifyResponseError, diagnoseUnreadableResponse } from '../utils/classify-response-error.js';
22
+ import { reportDegraded, degradedReportingIsOn, DegradedCode } from '../utils/degraded-finding.js';
23
+ import { countUnresolvedReferences } from '../utils/reference-stub.js';
24
+ import { findBindingDefects } from '../utils/check-bindings.js';
25
+ import { resolveServedBy } from '../utils/served-by.js';
16
26
  import { getPageLinkedPlacementFilter } from '../utils/build-composition-fetch-query.js';
17
27
  import { resolveByUrlSource } from '../url-metadata/build-template-query.js';
18
28
  import { parseUrlMetadata } from '../url-metadata/parse-url-metadata.js';
@@ -20,17 +30,15 @@ import { rankUrlMatches } from '../url-metadata/rank-url-matches.js';
20
30
  import { selectUrlWinner } from '../url-metadata/select-url-winner.js';
21
31
  import { COMPOSITION_PREVIEW_URL_SOURCES } from '../url-metadata/types.js';
22
32
  import { matchCompositionUrl } from '../url-metadata/url-pattern-matcher.js';
23
- import { getStatusCode, isContentstackAuthError, hasAuthErrorShape, isAuthError, isNetworkError, HttpStatus, ContentstackErrorCode, isServerError } from '../utils/http-error.constants.js';
24
- import { indexModularBlocks, isModularBlockPath, dropImpliedParents } from '../utils/include-path-rules.js';
33
+ import { indexModularBlocks, isModularBlockPath, compositionCarriesCompleteIncludes, dropImpliedParents } from '../utils/include-path-rules.js';
25
34
  import { getEntriesQueries, projectIncludePathsOntoOnlyKeys, getSchemaPath } from '../utils/reference_fetcher.js';
26
35
  import { applyUrlBudget, referencesExceedBudget } from '../utils/query-url-budget.js';
27
36
  import { collectAllDataNeeds, stableHashQuery, parseExternalDataForComponentProps } from './collect-data-needs.js';
28
37
  import { buildScopedDataSources } from './build-scoped-data.js';
29
38
  import { preProcessStaticValues } from './data/pre-process-static-values.js';
30
39
  import { StudioIntelligenceManager } from './studio-intelligence.manager.js';
31
- import { parseEntryFetchRootKey, TEMPLATE_FETCH_ROOT_KEY, resolveInstanceRootBinding, fetchRootFromBinding, resolveLegacySelectedFieldWithProvenance, isTemplateRootBinding, getRootBindingPath, resolveLegacySelectedField, isPageAbsoluteField, templateFetchRoot } from './section-data.js';
40
+ import { TEMPLATE_FETCH_ROOT_KEY, parseEntryFetchRootKey, resolveInstanceRootBinding, fetchRootFromBinding, resolveLegacySelectedFieldWithProvenance, isTemplateRootBinding, getRootBindingPath, resolveLegacySelectedField, isPageAbsoluteField, templateFetchRoot } from './section-data.js';
32
41
  import { decompressSpec } from '../studio-internal/dist/utils/spec-compression.js';
33
- import { ErrorMessageKey, TroubleshootingInfoKey } from '../utils/error-messages.default.js';
34
42
 
35
43
  // ✅ HYBRID APPROACH: List of internal components that should always be available
36
44
  // These include both built-in components AND system components (like "page")
@@ -625,7 +633,7 @@ function collectSectionInstanceBindings(ui, sectionsByUid, pageContentTypeUid) {
625
633
  // full slot path (mirrors the editor's `indexSectionSlotsContext`).
626
634
  const wrapperUi = sectionsByUid.get(compositionUid)?.ui;
627
635
  if (wrapperUi) {
628
- const wrapperUiNode = typeof wrapperUi === "string" ? decompressSpec(wrapperUi) : wrapperUi;
636
+ const wrapperUiNode = typeof wrapperUi === "string" ? parseUI(wrapperUi) : wrapperUi;
629
637
  slotSegments = new Map();
630
638
  mapSectionSlotSegments(wrapperUiNode, [], slotSegments);
631
639
  }
@@ -682,10 +690,10 @@ function collectSectionInstanceBindings(ui, sectionsByUid, pageContentTypeUid) {
682
690
  return out;
683
691
  }
684
692
  async function fetchSectionCompositionEntries(config, sectionUids, options) {
685
- if (!config.stackSdk || sectionUids.length === 0) {
693
+ if (sectionUids.length === 0) {
686
694
  return [];
687
695
  }
688
- const response = await config.stackSdk
696
+ const response = await requireStack(config)
689
697
  .ctQuery(config.contentTypeUid, {
690
698
  includeAll: true,
691
699
  includeAllDepth: INCLUDE_DEPTH_COUNT,
@@ -696,7 +704,7 @@ async function fetchSectionCompositionEntries(config, sectionUids, options) {
696
704
  return entriesFromResponse(response).map((entry) => ({
697
705
  ...entry,
698
706
  ui: typeof entry.ui === "string"
699
- ? decompressSpec(entry.ui)
707
+ ? parseUI(entry.ui, entry.composable_uid)
700
708
  : entry.ui,
701
709
  }));
702
710
  }
@@ -706,6 +714,46 @@ async function fetchSectionCompositionEntries(config, sectionUids, options) {
706
714
  * section) unioned with any `section-composition` nodes embedded in its `ui`.
707
715
  * One depth level of the nested-section graph.
708
716
  */
717
+ /**
718
+ * A component the stored layout uses that the registry does not have.
719
+ *
720
+ * Setup rather than content: the composition is fine, and the application did
721
+ * not tell the SDK about a component it refers to. The two kinds take opposite
722
+ * advice — ours register themselves on first import of the React package, so a
723
+ * missing built-in means the package root was never imported, while a missing
724
+ * custom one means a `registerComponent()` call had not run yet.
725
+ */
726
+ function componentsNotRegistered(componentTypes, areBuiltIn, config) {
727
+ return createStudioError({
728
+ code: StudioErrorCode.COMPONENT_NOT_REGISTERED,
729
+ headline: areBuiltIn
730
+ ? `Studio's own components are not registered: ${componentTypes.join(", ")}.`
731
+ : `These components are used by this composition and not registered: ${componentTypes.join(", ")}.`,
732
+ causes: areBuiltIn
733
+ ? [
734
+ {
735
+ cause: "The package root was never imported, so the built-in components never registered themselves.",
736
+ fix: 'Import it once before fetching: import "@contentstack/studio-react";',
737
+ },
738
+ {
739
+ cause: "The import was tree-shaken out of a server-only bundle.",
740
+ fix: "Keep the root import in the bundle that runs the fetch.",
741
+ },
742
+ ]
743
+ : [
744
+ {
745
+ cause: "The fetch ran before registerComponent() did.",
746
+ fix: "Import the module that registers them above the code that fetches.",
747
+ },
748
+ {
749
+ cause: "The composition uses a component this build does not have.",
750
+ fix: "Register it, or remove it from the composition.",
751
+ },
752
+ ],
753
+ context: buildStudioErrorContext(config),
754
+ findings: { componentTypes, areBuiltIn },
755
+ });
756
+ }
709
757
  /**
710
758
  * Adds FULL section entries inlined on `entry.linked_sections` (resolved by
711
759
  * `includeAll` depth) into `map`, RECURSIVELY — an inline section's own inline
@@ -729,7 +777,7 @@ function harvestInlineLinkedSections(entry, map) {
729
777
  if (map.has(e.uid))
730
778
  continue;
731
779
  const ui = typeof e.ui === "string"
732
- ? decompressSpec(e.ui)
780
+ ? parseUI(e.ui, e.composable_uid)
733
781
  : e.ui;
734
782
  map.set(e.uid, { ...e, ui });
735
783
  added.push(e.uid);
@@ -748,8 +796,10 @@ function referencedSectionUidsOf(entry) {
748
796
  uids.add(uid);
749
797
  }
750
798
  }
799
+ // This reader takes a narrowed shape that carries no uid, so the diagnosis
800
+ // names the case without naming the composition.
751
801
  const ui = typeof entry.ui === "string"
752
- ? decompressSpec(entry.ui)
802
+ ? parseUI(entry.ui)
753
803
  : entry.ui;
754
804
  if (ui)
755
805
  for (const u of collectSectionCompositionUIDs(ui))
@@ -769,7 +819,7 @@ async function getAllSectionCompositions(config, compositionEntry, options) {
769
819
  // that returned nothing (deleted section) or closing a cycle. Rounds =
770
820
  // nesting depth, not section count; breadth at a level is one call.
771
821
  const ui = typeof compositionEntry.ui === "string"
772
- ? decompressSpec(compositionEntry.ui)
822
+ ? parseUI(compositionEntry.ui, compositionEntry.composable_uid)
773
823
  : compositionEntry.ui;
774
824
  const requested = new Set();
775
825
  // Seed the frontier from the page UI + the page's linked_sections, plus the
@@ -820,14 +870,6 @@ async function getAllSectionCompositions(config, compositionEntry, options) {
820
870
  }
821
871
  return map;
822
872
  }
823
- function getAuthErrorMessage(err) {
824
- const detail = err?.error_message ||
825
- err?.errors?.api_key?.[0] ||
826
- err?.errors?.authorization?.[0] ||
827
- err?.message ||
828
- getErrorMessage(ErrorMessageKey.INVALID_CREDENTIALS_DEFAULT);
829
- return getErrorMessage(ErrorMessageKey.AUTHENTICATION_ERROR, { detail });
830
- }
831
873
  /**
832
874
  * SEO bindings are stored in the UI metadata with the same nested `value.path`
833
875
  * shape used by the normal data-binding system:
@@ -1109,20 +1151,10 @@ async function ensureUiComponentsLoaded(ui, sectionEntries) {
1109
1151
  }
1110
1152
  });
1111
1153
  if (missingBuiltInComponents.length > 0) {
1112
- throw new ComposableStudioError(ComposableStudioErrors.COMPONENT_NOT_FOUND, [
1113
- `[Composable Studio SDK] Internal components missing: ${missingBuiltInComponents.join(", ")}`,
1114
- "",
1115
- "Built-in components are auto-registered on first import of @contentstack/studio-react.",
1116
- "Fix: make sure the package root is imported at least once before fetch:",
1117
- ' import "@contentstack/studio-react";',
1118
- ].join("\n"));
1154
+ throw componentsNotRegistered(missingBuiltInComponents, true);
1119
1155
  }
1120
1156
  if (missingCustomComponents.length > 0) {
1121
- throw new ComposableStudioError(ComposableStudioErrors.COMPONENT_NOT_FOUND, [
1122
- `[Composable Studio SDK] Custom components not registered: ${missingCustomComponents.join(", ")}`,
1123
- "",
1124
- "Ensure all registerComponent() calls complete before fetching the composition.",
1125
- ].join("\n"));
1157
+ throw componentsNotRegistered(missingCustomComponents, false);
1126
1158
  }
1127
1159
  try {
1128
1160
  await componentRegistry.loadComponents(Array.from(usedComponents));
@@ -1132,116 +1164,6 @@ async function ensureUiComponentsLoaded(ui, sectionEntries) {
1132
1164
  throw error;
1133
1165
  }
1134
1166
  }
1135
- /**
1136
- * Helper function to detect and classify API errors
1137
- * @internal - Exported for testing purposes
1138
- */
1139
- function classifyApiError(err) {
1140
- const statusCode = getStatusCode(err);
1141
- // Check for authentication errors: Contentstack error_code 104/105 or errors.api_key/authorization (no HTTP status)
1142
- if (isContentstackAuthError(err) || (!statusCode && hasAuthErrorShape(err))) {
1143
- return {
1144
- errorType: ComposableStudioErrors.AUTHENTICATION_ERROR,
1145
- message: getAuthErrorMessage(err),
1146
- };
1147
- }
1148
- // Check for authentication errors (401, 403)
1149
- if (statusCode !== undefined && isAuthError(statusCode)) {
1150
- return {
1151
- errorType: ComposableStudioErrors.AUTHENTICATION_ERROR,
1152
- message: getAuthErrorMessage(err),
1153
- };
1154
- }
1155
- // Check for empty entry response (200 OK but no entries found)
1156
- // This happens when API succeeds but returns empty entry list
1157
- // Note: Pure empty objects {} should be treated as network errors, not empty responses
1158
- const isEmptyEntryResponse = statusCode === 200 &&
1159
- err &&
1160
- typeof err === "object" &&
1161
- err.entries &&
1162
- Array.isArray(err.entries) &&
1163
- err.entries.length === 0;
1164
- if (isEmptyEntryResponse) {
1165
- return {
1166
- errorType: ComposableStudioErrors.PREVIEW_ENTRY_NOT_FOUND,
1167
- message: getErrorMessage(ErrorMessageKey.PREVIEW_ENTRY_NOT_FOUND, {
1168
- contentType: "the composition",
1169
- }),
1170
- };
1171
- }
1172
- // Check for network errors (no response, timeout, connection refused)
1173
- if (!statusCode && isNetworkError(err)) {
1174
- // For empty objects, use the specific empty error message
1175
- if (typeof err === "object" && Object.keys(err).length === 0) {
1176
- return {
1177
- errorType: ComposableStudioErrors.NETWORK_ERROR,
1178
- message: getErrorMessage(ErrorMessageKey.NETWORK_ERROR_EMPTY),
1179
- };
1180
- }
1181
- // For other network errors, use the generic message with detail
1182
- return {
1183
- errorType: ComposableStudioErrors.NETWORK_ERROR,
1184
- message: getErrorMessage(ErrorMessageKey.NETWORK_ERROR_GENERIC, {
1185
- detail: err?.message ||
1186
- getErrorMessage(ErrorMessageKey.NETWORK_ERROR_DETAIL_DEFAULT),
1187
- }),
1188
- };
1189
- }
1190
- // Check for 404 - composition not found
1191
- if (statusCode === HttpStatus.NOT_FOUND ||
1192
- err?.error_code === ContentstackErrorCode.ENTRY_NOT_FOUND) {
1193
- return {
1194
- errorType: ComposableStudioErrors.COMPOSITION_NOT_FOUND,
1195
- message: err?.error_message ||
1196
- err?.message ||
1197
- getErrorMessage(ErrorMessageKey.COMPOSITION_NOT_FOUND_404),
1198
- };
1199
- }
1200
- // Check for server errors (5xx)
1201
- if (statusCode !== undefined && isServerError(statusCode)) {
1202
- return {
1203
- errorType: ComposableStudioErrors.SERVER_ERROR,
1204
- message: getErrorMessage(ErrorMessageKey.SERVER_ERROR, {
1205
- statusCode,
1206
- detail: err?.error_message ||
1207
- err?.message ||
1208
- getErrorMessage(ErrorMessageKey.SERVER_ERROR_DETAIL_DEFAULT),
1209
- }),
1210
- };
1211
- }
1212
- // Other HTTP errors or default: single COMPOSITION_NOT_FOUND return with shared message builder
1213
- const message = statusCode !== undefined
1214
- ? getErrorMessage(ErrorMessageKey.COMPOSITION_NOT_FOUND_API, {
1215
- statusCode,
1216
- detail: err?.error_message ||
1217
- err?.message ||
1218
- getErrorMessage(ErrorMessageKey.COMPOSITION_NOT_FOUND_API_DETAIL_DEFAULT),
1219
- })
1220
- : err?.error_message ||
1221
- err?.message ||
1222
- getErrorMessage(ErrorMessageKey.COMPOSITION_NOT_FOUND_DEFAULT);
1223
- return {
1224
- errorType: ComposableStudioErrors.COMPOSITION_NOT_FOUND,
1225
- message,
1226
- };
1227
- }
1228
- /**
1229
- * Helper function to get troubleshooting information for composition fetch errors.
1230
- * Uses getTroubleshootingInfo from error-messages (single source of truth).
1231
- * @internal
1232
- */
1233
- function getTroubleshootingInfoForCompositionFetchError(errorType, isUrlBased = false) {
1234
- if (errorType === ComposableStudioErrors.NETWORK_ERROR) {
1235
- return getTroubleshootingInfo(TroubleshootingInfoKey.NETWORK_ERROR);
1236
- }
1237
- if (errorType === ComposableStudioErrors.AUTHENTICATION_ERROR) {
1238
- return getTroubleshootingInfo(TroubleshootingInfoKey.AUTHENTICATION_ERROR);
1239
- }
1240
- if (isUrlBased) {
1241
- return getTroubleshootingInfo(TroubleshootingInfoKey.COMPOSITION_NOT_FOUND_URL);
1242
- }
1243
- return getTroubleshootingInfo(TroubleshootingInfoKey.COMPOSITION_NOT_FOUND_UID);
1244
- }
1245
1167
  function addEditableTags(entry, contentTypeUid, tagsAsObject, locale = "en-us") {
1246
1168
  if (entry) {
1247
1169
  const appliedVariants = entry._applied_variants || entry?.system?.applied_variants || null;
@@ -1450,6 +1372,30 @@ function isSdkInitDebugEnabled() {
1450
1372
  * 🚀 RESTORED: Send INIT_STUDIO via Advanced Post Message from the right place
1451
1373
  * This fires IMMEDIATELY when SDK is created, ensuring proper timing (like original handshake)
1452
1374
  */
1375
+ /**
1376
+ * The connection's facts, as they stand when the configuration arrives.
1377
+ *
1378
+ * Only what is known is reported. With no stack there is nothing to read, so
1379
+ * nothing is said rather than a row of falsey values that would read as claims
1380
+ * about the site's setup.
1381
+ */
1382
+ function readSetupFacts(config) {
1383
+ const stack = config.stackSdk;
1384
+ if (!stack)
1385
+ return undefined;
1386
+ const livePreview = stack.livePreviewConfig;
1387
+ return {
1388
+ apiKey: stack.apiKey,
1389
+ environment: stack.environment,
1390
+ locale: config.locale,
1391
+ host: stack.host,
1392
+ livePreviewEnabled: livePreview?.enable === true,
1393
+ // A boolean, never the value: the token must not cross this boundary.
1394
+ hasPreviewToken: Boolean(livePreview?.preview_token),
1395
+ previewHost: livePreview?.host,
1396
+ hasPreviewHash: Boolean(livePreview?.live_preview),
1397
+ };
1398
+ }
1453
1399
  function sendInitStudioSignal(config) {
1454
1400
  try {
1455
1401
  const initPayload = {
@@ -1464,11 +1410,10 @@ function sendInitStudioSignal(config) {
1464
1410
  configPassedToTheSdk: {
1465
1411
  contentTypeUid: config.contentTypeUid,
1466
1412
  },
1413
+ setup: readSetupFacts(config),
1467
1414
  };
1468
1415
  // Send via Advanced Post Message using static imports
1469
- composableStudioEventManager
1470
- ?.send(POST_MESSAGE_EVENTS.INIT_STUDIO, initPayload)
1471
- .catch((error) => {
1416
+ sendStudioEvent(POST_MESSAGE_EVENTS.INIT_STUDIO, initPayload).catch((error) => {
1472
1417
  console.warn("⚠️ SDK: INIT_STUDIO failed:", error);
1473
1418
  });
1474
1419
  }
@@ -1476,12 +1421,129 @@ function sendInitStudioSignal(config) {
1476
1421
  console.warn("⚠️ SDK: Could not send INIT_STUDIO from generateSdk:", error);
1477
1422
  }
1478
1423
  }
1424
+ /** `data_sources` as stored — a JSON string, an array, or an object keyed by uid. */
1425
+ function parseDataSourceList(raw) {
1426
+ try {
1427
+ const value = typeof raw === "string" ? JSON.parse(raw) : raw;
1428
+ if (Array.isArray(value))
1429
+ return value;
1430
+ return value && typeof value === "object" ? Object.values(value) : [];
1431
+ }
1432
+ catch {
1433
+ return [];
1434
+ }
1435
+ }
1436
+ let extendQueryDeprecationWarned = false;
1437
+ /**
1438
+ * `extendQuery` predates reference ticking: an app passed extra include[] paths
1439
+ * per content type at fetch time. Studio now saves every reference a composition
1440
+ * needs, ticked by the author or implied by a binding, so the option is not
1441
+ * needed. Still honoured, and flagged once in development.
1442
+ */
1443
+ function warnIfExtendQueryPassed(extendQuery) {
1444
+ if (extendQueryDeprecationWarned)
1445
+ return;
1446
+ if (!extendQuery || typeof extendQuery !== "object")
1447
+ return;
1448
+ if (Object.keys(extendQuery).length === 0)
1449
+ return;
1450
+ extendQueryDeprecationWarned = true;
1451
+ if (process.env.NODE_ENV === "development") {
1452
+ console.warn("[studio] `extendQuery` is deprecated and will be removed in the next major. Tick the references in Studio instead — they are saved with the composition.");
1453
+ }
1454
+ }
1455
+ /**
1456
+ * The include[] paths the SDK works out for one placed section on top of what the
1457
+ * compositions persist: the section's own reference-condition paths composed onto
1458
+ * where the section sits, and each cumulative step of that position. They belong
1459
+ * on the request of the instance's fetch root (ADR 0017).
1460
+ *
1461
+ * For the template root, a step the page UI places as a modular-block field or a
1462
+ * block is left out — the Delivery API ignores include[] for those. Every other
1463
+ * step is kept, because one of them can be the reference the section sits on
1464
+ * (anchored at `author`, or under a Repeater over `related_articles`).
1465
+ */
1466
+ function derivedIncludePathsForInstance(binding, sectionDerivedPaths, modularBlocks) {
1467
+ const prefix = composeSectionTemplatePrefix(binding.ancestorPrefix, binding.selectedField, binding.referenceCtUids, { pageAbsolute: binding.fieldIsPageAbsolute });
1468
+ const remapSeg = (seg) => binding.uidRemapping?.[seg] ?? seg;
1469
+ const paths = new Set();
1470
+ for (const p of sectionDerivedPaths) {
1471
+ const full = [...prefix, ...sanitizeFieldPath(p).map(remapSeg)].join(".");
1472
+ if (full)
1473
+ paths.add(full);
1474
+ }
1475
+ const acc = [];
1476
+ for (const seg of prefix) {
1477
+ acc.push(seg);
1478
+ const hop = acc.join(".");
1479
+ if (binding.fetchRootKey !== TEMPLATE_FETCH_ROOT_KEY ||
1480
+ !isModularBlockPath(hop, modularBlocks)) {
1481
+ paths.add(hop);
1482
+ }
1483
+ }
1484
+ return [...paths];
1485
+ }
1486
+ /** `getEntriesQueries` reads `ui` as a string; a section entry carries it parsed. */
1487
+ const asCompositionEntryWithUiString = (entry) => ({
1488
+ ...entry,
1489
+ ui: typeof entry.ui === "string" ? entry.ui : JSON.stringify(entry.ui),
1490
+ });
1491
+ /**
1492
+ * Every include[] path the SDK would work out on its own for a composition,
1493
+ * grouped by the fetch root whose request it belongs on — `"template"`, a
1494
+ * `<ct>:<uid>` pinned entry, or `query:<uid>` (ADR 0017, ADR 0018):
1495
+ *
1496
+ * - the composition's own reference-condition paths, on `"template"`;
1497
+ * - for every placed section, its reference-condition paths composed onto where
1498
+ * it sits, and each step of that position (`derivedIncludePathsForInstance`).
1499
+ *
1500
+ * Below COMPLETE_INCLUDES_FROM_SCHEMA_VERSION the SDK adds these at render. From
1501
+ * that version on it adds none: Studio calls this at save, keeps what the schema
1502
+ * confirms is a reference, and persists it on the matching data source, so the
1503
+ * composition carries everything its fetch roots need. The render path and the
1504
+ * save path share `derivedIncludePathsForInstance`, so they cannot drift apart.
1505
+ *
1506
+ * Paths are unvalidated — the SDK has no schema. A caller persisting them must
1507
+ * validate them first.
1508
+ */
1509
+ function derivePlacementIncludePaths(compositionEntry, sectionEntries) {
1510
+ const pageUi = typeof compositionEntry.ui === "string"
1511
+ ? decompressSpec(compositionEntry.ui)
1512
+ : compositionEntry.ui;
1513
+ if (!pageUi)
1514
+ return {};
1515
+ const connectedContentTypeUid = compositionEntry.connected_content_type || "";
1516
+ const out = new Map();
1517
+ const add = (key, paths) => {
1518
+ const kept = paths.filter(Boolean);
1519
+ if (!kept.length)
1520
+ return;
1521
+ const existing = out.get(key) ?? new Set();
1522
+ for (const path of kept)
1523
+ existing.add(path);
1524
+ out.set(key, existing);
1525
+ };
1526
+ add(TEMPLATE_FETCH_ROOT_KEY, getEntriesQueries(asCompositionEntryWithUiString({
1527
+ ...compositionEntry,
1528
+ ui: JSON.stringify(pageUi),
1529
+ }), connectedContentTypeUid, {}).templateReferencesPath);
1530
+ const sectionsByUid = new Map(sectionEntries.map((s) => [s.uid, s]));
1531
+ const modularBlocks = indexModularBlocks(pageUi);
1532
+ for (const binding of collectSectionInstanceBindings(pageUi, sectionsByUid, connectedContentTypeUid)) {
1533
+ const section = sectionsByUid.get(binding.compositionUid);
1534
+ if (!section)
1535
+ continue;
1536
+ const sectionRefs = getEntriesQueries(asCompositionEntryWithUiString(section), "", {});
1537
+ add(binding.fetchRootKey, derivedIncludePathsForInstance(binding, sectionRefs.templateReferencesPath, modularBlocks));
1538
+ }
1539
+ return Object.fromEntries([...out].map(([key, paths]) => [key, [...paths]]));
1540
+ }
1479
1541
  function generateSdk(userConfig) {
1480
1542
  const config = processUserConfig(userConfig);
1481
1543
  if (clientRendererModeUtil.isInsideStudioFrame()) {
1482
1544
  const sp = new URLSearchParams(window.location.search);
1483
1545
  const hash = sp.get(COMPOSABLE_STUDIO_QUERY_PARAM.PREVIEW_HASH) || "";
1484
- config.stackSdk.livePreviewQuery?.(hash);
1546
+ config.stackSdk?.livePreviewQuery?.(hash);
1485
1547
  // Studio is the source of truth for locale/variant when the SDK runs
1486
1548
  // inside its iframe. Overriding the user-supplied config values here
1487
1549
  // means every SDK-side fetch (initial spec, linked-entry references,
@@ -1583,13 +1645,26 @@ function generateSdk(userConfig) {
1583
1645
  * previously only the template entry saw the URL-pattern locale; the secondary
1584
1646
  * fetches dropped it.
1585
1647
  */
1586
- const resolveLocale = (patternLocale, optionLocale, searchParams) => {
1648
+ const resolveLocale = (patternLocale, optionLocale, searchParams) => resolveLocaleWithSource(patternLocale, optionLocale, searchParams).locale;
1649
+ /**
1650
+ * The same resolution, reporting which tier won — needed because a missing
1651
+ * language is the developer's fault or a visitor's typo depending on where
1652
+ * the locale came from. Inferring that from "a {{locale}} capture existed" is
1653
+ * wrong: the capture can lose to the Studio parameter. Shares the ranking
1654
+ * with resolveLocale so the two cannot disagree about what was sent.
1655
+ */
1656
+ const resolveLocaleWithSource = (patternLocale, optionLocale, searchParams) => {
1587
1657
  const studioLocale = readStudioParam(COMPOSABLE_STUDIO_QUERY_PARAM.LOCALE, searchParams);
1588
- return (studioLocale ||
1589
- patternLocale ||
1590
- optionLocale ||
1591
- config.locale ||
1592
- config.stackSdk?.locale);
1658
+ // Studio's own parameter is a setting an author chose, not part of the
1659
+ // address a visitor asked for, so it ranks as configuration.
1660
+ if (studioLocale)
1661
+ return { locale: studioLocale, source: "configuration" };
1662
+ if (patternLocale)
1663
+ return { locale: patternLocale, source: "url-pattern" };
1664
+ return {
1665
+ locale: optionLocale || config.locale || config.stackSdk?.locale,
1666
+ source: "configuration",
1667
+ };
1593
1668
  };
1594
1669
  /**
1595
1670
  * Resolve the URL-pattern locale for a composition ONCE per fetch, and return
@@ -1644,6 +1719,179 @@ function generateSdk(userConfig) {
1644
1719
  // The raw postMessage approach has been consolidated into the proven INIT_STUDIO system
1645
1720
  // REMOVED: initiateStudioHandshake - no longer needed with Advanced Post Message
1646
1721
  // The INIT_STUDIO system via composableStudioEventManager handles reliable delivery
1722
+ /**
1723
+ * Names the entry a binding reads, for the middle of a sentence.
1724
+ *
1725
+ * A binding that names its own entry gets the uid and the content type,
1726
+ * because in a project with many entries that is the whole of the lookup. A
1727
+ * template binding names neither — it reads whichever entry the composition is
1728
+ * connected to on this request — so it gets a phrase instead, and the sentence
1729
+ * says less rather than printing a stand-in where a uid should be.
1730
+ */
1731
+ function describeBindingSubject(defect) {
1732
+ if (!defect.entryUid || !defect.contentTypeUid) {
1733
+ return "the entry this composition is connected to";
1734
+ }
1735
+ return `entry ${defect.entryUid} of "${defect.contentTypeUid}"`;
1736
+ }
1737
+ /**
1738
+ * Says which bindings will render blank, and why.
1739
+ *
1740
+ * Walks every binding on the page, so it is skipped outright unless somebody
1741
+ * will read the result.
1742
+ *
1743
+ * The missing-path case carries two causes and asserts neither, and that is
1744
+ * the rule for this whole group rather than a hedge. We hold the entry, not
1745
+ * the content type's schema, so a field that was renamed and a field the
1746
+ * author simply has not filled in are the same absence from here. Picking one
1747
+ * would send half of these readers to change something that is correct.
1748
+ */
1749
+ function reportBindingDefects(pageUi, data, request) {
1750
+ if (!degradedReportingIsOn(config))
1751
+ return;
1752
+ for (const defect of findBindingDefects(pageUi, data.dataSources, request)) {
1753
+ if (defect.code === DegradedCode.PREVIEW_ASSET_PROJECTION_NULL) {
1754
+ reportDegraded({
1755
+ code: DegradedCode.PREVIEW_ASSET_PROJECTION_NULL,
1756
+ headline: `The asset at "${defect.path}" on ` +
1757
+ describeBindingSubject(defect) +
1758
+ " came back empty from the preview service. The same request " +
1759
+ "returns it from the published CDN.",
1760
+ causes: [
1761
+ {
1762
+ cause: "A known Preview API defect empties an asset asked for by a " +
1763
+ "dotted path when a modular-blocks field is asked for beside it.",
1764
+ fix: "Check the published site before changing anything — the binding is probably fine. Nothing in this project fixes it.",
1765
+ },
1766
+ {
1767
+ cause: "The asset is genuinely not set on this entry.",
1768
+ fix: "Set it, or leave it — the binding works either way.",
1769
+ },
1770
+ ],
1771
+ findings: {
1772
+ path: defect.path,
1773
+ entryUid: defect.entryUid,
1774
+ contentTypeUid: defect.contentTypeUid,
1775
+ },
1776
+ }, config);
1777
+ continue;
1778
+ }
1779
+ if (defect.code === DegradedCode.BINDING_PATH_MISSING) {
1780
+ reportDegraded({
1781
+ code: DegradedCode.BINDING_PATH_MISSING,
1782
+ headline: `The binding "${defect.path}" does not exist on ` +
1783
+ describeBindingSubject(defect) +
1784
+ ".",
1785
+ causes: [
1786
+ {
1787
+ cause: "The field was renamed or removed on the content type.",
1788
+ fix: "Re-point the binding at the field it should read.",
1789
+ },
1790
+ {
1791
+ cause: "The field is there and nobody has filled it in yet.",
1792
+ fix: "Nothing to fix here — add the content.",
1793
+ },
1794
+ ],
1795
+ findings: {
1796
+ path: defect.path,
1797
+ entryUid: defect.entryUid,
1798
+ contentTypeUid: defect.contentTypeUid,
1799
+ },
1800
+ }, config);
1801
+ continue;
1802
+ }
1803
+ reportDegraded({
1804
+ code: DegradedCode.BINDING_SHAPE_MISMATCH,
1805
+ headline: `The binding "${defect.path}" reads a single value and resolved ` +
1806
+ `to a ${defect.resolvedTo}.`,
1807
+ causes: [
1808
+ {
1809
+ cause: "The binding points at a container rather than at a field inside it.",
1810
+ fix: `Point it at a field within "${defect.path}".`,
1811
+ },
1812
+ ],
1813
+ findings: {
1814
+ path: defect.path,
1815
+ entryUid: defect.entryUid,
1816
+ contentTypeUid: defect.contentTypeUid,
1817
+ resolvedTo: defect.resolvedTo,
1818
+ },
1819
+ }, config);
1820
+ }
1821
+ }
1822
+ /**
1823
+ * Says how many references came back as pointers rather than as entries.
1824
+ *
1825
+ * Runs over everything that was fetched, so it is skipped outright unless
1826
+ * somebody will read the result — a production page that is fine should not
1827
+ * pay to walk its own content looking for a report nobody asked for.
1828
+ *
1829
+ * Two causes, neither asserted. A composition nesting past the include depth
1830
+ * and a referenced entry that was deleted produce byte-identical pointers, so
1831
+ * there is nothing here that could tell them apart. Depth leads because it is
1832
+ * the one a whole branch of pointers points at.
1833
+ */
1834
+ function reportUnresolvedReferences(data) {
1835
+ if (!degradedReportingIsOn(config))
1836
+ return;
1837
+ const unresolvedCount = countUnresolvedReferences(data.dataSources);
1838
+ if (unresolvedCount === 0)
1839
+ return;
1840
+ reportDegraded({
1841
+ code: DegradedCode.REFERENCES_UNRESOLVED,
1842
+ headline: `${unresolvedCount} ` +
1843
+ `${unresolvedCount === 1 ? "reference" : "references"} came back ` +
1844
+ "as pointers rather than entries, so anything bound past them has " +
1845
+ "nothing to show.",
1846
+ causes: [
1847
+ {
1848
+ cause: "This composition nests references deeper than " +
1849
+ `${INCLUDE_DEPTH_COUNT} levels, which is as far as one request follows them.`,
1850
+ fix: "Bind the entries further down directly, or flatten the nesting.",
1851
+ },
1852
+ {
1853
+ cause: "A referenced entry was deleted after something pointed at it.",
1854
+ fix: "Re-point those references, or remove the elements that read them.",
1855
+ },
1856
+ ],
1857
+ findings: { unresolvedCount, includeDepth: INCLUDE_DEPTH_COUNT },
1858
+ }, config);
1859
+ }
1860
+ /**
1861
+ * Says which bound entries did not arrive.
1862
+ *
1863
+ * Silent when every entry came back, which is the ordinary case — the report
1864
+ * exists for the batch that quietly returns fewer rows than it was asked for,
1865
+ * because from the page that is indistinguishable from an element nobody ever
1866
+ * bound.
1867
+ */
1868
+ function reportMissingEntries(contentTypeUid, requestedUids, missingUids) {
1869
+ if (missingUids.length === 0)
1870
+ return;
1871
+ reportDegraded({
1872
+ code: DegradedCode.FEWER_ENTRIES_THAN_REQUESTED,
1873
+ headline: `Asked "${contentTypeUid}" for ${requestedUids.length} ` +
1874
+ `${requestedUids.length === 1 ? "entry" : "entries"} and got ` +
1875
+ `${requestedUids.length - missingUids.length}. ` +
1876
+ `Missing: ${missingUids.join(", ")}.`,
1877
+ causes: [
1878
+ {
1879
+ cause: "The missing entries are not published to this environment.",
1880
+ fix: "Publish them, or check which environment this site reads.",
1881
+ },
1882
+ {
1883
+ cause: "They were deleted after something was bound to them.",
1884
+ fix: "Re-point those bindings, or remove the elements that read them.",
1885
+ },
1886
+ ],
1887
+ findings: {
1888
+ contentTypeUid,
1889
+ requestedCount: requestedUids.length,
1890
+ returnedCount: requestedUids.length - missingUids.length,
1891
+ missingUids,
1892
+ },
1893
+ }, config);
1894
+ }
1647
1895
  async function resolveStaticData(staticBindingQueries, staticBindingOnlyQueries, data, options = {}, searchParams) {
1648
1896
  const { variantAlias, locale } = options;
1649
1897
  const isInsideEditor = isEditorFetch(searchParams);
@@ -1688,7 +1936,7 @@ function generateSdk(userConfig) {
1688
1936
  return chunk(entryUids, STATIC_ENTRY_BATCH_SIZE).map((uids) => ({
1689
1937
  ct_uid: _content_type_uid,
1690
1938
  uids,
1691
- promise: config.stackSdk
1939
+ promise: requireStack(config)
1692
1940
  .ctQuery(_content_type_uid, {
1693
1941
  only: onlyQuery,
1694
1942
  references,
@@ -1711,18 +1959,15 @@ function generateSdk(userConfig) {
1711
1959
  addEditableTags(entry, ct_uid, true, entry?.locale || "en-us");
1712
1960
  }
1713
1961
  }
1714
- if (process.env.NODE_ENV === "development") {
1715
- const returnedUids = new Set(entries.map((entry) => entry.uid));
1716
- const missingUids = uids.filter((entry_uid) => !returnedUids.has(entry_uid));
1717
- if (missingUids.length) {
1718
- console.log(`Static entries missing from ${ct_uid} response: ${missingUids.join(", ")}`);
1719
- }
1720
- }
1962
+ const returnedUids = new Set(entries.map((entry) => entry.uid));
1963
+ reportMissingEntries(ct_uid, uids, uids.filter((entry_uid) => !returnedUids.has(entry_uid)));
1721
1964
  }
1722
1965
  else {
1723
- if (process.env.NODE_ENV === "development") {
1724
- console.log("Unhandled message case");
1725
- }
1966
+ // The batch never answered, so every entry in it is missing. The
1967
+ // request's own failure belongs to the diagnosis of a failed fetch;
1968
+ // what is reported here is the consequence the author can see, which
1969
+ // is that the elements bound to these entries have nothing to show.
1970
+ reportMissingEntries(ct_uid, uids, uids);
1726
1971
  }
1727
1972
  }
1728
1973
  }
@@ -1737,9 +1982,6 @@ function generateSdk(userConfig) {
1737
1982
  * Supports custom fetcher overrides (per-query > global > SDK default).
1738
1983
  */
1739
1984
  async function fetchTemplateEntry(fetchOptions, data, compositionEntry, compositionQueryOptions, urlPatternContext, searchParams) {
1740
- if (!config.stackSdk) {
1741
- return;
1742
- }
1743
1985
  const { connected_content_type, compositionQuery, includeQueries, onlyQueries: requestedOnlyQueries, } = fetchOptions;
1744
1986
  if (!connected_content_type) {
1745
1987
  return;
@@ -1809,35 +2051,39 @@ function generateSdk(userConfig) {
1809
2051
  if (!isInsideVB && !isInsideStudio) {
1810
2052
  queryOptions.only = onlyQueries;
1811
2053
  }
1812
- let dataQuery = config.stackSdk
2054
+ let dataQuery = requireStack(config)
1813
2055
  .ctQuery(connected_content_type, queryOptions)
1814
2056
  .limit(1);
1815
- dataQuery = config.stackSdk.where(dataQuery, "uid", resolvedOptions.templateEntryUid);
2057
+ dataQuery = requireStack(config).where(dataQuery, "uid", resolvedOptions.templateEntryUid);
1816
2058
  const response = await dataQuery.find().catch((err) => {
1817
- const { errorType, message } = classifyApiError(err);
1818
- const finalErrorType = errorType === ComposableStudioErrors.COMPOSITION_NOT_FOUND
1819
- ? ComposableStudioErrors.FETCHING_CONNECTED_DATA_FAILED
1820
- : errorType;
1821
- throw new ComposableStudioError(finalErrorType, finalErrorType ===
1822
- ComposableStudioErrors.FETCHING_CONNECTED_DATA_FAILED
1823
- ? getErrorMessage(ErrorMessageKey.FETCHING_CONNECTED_DATA_FAILED)
1824
- : message, {
1825
- options: fetchOptions,
1826
- response: err,
1827
- statusCode: err?.status || err?.statusCode,
1828
- errorCode: err?.error_code,
1829
- });
2059
+ // Classified by the same response rules as any other request. The
2060
+ // name it used to carry described the content it was after rather
2061
+ // than what went wrong, so a wrong api key and a delivery outage
2062
+ // both surfaced as "fetching connected data failed".
2063
+ const servedByNow = resolveServedBy(config.stackSdk?.livePreviewConfig);
2064
+ throw (classifyResponseError(err, config, { servedBy: servedByNow }) ??
2065
+ diagnoseUnreadableResponse(err, config, { servedBy: servedByNow }));
1830
2066
  });
1831
2067
  const entries = entriesFromResponse(response);
1832
2068
  if (!entries?.[0]) {
1833
- throw new ComposableStudioError(ComposableStudioErrors.PREVIEW_ENTRY_NOT_FOUND, getErrorMessage(ErrorMessageKey.PREVIEW_ENTRY_NOT_FOUND, {
1834
- contentType: connected_content_type,
1835
- }), {
1836
- contentType: connected_content_type,
1837
- hasStackSdk: !!config.stackSdk,
1838
- compositionQuery,
1839
- options: fetchOptions,
1840
- troubleshootingInfo: getTroubleshootingInfo(TroubleshootingInfoKey.PREVIEW_ENTRY_NOT_FOUND),
2069
+ throw createStudioError({
2070
+ code: StudioErrorCode.CONNECTED_ENTRY_NOT_FOUND,
2071
+ headline: `No entry was found for the content type "${connected_content_type}" this composition is connected to.`,
2072
+ causes: [
2073
+ {
2074
+ cause: `No entry of "${connected_content_type}" matches this composition.`,
2075
+ fix: "Create one, or point the composition at a content type that has entries.",
2076
+ },
2077
+ {
2078
+ cause: "The entry exists and is not published to this environment.",
2079
+ fix: "Publish it, or check which environment this site reads.",
2080
+ },
2081
+ ],
2082
+ context: buildStudioErrorContext(config, resolveServedBy(config.stackSdk?.livePreviewConfig)),
2083
+ findings: {
2084
+ contentTypeUid: connected_content_type,
2085
+ templateEntryUid: resolvedOptions?.templateEntryUid,
2086
+ },
1841
2087
  });
1842
2088
  }
1843
2089
  return entries[0];
@@ -1847,6 +2093,12 @@ function generateSdk(userConfig) {
1847
2093
  ? parseUrlMetadata(compositionEntry.url_metadata)
1848
2094
  : null;
1849
2095
  if (parsedMetadata && "url" in compositionQuery && compositionQuery.url) {
2096
+ // The only request in the SDK whose locale can come from the address
2097
+ // rather than the setup, which is what decides whose fault it is.
2098
+ let localeSent = {
2099
+ locale: undefined,
2100
+ source: "configuration",
2101
+ };
1850
2102
  // Metadata path: resolve using url_queries + extracted variables
1851
2103
  try {
1852
2104
  // Enhanced include queries with Studio Intelligence
@@ -1859,7 +2111,7 @@ function generateSdk(userConfig) {
1859
2111
  if (parsedMetadata.url_source ===
1860
2112
  COMPOSITION_PREVIEW_URL_SOURCES.CONTENT_TYPE_URL_PATTERN) {
1861
2113
  // content_type_url_pattern: Direct URL match (no pattern variables).
1862
- let directQuery = config.stackSdk
2114
+ let directQuery = requireStack(config)
1863
2115
  .ctQuery(connected_content_type, {
1864
2116
  references: allIncludeQueries,
1865
2117
  variantAlias: resolveVariant(),
@@ -1867,7 +2119,7 @@ function generateSdk(userConfig) {
1867
2119
  only: finalOnlyQueries,
1868
2120
  })
1869
2121
  .limit(1);
1870
- directQuery = config.stackSdk.where(directQuery, "url", compositionQuery.url);
2122
+ directQuery = requireStack(config).where(directQuery, "url", compositionQuery.url);
1871
2123
  const response = await directQuery.find();
1872
2124
  const entries = entriesFromResponse(response);
1873
2125
  if (entries?.[0]) {
@@ -1890,8 +2142,9 @@ function generateSdk(userConfig) {
1890
2142
  });
1891
2143
  if (matchResult.matched && matchResult.variables) {
1892
2144
  const patternMetadata = matchResult.variables.metadata;
2145
+ localeSent = resolveLocaleWithSource(patternMetadata.locale, resolvedOptions.locale, searchParams);
1893
2146
  // Build query using extracted variables and metadata
1894
- const templateQuery = resolveByUrlSource(config.stackSdk, parsedMetadata.url_source, compositionQuery, matchResult.variables, parsedMetadata.url_queries, connected_content_type, {
2147
+ const templateQuery = resolveByUrlSource(requireStack(config), parsedMetadata.url_source, compositionQuery, matchResult.variables, parsedMetadata.url_queries, connected_content_type, {
1895
2148
  references: allIncludeQueries,
1896
2149
  variantAlias: resolveVariant(),
1897
2150
  locale: resolveLocale(patternMetadata.locale, resolvedOptions.locale, searchParams),
@@ -1911,6 +2164,17 @@ function generateSdk(userConfig) {
1911
2164
  }
1912
2165
  }
1913
2166
  catch (metadataError) {
2167
+ // The legacy fallback below is for a pattern that did not resolve.
2168
+ // A setup or credential failure is not: retrying asks the same broken
2169
+ // connection the same question, then blames a missing page. So
2170
+ // anything we can diagnose is raised here instead of swallowed.
2171
+ const diagnosed = classifyResponseError(metadataError, config, {
2172
+ locale: localeSent.locale,
2173
+ localeSource: localeSent.source,
2174
+ url: compositionQuery.url,
2175
+ });
2176
+ if (diagnosed)
2177
+ throw diagnosed;
1914
2178
  console.warn("Metadata template resolution failed, falling back to legacy:", metadataError);
1915
2179
  }
1916
2180
  }
@@ -1932,38 +2196,42 @@ function generateSdk(userConfig) {
1932
2196
  if (!isInsideVB && !isInsideStudio) {
1933
2197
  queryOptions.only = onlyQueries;
1934
2198
  }
1935
- let dataQuery = config.stackSdk
2199
+ let dataQuery = requireStack(config)
1936
2200
  .ctQuery(connected_content_type, queryOptions)
1937
2201
  .limit(1);
1938
2202
  // Legacy URL matching (note: this is likely incorrect for patterned URLs as mentioned in plan)
1939
2203
  if ("url" in compositionQuery && compositionQuery.url) {
1940
- dataQuery = config.stackSdk.where(dataQuery, "url", compositionQuery.url);
2204
+ dataQuery = requireStack(config).where(dataQuery, "url", compositionQuery.url);
1941
2205
  }
1942
2206
  const response = await dataQuery.find().catch((err) => {
1943
- const { errorType, message } = classifyApiError(err);
1944
- const finalErrorType = errorType === ComposableStudioErrors.COMPOSITION_NOT_FOUND
1945
- ? ComposableStudioErrors.FETCHING_CONNECTED_DATA_FAILED
1946
- : errorType;
1947
- throw new ComposableStudioError(finalErrorType, finalErrorType ===
1948
- ComposableStudioErrors.FETCHING_CONNECTED_DATA_FAILED
1949
- ? getErrorMessage(ErrorMessageKey.FETCHING_CONNECTED_DATA_FAILED)
1950
- : message, {
1951
- options: fetchOptions,
1952
- response: err,
1953
- statusCode: err?.status || err?.statusCode,
1954
- errorCode: err?.error_code,
1955
- });
2207
+ // Classified by the same response rules as any other request. The
2208
+ // name it used to carry described the content it was after rather
2209
+ // than what went wrong, so a wrong api key and a delivery outage
2210
+ // both surfaced as "fetching connected data failed".
2211
+ const servedByNow = resolveServedBy(config.stackSdk?.livePreviewConfig);
2212
+ throw (classifyResponseError(err, config, { servedBy: servedByNow }) ??
2213
+ diagnoseUnreadableResponse(err, config, { servedBy: servedByNow }));
1956
2214
  });
1957
2215
  const entries = entriesFromResponse(response);
1958
2216
  if (!entries?.[0]) {
1959
- throw new ComposableStudioError(ComposableStudioErrors.PREVIEW_ENTRY_NOT_FOUND, getErrorMessage(ErrorMessageKey.PREVIEW_ENTRY_NOT_FOUND, {
1960
- contentType: connected_content_type,
1961
- }), {
1962
- contentType: connected_content_type,
1963
- hasStackSdk: !!config.stackSdk,
1964
- compositionQuery,
1965
- options: fetchOptions,
1966
- troubleshootingInfo: getTroubleshootingInfo(TroubleshootingInfoKey.PREVIEW_ENTRY_NOT_FOUND),
2217
+ throw createStudioError({
2218
+ code: StudioErrorCode.CONNECTED_ENTRY_NOT_FOUND,
2219
+ headline: `No entry was found for the content type "${connected_content_type}" this composition is connected to.`,
2220
+ causes: [
2221
+ {
2222
+ cause: `No entry of "${connected_content_type}" matches this composition.`,
2223
+ fix: "Create one, or point the composition at a content type that has entries.",
2224
+ },
2225
+ {
2226
+ cause: "The entry exists and is not published to this environment.",
2227
+ fix: "Publish it, or check which environment this site reads.",
2228
+ },
2229
+ ],
2230
+ context: buildStudioErrorContext(config, resolveServedBy(config.stackSdk?.livePreviewConfig)),
2231
+ findings: {
2232
+ contentTypeUid: connected_content_type,
2233
+ templateEntryUid: resolvedOptions?.templateEntryUid,
2234
+ },
1967
2235
  });
1968
2236
  }
1969
2237
  return entries[0];
@@ -1978,22 +2246,54 @@ function generateSdk(userConfig) {
1978
2246
  options: resolvedOptions,
1979
2247
  includeReferences: includeQueries,
1980
2248
  only: isInsideStudio || isInsideVB ? [] : onlyQueries,
1981
- stackSdk: config.stackSdk.sdk,
2249
+ stackSdk: config.stackSdk?.sdk,
1982
2250
  defaultFetch: defaultImpl,
1983
2251
  });
1984
2252
  if (!entry) {
1985
- throw new ComposableStudioError(ComposableStudioErrors.PREVIEW_ENTRY_NOT_FOUND, getErrorMessage(ErrorMessageKey.PREVIEW_ENTRY_NOT_FOUND, {
1986
- contentType: connected_content_type,
1987
- }));
2253
+ throw createStudioError({
2254
+ code: StudioErrorCode.CONNECTED_ENTRY_NOT_FOUND,
2255
+ headline: `No entry was found for the content type "${connected_content_type}" this composition is connected to.`,
2256
+ causes: [
2257
+ {
2258
+ cause: `No entry of "${connected_content_type}" matches this composition.`,
2259
+ fix: "Create one, or point the composition at a content type that has entries.",
2260
+ },
2261
+ {
2262
+ cause: "The entry exists and is not published to this environment.",
2263
+ fix: "Publish it, or check which environment this site reads.",
2264
+ },
2265
+ ],
2266
+ context: buildStudioErrorContext(config, resolveServedBy(config.stackSdk?.livePreviewConfig)),
2267
+ findings: {
2268
+ contentTypeUid: connected_content_type,
2269
+ templateEntryUid: resolvedOptions?.templateEntryUid,
2270
+ },
2271
+ });
1988
2272
  }
1989
2273
  }
1990
2274
  else {
1991
2275
  entry = await defaultImpl();
1992
2276
  // Check if defaultImpl returned empty/null entry (e.g., empty entry list from API)
1993
2277
  if (!entry) {
1994
- throw new ComposableStudioError(ComposableStudioErrors.PREVIEW_ENTRY_NOT_FOUND, getErrorMessage(ErrorMessageKey.PREVIEW_ENTRY_NOT_FOUND, {
1995
- contentType: connected_content_type,
1996
- }));
2278
+ throw createStudioError({
2279
+ code: StudioErrorCode.CONNECTED_ENTRY_NOT_FOUND,
2280
+ headline: `No entry was found for the content type "${connected_content_type}" this composition is connected to.`,
2281
+ causes: [
2282
+ {
2283
+ cause: `No entry of "${connected_content_type}" matches this composition.`,
2284
+ fix: "Create one, or point the composition at a content type that has entries.",
2285
+ },
2286
+ {
2287
+ cause: "The entry exists and is not published to this environment.",
2288
+ fix: "Publish it, or check which environment this site reads.",
2289
+ },
2290
+ ],
2291
+ context: buildStudioErrorContext(config, resolveServedBy(config.stackSdk?.livePreviewConfig)),
2292
+ findings: {
2293
+ contentTypeUid: connected_content_type,
2294
+ templateEntryUid: resolvedOptions?.templateEntryUid,
2295
+ },
2296
+ });
1997
2297
  }
1998
2298
  }
1999
2299
  if (config.cslp.appendTags) {
@@ -2047,42 +2347,69 @@ function generateSdk(userConfig) {
2047
2347
  })
2048
2348
  .filter((p) => p.length > 0)),
2049
2349
  ];
2050
- // Static entries (contentstack DS) → extendQuery[ctUid].includeReferences
2350
+ // `extendQuery` carries only what the consuming app passes, and that option
2351
+ // is deprecated: references are ticked in Studio and saved with the
2352
+ // composition. The saved sets are routed to the one request each belongs to
2353
+ // instead — the template set to the template entry, a pinned entry's set to
2354
+ // that entry. Pushed through `extendQuery` they applied per CONTENT TYPE:
2355
+ // onto the template request whenever a pinned entry shared its type, and
2356
+ // never onto a pinned entry the page does not bind directly (a section's
2357
+ // Section data root), which is where they were needed.
2358
+ warnIfExtendQueryPassed(options?.extendQuery);
2051
2359
  const csDS = rawDataSources.find((ds) => ds.uid === DATA_SOURCES.CONTENTSTACK);
2052
- if (csDS?.resolvedReferences && Array.isArray(csDS.data)) {
2053
- for (const entry of csDS.data) {
2054
- const raw = csDS.resolvedReferences[entry.uid] ?? [];
2055
- const paths = sanitizeResolvedPaths(raw);
2360
+ // Each pinned entry's saved set, keyed `<ct>:<uid>` — the page's own pinned
2361
+ // entries and every section's.
2362
+ const savedByPinnedEntry = new Map();
2363
+ const collectPinnedSaved = (dataSources) => {
2364
+ const ds = dataSources.find((d) => d?.uid === DATA_SOURCES.CONTENTSTACK);
2365
+ if (!ds?.resolvedReferences || !Array.isArray(ds.data))
2366
+ return;
2367
+ for (const entry of ds.data) {
2368
+ if (!entry?.uid || !entry?._content_type_uid)
2369
+ continue;
2370
+ const paths = sanitizeResolvedPaths(ds.resolvedReferences[entry.uid] ?? []);
2056
2371
  if (!paths.length)
2057
2372
  continue;
2058
- const ct = entry._content_type_uid;
2059
- if (!extendQuery[ct])
2060
- extendQuery[ct] = { includeReferences: [] };
2061
- extendQuery[ct].includeReferences = [
2062
- ...new Set([...(extendQuery[ct].includeReferences ?? []), ...paths]),
2063
- ];
2373
+ const key = `${entry._content_type_uid}:${entry.uid}`;
2374
+ savedByPinnedEntry.set(key, [
2375
+ ...new Set([...(savedByPinnedEntry.get(key) ?? []), ...paths]),
2376
+ ]);
2064
2377
  }
2378
+ };
2379
+ collectPinnedSaved(rawDataSources);
2380
+ for (const section of sectionEntries) {
2381
+ collectPinnedSaved(parseDataSourceList(section.data_sources));
2065
2382
  }
2066
- // Template entry (contentstackPreview DS) → extendQuery[connectedContentTypeUid].includeReferences
2067
- // Now safe to inject because sanitizeResolvedPaths filters out picker-tree
2068
- // tracking paths (pure numeric indexes) before they reach the CDA query.
2069
2383
  const connectedContentTypeUid = compositionEntry.connected_content_type || "";
2070
2384
  const previewDS = rawDataSources.find((ds) => ds.uid === DATA_SOURCES.TEMPLATE);
2071
- if (previewDS?.resolvedReferences && connectedContentTypeUid) {
2072
- const previewPaths = sanitizeResolvedPaths(Object.values(previewDS.resolvedReferences).flat());
2073
- if (previewPaths.length) {
2074
- if (!extendQuery[connectedContentTypeUid])
2075
- extendQuery[connectedContentTypeUid] = { includeReferences: [] };
2076
- extendQuery[connectedContentTypeUid].includeReferences = [
2077
- ...new Set([
2078
- ...(extendQuery[connectedContentTypeUid].includeReferences ?? []),
2079
- ...previewPaths,
2080
- ]),
2081
- ];
2082
- }
2083
- }
2385
+ // The template entry's saved set, for the template request only. Every
2386
+ // owner key is read — ticks live under their own keys beside the save's.
2387
+ const templateSavedPaths = previewDS?.resolvedReferences && connectedContentTypeUid
2388
+ ? sanitizeResolvedPaths(Object.values(previewDS.resolvedReferences).flat())
2389
+ : [];
2084
2390
  const resolvedOptions = { ...options, extendQuery };
2085
- const { templateReferencesPath, templateOnlyKeys, contentstackEntriesReferencesPath, contentstackEntriesOnlyKeys, } = getEntriesQueries(compositionEntry, connectedContentTypeUid, resolvedOptions);
2391
+ // Whether this SDK adds include[] paths of its own on top of the set the
2392
+ // composition carries (ADR 0018).
2393
+ //
2394
+ // Decided per composition, not per app. A composition saved before the set
2395
+ // became authoritative may hold only the author's ticks — the save-time
2396
+ // derive did not exist until 2026-07-17 — so the SDK's own derivation is the
2397
+ // only thing fetching a reference that was bound but never ticked. Dropping
2398
+ // it there would render those sections blank, which is why the version is
2399
+ // read off the entry rather than assumed from the SDK being up to date.
2400
+ //
2401
+ // From that version on it speaks for EVERY fetch root. At save, Studio runs
2402
+ // `derivePlacementIncludePaths` — this SDK's own derivation — validates the
2403
+ // result against the schema, and persists it on the matching data source:
2404
+ // the template's paths on `template`, a pinned entry's under its uid, a
2405
+ // query's under the query uid. Each set is routed below to the one request
2406
+ // it belongs to, so nothing is left for the SDK to work out.
2407
+ //
2408
+ // `deriveIncludePaths` overrides in either direction for a consumer who
2409
+ // knows better than the marker does.
2410
+ const derivesIncludePaths = config.deriveIncludePaths ??
2411
+ !compositionCarriesCompleteIncludes(compositionEntry.schema_version);
2412
+ const { templateReferencesPath: uiAndPersistedReferencesPath, persistedReferencesPath, templateOnlyKeys, contentstackEntriesReferencesPath, contentstackEntriesOnlyKeys, } = getEntriesQueries(compositionEntry, connectedContentTypeUid, resolvedOptions);
2086
2413
  // When inside Studio, ensure ALL configured contentstack DS entries are in
2087
2414
  // contentstackEntriesReferencesPath — not just those with active bindings.
2088
2415
  // Entries without bindings are still shown in Studio's data picker and must
@@ -2199,13 +2526,19 @@ function generateSdk(userConfig) {
2199
2526
  // reference chain (W1 → W2 → …) fetches the full nested include depth.
2200
2527
  const sectionsByUid = new Map(sectionEntries.map((s) => [s.uid, s]));
2201
2528
  const pageUi = typeof compositionEntry.ui === "string"
2202
- ? decompressSpec(compositionEntry.ui)
2529
+ ? parseUI(compositionEntry.ui, compositionEntry.composable_uid)
2203
2530
  : compositionEntry.ui;
2204
2531
  const instanceBindings = collectSectionInstanceBindings(pageUi, sectionsByUid, connectedContentTypeUid);
2205
2532
  // The author's own modular-block choices, used below to drop the include[]
2206
2533
  // paths the Delivery API discards.
2207
2534
  const modularBlocks = indexModularBlocks(pageUi);
2208
- const mergedTemplateRefs = [...templateReferencesPath];
2535
+ const templateReferencesPath = derivesIncludePaths
2536
+ ? uiAndPersistedReferencesPath
2537
+ : persistedReferencesPath;
2538
+ const mergedTemplateRefs = [
2539
+ ...templateReferencesPath,
2540
+ ...templateSavedPaths,
2541
+ ];
2209
2542
  const mergedTemplateOnly = [...templateOnlyKeys];
2210
2543
  // Include paths for sections whose Section data names a document OTHER than the
2211
2544
  // page template entry (ADR 0017). Keyed by fetch root so each set flushes to
@@ -2264,9 +2597,11 @@ function generateSdk(userConfig) {
2264
2597
  : JSON.stringify(section.ui),
2265
2598
  };
2266
2599
  const sectionRefs = getEntriesQueries(sectionAsCompositionEntry, config.contentTypeUid, resolvedOptions);
2267
- // Section reference include paths: UI-derived (reference conditions) plus
2268
- // saved toggle paths from the SECTION's own data_sources[template].
2269
- const sectionTemplateRefPaths = new Set(sectionRefs.templateReferencesPath);
2600
+ // The SECTION's own saved paths, from its data_sources[template]. Stored
2601
+ // relative to the section's own scope, so they are composed onto where it
2602
+ // sits here — the one job that cannot leave the SDK, since only the host
2603
+ // knows the placement. Sent in both modes.
2604
+ const sectionTemplateRefPaths = new Set(sectionRefs.persistedReferencesPath);
2270
2605
  try {
2271
2606
  const sds = Array.isArray(section.data_sources)
2272
2607
  ? section.data_sources
@@ -2289,29 +2624,27 @@ function generateSdk(userConfig) {
2289
2624
  if (full)
2290
2625
  pushForFetchRoot(fetchRootKey, full);
2291
2626
  }
2292
- // Include + project EVERY cumulative hop of the composed prefix so each
2293
- // reference in the chain is fetched and the next hop is reachable, e.g.
2294
- // include[]=related_articles, include[]=related_articles.author
2627
+ // What the SDK works out on its own for this placement: the section's
2628
+ // reference-condition paths and each step of its position. From
2629
+ // COMPLETE_INCLUDES_FROM_SCHEMA_VERSION on, Studio has saved these on the
2630
+ // fetch root's data source (`derivePlacementIncludePaths`), so none are
2631
+ // added here.
2632
+ if (derivesIncludePaths) {
2633
+ for (const path of derivedIncludePathsForInstance(binding, sectionRefs.templateReferencesPath, modularBlocks)) {
2634
+ pushForFetchRoot(fetchRootKey, path);
2635
+ }
2636
+ }
2637
+ // Project every cumulative step of the composed prefix so the next step is
2638
+ // reachable in the response, e.g.
2295
2639
  // only[BASE][]=related_articles, only[related_articles][]=author
2640
+ // Wanted in both modes — it is what keeps a block or a referenced entry in
2641
+ // the response, independent of whether the step is sent as an include[].
2296
2642
  {
2297
2643
  let parent = "BASE";
2298
2644
  const acc = [];
2299
2645
  for (const seg of prefix) {
2300
2646
  acc.push(seg);
2301
2647
  const hop = acc.join(".");
2302
- // Most hops of a section's position are the field holding the blocks,
2303
- // or a block itself. The Delivery API ignores an include[] for those,
2304
- // so adding one only costs URL space. The only[] row below is still
2305
- // wanted either way — it is what keeps the block in the response.
2306
- //
2307
- // The block index is read off the PAGE UI, so it can only judge a hop
2308
- // inside the page template entry. A hop inside another document — a
2309
- // pinned entry or query the section is rooted at (ADR 0017) — is
2310
- // routed to that document's request unconditionally.
2311
- if (fetchRootKey !== TEMPLATE_FETCH_ROOT_KEY ||
2312
- !isModularBlockPath(hop, modularBlocks)) {
2313
- pushForFetchRoot(fetchRootKey, hop);
2314
- }
2315
2648
  // only[] is carried for the template fetch root only in v1 —
2316
2649
  // `MergedEntryNeed` has no projection slot, and an only[] union is
2317
2650
  // SUBTRACTIVE: several sections and the page can request the same
@@ -2361,7 +2694,7 @@ function generateSdk(userConfig) {
2361
2694
  continue;
2362
2695
  const prefix = composeSectionTemplatePrefix(binding.ancestorPrefix, binding.selectedField, binding.referenceCtUids);
2363
2696
  const sectionUi = typeof section.ui === "string"
2364
- ? decompressSpec(section.ui)
2697
+ ? parseUI(section.ui, section.composable_uid)
2365
2698
  : section.ui;
2366
2699
  mapSectionRepeaterPaths(sectionUi, prefix, repeaterPathMap);
2367
2700
  }
@@ -2407,15 +2740,23 @@ function generateSdk(userConfig) {
2407
2740
  // include paths per (ct_uid, entry_uid) across requesters — the page asks
2408
2741
  // for the entry with its own includes, the section adds more, they merge.
2409
2742
  //
2410
- // A `query:<dsUid>` key is not flushed here: query includes are assembled
2411
- // from `resolvedReferences` inside `resolveQueryData`, so a query-rooted
2412
- // section contributes through the persisted path (step 9) rather than this
2413
- // one. Logged rather than dropped silently.
2743
+ // A `query:<uid>` key is handed to `resolveQueryData`, which assembles each
2744
+ // query's include[] and unions these in under that query's uid. They were
2745
+ // dropped here before — a section rooted at a query item got neither its
2746
+ // saved paths nor the steps of its position, and its references came back
2747
+ // as stubs.
2748
+ const sectionQueryIncludes = {};
2414
2749
  for (const [key, paths] of refsByFetchRoot.entries()) {
2415
2750
  const entryRef = parseEntryFetchRootKey(key);
2416
2751
  if (!entryRef) {
2417
- if (process.env.NODE_ENV === "development") {
2418
- console.warn(`[studio] section include paths for fetch root "${key}" are not routed by the spec fetch; they must come from persisted resolvedReferences. Paths: ${paths.join(", ")}`);
2752
+ const queryUid = key.startsWith("query:") ? key.slice(6) : "";
2753
+ if (queryUid) {
2754
+ sectionQueryIncludes[queryUid] = [
2755
+ ...new Set([...(sectionQueryIncludes[queryUid] ?? []), ...paths]),
2756
+ ];
2757
+ }
2758
+ else if (process.env.NODE_ENV === "development") {
2759
+ console.warn(`[studio] section include paths for fetch root "${key}" name no document the spec fetch knows. Paths: ${paths.join(", ")}`);
2419
2760
  }
2420
2761
  continue;
2421
2762
  }
@@ -2433,6 +2774,22 @@ function generateSdk(userConfig) {
2433
2774
  mergedOnly[contentTypeUid][entryUid] = [];
2434
2775
  }
2435
2776
  }
2777
+ // Each pinned entry's saved set goes on that entry's own request — whether
2778
+ // the page binds the entry directly or only a section's Section data names
2779
+ // it. Applied to entries being fetched anyway; a saved set is never a reason
2780
+ // to fetch an entry nothing reads.
2781
+ for (const [key, saved] of savedByPinnedEntry) {
2782
+ const entryRef = parseEntryFetchRootKey(key);
2783
+ if (!entryRef)
2784
+ continue;
2785
+ const { contentTypeUid, entryUid } = entryRef;
2786
+ const existing = mergedRefs[contentTypeUid]?.[entryUid];
2787
+ if (!existing)
2788
+ continue;
2789
+ mergedRefs[contentTypeUid][entryUid] = [
2790
+ ...new Set([...existing, ...saved]),
2791
+ ];
2792
+ }
2436
2793
  // Sections, the page itself and the caller's own extra references have all
2437
2794
  // been merged by this point, so this is the first place we can tell whether
2438
2795
  // a path is just the start of a longer one. Drop those here, before the
@@ -2456,6 +2813,14 @@ function generateSdk(userConfig) {
2456
2813
  seenOnly.add(sig);
2457
2814
  return true;
2458
2815
  });
2816
+ // Captured here rather than after the awaits below. Live-preview state sits
2817
+ // on a process-wide client, so under concurrent server rendering a value
2818
+ // read once these have resolved can belong to somebody else's request — and
2819
+ // a diagnosis that names the wrong service is worse than none.
2820
+ const requestFacts = {
2821
+ servedBy: resolveServedBy(config.stackSdk?.livePreviewConfig),
2822
+ projection: dedupedTemplateOnly,
2823
+ };
2459
2824
  await Promise.all([
2460
2825
  fetchTemplateEntry({
2461
2826
  connected_content_type: templateContentTypeUid,
@@ -2472,8 +2837,11 @@ function generateSdk(userConfig) {
2472
2837
  variantAlias: pageVariantAlias,
2473
2838
  locale: pageLocale,
2474
2839
  sectionEntries,
2840
+ sectionQueryIncludes,
2475
2841
  }, searchParams),
2476
2842
  ]);
2843
+ reportUnresolvedReferences(data);
2844
+ reportBindingDefects(pageUi, data, requestFacts);
2477
2845
  // D7: the folded template entry (fetched once, above) also feeds the static
2478
2846
  // entry pool so contentstack-entry references to it resolve without the
2479
2847
  // second fetch we removed from mergedRefs.
@@ -2496,17 +2864,15 @@ function generateSdk(userConfig) {
2496
2864
  return data;
2497
2865
  }
2498
2866
  async function fetchSpec(queryOptions, options, skipComponentLoading = false, searchParams) {
2499
- if (!config.stackSdk) {
2500
- throw new ComposableStudioError(ComposableStudioErrors.STACK_SDK_NOT_AVAILABLE, getErrorMessage(ErrorMessageKey.STACK_SDK_NOT_AVAILABLE));
2501
- }
2867
+ requireStack(config);
2502
2868
  // Phase 1: Get Studio Intelligence if available (graceful fallback)
2503
2869
  const studioIntelligence = await StudioIntelligenceManager.getStudioIntelligence(options, config);
2504
2870
  // Phase 2: Enhance options with Studio Intelligence (preserves user preferences)
2505
2871
  const enhancedOptions = StudioIntelligenceManager.enhanceOptionsWithStudioIntelligence(options, studioIntelligence);
2506
2872
  // Phase 3: Fetch with enhanced context (preserves custom fetchers)
2507
- const { compositionEntry, urlResolution } = await fetchComposition(config, queryOptions, enhancedOptions, isEditorFetch(searchParams));
2873
+ const { compositionEntry, urlResolution, requestContext } = await fetchComposition(config, queryOptions, enhancedOptions, isEditorFetch(searchParams));
2508
2874
  const ui = typeof compositionEntry.ui === "string"
2509
- ? decompressSpec(compositionEntry.ui)
2875
+ ? parseUI(compositionEntry.ui, compositionEntry.composable_uid)
2510
2876
  : compositionEntry.ui;
2511
2877
  const sectionEntries = await getAllSectionCompositions(config, compositionEntry, enhancedOptions);
2512
2878
  const data = await fetchData(compositionEntry, queryOptions, enhancedOptions, Array.from(sectionEntries.values()), searchParams);
@@ -2543,32 +2909,11 @@ function generateSdk(userConfig) {
2543
2909
  });
2544
2910
  // Handle missing internal components (SDK import issue)
2545
2911
  if (missingBuiltInComponents.length > 0) {
2546
- const errorMessage = [
2547
- `[Composable Studio SDK] Internal components missing: ${missingBuiltInComponents.join(", ")}`,
2548
- "",
2549
- "Built-in components are auto-registered on first import of @contentstack/studio-react.",
2550
- "If you're seeing this, the package root was either not imported on this code path",
2551
- "(e.g. a server-only bundle that pulls a subpath but not the root) or was tree-shaken away.",
2552
- "",
2553
- "Fix: make sure the package root is imported at least once before fetchSpec runs:",
2554
- ' import "@contentstack/studio-react";',
2555
- ].join("\n");
2556
- throw new ComposableStudioError(ComposableStudioErrors.COMPONENT_NOT_FOUND, errorMessage);
2912
+ throw componentsNotRegistered(missingBuiltInComponents, true, config);
2557
2913
  }
2558
2914
  // Handle missing custom components (normal - user needs to register)
2559
2915
  if (missingCustomComponents.length > 0) {
2560
- const errorMessage = [
2561
- `[Composable Studio SDK] Custom components not registered: ${missingCustomComponents.join(", ")}`,
2562
- "",
2563
- "This error occurs when fetchSpec() is called before custom components are registered.",
2564
- "In SSR environments, ensure all registerComponent() calls complete before fetchSpec().",
2565
- "",
2566
- "Fix: Import your component registry module at the top of your server file:",
2567
- ' import "./components/registry"; // Register custom components',
2568
- " const spec = await fetchSpec({ ... }); // Now safe to use",
2569
- "",
2570
- ].join("\n");
2571
- throw new ComposableStudioError(ComposableStudioErrors.COMPONENT_NOT_FOUND, errorMessage);
2916
+ throw componentsNotRegistered(missingCustomComponents, false, config);
2572
2917
  }
2573
2918
  // Load the components
2574
2919
  try {
@@ -2586,6 +2931,7 @@ function generateSdk(userConfig) {
2586
2931
  sectionCompositions: Array.from(sectionEntries.values()),
2587
2932
  // Studio-only resolution diagnostics (URL metadata path); undefined otherwise.
2588
2933
  urlResolution,
2934
+ requestContext,
2589
2935
  config: {
2590
2936
  ...getLightConfig(),
2591
2937
  // Debug information for compatibility checking (type assertion for internal properties)
@@ -2604,14 +2950,12 @@ function generateSdk(userConfig) {
2604
2950
  * Runs in both SSR and CSR (plain async, not a hook).
2605
2951
  */
2606
2952
  async function fetchCompositionSpecOnly(queryOptions, options, skipComponentLoading = false) {
2607
- if (!config.stackSdk) {
2608
- throw new ComposableStudioError(ComposableStudioErrors.STACK_SDK_NOT_AVAILABLE, getErrorMessage(ErrorMessageKey.STACK_SDK_NOT_AVAILABLE));
2609
- }
2953
+ requireStack(config);
2610
2954
  const studioIntelligence = await StudioIntelligenceManager.getStudioIntelligence(options, config);
2611
2955
  const enhancedOptions = StudioIntelligenceManager.enhanceOptionsWithStudioIntelligence(options, studioIntelligence);
2612
- const { compositionEntry, urlResolution } = await fetchComposition(config, queryOptions, enhancedOptions, isEditorFetch());
2956
+ const { compositionEntry, urlResolution, requestContext } = await fetchComposition(config, queryOptions, enhancedOptions, isEditorFetch());
2613
2957
  const ui = typeof compositionEntry.ui === "string"
2614
- ? decompressSpec(compositionEntry.ui)
2958
+ ? parseUI(compositionEntry.ui, compositionEntry.composable_uid)
2615
2959
  : compositionEntry.ui;
2616
2960
  // Section composition entries are STRUCTURAL (their ui trees are needed to
2617
2961
  // render embedded section nodes and to compute section scoping) — keep them.
@@ -2630,6 +2974,7 @@ function generateSdk(userConfig) {
2630
2974
  compositionEntry,
2631
2975
  sectionCompositions: Array.from(sectionEntries.values()),
2632
2976
  urlResolution,
2977
+ requestContext,
2633
2978
  config: {
2634
2979
  ...getLightConfig(),
2635
2980
  _studioEnhanced: enhancedOptions._enhancementMode === "studio-aware",
@@ -2638,9 +2983,7 @@ function generateSdk(userConfig) {
2638
2983
  };
2639
2984
  }
2640
2985
  async function fetchMultipleSpecs(queries, options) {
2641
- if (!config.stackSdk) {
2642
- throw new ComposableStudioError(ComposableStudioErrors.STACK_SDK_NOT_AVAILABLE, getErrorMessage(ErrorMessageKey.STACK_SDK_NOT_AVAILABLE));
2643
- }
2986
+ requireStack(config);
2644
2987
  // Fetch all specs in parallel (skip individual component loading)
2645
2988
  const specs = await Promise.all(queries.map((query) => fetchSpec(query, options, true)));
2646
2989
  // In production mode, perform union analysis and load components once.
@@ -2680,33 +3023,11 @@ function generateSdk(userConfig) {
2680
3023
  });
2681
3024
  // Handle missing internal components (SDK import issue)
2682
3025
  if (missingBuiltInComponents.length > 0) {
2683
- const errorMessage = [
2684
- `[Composable Studio SDK] Internal components missing: ${missingBuiltInComponents.join(", ")}`,
2685
- "",
2686
- "Built-in components are auto-registered on first import of @contentstack/studio-react.",
2687
- "If you're seeing this, the package root was either not imported on this code path",
2688
- "(e.g. a server-only bundle that pulls a subpath but not the root) or was tree-shaken away.",
2689
- "",
2690
- "Fix: make sure the package root is imported at least once before fetchSpec runs:",
2691
- ' import "@contentstack/studio-react";',
2692
- ].join("\n");
2693
- throw new ComposableStudioError(ComposableStudioErrors.COMPONENT_NOT_FOUND, errorMessage);
3026
+ throw componentsNotRegistered(missingBuiltInComponents, true, config);
2694
3027
  }
2695
3028
  // Handle missing custom components (normal - user needs to register)
2696
3029
  if (missingCustomComponents.length > 0) {
2697
- const errorMessage = [
2698
- `[Composable Studio SDK] Custom components not registered: ${missingCustomComponents.join(", ")}`,
2699
- "",
2700
- "This error occurs when fetchMultipleSpecs() is called before custom components are registered.",
2701
- "In SSR environments, ensure all registerComponent() calls complete before fetchMultipleSpecs().",
2702
- "",
2703
- "Fix: Import your component registry module at the top of your server file:",
2704
- ' import "./components/registry"; // Register custom components',
2705
- " const specs = await fetchMultipleSpecs([...]); // Now safe to use",
2706
- "",
2707
- `Missing components: ${missingCustomComponents.join(", ")}`,
2708
- ].join("\n");
2709
- throw new ComposableStudioError(ComposableStudioErrors.COMPONENT_NOT_FOUND, errorMessage);
3030
+ throw componentsNotRegistered(missingCustomComponents, false, config);
2710
3031
  }
2711
3032
  // Load all unique components in parallel (deduplication happens automatically)
2712
3033
  try {
@@ -2723,11 +3044,21 @@ function generateSdk(userConfig) {
2723
3044
  * Reusable helper to fetch data from Contentstack
2724
3045
  * Now uses QueryExecutor internally to support full QuerySpec with filters, sorting, etc.
2725
3046
  *
3047
+ * An empty result is reported from in here rather than by the caller, and
3048
+ * that placement is the point: every path out of this function returns an
3049
+ * empty list, so a caller cannot tell a query that ran and matched nothing
3050
+ * from one that never ran at all. Saying "this data source returned no
3051
+ * entries" about a query that failed is the same mistake as calling a broken
3052
+ * request a missing page.
3053
+ *
2726
3054
  * @param querySpec - Full QuerySpec with filters, sorting, pagination, etc.
2727
3055
  * @param context - RuntimeContext for expression resolution (URL params, etc.)
3056
+ * @param dataSourceUid - The data source this query belongs to, named in the
3057
+ * report when it comes back empty. Optional because a caller that has no
3058
+ * name for it would rather have the query than the report.
2728
3059
  * @returns Promise with data array and count
2729
3060
  */
2730
- async function fetchContentstackData(querySpec, context = {}, options) {
3061
+ async function fetchContentstackData(querySpec, context = {}, options, dataSourceUid) {
2731
3062
  if (!config.stackSdk) {
2732
3063
  return { entries: [], count: 0 };
2733
3064
  }
@@ -2741,6 +3072,21 @@ function generateSdk(userConfig) {
2741
3072
  const result = await executor.execute(querySpec, 1, context, options);
2742
3073
  const entries = result.entries || [];
2743
3074
  const count = result.count || 0;
3075
+ if (entries.length === 0 && dataSourceUid) {
3076
+ // Carries no causes on purpose. A query matching nothing is not a
3077
+ // failure by any measure available here — the filters may be right and
3078
+ // the content simply not written yet — so naming a fix would invent a
3079
+ // problem. It is reported because "why is my list empty" is the
3080
+ // question this whole group exists to answer.
3081
+ reportDegraded({
3082
+ code: DegradedCode.QUERY_RETURNED_NO_ROWS,
3083
+ headline: `The data source "${dataSourceUid}" returned no entries.`,
3084
+ findings: {
3085
+ dataSourceUid,
3086
+ contentTypeUid: querySpec.contentType,
3087
+ },
3088
+ }, config);
3089
+ }
2744
3090
  // Add editable tags (CSLP)
2745
3091
  if (config.cslp.appendTags && Array.isArray(entries)) {
2746
3092
  entries.forEach((entry) => {
@@ -2752,9 +3098,28 @@ function generateSdk(userConfig) {
2752
3098
  count: count,
2753
3099
  };
2754
3100
  }
2755
- catch (error) {
2756
- if (process.env.NODE_ENV === "development") {
2757
- console.error("Error resolving query data:", error);
3101
+ catch {
3102
+ // The same empty list as a query that matched nothing, and a completely
3103
+ // different thing to tell somebody. Without this the page shows an empty
3104
+ // list, the console says nothing, and the only available reading is that
3105
+ // the filters are wrong — which sends an author to edit a data source
3106
+ // that was never the problem.
3107
+ if (dataSourceUid) {
3108
+ reportDegraded({
3109
+ code: DegradedCode.QUERY_REQUEST_FAILED,
3110
+ headline: `The data source "${dataSourceUid}" could not be fetched, so ` +
3111
+ "its list is empty.",
3112
+ causes: [
3113
+ {
3114
+ cause: "The request did not reach Contentstack, or it failed.",
3115
+ fix: "Retry the page. Nothing about the data source's filters is involved.",
3116
+ },
3117
+ ],
3118
+ findings: {
3119
+ dataSourceUid,
3120
+ contentTypeUid: querySpec.contentType,
3121
+ },
3122
+ }, config);
2758
3123
  }
2759
3124
  return { entries: [], count: 0 };
2760
3125
  }
@@ -2769,10 +3134,26 @@ function generateSdk(userConfig) {
2769
3134
  ? parsed
2770
3135
  : Object.values(parsed);
2771
3136
  }
2772
- catch (error) {
2773
- if (process.env.NODE_ENV === "development") {
2774
- console.error("Error parsing data sources JSON:", error);
2775
- }
3137
+ catch {
3138
+ // Not fatal, and deliberately so: the layout rendered, and taking the
3139
+ // page down over its queries would turn a partly-empty page into no
3140
+ // page at all. The bytes never travel — a report is built to be pasted
3141
+ // somewhere public and this is the customer's content.
3142
+ reportDegraded({
3143
+ code: DegradedCode.DATA_SOURCES_UNREADABLE,
3144
+ headline: `The stored data sources for ${compositionEntry.composable_uid} ` +
3145
+ "could not be read, so none of its queries ran.",
3146
+ causes: [
3147
+ {
3148
+ cause: "The stored data sources are damaged.",
3149
+ fix: "Nothing in this project will fix it — report it.",
3150
+ },
3151
+ ],
3152
+ findings: {
3153
+ subject: compositionEntry.composable_uid,
3154
+ byteLength: compositionEntry.data_sources.length,
3155
+ },
3156
+ }, config);
2776
3157
  }
2777
3158
  }
2778
3159
  const queriesDS = pageDataSources.find((ds) => ds.uid === DATA_SOURCES.QUERY || ds.id === DATA_SOURCES.QUERY);
@@ -2830,6 +3211,11 @@ function generateSdk(userConfig) {
2830
3211
  /* per-section JSON failure already logged in collect-data-needs */
2831
3212
  }
2832
3213
  }
3214
+ for (const [queryUid, paths] of Object.entries(options?.sectionQueryIncludes ?? {})) {
3215
+ queriesResolvedRefs[queryUid] = [
3216
+ ...new Set([...(queriesResolvedRefs[queryUid] ?? []), ...paths]),
3217
+ ];
3218
+ }
2833
3219
  const dedupedQueries = Array.from(queryDeduper.values());
2834
3220
  // Nothing to resolve (neither page nor any section declared a query).
2835
3221
  if (dedupedQueries.length === 0)
@@ -2910,7 +3296,7 @@ function generateSdk(userConfig) {
2910
3296
  },
2911
3297
  }
2912
3298
  : spec;
2913
- const result = await fetchContentstackData(mergedSpec, context, options);
3299
+ const result = await fetchContentstackData(mergedSpec, context, options, uid);
2914
3300
  // Fan out result to every uid that resolved to this query spec
2915
3301
  // (page's data_source uid + each section instance's data_source uid).
2916
3302
  const hash = stableHashQuery(spec);
@@ -2986,9 +3372,7 @@ function generateSdk(userConfig) {
2986
3372
  * options object.
2987
3373
  */
2988
3374
  fetchCompositionData: async (queryOptions, options) => {
2989
- if (!config.stackSdk) {
2990
- throw new ComposableStudioError(ComposableStudioErrors.STACK_SDK_NOT_AVAILABLE, getErrorMessage(ErrorMessageKey.STACK_SDK_NOT_AVAILABLE));
2991
- }
3375
+ requireStack(config);
2992
3376
  const { searchQuery, ...compositionQueryInput } = queryOptions;
2993
3377
  const compositionQuery = convertCompositionQueryInputToCompositionQuery(compositionQueryInput);
2994
3378
  const urlSearchParam = new URLSearchParams(searchQuery);
@@ -3006,7 +3390,7 @@ function generateSdk(userConfig) {
3006
3390
  const previewHash = urlSearchParam.get(COMPOSABLE_STUDIO_QUERY_PARAM.PREVIEW_HASH) ||
3007
3391
  urlSearchParam.get(COMPOSABLE_STUDIO_QUERY_PARAM.LIVE_PREVIEW_HASH);
3008
3392
  if (previewHash) {
3009
- config.stackSdk.livePreviewQuery(previewHash);
3393
+ requireStack(config).livePreviewQuery(previewHash);
3010
3394
  }
3011
3395
  const rendererModeUtil = new RendererModeUtil(urlSearchParam);
3012
3396
  // P4.2 (ADR-0005): always fetch and return the spec — uniformly for the
@@ -3038,6 +3422,10 @@ function generateSdk(userConfig) {
3038
3422
  spec,
3039
3423
  hasSpec: !!spec.compositionEntry,
3040
3424
  hasTemplate: !!spec.data.dataSources[DATA_SOURCES.TEMPLATE],
3425
+ // Normalised here so a host does not have to: the CMS stores "no
3426
+ // connected content type" as an empty string on some entries and as an
3427
+ // absent field on others, and both mean freeform.
3428
+ connectedContentTypeUid: spec.compositionEntry?.connected_content_type || null,
3041
3429
  fetchOptions: {
3042
3430
  // TODO: @Nilesh - see if we can remove this as this config is already available in the spec.
3043
3431
  config: getLightConfig(),
@@ -3063,9 +3451,7 @@ function generateSdk(userConfig) {
3063
3451
  * @returns `Promise<StudioSpec>` — the composition spec with empty data.
3064
3452
  */
3065
3453
  fetchComposition: async (queryOptions, options) => {
3066
- if (!config.stackSdk) {
3067
- throw new ComposableStudioError(ComposableStudioErrors.STACK_SDK_NOT_AVAILABLE, getErrorMessage(ErrorMessageKey.STACK_SDK_NOT_AVAILABLE));
3068
- }
3454
+ requireStack(config);
3069
3455
  const { searchQuery, ...compositionQueryInput } = queryOptions;
3070
3456
  const compositionQuery = convertCompositionQueryInputToCompositionQuery(compositionQueryInput);
3071
3457
  const urlSearchParam = new URLSearchParams(searchQuery);
@@ -3074,7 +3460,7 @@ function generateSdk(userConfig) {
3074
3460
  const previewHash = urlSearchParam.get(COMPOSABLE_STUDIO_QUERY_PARAM.PREVIEW_HASH) ||
3075
3461
  urlSearchParam.get(COMPOSABLE_STUDIO_QUERY_PARAM.LIVE_PREVIEW_HASH);
3076
3462
  if (previewHash) {
3077
- config.stackSdk.livePreviewQuery(previewHash);
3463
+ requireStack(config).livePreviewQuery(previewHash);
3078
3464
  }
3079
3465
  return fetchCompositionSpecOnly(compositionQuery, options);
3080
3466
  },
@@ -3123,9 +3509,37 @@ function countFromResponse(response) {
3123
3509
  const count = response?.count;
3124
3510
  return typeof count === "number" ? count : undefined;
3125
3511
  }
3512
+ /**
3513
+ * Raises unless the reply is one we can actually read entries out of.
3514
+ *
3515
+ * The delivery client hands back either an array or an object carrying `entries`.
3516
+ * Anything else answered on the address we asked without being Contentstack, and
3517
+ * the absent entries list must not be mistaken for an empty project.
3518
+ */
3519
+ function assertReadableEntries(response, config) {
3520
+ const readable = Array.isArray(response) ||
3521
+ (typeof response === "object" &&
3522
+ response !== null &&
3523
+ Array.isArray(response.entries));
3524
+ if (readable)
3525
+ return;
3526
+ const host = config.stackSdk?.host;
3527
+ throw createStudioError({
3528
+ code: StudioErrorCode.RESPONSE_UNUSABLE,
3529
+ headline: `The reply from ${host ?? "Contentstack"} is not a usable delivery response.`,
3530
+ causes: [
3531
+ {
3532
+ cause: "Something answered on that address without being Contentstack.",
3533
+ fix: "Check anything sitting between this app and Contentstack — a proxy, a gateway, an offline page. If there is nothing, report it.",
3534
+ },
3535
+ ],
3536
+ context: buildStudioErrorContext(config),
3537
+ findings: { host },
3538
+ });
3539
+ }
3126
3540
  async function fetchAllPageCompositions(config, locale) {
3127
3541
  const fetchPage = (page, includeCount) => {
3128
- let query = config.stackSdk
3542
+ let query = requireStack(config)
3129
3543
  .ctQuery(config.contentTypeUid, {
3130
3544
  locale: locale || config.locale,
3131
3545
  query: { ...getPageLinkedPlacementFilter() },
@@ -3146,6 +3560,10 @@ async function fetchAllPageCompositions(config, locale) {
3146
3560
  // Page 0 carries include_count so the remaining pages can be fetched in one
3147
3561
  // parallel wave instead of one serial round-trip per page.
3148
3562
  const firstRes = await fetchPage(0, true);
3563
+ // A reply we cannot read is not a reply that said "nothing". Absent entries
3564
+ // here would read as an empty project and 404 every page at once, so the shape
3565
+ // is checked before it is believed.
3566
+ assertReadableEntries(firstRes, config);
3149
3567
  const first = entriesFromResponse(firstRes);
3150
3568
  if (first.length < CANDIDATE_PAGE_SIZE) {
3151
3569
  return { entries: first, truncated: false };
@@ -3185,6 +3603,93 @@ async function fetchAllPageCompositions(config, locale) {
3185
3603
  * Returns the winner's composable_uid (or undefined if nothing owns the URL) and
3186
3604
  * the per-candidate ownership outcome for diagnostics.
3187
3605
  */
3606
+ /**
3607
+ * The publishing line, and only when published content is what answered.
3608
+ *
3609
+ * On the preview service an unpublished composition is served anyway, so telling
3610
+ * that reader to check publishing sends them to rule out something that cannot be
3611
+ * the cause. `servedBy` is what makes the difference knowable.
3612
+ */
3613
+ function unpublishedCause(servedBy, config, subject) {
3614
+ if (servedBy !== "cdn")
3615
+ return [];
3616
+ const environment = config.stackSdk?.environment;
3617
+ return [
3618
+ {
3619
+ cause: environment
3620
+ ? `${subject} may not be published to "${environment}".`
3621
+ : `${subject} may not be published to the environment this site queries.`,
3622
+ fix: "Check its publish status in Contentstack.",
3623
+ },
3624
+ ];
3625
+ }
3626
+ /**
3627
+ * Why no composition matched an address.
3628
+ *
3629
+ * Deliberately never says "create an entry". On the legacy connected-entry path
3630
+ * the lookup compares an entry's address against the composition's raw pattern,
3631
+ * which for a patterned composition can never match — so the entry an author
3632
+ * would be told to create is one they already have.
3633
+ */
3634
+ function notFoundByUrlCauses(url, servedBy, config) {
3635
+ return [
3636
+ {
3637
+ cause: `The address "${url}" may not be the one the composition is set up for.`,
3638
+ fix: "Compare it with the composition's URL in Studio.",
3639
+ },
3640
+ {
3641
+ cause: "The composition's URL pattern may not produce this address.",
3642
+ fix: "Open the pattern in Studio and check it against the address.",
3643
+ },
3644
+ ...unpublishedCause(servedBy, config, "The composition"),
3645
+ ];
3646
+ }
3647
+ /**
3648
+ * Why an address that several compositions claim has nothing behind it.
3649
+ *
3650
+ * Never says "create an entry". On the legacy connected-entry path the lookup
3651
+ * compares an entry's address against the composition's raw pattern, which for a
3652
+ * patterned composition can never match — so the entry an author would be told to
3653
+ * create is one they may already have.
3654
+ */
3655
+ function matchedNoEntryCauses(considered, servedBy, config) {
3656
+ const contentTypes = Array.from(new Set(considered
3657
+ .map((row) => row.connected_content_type)
3658
+ .filter((uid) => Boolean(uid))));
3659
+ return [
3660
+ {
3661
+ cause: contentTypes.length
3662
+ ? `No entry in ${contentTypes.map((uid) => `"${uid}"`).join(" or ")} has this address.`
3663
+ : "No entry behind these compositions has this address.",
3664
+ fix: "Open the composition in Studio and check the entry it reads from.",
3665
+ },
3666
+ ...unpublishedCause(servedBy, config, "The entry"),
3667
+ {
3668
+ cause: "A composition may be connected to the wrong content type.",
3669
+ fix: "Check the connected content type on each of them in Studio.",
3670
+ },
3671
+ ];
3672
+ }
3673
+ /** Why a composition uid found nothing. Never claims the composition does not exist. */
3674
+ function uidNotFoundCauses(servedBy, config) {
3675
+ return [
3676
+ {
3677
+ cause: "The uid may not be the one this composition has.",
3678
+ fix: "You can find it on the composition in Studio.",
3679
+ },
3680
+ ...unpublishedCause(servedBy, config, "The composition"),
3681
+ ];
3682
+ }
3683
+ /** Why a content type has no composition connected to it. */
3684
+ function templateContentTypeCauses(contentTypeUid, servedBy, config) {
3685
+ return [
3686
+ {
3687
+ cause: `No composition in this project is connected to "${contentTypeUid}".`,
3688
+ fix: "Connect one in Studio, or ask for a different content type.",
3689
+ },
3690
+ ...unpublishedCause(servedBy, config, "A composition that uses it"),
3691
+ ];
3692
+ }
3188
3693
  async function resolveUrlWinner(config, requestUrl, ranking, candidatesByUid, locale) {
3189
3694
  const topTier = ranking.matches;
3190
3695
  // Happy path — a single (or no) top-tier candidate needs no probe.
@@ -3203,10 +3708,10 @@ async function resolveUrlWinner(config, requestUrl, ranking, candidatesByUid, lo
3203
3708
  // content type) is unprobeable.
3204
3709
  const meta = parseUrlMetadata(lightweight?.url_metadata);
3205
3710
  if (!m.variables || !m.connected_content_type) {
3206
- return { uid: m.composable_uid, owns: false };
3711
+ return { uid: m.composable_uid, owns: false, answered: true };
3207
3712
  }
3208
3713
  try {
3209
- const probeQuery = resolveByUrlSource(config.stackSdk, meta.url_source, { url: requestUrl }, m.variables, meta.url_queries, m.connected_content_type, {
3714
+ const probeQuery = resolveByUrlSource(requireStack(config), meta.url_source, { url: requestUrl }, m.variables, meta.url_queries, m.connected_content_type, {
3210
3715
  references: [],
3211
3716
  only: [["BASE", "uid"]],
3212
3717
  locale: m.variables.metadata.locale || locale || config.locale,
@@ -3219,13 +3724,35 @@ async function resolveUrlWinner(config, requestUrl, ranking, candidatesByUid, lo
3219
3724
  return {
3220
3725
  uid: m.composable_uid,
3221
3726
  owns: entriesFromResponse(res).length > 0,
3727
+ answered: true,
3222
3728
  };
3223
3729
  }
3224
- catch {
3225
- // A failed probe counts as non-owning; another candidate may still own it.
3226
- return { uid: m.composable_uid, owns: false };
3730
+ catch (probeError) {
3731
+ // A failed probe counts as non-owning so the others still get their say.
3732
+ // `answered` is what stops that being mistaken for evidence: a check we
3733
+ // could not make says nothing, and if none of them could be made there is
3734
+ // no absence to report.
3735
+ if (isSetupFault(probeError))
3736
+ throw probeError;
3737
+ return { uid: m.composable_uid, owns: false, answered: false };
3227
3738
  }
3228
3739
  }));
3740
+ // Every check failing is an outage, not an answer. Reporting "no candidate owns
3741
+ // this address" here would 404 a page that exists.
3742
+ if (probeOutcomes.length > 0 && probeOutcomes.every((r) => !r.answered)) {
3743
+ throw createStudioError({
3744
+ code: StudioErrorCode.URL_OWNERSHIP_PROBE_FAILED,
3745
+ headline: `Could not check which composition owns "${requestUrl}" — every ownership check failed.`,
3746
+ causes: [
3747
+ {
3748
+ cause: "The checks against Contentstack did not complete.",
3749
+ fix: "Try again shortly; if it persists, report it.",
3750
+ },
3751
+ ],
3752
+ context: buildStudioErrorContext(config),
3753
+ findings: { url: requestUrl, probeCount: probeOutcomes.length },
3754
+ });
3755
+ }
3229
3756
  const ownsByUid = new Map(probeOutcomes.map((r) => [r.uid, r.owns]));
3230
3757
  return selectUrlWinner(topTier, ownsByUid);
3231
3758
  }
@@ -3246,9 +3773,23 @@ isInsideEditor = false) {
3246
3773
  // Captured by the URL metadata (Phase A) path for Studio resolution
3247
3774
  // diagnostics — every candidate considered, with specificity.
3248
3775
  let urlResolution;
3776
+ // Which service this request reached. Set inside `defaultImpl`, which is what
3777
+ // makes it honest in all three cases: the ordinary path records the real
3778
+ // route, a custom fetcher that delegates records it too, and one that never
3779
+ // delegates leaves it "unknown" rather than reporting a route we did not take.
3780
+ let servedBy = "unknown";
3249
3781
  const defaultImpl = async () => {
3782
+ // Settle the connection before any branch below can start falling back over
3783
+ // it. Every path here needs the stack, so this raises nothing new — it moves
3784
+ // the raise out of the fallbacks and in front of them. A caller's own
3785
+ // fetcher sits deliberately upstream of this: it may not need our stack.
3786
+ requireStack(config);
3787
+ // Read synchronously, before anything awaits: live-preview state is
3788
+ // process-wide, so a later read can belong to a different request.
3789
+ servedBy = resolveServedBy(config.stackSdk?.livePreviewConfig);
3250
3790
  if ("composableUid" in queryOptions) {
3251
- const uiQuery = config.stackSdk.where(config.stackSdk.ctQuery(config.contentTypeUid, {
3791
+ const stack = requireStack(config);
3792
+ const uiQuery = stack.where(stack.ctQuery(config.contentTypeUid, {
3252
3793
  locale: locale || config.locale,
3253
3794
  }), "composable_uid", queryOptions.composableUid);
3254
3795
  return await uiQuery
@@ -3262,11 +3803,15 @@ isInsideEditor = false) {
3262
3803
  response = res.entries[0];
3263
3804
  }
3264
3805
  if (!response) {
3265
- throw new ComposableStudioError(ComposableStudioErrors.COMPOSITION_NOT_FOUND, getErrorMessage(ErrorMessageKey.COMPOSITION_NOT_FOUND_404), {
3266
- compositionUid: queryOptions.composableUid,
3267
- hasStackSdk: !!config.stackSdk,
3268
- options: queryOptions,
3269
- troubleshootingInfo: getTroubleshootingInfoForCompositionFetchError(ComposableStudioErrors.COMPOSITION_NOT_FOUND, false),
3806
+ throw createStudioError({
3807
+ code: StudioErrorCode.COMPOSITION_UID_NOT_FOUND,
3808
+ headline: `No composition with the uid "${queryOptions.composableUid}" in content type "${config.contentTypeUid}".`,
3809
+ causes: uidNotFoundCauses(servedBy, config),
3810
+ context: buildStudioErrorContext(config, servedBy),
3811
+ findings: {
3812
+ compositionUid: queryOptions.composableUid,
3813
+ contentTypeUid: config.contentTypeUid,
3814
+ },
3270
3815
  });
3271
3816
  }
3272
3817
  return response;
@@ -3274,21 +3819,29 @@ isInsideEditor = false) {
3274
3819
  .catch((err) => {
3275
3820
  if (err instanceof ComposableStudioError)
3276
3821
  throw err;
3277
- const { errorType, message } = classifyApiError(err);
3278
- throw new ComposableStudioError(errorType, message, {
3279
- compositionUid: queryOptions.composableUid,
3280
- hasStackSdk: !!config.stackSdk,
3281
- statusCode: err?.status || err?.statusCode || "none",
3282
- errorCode: err?.error_code || "none",
3283
- errorMessage: err?.error_message || err?.message || "none",
3284
- troubleshootingInfo: getTroubleshootingInfoForCompositionFetchError(errorType, false),
3285
- });
3822
+ const diagnosed = classifyResponseError(err, config, { servedBy });
3823
+ if (diagnosed)
3824
+ throw diagnosed;
3825
+ // The request failed. Absence is settled on the success path above,
3826
+ // so nothing here is evidence that the page is missing.
3827
+ // An unplaceable 141 reads as a missing page, and which missing page
3828
+ // it is depends on what was asked for.
3829
+ throw diagnoseUnreadableResponse(err, config, { servedBy }, () => createStudioError({
3830
+ code: StudioErrorCode.COMPOSITION_UID_NOT_FOUND,
3831
+ headline: `No composition with the uid "${queryOptions.composableUid}" was found in content type "${config.contentTypeUid}".`,
3832
+ causes: uidNotFoundCauses(servedBy, config),
3833
+ context: buildStudioErrorContext(config, servedBy),
3834
+ findings: {
3835
+ compositionUid: queryOptions.composableUid,
3836
+ contentTypeUid: config.contentTypeUid,
3837
+ },
3838
+ }));
3286
3839
  });
3287
3840
  }
3288
3841
  else if ("templateContentTypeUid" in queryOptions) {
3289
3842
  // Fetch by connected content type - takes priority over url when both are present
3290
3843
  const placementFilter = getPageLinkedPlacementFilter();
3291
- return await config.stackSdk
3844
+ return await requireStack(config)
3292
3845
  .ctQuery(config.contentTypeUid, {
3293
3846
  includeAll: true,
3294
3847
  includeAllDepth: INCLUDE_DEPTH_COUNT,
@@ -3304,11 +3857,14 @@ isInsideEditor = false) {
3304
3857
  const entries = entriesFromResponse(res);
3305
3858
  const entry = entries[0];
3306
3859
  if (!entry) {
3307
- throw new ComposableStudioError(ComposableStudioErrors.COMPOSITION_NOT_FOUND, getErrorMessage(ErrorMessageKey.COMPOSITION_NOT_FOUND_404), {
3308
- templateContentTypeUid: queryOptions.templateContentTypeUid,
3309
- hasStackSdk: !!config.stackSdk,
3310
- options: queryOptions,
3311
- troubleshootingInfo: getTroubleshootingInfoForCompositionFetchError(ComposableStudioErrors.COMPOSITION_NOT_FOUND, false),
3860
+ throw createStudioError({
3861
+ code: StudioErrorCode.NO_COMPOSITION_FOR_TEMPLATE_CONTENT_TYPE,
3862
+ headline: `No composition is connected to the content type "${queryOptions.templateContentTypeUid}".`,
3863
+ causes: templateContentTypeCauses(queryOptions.templateContentTypeUid, servedBy, config),
3864
+ context: buildStudioErrorContext(config, servedBy),
3865
+ findings: {
3866
+ templateContentTypeUid: queryOptions.templateContentTypeUid,
3867
+ },
3312
3868
  });
3313
3869
  }
3314
3870
  return entry;
@@ -3316,15 +3872,22 @@ isInsideEditor = false) {
3316
3872
  .catch((err) => {
3317
3873
  if (err instanceof ComposableStudioError)
3318
3874
  throw err;
3319
- const { errorType, message } = classifyApiError(err);
3320
- throw new ComposableStudioError(errorType, message, {
3321
- templateContentTypeUid: queryOptions.templateContentTypeUid,
3322
- hasStackSdk: !!config.stackSdk,
3323
- statusCode: err?.status || err?.statusCode || "none",
3324
- errorCode: err?.error_code || "none",
3325
- errorMessage: err?.error_message || err?.message || "none",
3326
- troubleshootingInfo: getTroubleshootingInfoForCompositionFetchError(errorType, false),
3327
- });
3875
+ const diagnosed = classifyResponseError(err, config, { servedBy });
3876
+ if (diagnosed)
3877
+ throw diagnosed;
3878
+ // The request failed. Absence is settled on the success path above,
3879
+ // so nothing here is evidence that the page is missing.
3880
+ // An unplaceable 141 reads as a missing page, and which missing page
3881
+ // it is depends on what was asked for.
3882
+ throw diagnoseUnreadableResponse(err, config, { servedBy }, () => createStudioError({
3883
+ code: StudioErrorCode.NO_COMPOSITION_FOR_TEMPLATE_CONTENT_TYPE,
3884
+ headline: `No composition in this project is connected to the content type "${queryOptions.templateContentTypeUid}".`,
3885
+ causes: templateContentTypeCauses(queryOptions.templateContentTypeUid, servedBy, config),
3886
+ context: buildStudioErrorContext(config, servedBy),
3887
+ findings: {
3888
+ templateContentTypeUid: queryOptions.templateContentTypeUid,
3889
+ },
3890
+ }));
3328
3891
  });
3329
3892
  }
3330
3893
  else if ("url" in queryOptions) {
@@ -3345,7 +3908,7 @@ isInsideEditor = false) {
3345
3908
  // diagnostics keep the full candidate pool.
3346
3909
  if (requestUrl && !isInsideEditor) {
3347
3910
  try {
3348
- const exactRes = await config.stackSdk
3911
+ const exactRes = await requireStack(config)
3349
3912
  .ctQuery(config.contentTypeUid, {
3350
3913
  includeAll: true,
3351
3914
  includeAllDepth: INCLUDE_DEPTH_COUNT,
@@ -3375,17 +3938,22 @@ isInsideEditor = false) {
3375
3938
  }
3376
3939
  catch (fastPathError) {
3377
3940
  // The fast path must never make resolution less reliable than the
3378
- // scan it short-cuts — swallow and fall through.
3941
+ // scan it short-cuts — swallow and fall through. What it falls back
3942
+ // from is a request that did not work out; a failure we diagnosed is
3943
+ // not that. It is a conclusion, the scan would reach it again, and
3944
+ // burying it means the reader gets whatever the second attempt
3945
+ // happened to fail with instead.
3946
+ if (fastPathError instanceof ComposableStudioError &&
3947
+ fastPathError.code) {
3948
+ throw fastPathError;
3949
+ }
3379
3950
  if (process.env.NODE_ENV === "development") {
3380
- console.warn("[Composable Studio SDK] Exact-match URL lookup failed; falling back to the candidate scan:", fastPathError);
3951
+ console.warn("[Contentstack Studio] Exact-match URL lookup failed; falling back to the candidate scan:", fastPathError);
3381
3952
  }
3382
3953
  }
3383
3954
  }
3384
3955
  // 1. Fetch every page-linked candidate (lightweight, paginated).
3385
3956
  const { entries: candidates, truncated } = await fetchAllPageCompositions(config, locale);
3386
- if (truncated) {
3387
- console.warn(`[Composable Studio SDK] Composition candidate list hit the pagination cap while resolving "${requestUrl}"; some compositions may not have been considered.`);
3388
- }
3389
3957
  // 2. Rank the whole pool by literal-character specificity.
3390
3958
  const ranking = rankUrlMatches(requestUrl, candidates);
3391
3959
  if (ranking.composableUids.length > 0) {
@@ -3402,7 +3970,7 @@ isInsideEditor = false) {
3402
3970
  };
3403
3971
  if (winnerUid) {
3404
3972
  // 5. Full-fetch the winning composition only.
3405
- const fullQuery = config.stackSdk.ctQuery(config.contentTypeUid, {
3973
+ const fullQuery = requireStack(config).ctQuery(config.contentTypeUid, {
3406
3974
  includeAll: true,
3407
3975
  includeAllDepth: INCLUDE_DEPTH_COUNT,
3408
3976
  locale: locale || config.locale,
@@ -3415,33 +3983,78 @@ isInsideEditor = false) {
3415
3983
  }
3416
3984
  }
3417
3985
  }
3418
- // Nothing matched, or no tied candidate owns the URL.
3419
- throw new ComposableStudioError(ComposableStudioErrors.COMPOSITION_NOT_FOUND_BY_URL, getErrorMessage(ErrorMessageKey.COMPOSITION_NOT_FOUND_BY_URL, {
3420
- url: requestUrl,
3421
- }), {
3422
- url: requestUrl,
3423
- hasStackSdk: !!config.stackSdk,
3424
- options: queryOptions,
3425
- troubleshootingInfo: getTroubleshootingInfoForCompositionFetchError(ComposableStudioErrors.COMPOSITION_NOT_FOUND_BY_URL, true),
3986
+ // Absence has to be established, not assumed. If the scan stopped at its
3987
+ // cap we never finished looking, so "nothing matched" is a statement we
3988
+ // are not entitled to make — and the 404 it becomes is the one answer a
3989
+ // crawler acts on permanently.
3990
+ if (truncated) {
3991
+ throw createStudioError({
3992
+ code: StudioErrorCode.SEARCH_INCOMPLETE,
3993
+ headline: `Stopped after considering ${candidates.length} compositions without finding a match for "${requestUrl}". The search did not finish, so this is not a 404.`,
3994
+ causes: [
3995
+ {
3996
+ cause: "This project has more compositions than one search can cover.",
3997
+ fix: "Nothing here will fix it — report it, and we will raise the cap or narrow the search.",
3998
+ },
3999
+ ],
4000
+ context: buildStudioErrorContext(config, servedBy),
4001
+ findings: { url: requestUrl, consideredCount: candidates.length },
4002
+ });
4003
+ }
4004
+ // The scan finished and every check answered, so this is absence rather
4005
+ // than a gap in what we know — which is what entitles a host to return
4006
+ // 404 for it. Which absence it is decides what the reader does next.
4007
+ const considered = urlResolution?.shortlisted ?? [];
4008
+ if (considered.length > 0) {
4009
+ // Compositions are set up for this address and none of them has an
4010
+ // entry. The routing is right; the content is what is missing.
4011
+ throw createStudioError({
4012
+ code: StudioErrorCode.URL_MATCHED_NO_ENTRY,
4013
+ headline: `${considered.length} compositions match "${requestUrl}", and none of them has an entry for it.`,
4014
+ causes: matchedNoEntryCauses(considered, servedBy, config),
4015
+ context: buildStudioErrorContext(config, servedBy),
4016
+ findings: { url: requestUrl, considered },
4017
+ });
4018
+ }
4019
+ throw createStudioError({
4020
+ code: StudioErrorCode.NO_COMPOSITION_FOR_URL,
4021
+ headline: `No composition matches "${requestUrl}". Considered ${candidates.length} compositions.`,
4022
+ causes: notFoundByUrlCauses(requestUrl, servedBy, config),
4023
+ context: buildStudioErrorContext(config, servedBy),
4024
+ findings: { url: requestUrl, consideredCount: candidates.length },
3426
4025
  });
3427
4026
  }
3428
4027
  catch (err) {
3429
4028
  if (err instanceof ComposableStudioError)
3430
4029
  throw err;
3431
- const { errorType, message } = classifyApiError(err);
3432
- throw new ComposableStudioError(errorType, message, {
3433
- url: requestUrl,
3434
- hasStackSdk: !!config.stackSdk,
3435
- statusCode: err?.status || err?.statusCode || "none",
3436
- errorCode: err?.error_code || "none",
3437
- errorMessage: err?.error_message || err?.message || "none",
3438
- troubleshootingInfo: getTroubleshootingInfoForCompositionFetchError(errorType, true),
3439
- });
4030
+ const diagnosed = classifyResponseError(err, config, { servedBy });
4031
+ if (diagnosed)
4032
+ throw diagnosed;
4033
+ // The request failed. Absence is settled on the success path above,
4034
+ // so nothing here is evidence that the page is missing.
4035
+ // An unplaceable 141 reads as a missing page, and which missing page
4036
+ // it is depends on what was asked for.
4037
+ throw diagnoseUnreadableResponse(err, config, { servedBy }, () => createStudioError({
4038
+ code: StudioErrorCode.NO_COMPOSITION_FOR_URL,
4039
+ headline: `No composition is set up for the address ${requestUrl}.`,
4040
+ causes: notFoundByUrlCauses(requestUrl, servedBy, config),
4041
+ context: buildStudioErrorContext(config, servedBy),
4042
+ findings: { url: requestUrl, consideredCount: 0 },
4043
+ }));
3440
4044
  }
3441
4045
  }
3442
4046
  else {
3443
- throw new ComposableStudioError(ComposableStudioErrors.MISSING_COMPOSITION_IDENTIFIER, getErrorMessage(ErrorMessageKey.MISSING_COMPOSITION_IDENTIFIER), {
3444
- options: queryOptions,
4047
+ throw createStudioError({
4048
+ code: StudioErrorCode.COMPOSITION_IDENTIFIER_MISSING,
4049
+ headline: "No composition was asked for.",
4050
+ causes: [
4051
+ {
4052
+ cause: "The call named none of the three ways to identify a composition.",
4053
+ fix: "Pass one of compositionUid, url or templateContentTypeUid.",
4054
+ },
4055
+ ],
4056
+ context: buildStudioErrorContext(config, servedBy),
4057
+ findings: { lookedIn: "call" },
3445
4058
  });
3446
4059
  }
3447
4060
  };
@@ -3451,32 +4064,53 @@ isInsideEditor = false) {
3451
4064
  compositionQuery: queryOptions,
3452
4065
  contentTypeUid: config.contentTypeUid,
3453
4066
  options: resolvedOptions,
3454
- stackSdk: config.stackSdk.sdk,
4067
+ stackSdk: config.stackSdk?.sdk,
3455
4068
  defaultFetch: defaultImpl,
3456
4069
  });
3457
4070
  if (!entry) {
3458
- const isUrlBased = "url" in queryOptions;
3459
- throw new ComposableStudioError(isUrlBased
3460
- ? ComposableStudioErrors.COMPOSITION_NOT_FOUND_BY_URL
3461
- : ComposableStudioErrors.COMPOSITION_NOT_FOUND, isUrlBased
3462
- ? getErrorMessage(ErrorMessageKey.COMPOSITION_NOT_FOUND_BY_URL, {
3463
- url: queryOptions.url,
3464
- })
3465
- : getErrorMessage(ErrorMessageKey.COMPOSITION_NOT_FOUND_404));
4071
+ // A caller's own fetcher returned nothing. Which not-found this is
4072
+ // depends on what was asked for, and the two take opposite advice: an
4073
+ // address that matches nothing is a routing problem, a uid that matches
4074
+ // nothing is a content one.
4075
+ const servedByNow = resolveServedBy(config.stackSdk?.livePreviewConfig);
4076
+ const notFoundContext = buildStudioErrorContext(config, servedByNow);
4077
+ if ("url" in queryOptions) {
4078
+ throw createStudioError({
4079
+ code: StudioErrorCode.NO_COMPOSITION_FOR_URL,
4080
+ headline: `No composition is set up for the address ${queryOptions.url}.`,
4081
+ causes: notFoundByUrlCauses(queryOptions.url, servedByNow, config),
4082
+ context: notFoundContext,
4083
+ findings: { url: queryOptions.url, consideredCount: 0 },
4084
+ });
4085
+ }
4086
+ throw createStudioError({
4087
+ code: StudioErrorCode.COMPOSITION_UID_NOT_FOUND,
4088
+ headline: `No composition with the uid "${"composableUid" in queryOptions ? queryOptions.composableUid : ""}" was returned.`,
4089
+ causes: uidNotFoundCauses(servedByNow, config),
4090
+ context: notFoundContext,
4091
+ findings: {
4092
+ compositionUid: "composableUid" in queryOptions ? queryOptions.composableUid : "",
4093
+ contentTypeUid: config.contentTypeUid,
4094
+ },
4095
+ });
3466
4096
  }
3467
4097
  return {
3468
4098
  compositionEntry: entry,
3469
4099
  // Populated if the custom fetcher delegated to `defaultFetch` and it
3470
4100
  // resolved via the URL metadata path; otherwise undefined.
3471
4101
  urlResolution,
4102
+ // Built here rather than at the surface, so it reports the route this
4103
+ // fetch actually took. A caller's own fetcher leaves `servedBy` unknown.
4104
+ requestContext: buildStudioErrorContext(config, servedBy),
3472
4105
  };
3473
4106
  }
3474
4107
  const entry = await defaultImpl();
3475
4108
  return {
3476
4109
  compositionEntry: entry,
3477
4110
  urlResolution,
4111
+ requestContext: buildStudioErrorContext(config, servedBy),
3478
4112
  };
3479
4113
  }
3480
4114
 
3481
- export { buildSectionScopedData, classifyApiError, collectSectionInstanceBindings as collectSectionInstanceBindingsForTest, composeSectionTemplatePrefix, fetchComposition as fetchCompositionForTest, flattenBindingPathFromValue, generateSdk, getAllSectionCompositions as getAllSectionCompositionsForTest, getSeoMetadataPure, isTemplateBinding, mapSectionRepeaterPaths as mapSectionRepeaterPathsForTest, projectCrossBoundaryRepeaterBindings as projectCrossBoundaryRepeaterBindingsForTest, resolveSeoBindingValue };
4115
+ export { buildSectionScopedData, collectSectionInstanceBindings as collectSectionInstanceBindingsForTest, composeSectionTemplatePrefix, derivePlacementIncludePaths, fetchComposition as fetchCompositionForTest, flattenBindingPathFromValue, generateSdk, getAllSectionCompositions as getAllSectionCompositionsForTest, getSeoMetadataPure, isTemplateBinding, mapSectionRepeaterPaths as mapSectionRepeaterPathsForTest, parseUI, projectCrossBoundaryRepeaterBindings as projectCrossBoundaryRepeaterBindingsForTest, resolveSeoBindingValue };
3482
4116
  //# sourceMappingURL=sdk.js.map