@shopgate/engage 7.31.6 → 7.32.0-beta.10

package/admin-preview/components/FrontendSettingsPreviewBridge/helpers.js

@@ -0,0 +1,61 @@
+import "core-js/modules/es.string.replace.js";
+export const PREVIEW_STYLE_TAG_ID = 'frontend-settings-preview-overrides';
+const INSERTION_POINT_SELECTOR = 'meta[name="preview-css-insertion-point"]';
+const UNITLESS_PROPERTIES = new Set(['font-weight', 'line-height', 'opacity', 'z-index', 'flex', 'flex-grow', 'flex-shrink', 'order']);
+const toKebabCase = property => property.replace(/[A-Z]/g, character => `-${character.toLowerCase()}`);
+const stringifyValue = (property, value) => {
+  if (typeof value === 'string') return value;
+  if (value === 0) return '0';
+  if (property.startsWith('--') || UNITLESS_PROPERTIES.has(property)) return `${value}`;
+  return `${value}px`;
+};
+
+/**
+ * Converts selector/declaration maps from the preview payload into a CSS string.
+ *
+ * @param styling Selector-to-declarations map received from the admin preview.
+ * @returns Serialized CSS that can be assigned to a style tag.
+ */
+export const serializeStyling = styling => Object.entries(styling).map(([selector, declarations]) => {
+  const declarationString = Object.entries(declarations).map(([propertyName, value]) => {
+    const cssProperty = propertyName.startsWith('--') ? propertyName : toKebabCase(propertyName);
+    return `${cssProperty}: ${stringifyValue(cssProperty, value)};`;
+  }).join(' ');
+  if (!declarationString) return '';
+  return `${selector} { ${declarationString} }`;
+}).filter(Boolean).join('\n');
+
+/**
+ * Returns the existing preview style tag or creates it at the preview css insertion point, which
+ * the html template declares directly below the theme css one. The preview has to override both
+ * the defaults that theme initialization generates and the theme css file, and since all three
+ * have the same specificity, only document order decides.
+ *
+ * Falls back to appending when the meta is absent, which is where the tag used to live before the
+ * insertion points existed.
+ *
+ * @returns The style element used for frontend settings preview overrides.
+ */
+export const getOrCreateStyleTag = () => {
+  let styleTag = document.querySelector(`#${PREVIEW_STYLE_TAG_ID}`);
+  if (!styleTag) {
+    styleTag = document.createElement('style');
+    styleTag.setAttribute('id', PREVIEW_STYLE_TAG_ID);
+    styleTag.setAttribute('type', 'text/css');
+    const insertionPoint = document.querySelector(INSERTION_POINT_SELECTOR);
+    if (insertionPoint) {
+      insertionPoint.parentNode?.insertBefore(styleTag, insertionPoint.nextSibling);
+    } else {
+      document.head.appendChild(styleTag);
+    }
+  }
+  return styleTag;
+};
+
+/**
+ * Removes the preview override style tag from the document head if it exists.
+ */
+export const removeStyleTag = () => {
+  const styleTag = document.querySelector(`#${PREVIEW_STYLE_TAG_ID}`);
+  styleTag?.remove();
+};

package/admin-preview/components/FrontendSettingsPreviewBridge/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './FrontendSettingsPreviewBridge';
+//# sourceMappingURL=index.d.ts.map

package/admin-preview/components/FrontendSettingsPreviewBridge/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../admin-preview/components/FrontendSettingsPreviewBridge/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC"}

package/admin-preview/components/FrontendSettingsPreviewBridge/index.js

@@ -0,0 +1 @@
+export { default } from "./FrontendSettingsPreviewBridge";

package/admin-preview/components/FrontendSettingsPreviewBridge/types.d.ts

