personalize-connect-sdk 1.2.0 → 1.2.1

package/dist/index.d.mts

@@ -63,6 +63,8 @@ interface PersonalizeConnectProviderProps {
     resolveDatasource?: (datasourceId: string) => Promise<ComponentFields>;
     /** Override editing mode detection. When true the HOC renders a visual indicator. */
     isEditing?: boolean;
+    /** Enable debug logging to the browser console. */
+    debug?: boolean;
     children: ReactNode;
 }
 /** Resolved datasource fields passed as component props */
@@ -88,7 +90,7 @@ interface PersonalizeContextValue {
     siteName: string;
 }
 
-declare function PersonalizeProvider({ children, sitecoreEdgeContextId, sitecoreEdgeUrl, siteName, clientKey, pointOfSale, edgeUrl, apiKey, channel, language, currencyCode, timeout, resolveDatasource, isEditing: isEditingProp, }: PersonalizeConnectProviderProps): react_jsx_runtime.JSX.Element;
+declare function PersonalizeProvider({ children, sitecoreEdgeContextId, sitecoreEdgeUrl, siteName, clientKey, pointOfSale, edgeUrl, apiKey, channel, language, currencyCode, timeout, resolveDatasource, isEditing: isEditingProp, debug, }: PersonalizeConnectProviderProps): react_jsx_runtime.JSX.Element;
 declare function usePersonalizeContext(): PersonalizeContextValue | null;
 
 /**
@@ -131,13 +133,13 @@ declare function resolveContent(options: ResolveContentOptions): Promise<Resolve
 
 type GetConfigFromProps<P> = (props: P) => PersonalizeConnectConfig | undefined;
 /**
- * HOC that wraps any JSS/Content SDK component.
+ * HOC that wraps any JSS component.
  * If the rendering has a personalizeConnect config, it renders with defaultKey first,
  * then asynchronously fetches the personalized content and re-renders.
  * If no config, passes through unchanged.
  *
- * In editing mode (Page Builder / Experience Editor), renders a visual
- * indicator (border + badge) on components that have personalization configured.
+ * In Page Builder, renders a visual indicator (border + badge) on
+ * components that have personalization configured.
  */
 declare function withPersonalizeConnect<P extends object>(WrappedComponent: ComponentType<P>, getConfig?: GetConfigFromProps<P>): ComponentType<P>;
 
