@liquidcommerce/elements-sdk 2.7.23 → 2.7.25

package/dist/types/core/google-tag-manager.service.d.ts

@@ -63,6 +63,7 @@ export declare class GoogleTagManagerService {
     private readonly clientConfigService;
     constructor();
     static getInstance(): GoogleTagManagerService;
+    private isGTMEnabledEnvironment;
     private waitForDOMReady;
     private isGTMAlreadyLoaded;
     private isContainerLoaded;

package/dist/types/interfaces/configs/global.interface.d.ts

@@ -40,6 +40,8 @@ export interface IGlobalLayout {
     personalizationCardStyle: 'outlined' | 'filled';
     allowPromoCodes: boolean;
     inputFieldStyle: 'outlined' | 'filled';
+    enableOrderedProductSizes: boolean;
+    orderedProductSizes: string[];
     showPoweredBy: boolean;
     poweredByMode: 'light' | 'dark';
 }

package/dist/types/modules/product/components/product-image-carousel.component.d.ts

@@ -8,6 +8,7 @@ export interface IImageCarouselParams {
 export declare class ProductImageCarouselComponent extends BaseComponent<IImageCarouselParams, IProductComponent> {
     get hostClasses(): string[];
     private mainImageElement;
+    private mainImageMediaElement;
     private galleryViewport;
     private galleryContainer;
     private thumbnails;

package/dist/types/modules/product-list/components/product-list-product-pre-cart.component.d.ts

@@ -5,6 +5,7 @@ export interface IProductListProductPreCartComponentParams {
     productId: string;
 }
 export declare class ProductListProductPreCartComponent extends BaseComponent<IProductListProductPreCartComponentParams, IProductListComponent> {
+    get hostClasses(): string[];
     private showRetailersContent;
     private showEngravingForm;
     private isInitialRender;

package/dist/types/utils/image-bg-removal.d.ts

@@ -0,0 +1,3 @@
+export declare const IMG_BG_REMOVAL_HOST_CLASS = "lc-bg-removal";
+export declare function applyImageBackgroundTreatment(target: HTMLElement | null, imageUrl: string | undefined | null, bgProbe?: Element): void;
+export declare const getImageBgRemovalStyles: () => string;

package/docs/v1/api/actions/cart-actions.md

@@ -169,11 +169,16 @@ applyPromoCode(promoCode: string): Promise<void>
 ### Example
 
 ```javascript
+// Listen for the outcome — an invalid code surfaces here, not as a rejection
+window.addEventListener('lce:actions.cart_promo_code_failed', (event) => {
+  console.error('Invalid promo code:', event.detail.data);
+});
+
 try {
   await window.LiquidCommerce.elements.actions.cart.applyPromoCode('SUMMER20');
-  console.log('Promo code applied successfully');
 } catch (error) {
-  console.error('Invalid promo code:', error);
+  // Only reached on unexpected errors, not for an invalid code
+  console.error('Failed to apply promo code:', error);
 }
 ```
 
@@ -183,6 +188,8 @@ try {
 - Promo codes must be enabled in configuration
 - Only one promo code can be active at a time
 - Applying a new code replaces the existing one
+- An invalid/rejected code does **not** reject the promise — the failure is surfaced via the `lce:actions.cart_promo_code_failed` event. Listen for that event to handle invalid codes.
+- An empty or whitespace-only code is a silent no-op: it sets a `cart.error` on the store and returns without throwing.
 
 ---
 

package/docs/v1/api/actions/checkout-actions.md

@@ -4,6 +4,8 @@ Checkout actions allow you to programmatically control the checkout flow.
 
 ## Navigation Actions
 
+> **Note:** `openCheckout()`, `closeCheckout()`, and `toggleCheckout()` are only available on the full `Elements()` client's `actions.checkout`. They are **not** present on the checkout-only client (`ElementsCheckout()`), whose `actions.checkout` is typed `IElementsCheckoutActions = Omit<ICheckoutActions, 'openCheckout' | 'closeCheckout' | 'toggleCheckout'>`. The remaining checkout actions are available on both clients.
+
 ### actions.checkout.openCheckout()
 
 ```typescript

package/docs/v1/api/client.md

@@ -11,7 +11,7 @@ Initialize the full SDK client.
 ```typescript
 function Elements(
   apiKey: string,
-  config: ILiquidCommerceElementsConfig
+  config?: ILiquidCommerceElementsConfig
 ): Promise<ILiquidCommerceElementsClient | null>
 ```
 
@@ -20,7 +20,7 @@ function Elements(
 | Parameter | Type                          | Required | Description                 |
 |-----------|-------------------------------|----------|-----------------------------|
 | `apiKey`  | string                        | Yes      | Your LiquidCommerce API key |
-| `config`  | ILiquidCommerceElementsConfig | Yes      | Configuration object        |
+| `config`  | ILiquidCommerceElementsConfig | No       | Configuration object        |
 
 **Returns:** Promise that resolves to the client instance, or `null` if initialization fails.
 
@@ -43,7 +43,7 @@ Initialize the checkout-only client (tree-shaken build).
 ```typescript
 function ElementsCheckout(
   apiKey: string,
-  config: ILiquidCommerceElementsCheckoutClientConfig
+  config?: ILiquidCommerceElementsCheckoutClientConfig
 ): Promise<IElementsCheckoutClient | null>
 ```
 
@@ -52,7 +52,7 @@ function ElementsCheckout(
 | Parameter | Type                                        | Required | Description                 |
 |-----------|---------------------------------------------|----------|-----------------------------|
 | `apiKey`  | string                                      | Yes      | Your LiquidCommerce API key |
-| `config`  | ILiquidCommerceElementsCheckoutClientConfig | Yes      | Checkout configuration      |
+| `config`  | ILiquidCommerceElementsCheckoutClientConfig | No       | Checkout configuration      |
 
 **Example:**
 
@@ -71,7 +71,7 @@ Initialize the builder client, which exposes manual `inject*` / `update*` method
 ```typescript
 function ElementsBuilder(
   apiKey: string,
-  config: ILiquidCommerceElementsBuilderConfig
+  config?: ILiquidCommerceElementsBuilderConfig
 ): Promise<ILiquidCommerceElementsBuilderClient | null>
 ```
 
@@ -80,7 +80,7 @@ function ElementsBuilder(
 | Parameter | Type                                 | Required | Description                 |
 |-----------|--------------------------------------|----------|-----------------------------|
 | `apiKey`  | string                               | Yes      | Your LiquidCommerce API key |
-| `config`  | ILiquidCommerceElementsBuilderConfig | Yes      | Builder configuration object (same shape as `ILiquidCommerceElementsConfig`) |
+| `config`  | ILiquidCommerceElementsBuilderConfig | No       | Builder configuration object (same shape as `ILiquidCommerceElementsConfig`) |
 
 **Returns:** Promise that resolves to the builder client instance (`ILiquidCommerceElementsBuilderClient`), or `null` if initialization fails or it is called outside the browser.
 
@@ -296,6 +296,84 @@ interface ILiquidCommerceElementsClient {
 }
 ```
 
+### ILiquidCommerceElementsBuilderClient
+
+The builder client (returned by `ElementsBuilder()`) exposes the same `inject*` methods plus a set of `update*Component` methods for applying theme/layout changes at runtime:
+
+```typescript
+interface ILiquidCommerceElementsBuilderClient {
+  // Runtime theme/layout updates (builder-only)
+  updateComponentGlobalConfigs(configs: UpdateComponentGlobalConfigs): Promise<void>;
+  updateProductComponent(configs: UpdateProductComponent): Promise<void>;
+  updateAddressComponent(configs: UpdateAddressComponent): void;
+  updateCartComponent(configs: UpdateCartComponent): void;
+  updateCheckoutComponent(configs: UpdateCheckoutComponent): void;
+  updateProductListComponent(configs: UpdateProductListComponent): void;
+
+  // Injection methods
+  injectElement(params: IBuilderInjectElementParams): Promise<IInjectedComponent | null>;
+  injectProductElement(params: IInjectProductElement[]): Promise<IInjectedComponent[]>;
+  injectAddressElement(containerId: string, options?: IAddressOptions): Promise<IInjectedComponent | null>;
+  injectCartElement(containerId: string): Promise<IInjectedComponent | null>;
+  injectCheckoutElement(params: IInjectCheckoutBuilderParams): Promise<IInjectedComponent | null>;
+  injectProductList(params: IInjectProductListParams): Promise<void>;
+
+  // Actions
+  actions: ILiquidCommerceElementsActions;
+
+  // Cleanup
+  destroy(): void;
+}
+```
+
+#### Runtime theme updates (`update*Component`)
+
+These methods are **builder-only** — they exist on the client returned by `ElementsBuilder()` and are **not** available on the full `Elements()` client. Each method applies theme changes to its scope and, when the passed `configs` include a non-empty `layout`, triggers targeted rerenders of only the components affected by those layout fields.
+
+Return types are not uniform:
+
+- `updateComponentGlobalConfigs()` and `updateProductComponent()` return `Promise<void>` (they may await product rerenders) — `await` them.
+- `updateCartComponent()`, `updateCheckoutComponent()`, `updateAddressComponent()`, and `updateProductListComponent()` return `void` (synchronous).
+
+```javascript
+const builder = await ElementsBuilder('YOUR_API_KEY', { env: 'production' });
+
+// Asynchronous — await these
+await builder.updateComponentGlobalConfigs({
+  theme: { primaryColor: '#0a7d33', buttonCornerRadius: '8px' },
+  layout: { allowPromoCodes: true }
+});
+await builder.updateProductComponent({
+  theme: { backgroundColor: '#ffffff' },
+  layout: { addToCartButtonText: 'Add to bag' }
+});
+
+// Synchronous — no await needed
+builder.updateCartComponent({ layout: { drawerHeaderText: 'Your bag' } });
+builder.updateCheckoutComponent({ layout: { placeOrderButtonText: 'Pay now' } });
+```
+
+#### injectCheckoutElement (builder)
+
+The builder's `injectCheckoutElement()` accepts `IInjectCheckoutBuilderParams`, which extends `IInjectCheckoutParams` with two **preview-only** fields:
+
+```typescript
+interface IInjectCheckoutBuilderParams extends IInjectCheckoutParams {
+  simulatePresale?: boolean;         // simulate a presale lock in builder mode
+  presaleExpiresInMinutes?: number;  // minutes until the simulated lock expires (defaults to 15)
+}
+```
+
+`simulatePresale` and `presaleExpiresInMinutes` only take effect in the builder preview and have no counterpart on the full `Elements()` client's `injectCheckoutElement()`.
+
+```javascript
+await builder.injectCheckoutElement({
+  containerId: 'checkout',
+  simulatePresale: true,
+  presaleExpiresInMinutes: 30
+});
+```
+
 ## Methods Overview
 
 ### Injection Methods

package/docs/v1/api/configuration.md

@@ -30,6 +30,8 @@ interface ILiquidCommerceElementsConfig {
 | `proxy` | `IElementsProxyConfig` | No | Proxy configuration for API requests |
 | `development` | `ILiquidCommerceElementsDevelopmentConfig` | No | Development/testing options |
 
+> **Note:** `debugMode` (`'console'` or `'panel'`) is **ignored in production** -- it is forced off when `env` is `'production'`. It only takes effect in non-production environments (`'development'` / `'staging'`).
+
 ---
 
 ## Theme Configuration
@@ -100,6 +102,8 @@ interface IFontFamily {
 }
 ```
 
+> **Note:** Only Google Fonts are supported -- `name` must be a valid Google Fonts family. `Poppins` is always injected as the default font family in addition to any fonts you specify. Font loading requires network access to `fonts.googleapis.com` and `fonts.gstatic.com`; if you run behind a CSP or proxy, allow these hosts.
+
 #### IGlobalLayout
 
 ```typescript
@@ -109,6 +113,8 @@ interface IGlobalLayout {
   personalizationCardStyle: 'outlined' | 'filled';
   allowPromoCodes: boolean;
   inputFieldStyle: 'outlined' | 'filled';
+  enableOrderedProductSizes: boolean;
+  orderedProductSizes: string[];
   showPoweredBy: boolean;
   poweredByMode: 'light' | 'dark';
 }
@@ -121,9 +127,13 @@ interface IGlobalLayout {
 | `personalizationCardStyle` | `'outlined' \| 'filled'` | Visual style for personalization cards |
 | `allowPromoCodes` | `boolean` | Show promo code inputs in cart/checkout |
 | `inputFieldStyle` | `'outlined' \| 'filled'` | Visual style for input fields |
+| `enableOrderedProductSizes` | `boolean` | Enable a fixed display order for product/PLC size selectors (defined by `orderedProductSizes`) instead of the default ordering |
+| `orderedProductSizes` | `string[]` | Ordered list of size values controlling the sequence in which size selectors are rendered; changes trigger targeted rerenders of the affected size selectors |
 | `showPoweredBy` | `boolean` | Show "Powered by LiquidCommerce" badge |
 | `poweredByMode` | `'light' \| 'dark'` | Color mode for the powered-by badge |
 
+> **Note:** `showPoweredBy` is a server/plan-controlled setting and **cannot** be overridden by hosts. Any value supplied via `customTheme` (or a later config update) is stripped and the server value is restored. Only `poweredByMode` (`'light' \| 'dark'`) is host-overridable.
+
 **Example:**
 
 ```javascript

package/docs/v1/api/typescript-types.md

@@ -178,6 +178,8 @@ interface IInjectCheckoutParams {
 
 ### IInjectCheckoutBuilderParams
 
+`simulatePresale` and `presaleExpiresInMinutes` are builder-only preview controls (presale lock defaults to 15 minutes) and only take effect via `ElementsBuilder().injectCheckoutElement()`.
+
 ```typescript
 interface IInjectCheckoutBuilderParams extends IInjectCheckoutParams {
   simulatePresale?: boolean;
@@ -293,7 +295,7 @@ interface ILiquidCommerceElementsActions {
 
 ### IElementsCheckoutActions
 
-Checkout actions available in the checkout-only client. Omits drawer-related methods.
+Checkout actions available in the checkout-only client. This is `ICheckoutActions` with `openCheckout`, `closeCheckout`, and `toggleCheckout` omitted -- the checkout-only client renders checkout independently and has no drawer navigation to open, close, or toggle.
 
 ```typescript
 interface IElementsCheckoutActions extends Omit<ICheckoutActions, 'openCheckout' | 'closeCheckout' | 'toggleCheckout'> {}
@@ -378,6 +380,8 @@ interface UpdateProductListComponent {
 }
 ```
 
+These `Update*Component` types are the arguments to the `ElementsBuilder()` client's `update*Component` methods; see [Client API](./client.md) for their behavior and usage.
+
 See [Configuration Reference](./configuration.md) for detailed theme property descriptions.
 
 ---

package/docs/v1/getting-started/concepts.md

@@ -96,11 +96,11 @@ The SDK uses a two-phase initialization strategy for optimal performance:
 - Store initialization
 - Theme setup
 - Core component registration
-- Telemetry / logger wiring
+- Telemetry / logger wiring (see [Telemetry & Privacy](../reference/telemetry.md))
 - Debug panel (if enabled)
 
 **Phase 2: Deferred Services (next macrotask, via `setTimeout(…, 0)`)**
-- Analytics (Google Tag Manager)
+- Analytics (Google Tag Manager — see [Analytics (GTM/GA4)](../reference/analytics.md))
 - Cart pre-loading
 - Heavy component registration
 
@@ -368,10 +368,12 @@ const client = await Elements('YOUR_API_KEY', {
 ```
 
 **Debug Modes:**
-- `'none'` - No debug output (production default)
+- `'none'` - No debug output (default)
 - `'console'` - Log to browser console
 - `'panel'` - Show debug panel on page
 
+> **Production note:** `debugMode` has no effect when `env` is `'production'`. All debug output — console logging and the debug panel — is disabled in production regardless of the `debugMode` you pass. `'console'` and `'panel'` only take effect in non-production environments.
+
 ## Security & API Keys
 
 ### API Key Protection

package/docs/v1/getting-started/installation.md

@@ -30,6 +30,16 @@ Add the following script tag to your page's `<head>` section:
 ></script>
 ```
 
+> **Note:** The host `elements.reservebar-worker.workers.dev` shown above is an example, partner-specific endpoint. Use the CDN URL provided by your LiquidCommerce representative in place of this host.
+
+The path segment selects which bundle is served:
+
+| Path | Bundle |
+|------|--------|
+| `/all/elements.js` | Full SDK bundle (product, cart, checkout, and all other elements) |
+| `/checkout/elements.js` | Checkout-only bundle (tree-shaken, smaller) |
+| `/all/beta/elements.js` | Beta channel of the full SDK bundle |
+
 ### Script Attributes
 
 | Attribute | Required | Description |
@@ -140,7 +150,16 @@ const config: ILiquidCommerceElementsConfig = {
   }
 };
 
-const client: ILiquidCommerceElementsClient = await Elements('YOUR_API_KEY', config);
+// Elements() returns `null` in SSR / non-browser environments, so the
+// client is typed as `ILiquidCommerceElementsClient | null`.
+const client: ILiquidCommerceElementsClient | null = await Elements('YOUR_API_KEY', config);
+
+if (client) {
+  // Safe to use the client here
+  client.injectProductElement([
+    { containerId: 'product-1', identifier: '00619947000020' }
+  ]);
+}
 ```
 
 ## Framework Integration
@@ -255,6 +274,8 @@ const client = await Elements('YOUR_API_KEY', {
 });
 ```
 
+> **Note:** `debugMode` is ignored when `env` is `'production'`. Debug logging and the debug panel are only activated in non-production environments (`development` or `staging`).
+
 See [Configuration Reference](../api/configuration.md) for complete configuration options.
 
 ## Verification

package/docs/v1/guides/cart-component.md

@@ -6,6 +6,7 @@ The Cart component provides a slide-out drawer for managing shopping cart items,
 
 The Cart component automatically:
 - Displays cart items with images and details
+- Removes white / near-white backgrounds from item images so products blend into the drawer (automatic, not host-configurable)
 - Groups items by retailer
 - Shows real-time pricing and totals
 - Supports quantity updates
@@ -342,6 +343,17 @@ window.addEventListener('lce:actions.cart_item_quantity_decrease', (event) => {
 });
 ```
 
+### Engraving Updated
+
+Fired when a cart line item's engraving is added or edited from the drawer (see [Engraving](#engraving)):
+
+```javascript
+window.addEventListener('lce:actions.cart_item_engraving_updated', (event) => {
+  const { cartId, itemId, engravingLines, previousEngravingLines } = event.detail.data;
+  console.log(`Engraving updated for ${itemId}:`, engravingLines);
+});
+```
+
 ### Promo Code Events
 
 ```javascript
@@ -546,6 +558,26 @@ Items are automatically grouped by retailer in the cart:
 └─────────────────────────────────────┘
 ```
 
+## Order Minimums
+
+Retailers can require a minimum purchase amount before their items can be checked out. The cart enforces this per retailer:
+
+- When a retailer's minimum is not met, the cart drawer shows a per-retailer alert reading `+$X needed for order minimum`, where `$X` is the remaining amount required for that retailer.
+- The **Checkout** button is disabled until every retailer's minimum is met. (It is also disabled while the cart is loading/updating or when the cart is empty.)
+
+No configuration is required — the minimums are defined by each retailer and enforced automatically.
+
+## Engraving
+
+For engravable items, shoppers can add or edit engraving directly from a cart line item, without leaving the drawer.
+
+- If an engravable item has no engraving yet, the line item shows an **Add personalization** action (with the engraving fee) that opens the engraving form.
+- If the item already has engraving, its engraving is shown on the line item with an **Edit** button that reopens the form.
+
+The form respects the item's engraving constraints — `maxLines`, `maxCharsPerLine`, and the per-item `fee`. Saving emits [`lce:actions.cart_item_engraving_updated`](#engraving-updated) with the item's `engravingLines` and `previousEngravingLines`.
+
+**Note:** This in-drawer editing is distinct from the `engravingLines` array passed to [`addProduct`](#add-product-to-cart), which pre-fills engraving at the time an item is added.
+
 ## Checkout Navigation
 
 ### Checkout Drawer (Default)

package/docs/v1/guides/product-component.md

@@ -148,6 +148,8 @@ Products with multiple images display in an interactive carousel:
 - Thumbnail preview
 - Lazy loading for performance
 
+**Background removal:** Product images (the main detail image and the gallery) automatically have their white/near-white background removed so photos blend into the surrounding page background instead of sitting on a white box. The SDK picks the technique per image based on the host background — blending the white away on light backgrounds, or keying it out to true transparency on dark or transparent backgrounds — and skips SVG artwork, which is already transparent. This is applied automatically and is not currently host-configurable.
+
 ### Size Selection
 
 For products with multiple sizes:
@@ -206,8 +208,8 @@ For products with multiple retailers:
 
 **Popup View**
 - "See Delivery Options" button (shows the available fulfillment count, e.g. "See Delivery Options (3)")
-- Modal with full retailer list
-- Filter and search capabilities
+- Opens a plain, scrollable list of the available delivery/retailer options
+- No filtering or search — select a retailer from the list to choose it
 
 ### Personalization/Engraving
 
@@ -366,6 +368,7 @@ const client = await Elements('YOUR_API_KEY', {
         showOnlyMainImage: false,  // Show all images or just the main one
         showTitle: true,
         showDescription: true,
+        descriptionPosition: 'below',  // Description placement: 'above' or 'below'
         showQuantityCounter: true,
         showOffHours: true,  // Show when retailer is closed
         quantityCounterStyle: 'outlined',  // or 'ghost'
@@ -376,6 +379,7 @@ const client = await Elements('YOUR_API_KEY', {
         addToCartButtonShowTotalPrice: true,
         buyNowButtonText: 'Buy Now',
         preSaleButtonText: 'Pre-Order',
+        prioritizeEngraving: false,  // Show engraving option before add-to-cart
         noAvailabilityText: 'Not available in your area'
       }
     }

package/docs/v1/guides/product-list-component.md

@@ -260,18 +260,19 @@ Each product card shows:
 - Product name
 - Brand
 - Price (or price range for multiple sizes)
-- Rating (if available)
 - Clickable image/card linking to the product detail page (when `productUrl` is configured)
 - "Add to Cart" button (optional)
 - Availability indicator
 
+Product card images automatically have their white/near-white backgrounds removed so the product blends into the surrounding card and page background. This treatment is applied at render time and is not host-configurable.
+
 ### Card Interaction
 
 **Click on card:** Navigate to product detail page (if `productUrl` configured — see [Product URL Map](#product-url-map) for partner-owned PDP URLs that aren't derivable from a token).
 
 **Quick Add:** Add product to cart directly from list view (if enabled)
 
-**Click on image:** Open image in lightbox or navigate to product page
+**Click on image:** Navigate to the configured `productUrl` (only when `productUrl` is set — otherwise the image is not a link)
 
 ## Customization
 
@@ -514,10 +515,8 @@ The product list component includes:
 ### Optimization Features
 
 - **Image lazy loading**: Images load as they enter viewport
-- **Virtual scrolling**: Only renders visible products
+- **Progressive loading**: Products load in batches via an `IntersectionObserver` sentinel as you scroll — each page is appended to the grid and loaded cards remain in the DOM
 - **Debounced search**: Reduces API calls during typing
-- **Filter caching**: Caches filter results
-- **Progressive loading**: Loads in batches
 
 ### Large Catalogs
 

package/docs/v1/guides/theming.md

@@ -53,6 +53,12 @@ customTheme: {
 }
 ```
 
+**Constraints:**
+
+- Only Google Fonts are supported. Each font's `name` must be a valid Google Font name (for example, `'Poppins'` or `'Inter'`).
+- `Poppins` is always loaded as the default font regardless of your configuration, so it remains available even if you do not specify it.
+- Font loading requires network access to `fonts.googleapis.com` and `fonts.gstatic.com`. If your environment enforces a Content Security Policy or routes traffic through a proxy, allow these hosts so fonts can load.
+
 ### Border Radius
 
 ```javascript
@@ -77,12 +83,16 @@ customTheme: {
       personalizationCardStyle: 'outlined',  // or 'filled'
       allowPromoCodes: true,
       inputFieldStyle: 'outlined',  // or 'filled'
+      enableOrderedProductSizes: true,  // enable custom ordering of the size selectors
+      orderedProductSizes: ['750ml', '1L', '1.75L'],  // order applied to product and product-list size selectors
       poweredByMode: 'light'  // or 'dark'  (note: showPoweredBy is controlled server-side and cannot be overridden via customTheme)
     }
   }
 }
 ```
 
+`enableOrderedProductSizes` and `orderedProductSizes` control the ordering of the size selectors rendered by the product and product-list components. When `enableOrderedProductSizes` is `true`, size options are sorted to match the sequence in the `orderedProductSizes` string array. Updating either key triggers a targeted rerender of the affected size selectors.
+
 ## Component Themes
 
 ### Product Component

package/docs/v1/reference/analytics.md

@@ -0,0 +1,108 @@
+# Analytics & Google Tag Manager
+
+The SDK ships with a built-in Google Tag Manager (GTM) / Google Analytics 4 (GA4) integration. It automatically pushes GA4 ecommerce events for the interactions your shoppers perform in Elements components — product views, cart changes, checkout steps, purchases, and more.
+
+This runs entirely inside the SDK. In most cases you do not need to configure or code anything.
+
+## What You Need To Do
+
+**Typically nothing.** The integration is automatic in production and staging. The SDK receives its GTM container configuration from the LiquidCommerce platform (per partner) and initializes itself after the DOM is ready.
+
+It coexists with a host site's own GTM — see [Coexisting With Your Own GTM](#coexisting-with-your-own-gtm) below.
+
+## Supported Environments
+
+GTM initialization and every event push are enabled in production and staging. When the SDK is running in development or Builder mode, no container is loaded and no events are sent.
+
+Events are suppressed when any of the following is true:
+
+- `window` is undefined (server-side rendering).
+- The SDK is running in Builder mode.
+- The environment is `development`.
+
+The environment defaults to `production` when none is provided, so a standard production embed is analytics-enabled out of the box; a staging embed is also analytics-enabled when server GTM config is enabled for the partner.
+
+## How It Works
+
+### Container injection
+
+When enabled, the SDK injects the GTM container script:
+
+```
+https://www.googletagmanager.com/gtm.js?id=<containerId>
+```
+
+The script is appended to `<head>` with `async` and `crossorigin="anonymous"`, and the SDK waits for GTM to initialize before flushing events.
+
+### dataLayer and gtag
+
+The SDK initializes the standard GTM globals **without clobbering an existing setup**:
+
+- `window.dataLayer` is created only if it does not already exist.
+- `window.gtag` is defined only if it is not already present.
+
+Events are delivered using Google's recommended `window.dataLayer.push()` pattern.
+
+### Event queueing
+
+Events fired before GTM finishes initializing are queued (up to 100, oldest dropped first) and flushed once the container is ready. Queued events older than 30 seconds at flush time are discarded.
+
+## Coexisting With Your Own GTM
+
+The SDK detects an already-present partner/host GTM container rather than replacing it. When a host GTM install (an existing `gtag` function or an existing `googletagmanager.com/gtm.js` script tag) is detected, the SDK integrates with it.
+
+When both the LiquidCommerce container and a partner container are initialized, events are sent to both using GA4's `send_to` targeting (a dual-container send). Only containers that are actually initialized are added to `send_to`, so events are never routed to a container that failed to load.
+
+If the LiquidCommerce container can't be loaded, the SDK falls back — in order — to the partner container, any initialized GTM container on the page, or the basic `dataLayer` — so event tracking degrades gracefully instead of failing.
+
+## Source Tracking (`tenant_*`)
+
+Every event automatically carries source-tracking fields identifying the tenant and the SDK build:
+
+| Field | Value |
+| --- | --- |
+| `tenant_name` | Partner name |
+| `tenant_code` | Partner code |
+| `tenant_env` | SDK environment |
+| `tenant_source` | SDK package description and version |
+
+## Events
+
+All events are GA4-shaped and follow the standard ecommerce schema (`items[]`, `value`, `currency` — the SDK uses `USD`, `coupon`, etc.).
+
+### Standard GA4 ecommerce events
+
+| Event | Fired when |
+| --- | --- |
+| `view_item` | A shopper views a product |
+| `view_item_list` | A shopper views a list of products |
+| `select_item` | A shopper selects a product from a list |
+| `add_to_cart` | A shopper adds an item to the cart |
+| `view_cart` | A shopper views the cart |
+| `remove_from_cart` | A shopper removes an item from the cart |
+| `begin_checkout` | A shopper begins checkout |
+| `add_shipping_info` | Shipping info is added during checkout |
+| `add_payment_info` | Payment info is added during checkout |
+| `purchase` | A purchase completes |
+
+### Custom events
+
+| Event | Fired when |
+| --- | --- |
+| `promo_code_attempt` | A promo code is submitted |
+| `promo_code_applied` | A promo code is successfully applied |
+| `promo_code_failed` | A promo code fails to apply |
+| `gift_card_attempt` | A gift card is submitted |
+| `gift_card_applied` | A gift card is successfully applied |
+| `gift_card_failed` | A gift card fails to apply |
+| `address_updated` | An address is successfully updated |
+| `address_failed` | An address operation fails |
+| `product_no_availability` | A product has no availability for any size/fulfillment |
+| `product_size_no_availability` | A selected size has no availability |
+| `product_fulfillment_no_availability` | A selected fulfillment type has no availability |
+
+## Related Docs
+
+- [Events Guide](../guides/events.md)
+- [Client API](../api/client.md)
+- [Troubleshooting](./troubleshooting.md)

package/docs/v1/reference/browser-support.md

@@ -25,7 +25,9 @@ In non-browser environments, initialization is skipped. If you call the SDK on t
 it returns `null` and logs a warning instead of throwing.
 
 Call `Elements`, `ElementsCheckout`, or `ElementsBuilder` from client-only code (e.g., after mount)
-to render components.
+to render components. `Elements` and `ElementsBuilder` resolve to no-op stubs from the main SSR
+entry; `ElementsCheckout` ships in its own tree-shaken entry with a separate stub, so it is safe to
+import even if you never use the other two.
 
 ## Polyfills (Legacy Browsers)
 

package/docs/v1/reference/error-handling.md

@@ -68,6 +68,14 @@ window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
 
 When a component fails to load, the SDK renders an error view inside the container and logs details to the console.
 
+## Global Error Interception
+
+On load, the SDK installs its own global handlers by reassigning `window.onerror` and `window.onunhandledrejection`. Each incoming error or rejection is classified by an `isSDKError` heuristic that inspects the error's message, stack, and source — matching a script `src` ending in `/elements.js`, known SDK class and directory patterns, and an `isSdk` flag on `SDKError` instances.
+
+When an error is classified as SDK-originated, the handler logs it to the console and returns `true` (for `onerror`) or calls `event.preventDefault()` (for `onunhandledrejection`), so the error is swallowed and never reaches your app. Errors that are not classified as SDK-originated are chained to any handler that was already installed before the SDK loaded.
+
+> **Implications:** SDK-originated errors are intentionally suppressed and will **not** surface in your host error monitoring (e.g. Sentry). Conversely, the heuristic is pattern-based and can occasionally match a non-SDK error, causing it to be swallowed too. If you rely on catching failures, use the `*_failed` events and `try/catch` described above rather than global error monitoring.
+
 ## Related Docs
 
 - [Events Guide](../guides/events.md)