@@ -0,0 +1,27 @@
+import type { AppSettingsPayload } from '@shopgate/engage/settings/types/appSettings';
+import type { ColorSchemeName } from '@shopgate/engage/styles/theme/createTheme';
+export type CSSDeclarationValue = string | number;
+export type FrontendSettingsStyling = Record<string, Record<string, CSSDeclarationValue>>;
+export type FrontendSettingsPreviewBridgeMessage = {
+    type: 'receiveFrontendSettings';
+    payload?: {
+        styling?: FrontendSettingsStyling;
+        appSettings?: AppSettingsPayload;
+    };
+} | {
+    type: 'setColorScheme';
+    payload: {
+        colorScheme: ColorSchemeName;
+    };
+} | {
+    type: 'frontendSettingsPreviewReady';
+    payload?: never;
+} | {
+    /**
+     * Outbound. Announces that the first settings payload has been applied and the app rendered
+     * with it, so the admin can drop the loading overlay it shows while the preview boots.
+     */
+    type: 'frontendSettingsPreviewApplied';
+    payload?: never;
+};
+//# sourceMappingURL=types.d.ts.map

package/admin-preview/components/FrontendSettingsPreviewBridge/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../admin-preview/components/FrontendSettingsPreviewBridge/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6CAA6C,CAAC;AACtF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2CAA2C,CAAC;AAEjF,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,MAAM,CAAC;AAClD,MAAM,MAAM,uBAAuB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC;AAE1F,MAAM,MAAM,oCAAoC,GAC5C;IACA,IAAI,EAAE,yBAAyB,CAAC;IAChC,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,uBAAuB,CAAC;QAClC,WAAW,CAAC,EAAE,kBAAkB,CAAC;KAClC,CAAC;CACH,GACC;IACA,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE;QACP,WAAW,EAAE,eAAe,CAAC;KAC9B,CAAC;CACH,GACC;IACA,IAAI,EAAE,8BAA8B,CAAC;IACrC,OAAO,CAAC,EAAE,KAAK,CAAC;CACjB,GACC;IACA;;;OAGG;IACH,IAAI,EAAE,gCAAgC,CAAC;IACvC,OAAO,CAAC,EAAE,KAAK,CAAC;CACjB,CAAC"}

package/admin-preview/components/FrontendSettingsPreviewBridge/types.js

@@ -0,0 +1 @@
+export {};

package/admin-preview/components/index.d.ts

@@ -0,0 +1,2 @@
+export { default as FrontendSettingsPreviewBridge } from './FrontendSettingsPreviewBridge';
+//# sourceMappingURL=index.d.ts.map

package/admin-preview/components/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../admin-preview/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,6BAA6B,EAAE,MAAM,iCAAiC,CAAC"}

package/admin-preview/components/index.js

@@ -0,0 +1 @@
+export { default as FrontendSettingsPreviewBridge } from "./FrontendSettingsPreviewBridge";

package/admin-preview/constants/index.d.ts

@@ -0,0 +1,6 @@
+export declare const PAGE_PREVIEW_PATTERN = "/shopgate-internal-page-preview";
+/**
+ * List of allowed origins for cms page preview iFrame communication.
+ */
+export declare const ALLOWED_ADMIN_PREVIEW_ORIGINS: string[];
+//# sourceMappingURL=index.d.ts.map

package/admin-preview/constants/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../admin-preview/constants/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,oCAAoC,CAAC;AAEtE;;GAEG;AACH,eAAO,MAAM,6BAA6B,UAMzC,CAAC"}

package/admin-preview/constants/index.js

@@ -0,0 +1,6 @@
+export const PAGE_PREVIEW_PATTERN = '/shopgate-internal-page-preview';
+
+/**
+ * List of allowed origins for cms page preview iFrame communication.
+ */
+export const ALLOWED_ADMIN_PREVIEW_ORIGINS = ['https://next.admin.shopgatedev.com', 'https://next.admin.shopgatepg.com', 'https://next.admin.shopgate.com', 'https://next.us.admin.shopgate.com', 'http://localhost:1337'];