@@ -171,17 +173,26 @@ declare function createEdgeResolver(edgeUrl: string, apiKey: string, language?:
 declare function createEdgeProxyResolver(edgeBaseUrl: string, contextId: string, language?: string): (datasourceId: string) => Promise<ComponentFields>;
 
 /**
- * Lightweight Sitecore editing mode detection.
- * Works in Experience Editor and XM Cloud Pages without importing JSS.
+ * XM Cloud Pages (Page Builder) editing mode detection.
+ * Uses the same Sitecore context shape that JSS for XMC writes to __NEXT_DATA__.
  */
 /**
- * Detects whether the page is currently rendered inside a Sitecore editor
- * (Experience Editor or XM Cloud Pages). Result is cached after the first call.
+ * Detects whether the page is rendered inside XM Cloud Pages (Page Builder).
+ * Checks the JSS Sitecore context for pageEditing / pageState, and whether
+ * the rendering host is loaded in an iframe (Pages always iframes the site).
+ * Result is cached after the first call.
  */
 declare function isEditingMode(): boolean;
 /** Reset the cached result (useful for testing). */
 declare function resetEditingDetectionCache(): void;
 
+/**
+ * SDK debug logger. All output is prefixed with [PersonalizeConnect].
+ * Enable by passing debug={true} on PersonalizeProvider.
+ */
+declare function setDebug(on: boolean): void;
+declare function isDebugEnabled(): boolean;
+
 /**
  * Manages the Sitecore CDP browser ID.
  *
@@ -205,4 +216,4 @@ declare function getEdgeBrowserId(edgeUrl: string, contextId: string, siteName:
 /** Reset the cached init promise (for testing). */
 declare function resetEdgeInitCache(): void;
 
-export { type CallFlowsRequest, type CallPersonalizeOptions, type ComponentFields, type EdgeInitResponse, type GetConfigFromProps, type PersonalizeConnectConfig, type PersonalizeConnectProviderProps, type PersonalizeConnectResponse, type PersonalizeContextValue, PersonalizeProvider, type ResolveContentOptions, type ResolvedContent, type UsePersonalizeExperienceResult, callPersonalize, createEdgeProxyResolver, createEdgeResolver, getBrowserId, getEdgeBrowserId, isEditingMode, resetEdgeInitCache, resetEditingDetectionCache, resolveContent, usePersonalizeContext, usePersonalizeExperience, withPersonalizeConnect };
+export { type CallFlowsRequest, type CallPersonalizeOptions, type ComponentFields, type EdgeInitResponse, type GetConfigFromProps, type PersonalizeConnectConfig, type PersonalizeConnectProviderProps, type PersonalizeConnectResponse, type PersonalizeContextValue, PersonalizeProvider, type ResolveContentOptions, type ResolvedContent, type UsePersonalizeExperienceResult, callPersonalize, createEdgeProxyResolver, createEdgeResolver, getBrowserId, getEdgeBrowserId, isDebugEnabled, isEditingMode, resetEdgeInitCache, resetEditingDetectionCache, resolveContent, setDebug, usePersonalizeContext, usePersonalizeExperience, withPersonalizeConnect };

package/dist/index.d.ts

@@ -63,6 +63,8 @@ interface PersonalizeConnectProviderProps {
     resolveDatasource?: (datasourceId: string) => Promise<ComponentFields>;
     /** Override editing mode detection. When true the HOC renders a visual indicator. */
     isEditing?: boolean;
+    /** Enable debug logging to the browser console. */
+    debug?: boolean;
     children: ReactNode;
 }
 /** Resolved datasource fields passed as component props */
@@ -88,7 +90,7 @@ interface PersonalizeContextValue {
     siteName: string;
 }
 
-declare function PersonalizeProvider({ children, sitecoreEdgeContextId, sitecoreEdgeUrl, siteName, clientKey, pointOfSale, edgeUrl, apiKey, channel, language, currencyCode, timeout, resolveDatasource, isEditing: isEditingProp, }: PersonalizeConnectProviderProps): react_jsx_runtime.JSX.Element;
+declare function PersonalizeProvider({ children, sitecoreEdgeContextId, sitecoreEdgeUrl, siteName, clientKey, pointOfSale, edgeUrl, apiKey, channel, language, currencyCode, timeout, resolveDatasource, isEditing: isEditingProp, debug, }: PersonalizeConnectProviderProps): react_jsx_runtime.JSX.Element;
 declare function usePersonalizeContext(): PersonalizeContextValue | null;
 
 /**
@@ -131,13 +133,13 @@ declare function resolveContent(options: ResolveContentOptions): Promise<Resolve
 
 type GetConfigFromProps<P> = (props: P) => PersonalizeConnectConfig | undefined;
 /**
- * HOC that wraps any JSS/Content SDK component.
+ * HOC that wraps any JSS component.
  * If the rendering has a personalizeConnect config, it renders with defaultKey first,
  * then asynchronously fetches the personalized content and re-renders.
  * If no config, passes through unchanged.
  *
- * In editing mode (Page Builder / Experience Editor), renders a visual
- * indicator (border + badge) on components that have personalization configured.
+ * In Page Builder, renders a visual indicator (border + badge) on
+ * components that have personalization configured.
  */
 declare function withPersonalizeConnect<P extends object>(WrappedComponent: ComponentType<P>, getConfig?: GetConfigFromProps<P>): ComponentType<P>;
 
@@ -171,17 +173,26 @@ declare function createEdgeResolver(edgeUrl: string, apiKey: string, language?:
 declare function createEdgeProxyResolver(edgeBaseUrl: string, contextId: string, language?: string): (datasourceId: string) => Promise<ComponentFields>;
 
 /**
- * Lightweight Sitecore editing mode detection.
- * Works in Experience Editor and XM Cloud Pages without importing JSS.
+ * XM Cloud Pages (Page Builder) editing mode detection.
+ * Uses the same Sitecore context shape that JSS for XMC writes to __NEXT_DATA__.
  */
 /**
- * Detects whether the page is currently rendered inside a Sitecore editor
- * (Experience Editor or XM Cloud Pages). Result is cached after the first call.
+ * Detects whether the page is rendered inside XM Cloud Pages (Page Builder).
+ * Checks the JSS Sitecore context for pageEditing / pageState, and whether
+ * the rendering host is loaded in an iframe (Pages always iframes the site).
+ * Result is cached after the first call.
  */
 declare function isEditingMode(): boolean;
 /** Reset the cached result (useful for testing). */
 declare function resetEditingDetectionCache(): void;
 
+/**
+ * SDK debug logger. All output is prefixed with [PersonalizeConnect].
+ * Enable by passing debug={true} on PersonalizeProvider.
+ */
+declare function setDebug(on: boolean): void;
+declare function isDebugEnabled(): boolean;
+
 /**
  * Manages the Sitecore CDP browser ID.
  *
@@ -205,4 +216,4 @@ declare function getEdgeBrowserId(edgeUrl: string, contextId: string, siteName:
 /** Reset the cached init promise (for testing). */
 declare function resetEdgeInitCache(): void;
 
-export { type CallFlowsRequest, type CallPersonalizeOptions, type ComponentFields, type EdgeInitResponse, type GetConfigFromProps, type PersonalizeConnectConfig, type PersonalizeConnectProviderProps, type PersonalizeConnectResponse, type PersonalizeContextValue, PersonalizeProvider, type ResolveContentOptions, type ResolvedContent, type UsePersonalizeExperienceResult, callPersonalize, createEdgeProxyResolver, createEdgeResolver, getBrowserId, getEdgeBrowserId, isEditingMode, resetEdgeInitCache, resetEditingDetectionCache, resolveContent, usePersonalizeContext, usePersonalizeExperience, withPersonalizeConnect };
+export { type CallFlowsRequest, type CallPersonalizeOptions, type ComponentFields, type EdgeInitResponse, type GetConfigFromProps, type PersonalizeConnectConfig, type PersonalizeConnectProviderProps, type PersonalizeConnectResponse, type PersonalizeContextValue, PersonalizeProvider, type ResolveContentOptions, type ResolvedContent, type UsePersonalizeExperienceResult, callPersonalize, createEdgeProxyResolver, createEdgeResolver, getBrowserId, getEdgeBrowserId, isDebugEnabled, isEditingMode, resetEdgeInitCache, resetEditingDetectionCache, resolveContent, setDebug, usePersonalizeContext, usePersonalizeExperience, withPersonalizeConnect };

package/dist/index.js

@@ -26,10 +26,12 @@ __export(index_exports, {
   createEdgeResolver: () => createEdgeResolver,
   getBrowserId: () => getBrowserId,
   getEdgeBrowserId: () => getEdgeBrowserId,
+  isDebugEnabled: () => isDebugEnabled,
   isEditingMode: () => isEditingMode,
   resetEdgeInitCache: () => resetEdgeInitCache,
   resetEditingDetectionCache: () => resetEditingDetectionCache,
   resolveContent: () => resolveContent,
+  setDebug: () => setDebug,
   usePersonalizeContext: () => usePersonalizeContext,
   usePersonalizeExperience: () => usePersonalizeExperience,
   withPersonalizeConnect: () => withPersonalizeConnect
@@ -39,6 +41,31 @@ module.exports = __toCommonJS(index_exports);
 // src/PersonalizeProvider.tsx
 var import_react = require("react");
 
+// src/logger.ts
+var PREFIX = "[PersonalizeConnect]";
+var enabled = false;
+function setDebug(on) {
+  enabled = on;
+}
+function isDebugEnabled() {
+  return enabled;
+}
+function log(...args) {
+  if (enabled) console.log(PREFIX, ...args);
+}
+function warn(...args) {
+  if (enabled) console.warn(PREFIX, ...args);
+}
+function error(...args) {
+  if (enabled) console.error(PREFIX, ...args);
+}
+function group(label) {
+  if (enabled) console.groupCollapsed(`${PREFIX} ${label}`);
+}
+function groupEnd() {
+  if (enabled) console.groupEnd();
+}
+
 // src/browserId.ts
 var LEGACY_COOKIE_PREFIX = "bid_";
 var CONTEXT_COOKIE_PREFIX = "sc_";
@@ -71,6 +98,9 @@ function getBrowserId(clientKey) {
   if (!bid || typeof bid !== "string" || bid.length < 10) {
     bid = generateBrowserId();
     setCookie(cookieName, bid);
+    log("BrowserId (legacy): generated new", bid, `cookie=${cookieName}`);
+  } else {
+    log("BrowserId (legacy): from cookie", bid, `cookie=${cookieName}`);
   }
   return bid;
 }
@@ -78,15 +108,21 @@ var edgeInitPromise = null;
 async function getEdgeBrowserId(edgeUrl, contextId, siteName) {
   const cookieName = CONTEXT_COOKIE_PREFIX + contextId + CONTEXT_COOKIE_SUFFIX;
   const cached = getCookie(cookieName);
-  if (cached && cached.length >= 10) return cached;
+  if (cached && cached.length >= 10) {
+    log("BrowserId (edge): from cookie", cached, `cookie=${cookieName}`);
+    return cached;
+  }
+  log("BrowserId (edge): cookie miss, calling /v1/init", { edgeUrl, contextId, siteName });
   if (!edgeInitPromise) {
     edgeInitPromise = fetchEdgeInit(edgeUrl, contextId, siteName);
   }
   try {
     const result = await edgeInitPromise;
+    log("BrowserId (edge): init returned", result);
     setCookie(cookieName, result.browserId);
     return result.browserId;
-  } catch {
+  } catch (e) {
+    warn("BrowserId (edge): init failed, generating fallback", e);
     const fallback = generateBrowserId();
     setCookie(cookieName, fallback);
     return fallback;
@@ -97,12 +133,17 @@ async function getEdgeBrowserId(edgeUrl, contextId, siteName) {
 async function fetchEdgeInit(edgeUrl, contextId, siteName) {
   const base = edgeUrl.replace(/\/$/, "");
   const url = `${base}/v1/init?sitecoreContextId=${encodeURIComponent(contextId)}&siteName=${encodeURIComponent(siteName)}`;
+  log("BrowserId (edge): GET", url);
   const res = await fetch(url, { method: "GET" });
+  log("BrowserId (edge): init response status:", res.status);
   if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    error("BrowserId (edge): init non-OK:", res.status, text);
     throw new Error(`Edge init failed: ${res.status}`);
   }
   const data = await res.json();
   if (!data.browserId || typeof data.browserId !== "string") {
+    error("BrowserId (edge): init response missing browserId", data);
     throw new Error("Edge init response missing browserId");
   }
   return data;
@@ -132,6 +173,7 @@ function mapFields(fields) {
   return result;
 }
 async function queryEdge(url, headers, datasourceId, language) {
+  log("Edge GraphQL request:", { url, datasourceId, language });
   const res = await fetch(url, {
     method: "POST",
     headers: { "Content-Type": "application/json", ...headers },
@@ -140,16 +182,26 @@ async function queryEdge(url, headers, datasourceId, language) {
       variables: { itemId: datasourceId, language }
     })
   });
+  log("Edge GraphQL response status:", res.status);
   if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    error("Edge GraphQL non-OK response:", res.status, text);
     throw new Error(`Experience Edge request failed: ${res.status}`);
   }
   const json = await res.json();
   if (json.errors?.length) {
-    throw new Error(json.errors.map((e) => e.message ?? String(e)).join("; "));
+    const msg = json.errors.map((e) => e.message ?? String(e)).join("; ");
+    error("Edge GraphQL errors:", msg);
+    throw new Error(msg);
   }
   const fields = json.data?.item?.fields;
-  if (!fields || !Array.isArray(fields)) return {};
-  return mapFields(fields);
+  if (!fields || !Array.isArray(fields)) {
+    warn("Edge GraphQL: item not found or has no fields for", datasourceId);
+    return {};
+  }
+  const mapped = mapFields(fields);
+  log("Edge GraphQL resolved fields:", { datasourceId, fieldCount: Object.keys(mapped).length, fieldNames: Object.keys(mapped) });
+  return mapped;
 }
 function createEdgeResolver(edgeUrl, apiKey, language = "en") {
   return (datasourceId) => queryEdge(edgeUrl, { sc_apikey: apiKey }, datasourceId, language);
@@ -162,23 +214,46 @@ function createEdgeProxyResolver(edgeBaseUrl, contextId, language = "en") {
 
 // src/editingDetection.ts
 var cachedResult = null;
+function getSitecoreContext() {
+  if (typeof window === "undefined") return void 0;
+  try {
+    const nd = window.__NEXT_DATA__;
+    return nd?.props?.pageProps?.layoutData?.sitecore?.context;
+  } catch {
+    return void 0;
+  }
+}
 function isEditingMode() {
-  if (typeof window === "undefined") return false;
-  if (cachedResult !== null) return cachedResult;
-  const params = new URLSearchParams(window.location.search);
-  const scMode = params.get("sc_mode");
-  if (scMode && scMode !== "normal") {
-    cachedResult = true;
-    return true;
+  if (typeof window === "undefined") {
+    log("Editing detection: SSR \u2014 returning false");
+    return false;
   }
-  if (params.has("sc_layoutKind") || params.has("sc_itemid")) {
+  if (cachedResult !== null) {
+    log("Editing detection: returning cached result", cachedResult);
+    return cachedResult;
+  }
+  log("Editing detection: running checks...");
+  const sc = getSitecoreContext();
+  log("Editing detection: __NEXT_DATA__ sitecore context:", sc ?? "(not found)");
+  if (sc?.pageEditing === true || sc?.pageState && sc.pageState !== "normal") {
+    log("Editing detection: MATCH \u2014 JSS context pageEditing/pageState", { pageEditing: sc.pageEditing, pageState: sc.pageState });
     cachedResult = true;
     return true;
   }
-  if (document.getElementById("scWebEditRibbon") || document.querySelector("[chrometype]")) {
+  try {
+    const inIframe = window.self !== window.top;
+    log("Editing detection: iframe check \u2014 window.self !== window.top:", inIframe);
+    if (inIframe) {
+      log("Editing detection: MATCH \u2014 running inside iframe (Page Builder)");
+      cachedResult = true;
+      return true;
+    }
+  } catch {
+    log("Editing detection: MATCH \u2014 cross-origin iframe access threw (Page Builder)");
     cachedResult = true;
     return true;
   }
+  log("Editing detection: no match \u2014 not in editing mode");
   cachedResult = false;
   return false;
 }
@@ -197,43 +272,87 @@ var DEFAULT_EDGE_URL = "https://edge-platform.sitecorecloud.io";
 var noopResolver = async () => ({});
 function PersonalizeProvider({
   children,
-  // Context ID mode
   sitecoreEdgeContextId,
   sitecoreEdgeUrl = DEFAULT_EDGE_URL,
   siteName = "",
-  // Legacy mode
   clientKey = "",
   pointOfSale = "",
   edgeUrl,
   apiKey,
-  // Common
   channel = DEFAULT_CHANNEL,
   language = DEFAULT_LANGUAGE,
   currencyCode = DEFAULT_CURRENCY,
   timeout = DEFAULT_TIMEOUT,
   resolveDatasource,
-  isEditing: isEditingProp
+  isEditing: isEditingProp,
+  debug = false
 }) {
   const useEdgeProxy = Boolean(sitecoreEdgeContextId);
   const [browserId, setBrowserId] = (0, import_react.useState)("");
   const [detectedEditing, setDetectedEditing] = (0, import_react.useState)(false);
+  (0, import_react.useEffect)(() => {
+    setDebug(debug);
+  }, [debug]);
+  (0, import_react.useEffect)(() => {
+    setDebug(debug);
+    log("Provider mounting", {
+      mode: useEdgeProxy ? "Context ID" : "Legacy",
+      sitecoreEdgeContextId: sitecoreEdgeContextId ?? "(none)",
+      sitecoreEdgeUrl,
+      siteName: siteName || "(none)",
+      clientKey: clientKey ? `${clientKey.slice(0, 8)}...` : "(none)",
+      pointOfSale: pointOfSale || "(none)",
+      edgeUrl: edgeUrl ?? "(none)",
+      apiKey: apiKey ? `${apiKey.slice(0, 8)}...` : "(none)",
+      language,
+      channel,
+      hasCustomResolver: Boolean(resolveDatasource),
+      isEditingProp: isEditingProp ?? "auto-detect"
+    });
+  }, []);
   (0, import_react.useEffect)(() => {
     if (useEdgeProxy) {
-      getEdgeBrowserId(sitecoreEdgeUrl, sitecoreEdgeContextId, siteName).then(setBrowserId);
+      log("BrowserId: fetching via Edge init", { sitecoreEdgeUrl, sitecoreEdgeContextId, siteName });
+      getEdgeBrowserId(sitecoreEdgeUrl, sitecoreEdgeContextId, siteName).then((bid) => {
+        log("BrowserId: resolved via Edge init", bid);
+        setBrowserId(bid);
+      }).catch((err) => {
+        warn("BrowserId: Edge init failed, will use fallback", err);
+      });
     } else if (clientKey) {
-      setBrowserId(getBrowserId(clientKey));
+      const bid = getBrowserId(clientKey);
+      log("BrowserId: resolved via local cookie", bid);
+      setBrowserId(bid);
+    } else {
+      warn("BrowserId: no clientKey and no sitecoreEdgeContextId \u2014 browserId will be empty");
     }
   }, [useEdgeProxy, sitecoreEdgeContextId, sitecoreEdgeUrl, siteName, clientKey]);
   (0, import_react.useEffect)(() => {
     if (isEditingProp === void 0) {
-      setDetectedEditing(isEditingMode());
+      const detected = isEditingMode();
+      log("Editing mode auto-detected:", detected);
+      setDetectedEditing(detected);
+    } else {
+      log("Editing mode overridden via prop:", isEditingProp);
     }
   }, [isEditingProp]);
   const effectiveEditing = isEditingProp ?? detectedEditing;
-  const effectiveResolver = (0, import_react.useCallback)(
-    resolveDatasource ?? (useEdgeProxy ? createEdgeProxyResolver(sitecoreEdgeUrl, sitecoreEdgeContextId, language) : edgeUrl && apiKey ? createEdgeResolver(edgeUrl, apiKey, language) : noopResolver),
-    [resolveDatasource, useEdgeProxy, sitecoreEdgeUrl, sitecoreEdgeContextId, edgeUrl, apiKey, language]
-  );
+  const effectiveResolver = (0, import_react.useCallback)(() => {
+    if (resolveDatasource) {
+      log("Resolver: using custom resolveDatasource callback");
+      return resolveDatasource;
+    }
+    if (useEdgeProxy) {
+      log("Resolver: using Edge proxy GraphQL", { sitecoreEdgeUrl, sitecoreEdgeContextId });
+      return createEdgeProxyResolver(sitecoreEdgeUrl, sitecoreEdgeContextId, language);
+    }
+    if (edgeUrl && apiKey) {
+      log("Resolver: using direct Edge GraphQL", { edgeUrl });
+      return createEdgeResolver(edgeUrl, apiKey, language);
+    }
+    warn("Resolver: no resolver configured \u2014 resolveDatasource will return {}. Provide sitecoreEdgeContextId, edgeUrl+apiKey, or a custom resolveDatasource.");
+    return noopResolver;
+  }, [resolveDatasource, useEdgeProxy, sitecoreEdgeUrl, sitecoreEdgeContextId, edgeUrl, apiKey, language])();
   const effectiveBrowserId = browserId || (!useEdgeProxy && clientKey && typeof window !== "undefined" ? getBrowserId(clientKey) : "");
   const value = (0, import_react.useMemo)(
     () => ({
@@ -277,10 +396,23 @@ function usePersonalizeContext() {
 var DEFAULT_API_BASE = "https://api.boxever.com";
 async function callPersonalize(options) {
   const { config, context, apiBase = DEFAULT_API_BASE, componentRef, pageRoute } = options;
+  group(`callPersonalize [${config.friendlyId}]`);
+  log("Config:", { friendlyId: config.friendlyId, defaultKey: config.defaultKey, contentMapKeys: Object.keys(config.contentMap) });
+  log("BrowserId:", context.browserId || "(empty \u2014 call will likely fail)");
+  if (!context.browserId) {
+    warn("BrowserId is empty \u2014 personalize call may fail or return default");
+  }
+  let result;
   if (context.useEdgeProxy) {
-    return callViaEdgeProxy(config, context, componentRef, pageRoute);
+    log("Route: Edge proxy");
+    result = await callViaEdgeProxy(config, context, componentRef, pageRoute);
+  } else {
+    log("Route: Legacy /v2/callFlows", { apiBase });
+    result = await callViaLegacy(config, context, apiBase, componentRef, pageRoute);
   }
-  return callViaLegacy(config, context, apiBase, componentRef, pageRoute);
+  log("Result contentKey:", result ?? "(null \u2014 will use defaultKey)");
+  groupEnd();
+  return result;
 }
 async function callViaEdgeProxy(config, context, componentRef, pageRoute) {
   const base = context.edgeProxyUrl.replace(/\/$/, "");
@@ -298,6 +430,8 @@ async function callViaEdgeProxy(config, context, componentRef, pageRoute) {
     if (pageRoute) params.pageRoute = pageRoute;
     body.params = params;
   }
+  log("Edge proxy POST", url);
+  log("Request body:", body);
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), context.timeout);
   try {
@@ -308,10 +442,18 @@ async function callViaEdgeProxy(config, context, componentRef, pageRoute) {
       signal: controller.signal
     });
     clearTimeout(timeoutId);
-    if (!res.ok) return null;
-    return extractContentKey(await res.json());
-  } catch {
+    log("Edge proxy response status:", res.status);
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      warn("Edge proxy non-OK response:", res.status, text);
+      return null;
+    }
+    const data = await res.json();
+    log("Edge proxy response body:", data);
+    return extractContentKey(data);
+  } catch (e) {
     clearTimeout(timeoutId);
+    error("Edge proxy fetch error:", e);
     return null;
   }
 }
@@ -330,20 +472,31 @@ async function callViaLegacy(config, context, apiBase, componentRef, pageRoute)
     if (componentRef) body.params.componentRef = componentRef;
     if (pageRoute) body.params.pageRoute = pageRoute;
   }
+  const url = `${apiBase.replace(/\/$/, "")}/v2/callFlows`;
+  log("Legacy POST", url);
+  log("Request body:", body);
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), context.timeout);
   try {
-    const res = await fetch(`${apiBase.replace(/\/$/, "")}/v2/callFlows`, {
+    const res = await fetch(url, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(body),
       signal: controller.signal
     });
     clearTimeout(timeoutId);
-    if (!res.ok) return null;
-    return extractContentKey(await res.json());
-  } catch {
+    log("Legacy response status:", res.status);
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      warn("Legacy non-OK response:", res.status, text);
+      return null;
+    }
+    const data = await res.json();
+    log("Legacy response body:", data);
+    return extractContentKey(data);
+  } catch (e) {
     clearTimeout(timeoutId);
+    error("Legacy fetch error:", e);
     return null;
   }
 }
@@ -357,14 +510,29 @@ function extractContentKey(data) {
 // src/contentResolver.ts
 async function resolveContent(options) {
   const { contentKey, config, resolveDatasource } = options;
-  const effectiveKey = contentKey && contentKey in config.contentMap ? contentKey : config.defaultKey;
+  const keyInMap = contentKey && contentKey in config.contentMap;
+  const effectiveKey = keyInMap ? contentKey : config.defaultKey;
+  if (!keyInMap) {
+    warn(
+      `Content key "${contentKey}" not found in contentMap [${Object.keys(config.contentMap).join(", ")}], falling back to defaultKey "${config.defaultKey}"`
+    );
+  }
   const datasourceId = config.contentMap[effectiveKey];
-  if (!datasourceId || typeof datasourceId !== "string") return null;
+  log("Resolving datasource:", { effectiveKey, datasourceId });
+  if (!datasourceId || typeof datasourceId !== "string") {
+    warn(`No datasource ID for key "${effectiveKey}" \u2014 contentMap may be misconfigured`);
+    return null;
+  }
   try {
     const fields = await resolveDatasource(datasourceId);
-    if (!fields || typeof fields !== "object") return null;
+    if (!fields || typeof fields !== "object") {
+      warn("resolveDatasource returned empty/invalid fields for", datasourceId);
+      return null;
+    }
+    log("Datasource resolved:", { datasourceId, fieldNames: Object.keys(fields) });
     return { datasourceId, fields };
-  } catch {
+  } catch (e) {
+    error("resolveDatasource threw for", datasourceId, e);
     return null;
   }
 }
@@ -397,24 +565,46 @@ var INDICATOR_BADGE = {
   pointerEvents: "none"
 };
 function withPersonalizeConnect(WrappedComponent, getConfig = DEFAULT_GET_CONFIG) {
+  const componentName = WrappedComponent.displayName ?? WrappedComponent.name ?? "Component";
   function PersonalizeConnectWrapper(props) {
     const context = usePersonalizeContext();
     const config = getConfig(props);
     const [resolvedFields, setResolvedFields] = (0, import_react2.useState)(null);
     const mountedRef = (0, import_react2.useRef)(true);
+    if (!config) {
+      log(`[${componentName}] No personalizeConnect config on rendering \u2014 passthrough`);
+    } else {
+      log(`[${componentName}] Config found:`, { friendlyId: config.friendlyId, defaultKey: config.defaultKey, keys: Object.keys(config.contentMap) });
+    }
+    if (!context) {
+      warn(`[${componentName}] PersonalizeContext is null \u2014 is PersonalizeProvider mounted?`);
+    }
     const runPersonalization = (0, import_react2.useCallback)(async () => {
       if (!config || !context) return;
+      group(`[${componentName}] personalization flow`);
+      log("Calling Personalize for experience:", config.friendlyId);
       const contentKey = await callPersonalize({ config, context });
-      if (!mountedRef.current) return;
+      if (!mountedRef.current) {
+        groupEnd();
+        return;
+      }
+      log("Resolving content for contentKey:", contentKey ?? "(null)");
       const resolved = await resolveContent({
         contentKey,
         config,
         resolveDatasource: context.resolveDatasource
       });
-      if (!mountedRef.current) return;
+      if (!mountedRef.current) {
+        groupEnd();
+        return;
+      }
       if (resolved) {
+        log(`[${componentName}] Fields resolved \u2014 swapping props.fields`, { datasourceId: resolved.datasourceId, fieldNames: Object.keys(resolved.fields) });
         setResolvedFields(resolved.fields);
+      } else {
+        warn(`[${componentName}] Content resolution returned null \u2014 component keeps original fields`);
       }
+      groupEnd();
     }, [config, context]);
     (0, import_react2.useEffect)(() => {
       mountedRef.current = true;
@@ -431,6 +621,7 @@ function withPersonalizeConnect(WrappedComponent, getConfig = DEFAULT_GET_CONFIG
     const mergedProps = resolvedFields ? { ...props, fields: resolvedFields } : props;
     const component = /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(WrappedComponent, { ...mergedProps });
     if (context.isEditing) {
+      log(`[${componentName}] Editing mode \u2014 rendering indicator badge`);
       return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { style: INDICATOR_BORDER, "data-personalize-connect": config.friendlyId, children: [
         /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { style: INDICATOR_BADGE, title: `Personalize: ${config.friendlyId}`, children: "\u26A1 Personalized" }),
         component
@@ -438,7 +629,7 @@ function withPersonalizeConnect(WrappedComponent, getConfig = DEFAULT_GET_CONFIG
     }
     return component;
   }
-  PersonalizeConnectWrapper.displayName = `WithPersonalizeConnect(${WrappedComponent.displayName ?? WrappedComponent.name ?? "Component"})`;
+  PersonalizeConnectWrapper.displayName = `WithPersonalizeConnect(${componentName})`;
   return PersonalizeConnectWrapper;
 }
 
@@ -449,7 +640,7 @@ function usePersonalizeExperience(config) {
   const [contentKey, setContentKey] = (0, import_react3.useState)(null);
   const [resolvedFields, setResolvedFields] = (0, import_react3.useState)(null);
   const [isLoading, setIsLoading] = (0, import_react3.useState)(true);
-  const [error, setError] = (0, import_react3.useState)(null);
+  const [error2, setError] = (0, import_react3.useState)(null);
   const mountedRef = (0, import_react3.useRef)(true);
   const runPersonalization = (0, import_react3.useCallback)(async () => {
     if (!config || !context) {
@@ -490,7 +681,7 @@ function usePersonalizeExperience(config) {
     contentKey,
     resolvedFields,
     isLoading,
-    error
+    error: error2
   };
 }
 // Annotate the CommonJS export names for ESM import in node:
@@ -501,10 +692,12 @@ function usePersonalizeExperience(config) {
   createEdgeResolver,
   getBrowserId,
   getEdgeBrowserId,
+  isDebugEnabled,
   isEditingMode,
   resetEdgeInitCache,
   resetEditingDetectionCache,
   resolveContent,
+  setDebug,
   usePersonalizeContext,
   usePersonalizeExperience,
   withPersonalizeConnect

package/dist/index.mjs

@@ -1,6 +1,31 @@
 // src/PersonalizeProvider.tsx
 import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
 
+// src/logger.ts
+var PREFIX = "[PersonalizeConnect]";
+var enabled = false;
+function setDebug(on) {
+  enabled = on;
+}
+function isDebugEnabled() {
+  return enabled;
+}
+function log(...args) {
+  if (enabled) console.log(PREFIX, ...args);
+}
+function warn(...args) {
+  if (enabled) console.warn(PREFIX, ...args);
+}
+function error(...args) {
+  if (enabled) console.error(PREFIX, ...args);
+}
+function group(label) {
+  if (enabled) console.groupCollapsed(`${PREFIX} ${label}`);
+}
+function groupEnd() {
+  if (enabled) console.groupEnd();
+}
+
 // src/browserId.ts
 var LEGACY_COOKIE_PREFIX = "bid_";
 var CONTEXT_COOKIE_PREFIX = "sc_";
@@ -33,6 +58,9 @@ function getBrowserId(clientKey) {
   if (!bid || typeof bid !== "string" || bid.length < 10) {
     bid = generateBrowserId();
     setCookie(cookieName, bid);
+    log("BrowserId (legacy): generated new", bid, `cookie=${cookieName}`);
+  } else {
+    log("BrowserId (legacy): from cookie", bid, `cookie=${cookieName}`);
   }
   return bid;
 }
@@ -40,15 +68,21 @@ var edgeInitPromise = null;
 async function getEdgeBrowserId(edgeUrl, contextId, siteName) {
   const cookieName = CONTEXT_COOKIE_PREFIX + contextId + CONTEXT_COOKIE_SUFFIX;
   const cached = getCookie(cookieName);
-  if (cached && cached.length >= 10) return cached;
+  if (cached && cached.length >= 10) {
+    log("BrowserId (edge): from cookie", cached, `cookie=${cookieName}`);
+    return cached;
+  }
+  log("BrowserId (edge): cookie miss, calling /v1/init", { edgeUrl, contextId, siteName });
   if (!edgeInitPromise) {
     edgeInitPromise = fetchEdgeInit(edgeUrl, contextId, siteName);
   }
   try {
     const result = await edgeInitPromise;
+    log("BrowserId (edge): init returned", result);
     setCookie(cookieName, result.browserId);
     return result.browserId;
-  } catch {
+  } catch (e) {
+    warn("BrowserId (edge): init failed, generating fallback", e);
     const fallback = generateBrowserId();
     setCookie(cookieName, fallback);
     return fallback;
@@ -59,12 +93,17 @@ async function getEdgeBrowserId(edgeUrl, contextId, siteName) {
 async function fetchEdgeInit(edgeUrl, contextId, siteName) {
   const base = edgeUrl.replace(/\/$/, "");
   const url = `${base}/v1/init?sitecoreContextId=${encodeURIComponent(contextId)}&siteName=${encodeURIComponent(siteName)}`;
+  log("BrowserId (edge): GET", url);
   const res = await fetch(url, { method: "GET" });
+  log("BrowserId (edge): init response status:", res.status);
   if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    error("BrowserId (edge): init non-OK:", res.status, text);
     throw new Error(`Edge init failed: ${res.status}`);
   }
   const data = await res.json();
   if (!data.browserId || typeof data.browserId !== "string") {
+    error("BrowserId (edge): init response missing browserId", data);
     throw new Error("Edge init response missing browserId");
   }
   return data;
@@ -94,6 +133,7 @@ function mapFields(fields) {
   return result;
 }
 async function queryEdge(url, headers, datasourceId, language) {
+  log("Edge GraphQL request:", { url, datasourceId, language });
   const res = await fetch(url, {
     method: "POST",
     headers: { "Content-Type": "application/json", ...headers },
@@ -102,16 +142,26 @@ async function queryEdge(url, headers, datasourceId, language) {
       variables: { itemId: datasourceId, language }
     })
   });
+  log("Edge GraphQL response status:", res.status);
   if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    error("Edge GraphQL non-OK response:", res.status, text);
     throw new Error(`Experience Edge request failed: ${res.status}`);
   }
   const json = await res.json();
   if (json.errors?.length) {
-    throw new Error(json.errors.map((e) => e.message ?? String(e)).join("; "));
+    const msg = json.errors.map((e) => e.message ?? String(e)).join("; ");
+    error("Edge GraphQL errors:", msg);
+    throw new Error(msg);
   }
   const fields = json.data?.item?.fields;
-  if (!fields || !Array.isArray(fields)) return {};
-  return mapFields(fields);
+  if (!fields || !Array.isArray(fields)) {
+    warn("Edge GraphQL: item not found or has no fields for", datasourceId);
+    return {};
+  }
+  const mapped = mapFields(fields);
+  log("Edge GraphQL resolved fields:", { datasourceId, fieldCount: Object.keys(mapped).length, fieldNames: Object.keys(mapped) });
+  return mapped;
 }
 function createEdgeResolver(edgeUrl, apiKey, language = "en") {
   return (datasourceId) => queryEdge(edgeUrl, { sc_apikey: apiKey }, datasourceId, language);
@@ -124,23 +174,46 @@ function createEdgeProxyResolver(edgeBaseUrl, contextId, language = "en") {
 
 // src/editingDetection.ts
 var cachedResult = null;
+function getSitecoreContext() {
+  if (typeof window === "undefined") return void 0;
+  try {
+    const nd = window.__NEXT_DATA__;
+    return nd?.props?.pageProps?.layoutData?.sitecore?.context;
+  } catch {
+    return void 0;
+  }
+}
 function isEditingMode() {
-  if (typeof window === "undefined") return false;
-  if (cachedResult !== null) return cachedResult;
-  const params = new URLSearchParams(window.location.search);
-  const scMode = params.get("sc_mode");
-  if (scMode && scMode !== "normal") {
-    cachedResult = true;
-    return true;
+  if (typeof window === "undefined") {
+    log("Editing detection: SSR \u2014 returning false");
+    return false;
   }
-  if (params.has("sc_layoutKind") || params.has("sc_itemid")) {
+  if (cachedResult !== null) {
+    log("Editing detection: returning cached result", cachedResult);
+    return cachedResult;
+  }
+  log("Editing detection: running checks...");
+  const sc = getSitecoreContext();
+  log("Editing detection: __NEXT_DATA__ sitecore context:", sc ?? "(not found)");
+  if (sc?.pageEditing === true || sc?.pageState && sc.pageState !== "normal") {
+    log("Editing detection: MATCH \u2014 JSS context pageEditing/pageState", { pageEditing: sc.pageEditing, pageState: sc.pageState });
     cachedResult = true;
     return true;
   }
-  if (document.getElementById("scWebEditRibbon") || document.querySelector("[chrometype]")) {
+  try {
+    const inIframe = window.self !== window.top;
+    log("Editing detection: iframe check \u2014 window.self !== window.top:", inIframe);
+    if (inIframe) {
+      log("Editing detection: MATCH \u2014 running inside iframe (Page Builder)");
+      cachedResult = true;
+      return true;
+    }
+  } catch {
+    log("Editing detection: MATCH \u2014 cross-origin iframe access threw (Page Builder)");
     cachedResult = true;
     return true;
   }
+  log("Editing detection: no match \u2014 not in editing mode");
   cachedResult = false;
   return false;
 }
@@ -159,43 +232,87 @@ var DEFAULT_EDGE_URL = "https://edge-platform.sitecorecloud.io";
 var noopResolver = async () => ({});
 function PersonalizeProvider({
   children,
-  // Context ID mode
   sitecoreEdgeContextId,
   sitecoreEdgeUrl = DEFAULT_EDGE_URL,
   siteName = "",
-  // Legacy mode
   clientKey = "",
   pointOfSale = "",
   edgeUrl,
   apiKey,
-  // Common
   channel = DEFAULT_CHANNEL,
   language = DEFAULT_LANGUAGE,
   currencyCode = DEFAULT_CURRENCY,
   timeout = DEFAULT_TIMEOUT,
   resolveDatasource,
-  isEditing: isEditingProp
+  isEditing: isEditingProp,
+  debug = false
 }) {
   const useEdgeProxy = Boolean(sitecoreEdgeContextId);
   const [browserId, setBrowserId] = useState("");
   const [detectedEditing, setDetectedEditing] = useState(false);
+  useEffect(() => {
+    setDebug(debug);
+  }, [debug]);
+  useEffect(() => {
+    setDebug(debug);
+    log("Provider mounting", {
+      mode: useEdgeProxy ? "Context ID" : "Legacy",
+      sitecoreEdgeContextId: sitecoreEdgeContextId ?? "(none)",
+      sitecoreEdgeUrl,
+      siteName: siteName || "(none)",
+      clientKey: clientKey ? `${clientKey.slice(0, 8)}...` : "(none)",
+      pointOfSale: pointOfSale || "(none)",
+      edgeUrl: edgeUrl ?? "(none)",
+      apiKey: apiKey ? `${apiKey.slice(0, 8)}...` : "(none)",
+      language,
+      channel,
+      hasCustomResolver: Boolean(resolveDatasource),
+      isEditingProp: isEditingProp ?? "auto-detect"
+    });
+  }, []);
   useEffect(() => {
     if (useEdgeProxy) {
-      getEdgeBrowserId(sitecoreEdgeUrl, sitecoreEdgeContextId, siteName).then(setBrowserId);
+      log("BrowserId: fetching via Edge init", { sitecoreEdgeUrl, sitecoreEdgeContextId, siteName });
+      getEdgeBrowserId(sitecoreEdgeUrl, sitecoreEdgeContextId, siteName).then((bid) => {
+        log("BrowserId: resolved via Edge init", bid);
+        setBrowserId(bid);
+      }).catch((err) => {
+        warn("BrowserId: Edge init failed, will use fallback", err);
+      });
     } else if (clientKey) {
-      setBrowserId(getBrowserId(clientKey));
+      const bid = getBrowserId(clientKey);
+      log("BrowserId: resolved via local cookie", bid);
+      setBrowserId(bid);
+    } else {
+      warn("BrowserId: no clientKey and no sitecoreEdgeContextId \u2014 browserId will be empty");
     }
   }, [useEdgeProxy, sitecoreEdgeContextId, sitecoreEdgeUrl, siteName, clientKey]);
   useEffect(() => {
     if (isEditingProp === void 0) {
-      setDetectedEditing(isEditingMode());
+      const detected = isEditingMode();
+      log("Editing mode auto-detected:", detected);
+      setDetectedEditing(detected);
+    } else {
+      log("Editing mode overridden via prop:", isEditingProp);
     }
   }, [isEditingProp]);
   const effectiveEditing = isEditingProp ?? detectedEditing;
-  const effectiveResolver = useCallback(
-    resolveDatasource ?? (useEdgeProxy ? createEdgeProxyResolver(sitecoreEdgeUrl, sitecoreEdgeContextId, language) : edgeUrl && apiKey ? createEdgeResolver(edgeUrl, apiKey, language) : noopResolver),
-    [resolveDatasource, useEdgeProxy, sitecoreEdgeUrl, sitecoreEdgeContextId, edgeUrl, apiKey, language]
-  );
+  const effectiveResolver = useCallback(() => {
+    if (resolveDatasource) {
+      log("Resolver: using custom resolveDatasource callback");
+      return resolveDatasource;
+    }
+    if (useEdgeProxy) {
+      log("Resolver: using Edge proxy GraphQL", { sitecoreEdgeUrl, sitecoreEdgeContextId });
+      return createEdgeProxyResolver(sitecoreEdgeUrl, sitecoreEdgeContextId, language);
+    }
+    if (edgeUrl && apiKey) {
+      log("Resolver: using direct Edge GraphQL", { edgeUrl });
+      return createEdgeResolver(edgeUrl, apiKey, language);
+    }
+    warn("Resolver: no resolver configured \u2014 resolveDatasource will return {}. Provide sitecoreEdgeContextId, edgeUrl+apiKey, or a custom resolveDatasource.");
+    return noopResolver;
+  }, [resolveDatasource, useEdgeProxy, sitecoreEdgeUrl, sitecoreEdgeContextId, edgeUrl, apiKey, language])();
   const effectiveBrowserId = browserId || (!useEdgeProxy && clientKey && typeof window !== "undefined" ? getBrowserId(clientKey) : "");
   const value = useMemo(
     () => ({
@@ -239,10 +356,23 @@ function usePersonalizeContext() {
 var DEFAULT_API_BASE = "https://api.boxever.com";
 async function callPersonalize(options) {
   const { config, context, apiBase = DEFAULT_API_BASE, componentRef, pageRoute } = options;
+  group(`callPersonalize [${config.friendlyId}]`);
+  log("Config:", { friendlyId: config.friendlyId, defaultKey: config.defaultKey, contentMapKeys: Object.keys(config.contentMap) });
+  log("BrowserId:", context.browserId || "(empty \u2014 call will likely fail)");
+  if (!context.browserId) {
+    warn("BrowserId is empty \u2014 personalize call may fail or return default");
+  }
+  let result;
   if (context.useEdgeProxy) {
-    return callViaEdgeProxy(config, context, componentRef, pageRoute);
+    log("Route: Edge proxy");
+    result = await callViaEdgeProxy(config, context, componentRef, pageRoute);
+  } else {
+    log("Route: Legacy /v2/callFlows", { apiBase });
+    result = await callViaLegacy(config, context, apiBase, componentRef, pageRoute);
   }
-  return callViaLegacy(config, context, apiBase, componentRef, pageRoute);
+  log("Result contentKey:", result ?? "(null \u2014 will use defaultKey)");
+  groupEnd();
+  return result;
 }
 async function callViaEdgeProxy(config, context, componentRef, pageRoute) {
   const base = context.edgeProxyUrl.replace(/\/$/, "");
@@ -260,6 +390,8 @@ async function callViaEdgeProxy(config, context, componentRef, pageRoute) {
     if (pageRoute) params.pageRoute = pageRoute;
     body.params = params;
   }
+  log("Edge proxy POST", url);
+  log("Request body:", body);
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), context.timeout);
   try {
@@ -270,10 +402,18 @@ async function callViaEdgeProxy(config, context, componentRef, pageRoute) {
       signal: controller.signal
     });
     clearTimeout(timeoutId);
-    if (!res.ok) return null;
-    return extractContentKey(await res.json());
-  } catch {
+    log("Edge proxy response status:", res.status);
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      warn("Edge proxy non-OK response:", res.status, text);
+      return null;
+    }
+    const data = await res.json();
+    log("Edge proxy response body:", data);
+    return extractContentKey(data);
+  } catch (e) {
     clearTimeout(timeoutId);
+    error("Edge proxy fetch error:", e);
     return null;
   }
 }
@@ -292,20 +432,31 @@ async function callViaLegacy(config, context, apiBase, componentRef, pageRoute)
     if (componentRef) body.params.componentRef = componentRef;
     if (pageRoute) body.params.pageRoute = pageRoute;
   }
+  const url = `${apiBase.replace(/\/$/, "")}/v2/callFlows`;
+  log("Legacy POST", url);
+  log("Request body:", body);
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), context.timeout);
   try {
-    const res = await fetch(`${apiBase.replace(/\/$/, "")}/v2/callFlows`, {
+    const res = await fetch(url, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(body),
       signal: controller.signal
     });
     clearTimeout(timeoutId);
-    if (!res.ok) return null;
-    return extractContentKey(await res.json());
-  } catch {
+    log("Legacy response status:", res.status);
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      warn("Legacy non-OK response:", res.status, text);
+      return null;
+    }
+    const data = await res.json();
+    log("Legacy response body:", data);
+    return extractContentKey(data);
+  } catch (e) {
     clearTimeout(timeoutId);
+    error("Legacy fetch error:", e);
     return null;
   }
 }
@@ -319,14 +470,29 @@ function extractContentKey(data) {
 // src/contentResolver.ts
 async function resolveContent(options) {
   const { contentKey, config, resolveDatasource } = options;
-  const effectiveKey = contentKey && contentKey in config.contentMap ? contentKey : config.defaultKey;
+  const keyInMap = contentKey && contentKey in config.contentMap;
+  const effectiveKey = keyInMap ? contentKey : config.defaultKey;
+  if (!keyInMap) {
+    warn(
+      `Content key "${contentKey}" not found in contentMap [${Object.keys(config.contentMap).join(", ")}], falling back to defaultKey "${config.defaultKey}"`
+    );
+  }
   const datasourceId = config.contentMap[effectiveKey];
-  if (!datasourceId || typeof datasourceId !== "string") return null;
+  log("Resolving datasource:", { effectiveKey, datasourceId });
+  if (!datasourceId || typeof datasourceId !== "string") {
+    warn(`No datasource ID for key "${effectiveKey}" \u2014 contentMap may be misconfigured`);
+    return null;
+  }
   try {
     const fields = await resolveDatasource(datasourceId);
-    if (!fields || typeof fields !== "object") return null;
+    if (!fields || typeof fields !== "object") {
+      warn("resolveDatasource returned empty/invalid fields for", datasourceId);
+      return null;
+    }
+    log("Datasource resolved:", { datasourceId, fieldNames: Object.keys(fields) });
     return { datasourceId, fields };
-  } catch {
+  } catch (e) {
+    error("resolveDatasource threw for", datasourceId, e);
     return null;
   }
 }
@@ -359,24 +525,46 @@ var INDICATOR_BADGE = {
   pointerEvents: "none"
 };
 function withPersonalizeConnect(WrappedComponent, getConfig = DEFAULT_GET_CONFIG) {
+  const componentName = WrappedComponent.displayName ?? WrappedComponent.name ?? "Component";
   function PersonalizeConnectWrapper(props) {
     const context = usePersonalizeContext();
     const config = getConfig(props);
     const [resolvedFields, setResolvedFields] = useState2(null);
     const mountedRef = useRef(true);
+    if (!config) {
+      log(`[${componentName}] No personalizeConnect config on rendering \u2014 passthrough`);
+    } else {
+      log(`[${componentName}] Config found:`, { friendlyId: config.friendlyId, defaultKey: config.defaultKey, keys: Object.keys(config.contentMap) });
+    }
+    if (!context) {
+      warn(`[${componentName}] PersonalizeContext is null \u2014 is PersonalizeProvider mounted?`);
+    }
     const runPersonalization = useCallback2(async () => {
       if (!config || !context) return;
+      group(`[${componentName}] personalization flow`);
+      log("Calling Personalize for experience:", config.friendlyId);
       const contentKey = await callPersonalize({ config, context });
-      if (!mountedRef.current) return;
+      if (!mountedRef.current) {
+        groupEnd();
+        return;
+      }
+      log("Resolving content for contentKey:", contentKey ?? "(null)");
       const resolved = await resolveContent({
         contentKey,
         config,
         resolveDatasource: context.resolveDatasource
       });
-      if (!mountedRef.current) return;
+      if (!mountedRef.current) {
+        groupEnd();
+        return;
+      }
       if (resolved) {
+        log(`[${componentName}] Fields resolved \u2014 swapping props.fields`, { datasourceId: resolved.datasourceId, fieldNames: Object.keys(resolved.fields) });
         setResolvedFields(resolved.fields);
+      } else {
+        warn(`[${componentName}] Content resolution returned null \u2014 component keeps original fields`);
       }
+      groupEnd();
     }, [config, context]);
     useEffect2(() => {
       mountedRef.current = true;
@@ -393,6 +581,7 @@ function withPersonalizeConnect(WrappedComponent, getConfig = DEFAULT_GET_CONFIG
     const mergedProps = resolvedFields ? { ...props, fields: resolvedFields } : props;
     const component = /* @__PURE__ */ jsx2(WrappedComponent, { ...mergedProps });
     if (context.isEditing) {
+      log(`[${componentName}] Editing mode \u2014 rendering indicator badge`);
       return /* @__PURE__ */ jsxs("div", { style: INDICATOR_BORDER, "data-personalize-connect": config.friendlyId, children: [
         /* @__PURE__ */ jsx2("span", { style: INDICATOR_BADGE, title: `Personalize: ${config.friendlyId}`, children: "\u26A1 Personalized" }),
         component
@@ -400,7 +589,7 @@ function withPersonalizeConnect(WrappedComponent, getConfig = DEFAULT_GET_CONFIG
     }
     return component;
   }
-  PersonalizeConnectWrapper.displayName = `WithPersonalizeConnect(${WrappedComponent.displayName ?? WrappedComponent.name ?? "Component"})`;
+  PersonalizeConnectWrapper.displayName = `WithPersonalizeConnect(${componentName})`;
   return PersonalizeConnectWrapper;
 }
 
@@ -411,7 +600,7 @@ function usePersonalizeExperience(config) {
   const [contentKey, setContentKey] = useState3(null);
   const [resolvedFields, setResolvedFields] = useState3(null);
   const [isLoading, setIsLoading] = useState3(true);
-  const [error, setError] = useState3(null);
+  const [error2, setError] = useState3(null);
   const mountedRef = useRef2(true);
   const runPersonalization = useCallback3(async () => {
     if (!config || !context) {
@@ -452,7 +641,7 @@ function usePersonalizeExperience(config) {
     contentKey,
     resolvedFields,
     isLoading,
-    error
+    error: error2
   };
 }
 export {
@@ -462,10 +651,12 @@ export {
   createEdgeResolver,
   getBrowserId,
   getEdgeBrowserId,
+  isDebugEnabled,
   isEditingMode,
   resetEdgeInitCache,
   resetEditingDetectionCache,
   resolveContent,
+  setDebug,
   usePersonalizeContext,
   usePersonalizeExperience,
   withPersonalizeConnect

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "personalize-connect-sdk",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Runtime SDK for Personalize Connect - resolves active experience outcomes and datasources in your rendering host",
   "author": "Dylan Young",
   "keywords": [