package/admin-preview/helpers/_internal/detection.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Internal to the admin-preview package - do not import this module from anywhere else. Consume
+ * the isAdminPreviewActive / isPageAdminPreviewActive / isFrontendSettingsAdminPreviewActive
+ * helpers from @shopgate/engage/admin-preview/helpers instead.
+ */
+export declare const FRONTEND_SETTINGS_PREVIEW_PARAM = "frontendSettingsPreview=true";
+/**
+ * Detects whether the app is in page admin preview mode. Once detected, the result is latched for
+ * the lifetime of the document, because the url is not guaranteed to keep the preview marker.
+ * @returns True if the app is in page admin preview mode, false otherwise.
+ */
+export declare const detectPageAdminPreview: () => boolean;
+/**
+ * Detects whether the app is in frontend settings admin preview mode. Once detected, the result is
+ * latched for the lifetime of the document, because the app keeps navigating while the preview is
+ * open and the query param only exists on the url it started on.
+ * @returns True if the app is in frontend settings admin preview mode, false otherwise.
+ */
+export declare const detectFrontendSettingsAdminPreview: () => boolean;
+/**
+ * Detects whether the app is in admin preview mode (pages or frontend settings).
+ * @returns True if the app is in admin preview mode, false otherwise.
+ */
+export declare const detectAdminPreview: () => boolean;
+/**
+ * Returns the current detection state. Exposed on window as SGAdminPreviewDebug so the values can
+ * be inspected on a deployed build, from the console of the preview iframe:
+ *
+ *   window.SGAdminPreviewDebug()
+ *
+ * Compare initialHref with currentHref to see whether the url changed since the app booted, and
+ * check latched to see whether a result came from the latch rather than the current url.
+ * @returns A snapshot of everything detection depends on.
+ */
+export declare const getAdminPreviewDebugInfo: () => {
+    initialHref: string;
+    currentHref: string;
+    pathname: string;
+    search: string;
+    urlChangedSinceBoot: boolean;
+    isInIframe: boolean;
+    referrer: string;
+    latched: {
+        page: boolean;
+        frontendSettings: boolean;
+    };
+    detected: {
+        page: boolean;
+        frontendSettings: boolean;
+        any: boolean;
+    };
+};
+//# sourceMappingURL=detection.d.ts.map

package/admin-preview/helpers/_internal/detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detection.d.ts","sourceRoot":"","sources":["../../../../admin-preview/helpers/_internal/detection.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,eAAO,MAAM,+BAA+B,iCAAiC,CAAC;AAsB9E;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,QAAO,OAQzC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC,QAAO,OAWrD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,QAAO,OAC4B,CAAC;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;CAiBnC,CAAC"}

package/admin-preview/helpers/_internal/detection.js

@@ -0,0 +1,93 @@
+import "core-js/modules/es.array.includes.js";
+/**
+ * Internal to the admin-preview package - do not import this module from anywhere else. Consume
+ * the isAdminPreviewActive / isPageAdminPreviewActive / isFrontendSettingsAdminPreviewActive
+ * helpers from @shopgate/engage/admin-preview/helpers instead.
+ */
+
+import { PAGE_PREVIEW_PATTERN } from "../../constants";
+export const FRONTEND_SETTINGS_PREVIEW_PARAM = 'frontendSettingsPreview=true';
+
+/**
+ * The url as it was when this module was first evaluated. Captured here because detection can run
+ * again later, when the url may already have been rewritten.
+ */
+const INITIAL_HREF = window.location.href;
+
+/**
+ * Preview mode is latched in memory rather than persisted. Session storage is scoped per origin
+ * per tab, not per iframe - the admin shows the preview in same-origin iframes on several screens
+ * within one tab, so a persisted flag from one screen would leak into the next. Module state is
+ * per document, so each iframe gets its own.
+ *
+ * The latches only ever go false -> true. Detection must not fall back to re-reading the url,
+ * because the frontend settings preview navigates the app normally: once the admin opens another
+ * page, the query param is gone from the url even though preview mode is still on.
+ */
+let pageAdminPreviewLatched = false;
+let frontendSettingsAdminPreviewLatched = false;
+
+/**
+ * Detects whether the app is in page admin preview mode. Once detected, the result is latched for
+ * the lifetime of the document, because the url is not guaranteed to keep the preview marker.
+ * @returns True if the app is in page admin preview mode, false otherwise.
+ */
+export const detectPageAdminPreview = () => {
+  if (pageAdminPreviewLatched) {
+    return true;
+  }
+  pageAdminPreviewLatched = window.location.pathname.startsWith(PAGE_PREVIEW_PATTERN);
+  return pageAdminPreviewLatched;
+};
+
+/**
+ * Detects whether the app is in frontend settings admin preview mode. Once detected, the result is
+ * latched for the lifetime of the document, because the app keeps navigating while the preview is
+ * open and the query param only exists on the url it started on.
+ * @returns True if the app is in frontend settings admin preview mode, false otherwise.
+ */
+export const detectFrontendSettingsAdminPreview = () => {
+  if (frontendSettingsAdminPreviewLatched) {
+    return true;
+  }
+  frontendSettingsAdminPreviewLatched = window.location.search.includes(FRONTEND_SETTINGS_PREVIEW_PARAM);
+  return frontendSettingsAdminPreviewLatched;
+};
+
+/**
+ * Detects whether the app is in admin preview mode (pages or frontend settings).
+ * @returns True if the app is in admin preview mode, false otherwise.
+ */
+export const detectAdminPreview = () => detectPageAdminPreview() || detectFrontendSettingsAdminPreview();
+
+/**
+ * Returns the current detection state. Exposed on window as SGAdminPreviewDebug so the values can
+ * be inspected on a deployed build, from the console of the preview iframe:
+ *
+ *   window.SGAdminPreviewDebug()
+ *
+ * Compare initialHref with currentHref to see whether the url changed since the app booted, and
+ * check latched to see whether a result came from the latch rather than the current url.
+ * @returns A snapshot of everything detection depends on.
+ */
+export const getAdminPreviewDebugInfo = () => ({
+  initialHref: INITIAL_HREF,
+  currentHref: window.location.href,
+  pathname: window.location.pathname,
+  search: window.location.search,
+  urlChangedSinceBoot: INITIAL_HREF !== window.location.href,
+  isInIframe: window.parent !== window,
+  referrer: document.referrer,
+  latched: {
+    page: pageAdminPreviewLatched,
+    frontendSettings: frontendSettingsAdminPreviewLatched
+  },
+  detected: {
+    page: detectPageAdminPreview(),
+    frontendSettings: detectFrontendSettingsAdminPreview(),
+    any: detectAdminPreview()
+  }
+});
+
+// @ts-expect-error - debug-only global, intentionally not on the Window type.
+window.SGAdminPreviewDebug = getAdminPreviewDebugInfo;

package/admin-preview/helpers/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Checks if the app is currently in admin preview mode (pages or frontend settings).
+ * @returns True if the app is in admin preview mode, false otherwise.
+ */
+export declare const isAdminPreviewActive: () => boolean;
+/**
+ * Checks if the app is currently in page admin preview mode.
+ * @returns True if the app is in page admin preview mode, false otherwise.
+ */
+export declare const isPageAdminPreviewActive: () => boolean;
+/**
+ * Checks if the app is currently in frontend settings admin preview mode.
+ * @returns True if the app is in frontend settings admin preview mode, false otherwise.
+ */
+export declare const isFrontendSettingsAdminPreviewActive: () => boolean;
+/**
+ * Checks if navigation is blocked. Page admin preview renders a single page in an iframe, so
+ * leaving that page would only ever show the admin something it did not ask to preview.
+ * Frontend settings preview is not affected - it previews styling on the regular app.
+ * @returns True if the app must not navigate, false otherwise.
+ */
+export declare const isNavigationBlocked: () => boolean;
+//# sourceMappingURL=index.d.ts.map

package/admin-preview/helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../admin-preview/helpers/index.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,eAAO,MAAM,oBAAoB,QAAO,OAClB,CAAC;AAEvB;;;GAGG;AACH,eAAO,MAAM,wBAAwB,QAAO,OAClB,CAAC;AAE3B;;;GAGG;AACH,eAAO,MAAM,oCAAoC,QAAO,OAClB,CAAC;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAAO,OACX,CAAC"}

package/admin-preview/helpers/index.js

@@ -0,0 +1,27 @@
+import { detectAdminPreview, detectFrontendSettingsAdminPreview, detectPageAdminPreview } from "./_internal/detection";
+
+/**
+ * Checks if the app is currently in admin preview mode (pages or frontend settings).
+ * @returns True if the app is in admin preview mode, false otherwise.
+ */
+export const isAdminPreviewActive = () => detectAdminPreview();
+
+/**
+ * Checks if the app is currently in page admin preview mode.
+ * @returns True if the app is in page admin preview mode, false otherwise.
+ */
+export const isPageAdminPreviewActive = () => detectPageAdminPreview();
+
+/**
+ * Checks if the app is currently in frontend settings admin preview mode.
+ * @returns True if the app is in frontend settings admin preview mode, false otherwise.
+ */
+export const isFrontendSettingsAdminPreviewActive = () => detectFrontendSettingsAdminPreview();
+
+/**
+ * Checks if navigation is blocked. Page admin preview renders a single page in an iframe, so
+ * leaving that page would only ever show the admin something it did not ask to preview.
+ * Frontend settings preview is not affected - it previews styling on the regular app.
+ * @returns True if the app must not navigate, false otherwise.
+ */
+export const isNavigationBlocked = () => isPageAdminPreviewActive();

package/admin-preview/hooks/index.d.ts

@@ -0,0 +1,36 @@
+export interface MessageData {
+    /**
+     * Identifier for the kind of message.
+     */
+    type: string;
+    /**
+     * Optional data payload for this message.
+     */
+    payload?: unknown;
+}
+export type OnIframeMessage<TMessage extends MessageData = MessageData> = (data: TMessage, rawEvent: MessageEvent<TMessage>) => void;
+export interface IframeMessengerResult<TMessage extends MessageData = MessageData> {
+    /**
+     * Send data up to window.parent.
+     * If targetOrigin is omitted, uses the most recently seen origin
+     * (from an incoming message). If none was seen yet, falls back to
+     * the origin derived from document.referrer, then parentOrigins[0], then "*".
+     */
+    sendToParent: (data: TMessage, targetOrigin?: string) => void;
+}
+/**
+ * Hook for postMessage communication when your component is inside an iframe.
+ *
+ * Listens on window for "message" events from any origin in parentOrigins,
+ * and only calls onMessage(data, rawEvent) if both origin and source match.
+ *
+ * @param onMessage Callback invoked when a trusted message arrives.
+ * Receives data and the raw event so consumers can inspect origin, source,
+ * and other metadata when needed.
+ * @param parentOrigins Array of allowed parent origin strings, e.g.
+ * ['https://a.example.com', 'https://b.example.com'].
+ * @returns An object with a single method:
+ * sendToParent(data, [targetOrigin]) to post data to the parent window.
+ */
+export declare function useIframeMessenger<TMessage extends MessageData = MessageData>(onMessage: OnIframeMessage<TMessage>, parentOrigins: string[]): IframeMessengerResult<TMessage>;
+//# sourceMappingURL=index.d.ts.map

package/admin-preview/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../admin-preview/hooks/index.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,eAAe,CAAC,QAAQ,SAAS,WAAW,GAAG,WAAW,IAAI,CACxE,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC,KAC7B,IAAI,CAAC;AAEV,MAAM,WAAW,qBAAqB,CAAC,QAAQ,SAAS,WAAW,GAAG,WAAW;IAC/E;;;;;OAKG;IACH,YAAY,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,SAAS,WAAW,GAAG,WAAW,EAC3E,SAAS,EAAE,eAAe,CAAC,QAAQ,CAAC,EACpC,aAAa,EAAE,MAAM,EAAE,GACtB,qBAAqB,CAAC,QAAQ,CAAC,CAmEjC"}

package/admin-preview/hooks/index.js

@@ -0,0 +1,74 @@
+import "core-js/modules/es.array.includes.js";
+import "core-js/modules/web.url.js";
+import "core-js/modules/web.url.to-json.js";
+import "core-js/modules/web.url-search-params.js";
+import { useCallback, useEffect, useRef } from 'react';
+import { logger } from '@shopgate/engage/core/helpers';
+/**
+ * Hook for postMessage communication when your component is inside an iframe.
+ *
+ * Listens on window for "message" events from any origin in parentOrigins,
+ * and only calls onMessage(data, rawEvent) if both origin and source match.
+ *
+ * @param onMessage Callback invoked when a trusted message arrives.
+ * Receives data and the raw event so consumers can inspect origin, source,
+ * and other metadata when needed.
+ * @param parentOrigins Array of allowed parent origin strings, e.g.
+ * ['https://a.example.com', 'https://b.example.com'].
+ * @returns An object with a single method:
+ * sendToParent(data, [targetOrigin]) to post data to the parent window.
+ */
+export function useIframeMessenger(onMessage, parentOrigins) {
+  // Keep a ref to the latest onMessage callback so the listener always has it.
+  const onMessageRef = useRef(onMessage);
+  useEffect(() => {
+    onMessageRef.current = onMessage;
+  }, [onMessage]);
+
+  // Keep track of the last allowed origin we heard from
+  const lastOriginRef = useRef(null);
+
+  /**
+   * Send a message up to the parent window.
+   * @param data - The data object to post.
+   * @param targetOrigin Optional override for the origin to post to.
+   * If omitted, uses the last seen origin, then referrer origin,
+   * then parentOrigins[0], then "*".
+   */
+  const sendToParent = useCallback((data, targetOrigin) => {
+    // Determine which origin to use: explicit, then last seen, then first, then "*".
+    const originToUse = typeof targetOrigin === 'string' ? targetOrigin : lastOriginRef.current ?? (document.referrer ? new URL(document.referrer).origin : undefined) ?? parentOrigins[0] ?? '*';
+    if (!originToUse) {
+      logger.warn('useIframeMessenger: no targetOrigin available. ' + 'Provide parentOrigins or pass targetOrigin.');
+      return;
+    }
+    window.parent.postMessage(data, originToUse);
+  }, [parentOrigins]);
+
+  // Attach / detach the "message" listener.
+  useEffect(() => {
+    /**
+     * Handler for incoming postMessage events.
+     * @param rawEvent The original MessageEvent object.
+     */
+    function handler(rawEvent) {
+      // Only proceed if the origin is in our whitelist.
+      if (!parentOrigins.includes(rawEvent.origin)) return;
+      // Ensure the message actually came from window.parent.
+      if (rawEvent.source !== window.parent) return;
+
+      // Record this origin as most recently seen.
+      lastOriginRef.current = rawEvent.origin;
+
+      // Forward the event.data and the raw event to the callback.
+      onMessageRef.current(rawEvent.data, rawEvent);
+    }
+    window.addEventListener('message', handler);
+    return () => {
+      window.removeEventListener('message', handler);
+    };
+  }, [parentOrigins, sendToParent]);
+  return {
+    sendToParent
+  };
+}

package/admin-preview/initialization/_internal/initialFrontendSettings.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Internal to the admin-preview package - do not import this module from anywhere else.
+ *
+ * Hands the payload that `awaitInitialFrontendSettings` received over to the
+ * FrontendSettingsPreviewBridge, which mounts long after app start finished. Module state rather
+ * than a store slice, because the styling map never belongs in redux - it is applied to a style
+ * tag, and the bridge only needs it to avoid removing what app start already applied.
+ */
+import type { FrontendSettingsStyling } from '../../components/FrontendSettingsPreviewBridge/types';
+/**
+ * Records the payload that app start received.
+ * @param initialStyling The styling map the payload carried, if any.
+ */
+export declare const setInitialFrontendSettings: (initialStyling: FrontendSettingsStyling | null) => void;
+/**
+ * Whether app start received a payload. A payload without a styling map still counts - it
+ * carried app settings, which is enough to consider the preview applied.
+ * @returns True when a payload arrived during app start.
+ */
+export declare const hasInitialFrontendSettings: () => boolean;
+/**
+ * The styling map that app start applied, so the bridge can seed its state with it instead of
+ * starting at null - which would make its first effect remove the style tag again.
+ * @returns The styling map, or null when none arrived.
+ */
+export declare const getInitialFrontendSettingsStyling: () => FrontendSettingsStyling | null;
+/**
+ * Test only. Module state outlives a test file's individual cases, so specs need a way back to the
+ * initial state.
+ */
+export declare const resetInitialFrontendSettings: () => void;
+//# sourceMappingURL=initialFrontendSettings.d.ts.map

package/admin-preview/initialization/_internal/initialFrontendSettings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"initialFrontendSettings.d.ts","sourceRoot":"","sources":["../../../../admin-preview/initialization/_internal/initialFrontendSettings.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sDAAsD,CAAC;AAMpG;;;GAGG;AACH,eAAO,MAAM,0BAA0B,GAAI,gBAAgB,uBAAuB,GAAG,IAAI,SAGxF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,QAAO,OAAmB,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,QAAO,uBAAuB,GAAG,IAAe,CAAC;AAE/F;;;GAGG;AACH,eAAO,MAAM,4BAA4B,YAGxC,CAAC"}

package/admin-preview/initialization/_internal/initialFrontendSettings.js

@@ -0,0 +1,43 @@
+/**
+ * Internal to the admin-preview package - do not import this module from anywhere else.
+ *
+ * Hands the payload that `awaitInitialFrontendSettings` received over to the
+ * FrontendSettingsPreviewBridge, which mounts long after app start finished. Module state rather
+ * than a store slice, because the styling map never belongs in redux - it is applied to a style
+ * tag, and the bridge only needs it to avoid removing what app start already applied.
+ */
+
+let received = false;
+let styling = null;
+
+/**
+ * Records the payload that app start received.
+ * @param initialStyling The styling map the payload carried, if any.
+ */
+export const setInitialFrontendSettings = initialStyling => {
+  received = true;
+  styling = initialStyling;
+};
+
+/**
+ * Whether app start received a payload. A payload without a styling map still counts - it
+ * carried app settings, which is enough to consider the preview applied.
+ * @returns True when a payload arrived during app start.
+ */
+export const hasInitialFrontendSettings = () => received;
+
+/**
+ * The styling map that app start applied, so the bridge can seed its state with it instead of
+ * starting at null - which would make its first effect remove the style tag again.
+ * @returns The styling map, or null when none arrived.
+ */
+export const getInitialFrontendSettingsStyling = () => styling;
+
+/**
+ * Test only. Module state outlives a test file's individual cases, so specs need a way back to the
+ * initial state.
+ */
+export const resetInitialFrontendSettings = () => {
+  received = false;
+  styling = null;
+};

package/admin-preview/initialization/awaitInitialFrontendSettings.d.ts

@@ -0,0 +1,22 @@
+interface PreviewStore {
+    dispatch: (action: unknown) => void;
+}
+/**
+ * Waits for the first settings message from the admin and applies it before the app renders.
+ *
+ * Without this the app paints with the theme defaults first: the bridge that owns the message
+ * listener only mounts once React committed, so everything the admin sent before that is dropped
+ * and the styling arrives as a visible restyle.
+ *
+ * The handshake goes to every allowed origin rather than to a single guessed one. Nothing has been
+ * received at this point, so there is no known parent origin, and the referrer is not guaranteed to
+ * survive the admin's referrer policy. The browser drops the copies whose target does not match.
+ *
+ * Resolves when the payload arrived or when REQUEST_TIMEOUT elapsed, and never rejects - an admin
+ * that stays silent has to fall back to the unstyled app, never to an iframe that never renders.
+ * @param store Reference to the store.
+ * @returns A promise that resolves once the first payload settled.
+ */
+export declare const awaitInitialFrontendSettings: (store: PreviewStore) => Promise<void>;
+export {};
+//# sourceMappingURL=awaitInitialFrontendSettings.d.ts.map

package/admin-preview/initialization/awaitInitialFrontendSettings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"awaitInitialFrontendSettings.d.ts","sourceRoot":"","sources":["../../../admin-preview/initialization/awaitInitialFrontendSettings.ts"],"names":[],"mappings":"AAmBA,UAAU,YAAY;IACpB,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CACrC;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,GAAI,OAAO,YAAY,KAAG,OAAO,CAAC,IAAI,CAqE3E,CAAC"}