@liquidcommerce/elements-sdk 2.6.0-beta.38 → 2.6.0-beta.39

package/README.md

@@ -9,1921 +9,25 @@ Elements SDK
 
 [![JavaScript](https://img.shields.io/badge/JavaScript-ES6+-F7DF1E?style=for-the-badge&logo=javascript&logoColor=black)](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5+-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![pnpm](https://img.shields.io/badge/pnpm-10+-F69220?style=for-the-badge&logo=pnpm&logoColor=white)](https://pnpm.io/)
-[![Rollup](https://img.shields.io/badge/Rollup-4+-EC4A3F?style=for-the-badge&logo=rollup.js&logoColor=white)](https://rollupjs.org/)
-![BiomeJs 2+](https://img.shields.io/badge/BiomeJs-2+-60a5fa?style=for-the-badge&logo=biome&logoColor=white)
-
-[![License: UNLICENSED](https://img.shields.io/badge/License-UNLICENSED-red.svg)](LICENSE)
-[![Zero Dependencies](https://img.shields.io/badge/Dependencies-Zero-brightgreen)](./package.json)
-[![Browser Support](https://img.shields.io/badge/Browsers-2018+-4285F4?logo=googlechrome&logoColor=white)](./docs/BROWSER_SUPPORT.md)
-
-**Add product, cart, and checkout experiences to any website with a few lines of code**
-
-</div>
-
-## 📋 Table of Contents
-
-<details>
-<summary>Click to expand</summary>
-
-- [Overview](#-overview)
-- [Quick Start](#-quick-start)
-- [Advanced Usage](#-advanced-usage)
-- [Browser Support](#-browser-support)
-- [Configuration](#-configuration)
-- [SDK Methods & API](#-sdk-methods--api)
-- [Actions](#-actions)
-- [Events](#-events)
-- [Themes & Customization](#-themes--customization)
-- [Features Deep Dive](#-features-deep-dive)
-- [Core Capabilities](#-core-capabilities)
-- [Integration Patterns](#-integration-patterns)
-- [Error Handling](#-error-handling)
-- [Performance & Best Practices](#-performance--best-practices)
-- [Proxy Configuration](#-proxy-configuration)
-- [Documentation](#-documentation)
-- [Versioning](#-versioning)
-- [Support](#-support)
-
-</details>
-
-## 🎯 Overview
-
-The LiquidCommerce Elements SDK is a **production-ready JavaScript library** that enables partners to seamlessly integrate product displays, shopping carts, and checkout flows into any website. Built with performance and developer experience in mind.
-
-### ✨ Key Features
-
-<table>
-<tr>
-<td width="50%">
-
-**🚀 Quick Integration**
-- Auto-initialization with data attributes
-- Zero configuration setup
-- CDN or NPM installation
-- Works with any framework or vanilla JS
-
-</td>
-<td width="50%">
-
-**🛍️ Complete E-commerce**
-- Product display components
-- Product list with filters and search
-- Shopping cart with real-time updates
-- Full checkout flow (drawer or hosted page)
-- Address management
-
-</td>
-</tr>
-<tr>
-<td width="50%">
-
-**🎨 Customizable UI**
-- Comprehensive theme system
-- Component-level styling
-- Responsive design
-- Modern, accessible components
-
-</td>
-<td width="50%">
-
-**⚡ Performance First**
-- ~150KB bundle size
-- Zero runtime dependencies
-- Lazy loading support
-- Optimized for Core Web Vitals
-
-</td>
-</tr>
-</table>
-
-## 🚀 Quick Start
-
-The fastest way to add e-commerce to your site is with **auto-initialization** - a single script tag that does everything.
-
-### The Simplest Setup (30 seconds)
-
-Add this single script tag to your page:
-
-```html
-<script
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  data-env="production"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-That's it! You now have:
-- ✅ A floating cart button (bottom right)
-- ✅ Full cart functionality
-- ✅ Complete checkout flow
-- ✅ Ready to add products
-
-### Adding Products to Your Page
-
-Now let's display products. Choose the method that fits your use case:
-
-#### Method 1: Direct Attributes (Best for static pages)
-
-Add products directly in the script tag:
-
-```html
-<div id="product-1"></div>
-<div id="product-2"></div>
-
-<script
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  data-env="production"
-  data-container-1="product-1"
-  data-product-1="00619947000020"
-  data-container-2="product-2"
-  data-product-2="00832889005513"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-**Use case:** Static HTML pages with known products
-
-#### Method 2: JSON Configuration (Best for CMS/dynamic content)
-
-Configure products via a JSON script block:
-
-```html
-<div id="product-1"></div>
-<div id="product-2"></div>
-
-<script data-liquid-commerce-elements-products type="application/json">
-[
-  { "containerId": "product-1", "identifier": "00619947000020" },
-  { "containerId": "product-2", "identifier": "00832889005513" }
-]
-</script>
-
-<script
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  data-env="production"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-**Use case:** CMS platforms, templating engines, server-side rendering
-
-#### Method 3: Annotated Elements (Best for grids/lists)
-
-Mark any div with a data attribute:
-
-```html
-<div class="product-grid">
-  <div data-lce-product="00619947000020"></div>
-  <div data-lce-product="00832889005513"></div>
-  <div data-lce-product="00851468007252"></div>
-</div>
-
-<script
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  data-env="production"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-**Use case:** Product grids, category pages, search results
-
-### Adding a Product List
-
-Display a filtered, paginated product catalog with infinite scroll. Perfect for category pages, catalog pages, and search results.
-
-Add a product list to any page with a data attribute:
-
-```html
-<div data-liquid-commerce-elements-products-list
-     data-rows="3"
-     data-columns="4"
-     data-filters="engraving,presale,fulfillment,price,brands"
-     data-product-url="/product/{upc}">
-</div>
-
-<script
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  data-env="production"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-**Attributes:**
-- `data-liquid-commerce-elements-products-list` - Enables product list on this div
-- `data-rows` - Number of rows per page (1-10, default: `3`)
-- `data-columns` - Number of columns (1-4, default: `4`)
-- `data-filters` - Comma-separated filters (see available filters below)
-- `data-product-url` - Product URL template with `{upc}` or `{grouping}` placeholder
-
-**Available filters:** `engraving`, `presale`, `fulfillment`, `price`, `brands`, `categories`, `flavor`, `region`, `variety`, `vintage`, `country`, `appellation`, `materials`, `sizes`
-
-**Use case:** Category pages, catalog pages, search results, filtered product browsing
-
-### Customizing the Cart Button
-
-By default, you get a floating cart button with badge. Here's how to customize it:
-
-#### Option 1: Cart Button in a Specific Container
-
-```html
-<nav>
-  <div id="header-cart"></div>
-</nav>
-
-<script
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  data-env="production"
-  data-cart-badge-button="header-cart"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-**Position Options:**
-
-You can control where the cart button is placed relative to a target element:
-
-```html
-<!-- Place inside the target (default) -->
-<script data-cart-badge-button="header-cart" ...></script>
-
-<!-- Place above the target -->
-<script data-cart-badge-button="above:.header-logo" ...></script>
-
-<!-- Place below the target -->
-<script data-cart-badge-button="below:#main-nav" ...></script>
-
-<!-- Replace the target -->
-<script data-cart-badge-button="replace:.old-cart" ...></script>
-```
-
-**ID Auto-Prefixing:**
-
-Element IDs are automatically prefixed with `#` if needed:
-
-```html
-<!-- These are equivalent: -->
-<script data-cart-button="header-cart" ...></script>
-<script data-cart-button="#header-cart" ...></script>
-```
-
-#### Option 2: Floating Cart Button (Default)
-
-If no cart button attribute is provided, or if the target element is not found, the SDK automatically falls back to a floating cart button (bottom-right corner):
-
-```html
-<!-- Empty attribute = floating cart button without badge -->
-<script data-cart-button="" ...></script>
-
-<!-- Empty badge attribute = floating cart button with badge -->
-<script data-cart-badge-button="" ...></script>
-
-<!-- Or simply omit the attribute for floating button with badge -->
-<script
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-#### Option 3: Separate Mobile Cart Button
-
-Configure different cart button placements for desktop and mobile:
-
-```html
-<script
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  data-env="production"
-  data-cart-badge-button="above:.desktop-nav"
-  data-cart-mobile-badge-button="below:.mobile-header"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-**Mobile button attributes:**
-- `data-cart-mobile-button` - Mobile cart button (no badge)
-- `data-cart-mobile-badge-button` - Mobile cart button with item count badge
-
-These support the same position prefixes as the desktop attributes (`above:`, `below:`, `replace:`, `inside:`).
-
-**Use case:** Different navigation layouts for desktop and mobile
-
-#### Option 4: Custom Cart Toggle Button
-
-Use your own button element to toggle the cart:
-
-```html
-<button data-lce-cart-toggle-button>My Cart</button>
-<span data-lce-cart-items-count>0</span>
-
-<script
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  data-env="production"
-  data-cart-button-hidden
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-**Attributes:**
-- `data-lce-cart-toggle-button` - Any element with this attribute becomes a cart toggle
-- `data-lce-cart-items-count` - Auto-updates with cart item count. Use value `"keep-zero"` to show count even when cart is empty
-
-**Use case:** Fully custom cart button with your own styling
-
-#### Option 5: No Cart Button (Manual Control)
-
-Hide the cart button completely when you want to manage cart access manually:
-
-```html
-<script
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  data-env="production"
-  data-cart-button-hidden
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-**Use case:** When you have a custom cart implementation or want to trigger cart display programmatically using `client.actions.cart.openCart()`
-
-### Advanced Auto-Init Features
-
-#### Add Product via URL (Marketing Links)
-
-Enable "add to cart" via URL parameters for email campaigns and ads:
-
-```html
-<script
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  data-env="production"
-  data-product-param="lce_product"
-  data-product-fulfillment-type-param="lce_fulfillment"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-Now this URL auto-adds a product to cart:
-```
-https://yoursite.com/shop?lce_product=00619947000020&lce_fulfillment=shipping
-```
-
-**Use case:** Email campaigns, social media ads, QR codes
-
-#### Apply Promo Code via URL (Campaign Tracking)
-
-Auto-apply promo codes from URL parameters:
-
-```html
-<script
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  data-env="production"
-  data-promo-code-param="lce_promo"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-Now this URL auto-applies a promo code:
-```
-https://yoursite.com/shop?lce_promo=SUMMER20
-```
-
-**Use case:** Promotional campaigns, influencer codes, affiliate links
-
-#### Promo Ticker (Rotating Promotions)
-
-Display rotating promotional messages:
-
-```html
-<script
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  data-env="production"
-  data-promo-code="FREESHIP"
-  data-promo-text="Free Shipping Today Only!|Use code FREESHIP at checkout"
-  data-promo-separator="•"
-  data-promo-active-from="2025-01-01T00:00:00Z"
-  data-promo-active-until="2025-01-31T23:59:59Z"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-**Use case:** Time-sensitive promotions, holiday sales, flash deals
-
-#### Debug Mode (Development)
-
-Enable debug logging during development:
-
-```html
-<script
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  data-env="development"
-  data-debug-mode="console"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-**Debug modes:**
-- `console` - Logs to browser console
-- `panel` - Shows visual debug panel + console logs
-- Not set - No debugging (production default)
-
-### Complete Auto-Init Reference
-
-Here's every available data attribute:
-
-```html
-<script
-  data-liquid-commerce-elements
-
-  <!-- Required -->
-  data-token="YOUR_API_KEY"
-
-  <!-- Environment -->
-  data-env="production|staging|development|local"
-
-  <!-- Cart Button (Desktop) -->
-  data-cart-button="container-id"              <!-- Simple cart button (no badge) -->
-  data-cart-badge-button="container-id"        <!-- Cart button with badge -->
-  data-cart-button-hidden                      <!-- Hide cart button completely -->
-
-  <!-- Cart Button (Mobile) -->
-  data-cart-mobile-button="container-id"       <!-- Mobile cart button (no badge) -->
-  data-cart-mobile-badge-button="container-id" <!-- Mobile cart button with badge -->
-
-  <!-- Cart Button with Position Prefixes -->
-  data-cart-button="above:.logo"               <!-- Place above target -->
-  data-cart-badge-button="below:#header"       <!-- Place below target -->
-  data-cart-button="inside:.nav"               <!-- Place inside target (default) -->
-  data-cart-badge-button="replace:.old-cart"   <!-- Replace target -->
-
-  <!-- Cart Button Floating (empty values) -->
-  data-cart-button=""                          <!-- Floating button without badge -->
-  data-cart-badge-button=""                    <!-- Floating button with badge -->
-
-  <!-- Products (Method 1: Direct) -->
-  data-container-1="div-id"
-  data-product-1="identifier"
-  data-container-2="div-id"
-  data-product-2="identifier"
-
-  <!-- URL Parameters -->
-  data-product-param="lce_product"
-  data-product-fulfillment-type-param="lce_fulfillment"
-  data-promo-code-param="lce_promo"
-
-  <!-- Promo Ticker -->
-  data-promo-code="CODE"
-  data-promo-text="Message 1|Message 2"
-  data-promo-separator="•"
-  data-promo-active-from="2025-01-01T00:00:00Z"
-  data-promo-active-until="2025-12-31T23:59:59Z"
-
-  <!-- Checkout Page (Hosted Checkout) -->
-  data-checkout-url="https://yoursite.com/checkout?id={id}"
-
-  <!-- Debugging (dev only) -->
-  data-debug-mode="console|panel"
-
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-
-<!-- Product List (on separate div element) -->
-<div data-liquid-commerce-elements-products-list
-     data-rows="3"
-     data-columns="4"
-     data-filters="engraving,presale,fulfillment,price,brands"
-     data-product-url="/product/{upc}">
-</div>
-
-<!-- Custom Cart Toggle Button (on any button/element) -->
-<button data-lce-cart-toggle-button>My Cart</button>
-
-<!-- Custom Cart Items Count Display (on any element) -->
-<span data-lce-cart-items-count>0</span>
-<!-- Use "keep-zero" value to always show count, even when 0 -->
-<span data-lce-cart-items-count="keep-zero">0</span>
-```
-
-**📖 For complete auto-init options:** See [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) for all data attributes and configuration details.
-
-### Hosted Checkout (External Checkout Page)
-
-Instead of using the default checkout drawer, you can redirect customers to a dedicated checkout page on your site. This is useful when you want a full-page checkout experience.
-
-#### Auto-Init Setup
-
-```html
-<!-- On your product/cart pages -->
-<script
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  data-env="production"
-  data-checkout-url="https://yoursite.com/checkout?id={id}"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-When `data-checkout-url` is set, the "Go to Checkout" button in the cart will redirect to that URL instead of opening the checkout drawer. The `{id}` placeholder is replaced with the checkout token generated by the SDK.
-
-#### Checkout Page Setup
-
-On your dedicated checkout page, use the **checkout-only build** for a smaller bundle:
-
-```html
-<div id="checkout-container"></div>
-
-<script
-  data-liquid-commerce-checkout
-  data-token="YOUR_API_KEY"
-  data-env="production"
-  src="https://assets-elements.liquidcommerce.us/checkout/elements.js"
-></script>
-```
-
-Or initialize programmatically:
-
-```js
-import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
-
-const client = await ElementsCheckout('YOUR_API_KEY', {
-  env: 'production'
-});
-
-// Inject checkout, optionally passing the checkout token from the URL
-const urlParams = new URLSearchParams(window.location.search);
-const component = await client.injectCheckout({
-  containerId: 'checkout-container',
-  checkoutId: urlParams.get('id'),  // The checkout token from the URL
-  hideHeader: true
-});
-```
-
-**Checkout-only build features:**
-- Smaller bundle size (tree-shaken, no product/cart/PLP components)
-- All checkout actions available (`actions.checkout.*`)
-- Same theming and event system as the full SDK
-- Auto-initialization via `data-liquid-commerce-checkout` attribute
-
-**Use case:** Dedicated checkout pages, custom checkout flows, multi-page checkout
-
-#### Programmatic Setup (Full SDK)
-
-You can also configure hosted checkout programmatically with the full SDK:
-
-```js
-const client = await Elements('YOUR_API_KEY', {
-  env: 'production',
-  checkout: {
-    pageUrl: 'https://yoursite.com/checkout?id={id}'
-  }
-});
-```
-
----
-
-## 🔧 Advanced Usage
-
-Need more control? Initialize programmatically for full access to the SDK API.
-
-### Installation
-
-**CDN:**
-```html
-<script src="https://assets-elements.liquidcommerce.us/all/elements.js"></script>
-
-<!-- Pin to specific version: -->
-<script src="https://assets-elements.liquidcommerce.us/all/1.2.3/elements.js"></script>
-```
-
-**NPM:**
-```bash
-npm install @liquidcommerce/elements-sdk
-# or
-pnpm add @liquidcommerce/elements-sdk
-```
-
-### Programmatic Initialization
-
-```html
-<script src="https://assets-elements.liquidcommerce.us/all/elements.js"></script>
-<script>
-(async () => {
-  const client = await window.Elements('YOUR_API_KEY', {
-    env: 'production',
-    debugMode: 'none',
-    customTheme: { /* theming overrides */ },
-    proxy: { /* proxy config */ }
-  });
-
-  // Inject components
-  const components = await client.injectProductElement([
-    { containerId: 'pdp-1', identifier: '00619947000020' }
-  ]);
-
-  // Create cart button
-  client.ui.cartButton('cart-container', true);
-
-  // Use actions API
-  await client.actions.cart.addProduct([{
-    identifier: '00619947000020',
-    fulfillmentType: 'shipping',
-    quantity: 1
-  }]);
-})();
-</script>
-```
-
-**NPM Import:**
-```js
-import { Elements } from '@liquidcommerce/elements-sdk';
-
-const client = await Elements('YOUR_API_KEY', { env: 'production' });
-```
-
----
-
-## 🌐 Browser Support
-
-⚠️ **Important**: This SDK is designed for browser environments only. It will not work in server-side rendering, Node.js, or other non-browser environments.
-
-### Supported Browsers (2018+)
-
-| Browser | Minimum Version | Released |
-|---------|----------------|----------|
-| Chrome | 66+ | April 2018 |
-| Firefox | 60+ | May 2018 |
-| Safari | 12+ | September 2018 |
-| Edge | 79+ (Chromium) | January 2020 |
-| Samsung Internet | 7.2+ | June 2018 |
-
-📖 See [`docs/BROWSER_SUPPORT.md`](docs/BROWSER_SUPPORT.md) for detailed compatibility.
-
-## ⚙️ Configuration
-
-### Basic Configuration
-
-```js
-const client = await Elements('YOUR_API_KEY', {
-  env: 'production',           // Environment
-  debugMode: 'none',           // Debug mode
-  customTheme: { },            // Theme overrides
-  proxy: { },                  // Proxy configuration
-  promoTicker: [ ],            // Promotional messages
-  checkout: {                  // Hosted checkout configuration
-    pageUrl: 'https://yoursite.com/checkout?id={id}'
-  }
-});
-```
-
-### Environment Options
-
-```js
-env: 'production'    // Live environment (default)
-env: 'staging'       // Pre-production testing
-env: 'development'   // Development with extra logging
-env: 'local'         // Local development
-```
-
-### Debug Modes
-
-```js
-debugMode: 'none'     // No debugging (production default)
-debugMode: 'console'  // Console logs only
-debugMode: 'panel'    // Visual debug panel + console logs
-```
-
-**Note:** Debug mode is automatically disabled in production environment for security.
-
-### Custom Theme
-
-Override default styles and layouts:
-
-```js
-customTheme: {
-  global: {
-    theme: {
-      primaryColor: '#007bff',
-      accentColor: '#6c757d',
-      successColor: '#28a745',
-      errorColor: '#dc3545',
-      buttonCornerRadius: '8px',
-      cardCornerRadius: '12px',
-      headingFont: {
-        name: 'Inter',
-        weights: [600, 700]
-      },
-      paragraphFont: {
-        name: 'Inter',
-        weights: [400, 500]
-      }
-    },
-    layout: {
-      allowPromoCodes: true,
-      inputFieldStyle: 'outlined'
-    }
-  },
-  product: {
-    layout: {
-      showDescription: true,
-      addToCartButtonText: 'Add to Cart',
-      fulfillmentDisplay: 'carousel'
-    }
-  },
-  cart: {
-    layout: {
-      showQuantityCounter: true,
-      drawerHeaderText: 'Your Cart'
-    }
-  },
-  checkout: {
-    layout: {
-      allowGiftCards: true,
-      emailOptIn: { show: true, checked: false, text: 'Email me with news' },
-      smsOptIn: { show: true, checked: false, text: 'Text me with updates' }
-    }
-  }
-}
-```
-
-**📖 For complete theming options:** See [`docs/THEMING.md`](docs/THEMING.md)
-
-### Proxy Configuration
-
-Route API requests through your server to avoid ad blockers:
-
-```js
-proxy: {
-  baseUrl: 'https://yourdomain.com/api/proxy',
-  headers: {
-    'X-Custom-Auth': 'your-token'
-  }
-}
-```
-
-See [`docs/PROXY.md`](docs/PROXY.md) for implementation guide.
-
-### Promo Ticker
-
-Display rotating promotional messages:
-
-```js
-promoTicker: [
-  {
-    promoCode: 'FREESHIP',
-    text: ['Free Shipping Today!', 'Use code FREESHIP'],
-    separator: '•',
-    activeFrom: '2025-01-01T00:00:00Z',
-    activeUntil: '2025-12-31T23:59:59Z'
-  }
-]
-```
-
-**📖 For all configuration options:** See [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) for complete reference with TypeScript types.
-
----
-
-## 📖 SDK Methods & API
-
-### Component Injection
-
-Inject SDK components into your page containers. All injection methods return wrapper objects that provide component control.
-
-#### Products
-
-```js
-const components = await client.injectProductElement([
-  { containerId: 'pdp-1', identifier: '00619947000020' },
-  { containerId: 'pdp-2', identifier: '00832889005513' }
-]);
-
-// Returns: IInjectedComponent[] - Array of component wrappers
-// components[0].rerender() - Rerender the first component
-// components[0].getElement() - Get the container element
-// components[0].getType() - Get component type
-```
-
-**Identifier types:** UPC, product ID, or Salsify grouping ID
-
-#### Cart
-
-```js
-const component = await client.injectCartElement('cart-container');
-
-// Returns: IInjectedComponent | null - Component wrapper or null if failed
-// component.rerender() - Rerender the component
-// component.getElement() - Get the container element
-// component.getType() - Get component type
-```
-
-**Use case:** Dedicated cart page
-
-#### Checkout
-
-```js
-const component = await client.injectCheckoutElement({
-  containerId: 'checkout-container',
-  checkoutId: 'checkout-token',    // Optional: load specific checkout by checkout token
-  hideHeader: false                // Optional: hide checkout header in standalone mode
-});
-
-// Returns: IInjectedComponent | null - Component wrapper or null if failed
-// component.rerender() - Rerender the component
-// component.getElement() - Get the container element
-// component.getType() - Get component type
-```
-
-**Parameters:**
-- `containerId` (required) - Where to inject the checkout
-- `checkoutId` (optional) - Checkout token to load a specific checkout session
-- `hideHeader` (optional) - Hide the checkout header when used in standalone/hosted mode
-
-**Use case:** Dedicated checkout page, hosted checkout
-
-#### Address
-
-```js
-const component = await client.injectAddressElement('address-container');
-
-// Returns: IInjectedComponent | null - Component wrapper or null if failed
-// component.rerender() - Rerender the component
-// component.getElement() - Get the container element
-// component.getType() - Get component type
-```
-
-**Use case:** Shipping address collection page
-
-#### Product List
-
-```js
-await client.injectProductList({
-  containerId: 'product-list-container',
-  rows: 3,                       // Number of rows per page (1-10)
-  columns: 4,                    // Number of columns (1-4)
-  filters: [                     // Optional filters
-    'engraving',                 // Engravable/personalizable products
-    'presale',                   // Pre-order products
-    'fulfillment',               // Delivery type filter (shipping, onDemand)
-    'price',                     // Price range filter
-    'brands',                    // Brand filter
-    'categories',                // Category filter
-    'flavor',                    // Flavor filter
-    'region',                    // Region filter
-    'variety',                   // Variety filter
-    'vintage',                   // Vintage filter
-    'country',                   // Country filter
-    'appellation',               // Appellation filter
-    'materials',                 // Materials filter
-    'sizes'                      // Size filter
-  ],
-  productUrl: '/product/{upc}'   // Optional: Product detail page URL template
-});
-```
-
-**Parameters:**
-- `containerId` - Where to inject the product list
-- `rows` - Number of rows to display per page (1-10, default: `3`)
-- `columns` - Number of columns in the grid (1-4, default: `4`)
-- `filters` - Array of filter types to enable (see available filters below)
-- `productUrl` - Optional URL template for product links. Use `{upc}` or `{grouping}` placeholder
-
-**Available filters:** `engraving`, `presale`, `fulfillment`, `price`, `brands`, `categories`, `flavor`, `region`, `variety`, `vintage`, `country`, `appellation`, `materials`, `sizes`
-
-**Features:**
-- ✅ Infinite scroll pagination
-- ✅ Rich filtering (14 filter types)
-- ✅ Address-aware (reloads when address changes)
-- ✅ Loading states and error handling
-- ✅ Automatic GTM tracking (`view_item_list`, `select_item`)
-- ✅ Add to cart directly from cards
-- ✅ Product links with tracking
-
-**Use case:** Category pages, catalog pages, search results, filtered product browsing
-
-**Note:** The product list automatically reloads when the address changes to show availability for the new location.
-
-#### Product List Search
-
-```js
-await client.injectProductListSearch({
-  containerId: 'search-container'
-});
-```
-
-Injects a search input component that works with the product list to filter products by keyword.
-
-**Use case:** Search bars on catalog/category pages
-
-#### Product List Filters
-
-```js
-await client.injectProductListFilters({
-  containerId: 'filters-container',
-  filters: ['price', 'brands', 'categories', 'variety']
-});
-```
-
-Injects a standalone filter panel component that works with the product list. Use this when you want the filters in a separate container from the product grid (e.g., a sidebar).
-
-**Parameters:**
-- `containerId` - Where to inject the filter panel
-- `filters` - Array of filter types to display
-
-**Use case:** Sidebar filter panels on category pages
-
-#### Access All Injected Components
-
-```js
-// Get all injected components
-const injectedComponents = client.getInjectedComponents();
-
-// Access specific components by container ID
-const productComponent = injectedComponents.get('product-container-1');
-const cartComponent = injectedComponents.get('cart-container');
-
-// Iterate through all components
-injectedComponents.forEach((component, containerId) => {
-  console.log(`Container: ${containerId}, Type: ${component.getType()}`);
-  
-  // Rerender specific components
-  if (component.getType() === 'product') {
-    component.rerender();
-  }
-});
-
-// Get all components of a specific type
-const productComponents = Array.from(injectedComponents.values())
-  .filter(component => component.getType() === 'product');
-
-// Rerender all components of a type
-productComponents.forEach(component => component.rerender());
-```
-
-**Returns:** `Map<string, IInjectedComponent>` - Map of container IDs to component wrappers
-
-**Use cases:** 
-- Debugging and inspecting injected components
-- Bulk operations on multiple components
-- Component management and cleanup
-
-### UI Helpers
-
-Create standalone UI elements that integrate with the SDK.
-
-#### Cart Button (in container)
-
-```js
-client.ui.cartButton('header-cart', true);
-```
-
-**Parameters:**
-- `containerId` - Where to place the button
-- `showItemsCount` - Show item count badge (optional)
-
-**Use case:** Header navigation, sidebar
-
-#### Floating Cart Button
-
-```js
-client.ui.floatingCartButton(true);
-```
-
-**Parameters:**
-- `showItemsCount` - Show item count badge (optional)
-
-**Use case:** Always-visible cart access (bottom-right corner)
-
-#### Live Cart Data Display
-
-Bind elements to auto-update with cart data:
-
-```js
-// Show live subtotal
-client.ui.cartSubtotal('cart-total-display');
-
-// Show live item count (default behavior: hides when count is 0)
-client.ui.cartItemsCount('cart-badge');
-
-// Show live item count (always visible, even when 0)
-client.ui.cartItemsCount('cart-badge', { hideZero: false });
-```
-
-**Parameters for `cartItemsCount`:**
-- `elementId` (string) - ID of the element to update
-- `options` (object, optional) - Configuration options:
-  - `hideZero` (boolean, default: `true`) - When `true`, element is hidden when cart count is 0. When `false`, element remains visible showing "0".
-
-**Example:**
-```html
-<nav>
-  <span>Cart: $<span id="cart-total-display">0.00</span></span>
-  <span>(<span id="cart-badge">0</span> items)</span>
-</nav>
-
-<script>
-  // Default behavior - badge hidden when cart is empty
-  client.ui.cartItemsCount('cart-badge');
-  
-  // Always show count, even when 0
-  client.ui.cartItemsCount('cart-badge', { hideZero: false });
-</script>
-```
-
-### Builder Methods (Development Mode)
-
-When `isBuilder: true` is set, additional methods are available for theme customization:
-
-```js
-const client = await Elements('YOUR_API_KEY', {
-  env: 'development',
-  isBuilder: true
-});
-
-// Update component themes
-await client.builder.updateComponentGlobalConfigs(globalTheme);
-await client.builder.updateProductComponent(productTheme);
-client.builder.updateCartComponent(cartTheme);
-client.builder.updateCheckoutComponent(checkoutTheme);
-client.builder.updateAddressComponent(addressTheme);
-
-// Builder injection methods (same as regular methods)
-const components = await client.builder.injectProductElement(params);
-const component = await client.builder.injectCartElement(containerId);
-const checkoutComponent = await client.builder.injectCheckoutElement({
-  containerId,
-  checkoutId,     // Optional
-  hideHeader      // Optional
-});
-const addressComponent = await client.builder.injectAddressElement(containerId);
-
-// All return IInjectedComponent wrapper objects with rerender(), getElement(), getType() methods
-```
-
-## 🎬 Actions
-
-Actions provide programmatic control over SDK components. Access them via `client.actions` or `window.elements.actions`:
-
-```js
-// Available after client initialization
-const actions = client.actions;
-// OR globally
-const actions = window.elements.actions;
-```
-
-### Product Actions
-
-```js
-// Get product details
-const product = actions.product.getDetails('product-123');
-console.log(product.name, product.brand, product.region, product.variety);
-console.log(product.priceInfo, product.description, product.tastingNotes);
-```
-
-### Address Actions
-
-```js
-// Set address using Google Places ID
-await actions.address.setAddressByPlacesId('ChIJ0SRjyK5ZwokRp1TwT8dJSv8');
-
-// Set address manually without Google Places (perfect for custom address forms)
-await actions.address.setAddressManually(
-  {
-    one: '123 Main St',
-    two: 'Apt 4B',          // Optional apartment/suite
-    city: 'New York',
-    state: 'NY',
-    zip: '10001',
-    country: 'United States' // Optional, will be included in formatted address
-  },
-  {
-    lat: 40.7505045,
-    long: -73.9934387
-  }
-);
-
-// Listen for success/failure via events
-window.addEventListener('lce:actions.address_updated', function(event) {
-  const address = event.detail.data;
-  console.log('✅ Address set!', address.formattedAddress);
-  updateShippingOptions(address.coordinates);
-});
-
-window.addEventListener('lce:actions.address_failed', function(event) {
-  const error = event.detail.data;
-  console.log('❌ Address failed:', error.message);
-  showAddressForm();
-});
-
-// Get current address
-const address = actions.address.getDetails();
-
-// Clear saved address
-actions.address.clear();
-```
-
-#### Clear Address - Complete Reset
-
-The `actions.address.clear()` action performs a comprehensive reset of the user's address and shopping session:
-
-**What it clears:**
-- ✅ **Address Data**: Removes all saved address information (street, city, state, zip, coordinates)
-- ✅ **Cart Contents**: Completely resets the cart (removes all items, totals, promo codes)
-- ✅ **Local Storage**: Completely removes the localStorage entry and its value
-- ✅ **Database**: Deletes the persisted store from the server database
-- ✅ **Checkout State**: Resets any pending checkout information
-
-**Why it resets the cart:**
-When an address is cleared, the cart must be reset because:
-- Cart items have location-specific pricing and availability
-- Fulfillment options are tied to specific addresses
-- Delivery fees and shipping costs depend on location
-- Without a valid address, cart operations would fail or show incorrect data
-
-**Events fired:**
-- `lce:actions.address_cleared` - Address successfully cleared
-- `lce:actions.cart_reset` - Cart successfully reset
-
-**Use cases:**
-- Guest checkout option (clear previous user's data)
-- Location change (start fresh with new address)
-- Privacy compliance (complete data removal)
-- Testing/development (reset to clean state)
-
-**Notes**: 
-- To find Google Places IDs for the `setAddressByPlacesId` action, use the [Google Places ID Finder](https://developers.google.com/maps/documentation/places/web-service/place-id#find-id)
-- The `setAddressManually` action automatically generates a Google Places API-formatted address string from the provided components
-- Manual addresses have an empty Places ID (as they don't come from Google Places API)
-
-**Action Feedback**: All actions provide feedback through events. Listen for success/failure events to handle results and provide user feedback.
-
-### Cart Actions
-
-```js
-// Control cart visibility
-actions.cart.openCart();
-actions.cart.closeCart();
-actions.cart.toggleCart();
-
-// Add products to cart
-await actions.cart.addProduct([{
-  identifier: 'product-123',
-  fulfillmentType: 'shipping', // or 'onDemand'
-  quantity: 2
-}]);
-
-// Listen for add product feedback
-window.addEventListener('lce:actions.cart_product_add_success', function(event) {
-  const { itemsAdded, identifiers } = event.detail.data;
-  console.log(`✅ Added ${itemsAdded} products to cart:`, identifiers);
-  showSuccessMessage('Products added to cart!');
-});
-
-window.addEventListener('lce:actions.cart_product_add_failed', function(event) {
-  const { identifiers, error } = event.detail.data;
-  console.log(`❌ Failed to add products:`, error);
-  showErrorMessage('Could not add products. Please try again.');
-});
-
-// Apply promo codes
-await actions.cart.applyPromoCode('WELCOME10');
-
-// Listen for promo code feedback
-window.addEventListener('lce:actions.cart_promo_code_applied', function(event) {
-  const { discount, newTotal } = event.detail.data;
-  console.log(`✅ Promo applied! Discount: $${discount}, New total: $${newTotal}`);
-  showSavingsMessage(discount);
-});
-
-window.addEventListener('lce:actions.cart_promo_code_failed', function(event) {
-  const { error } = event.detail.data;
-  console.log(`❌ Promo failed:`, error);
-  showErrorMessage('Promo code could not be applied');
-});
-
-// Remove promo codes
-await actions.cart.removePromoCode();
-
-// Get cart details
-const cart = actions.cart.getDetails();
-console.log(cart.itemCount, cart.amounts.total, cart.amounts.giftCardTotal);
-
-// Reset cart
-await actions.cart.resetCart();
-```
-
-### Checkout Actions
-
-```js
-// Control checkout visibility
-actions.checkout.openCheckout();
-actions.checkout.closeCheckout();
-actions.checkout.toggleCheckout();
-actions.checkout.exitCheckout();       // Exit checkout (return to cart)
-
-// Pre-fill customer information
-actions.checkout.updateCustomerInfo({
-  firstName: 'John',
-  lastName: 'Doe',
-  email: 'john@example.com',
-  phone: '+1234567890'
-});
-
-// Pre-fill billing information
-actions.checkout.updateBillingInfo({
-  firstName: 'John',
-  lastName: 'Doe',
-  street1: '123 Main St',
-  city: 'Anytown',
-  state: 'CA',
-  zipCode: '12345'
-});
-
-// Manage gift options
-await actions.checkout.toggleIsGift(true);
-actions.checkout.updateGiftInfo({
-  giftMessage: 'Happy Birthday!',
-  giftFrom: 'Your Friend'
-});
-
-// Apply discounts and gift cards
-await actions.checkout.applyPromoCode('SAVE20');
-await actions.checkout.applyGiftCard('GIFT123');
-
-// Listen for checkout promo code feedback
-window.addEventListener('lce:actions.checkout_promo_code_applied', function(event) {
-  const { discount, newTotal } = event.detail.data;
-  console.log(`✅ Checkout promo applied! Saved: $${discount}`);
-  updateCheckoutTotal(newTotal);
-});
-
-window.addEventListener('lce:actions.checkout_promo_code_failed', function(event) {
-  const { error } = event.detail.data;
-  console.log(`❌ Checkout promo failed:`, error);
-  showCheckoutError('Promo code could not be applied');
-});
-
-// Listen for gift card feedback
-window.addEventListener('lce:actions.checkout_gift_card_applied', function(event) {
-  const { newTotal } = event.detail.data;
-  console.log('✅ Gift card applied successfully!');
-  updateCheckoutTotal(newTotal);
-  showSuccessMessage('Gift card applied to your order');
-});
-
-window.addEventListener('lce:actions.checkout_gift_card_failed', function(event) {
-  const { error } = event.detail.data;
-  console.log(`❌ Gift card failed:`, error);
-  showCheckoutError('Gift card could not be applied');
-});
-
-// Get checkout details (safe, non-sensitive data only)
-const checkout = actions.checkout.getDetails();
-console.log(checkout.itemCount, checkout.amounts.total, checkout.isGift);
-console.log(checkout.hasAgeVerify, checkout.hasPromoCode, checkout.hasGiftCards);
-console.log(checkout.acceptedAccountCreation, checkout.billingSameAsShipping);
-console.log(checkout.marketingPreferences);
-
-// Configure checkout options
-await actions.checkout.toggleBillingSameAsShipping(true);
-actions.checkout.toggleMarketingPreferences('canEmail', true);
-```
-
-See [`docs/ACTIONS.md`](docs/ACTIONS.md) for complete action reference with business use cases.
-
-## 📡 Events
-
-The SDK emits real-time events for all user interactions. Listen to these events to trigger custom behavior:
-
-```js
-// Listen for specific events
-window.addEventListener('lce:actions.product_add_to_cart', function(event) {
-  const data = event.detail.data;
-  console.log('Added to cart:', data.identifier);
-  
-  // Your custom logic here
-  analytics.track('Product Added', {
-    identifier: data.identifier,
-    quantity: data.quantity,
-    upc: data.upc
-  });
-});
-
-// Or use the helper methods (available after initialization)
-window.elements.onAllForms((data, metadata) => {
-  console.log('Form Event', { data, metadata });
-});
-
-window.elements.onAllActions((data, metadata) => {
-  console.log('Action Event', { data, metadata });
-});
-```
-
-### Available Events
-
-#### Product Events
-- `lce:actions.product_loaded` - Product component loaded with comprehensive product details (region, country, abv, proof, age, variety, vintage, descriptions, tasting notes)
-- `lce:actions.product_add_to_cart` - Item added to cart
-- `lce:actions.product_quantity_increase` - Quantity increased
-- `lce:actions.product_quantity_decrease` - Quantity decreased
-- `lce:actions.product_size_changed` - Product size/variant changed
-- `lce:actions.product_fulfillment_type_changed` - Delivery method changed
-
-#### Cart Events
-- `lce:actions.cart_loaded` - Cart data loaded with complete cart information (itemCount, all amounts including giftCardTotal, detailed item data)
-- `lce:actions.cart_opened` - Cart displayed
-- `lce:actions.cart_closed` - Cart hidden
-- `lce:actions.cart_updated` - Cart contents changed
-- `lce:actions.cart_item_added` - Item added
-- `lce:actions.cart_item_removed` - Item removed
-- `lce:actions.cart_reset` - Cart cleared
-
-#### Checkout Events
-- `lce:actions.checkout_loaded` - Checkout data loaded with comprehensive details (acceptedAccountCreation, hasSubstitutionPolicy, billingSameAsShipping, marketing preferences, detailed items)
-- `lce:actions.checkout_opened` - Checkout started
-- `lce:actions.checkout_closed` - Checkout abandoned
-- `lce:actions.checkout_submit_started` - Order submission began
-- `lce:actions.checkout_submit_completed` - Order completed successfully
-- `lce:actions.checkout_submit_failed` - Order failed
-- `lce:actions.checkout_customer_information_updated` - Customer info entered (returns boolean only, no sensitive data)
-- `lce:actions.checkout_gift_information_updated` - Gift recipient info entered (returns boolean only, no sensitive data)
-- `lce:actions.checkout_billing_information_updated` - Billing info entered (returns boolean only, no sensitive data)
-
-**Security Note:** Form update events return only `boolean: true` to track completion without exposing sensitive customer information (names, emails, phone numbers, addresses, etc.). This protects your customers from malicious scripts and data breaches.
-
-#### Address Events
-- `lce:actions.address_updated` - Address information changed
-- `lce:actions.address_cleared` - Address removed
-
-See [`docs/EVENTS.md`](docs/EVENTS.md) for complete event reference with all available fields and implementation examples.
-
-## 🎨 Themes & Customization
-
-The SDK provides a theming system that lets you match components to your brand.
-
-### Global Theming
-
-```js
-const client = await Elements('YOUR_API_KEY', {
-  customTheme: {
-    global: {
-      theme: {
-        primaryColor: '#007bff',
-        accentColor: '#6c757d',
-        successColor: '#28a745',
-        errorColor: '#dc3545',
-        warningColor: '#ffc107',
-        defaultTextColor: '#212529',
-        selectedTextColor: '#ffffff',
-        linkTextColor: '#1d4ed8',
-        drawerBackgroundColor: '#ffffff',
-        buttonCornerRadius: '8px',
-        cardCornerRadius: '12px',
-        headingFont: {
-          name: 'Inter',
-          weights: [600, 700]
-        },
-        paragraphFont: {
-          name: 'Inter',
-          weights: [400, 500]
-        }
-      },
-      layout: {
-      enablePersonalization: true,
-      personalizationText: 'Customize your product',
-      personalizationCardStyle: 'outlined',
-      allowPromoCodes: true,
-      inputFieldStyle: 'outlined',
-      poweredByMode: 'light'
-      }
-    }
-  }
-});
-```
-
-### Component-Specific Theming
-
-#### Product Component
-
-```js
-customTheme: {
-  product: {
-    theme: {
-      backgroundColor: '#ffffff'
-    },
-    layout: {
-      showImages: true,
-      showTitle: true,
-      showDescription: true,
-      showQuantityCounter: true,
-      quantityCounterStyle: 'outlined',
-      fulfillmentDisplay: 'carousel',
-      enableShippingFulfillment: true,
-      enableOnDemandFulfillment: true,
-      addToCartButtonText: 'Add to Cart',
-      buyNowButtonText: 'Buy Now'
-    }
-  }
-}
-```
-
-#### Cart Component
-
-```js
-customTheme: {
-  cart: {
-    theme: {
-      backgroundColor: '#ffffff'
-    },
-    layout: {
-      showQuantityCounter: true,
-      quantityCounterStyle: 'outlined',
-      drawerHeaderText: 'Your Cart',
-      goToCheckoutButtonText: 'Checkout'
-    }
-  }
-}
-```
-
-#### Checkout Component
-
-```js
-customTheme: {
-  checkout: {
-    theme: {
-      backgroundColor: '#ffffff',
-      checkoutCompleted: {
-        customLogo: 'https://yourdomain.com/logo.png',
-        customText: 'Thank you for your order!'
-      }
-    },
-    layout: {
-      emailOptIn: {
-        show: true,
-        checked: false,
-        text: 'Email me with news'
-      },
-      smsOptIn: {
-        show: true,
-        checked: false,
-        text: 'Text me updates'
-      },
-      allowGiftCards: true,
-      drawerHeaderText: 'Checkout',
-      placeOrderButtonText: 'Place Order'
-    }
-  }
-}
-```
-
-#### Address Component
-
-```js
-customTheme: {
-  address: {
-    theme: {
-      backgroundColor: '#ffffff'
-    }
-  }
-}
-```
-
-### Dynamic Theme Updates (Builder Mode)
-
-In development with `isBuilder: true`, update themes in real-time:
-
-```js
-const client = await Elements('YOUR_API_KEY', {
-  env: 'development',
-  isBuilder: true
-});
-
-// Update global theme
-await client.builder.updateComponentGlobalConfigs({
-  theme: { primaryColor: '#ff6b6b' }
-});
-
-// Update component-specific themes
-await client.builder.updateProductComponent({
-  layout: { addToCartButtonText: 'Add to Bag' }
-});
-
-client.builder.updateCartComponent({
-  layout: { drawerHeaderText: 'Shopping Bag' }
-});
-
-client.builder.updateCheckoutComponent({
-  layout: { placeOrderButtonText: 'Complete Purchase' }
-});
-
-client.builder.updateAddressComponent({
-  theme: { backgroundColor: '#f8f9fa' }
-});
-```
-
-**📖 For complete theming documentation:** See [`docs/THEMING.md`](docs/THEMING.md)
-
----
-
-## 🎁 Features Deep Dive
-
-### Product Personalization (Engraving)
-
-The SDK provides a comprehensive personalization/engraving feature for products that support it. The personalization experience varies based on context:
-
-#### Product View
-When browsing products, customers can add personalization through an enhanced form that includes:
-- Product information with pricing
-- Fulfillment/retailer selection (with pricing comparison)
-- Multi-line engraving inputs with character limits
-- Real-time price updates as customers select different retailers
-- Add-to-cart with personalization in one step
-
-```js
-// Personalization appears automatically for engravable products
-// Customers can add engraving text and select which retailer to fulfill from
-
-// Listen for when personalization is added via add-to-cart
-window.addEventListener('lce:actions.product_add_to_cart', (event) => {
-  const { hasEngraving, engravingLines } = event.detail.data;
-  if (hasEngraving) {
-    console.log('Customer personalized:', engravingLines);
-  }
-});
-```
-
-#### Cart View
-In the cart, personalized items display:
-- Personalization text lines
-- Engraving fee (per item and total for quantity)
-- **Edit** button to modify the personalization
-- **Remove** button to remove personalization
-
-```js
-// Customers can edit or remove engraving from cart items
-window.addEventListener('lce:actions.cart_item_engraving_updated', (event) => {
-  const { identifier, engravingLines } = event.detail.data;
-  console.log('Cart item engraving updated:', engravingLines);
-});
-```
-
-#### Checkout View
-During checkout, personalized items show:
-- Personalization text lines (read-only)
-- Engraving fee included in pricing
-- **Remove** button only (editing not allowed in checkout)
-
-**Design Decision:** Editing personalization during checkout is intentionally disabled to prevent order processing complications. Customers must return to the cart to make changes.
-
-#### Theming & Configuration
-
-Control personalization display through global configuration:
-
-```js
-customTheme: {
-  global: {
-    layout: {
-      enablePersonalization: true,
-      personalizationText: 'Personalize your product',
-      personalizationCardStyle: 'outlined' // or 'filled'
-    }
-  }
-}
-```
-
-#### Key Features
-- **Smart pricing:** Automatically includes engraving fees in product price
-- **Retailer selection:** Compare prices from different retailers during personalization
-- **Character limits:** Enforces maximum characters per line
-- **Uppercase conversion:** Engraving text is automatically converted to uppercase
-- **Multi-line support:** Products can support 1 or more engraving lines
-- **Fee transparency:** Shows per-item and total fees (e.g., "$5.00 ($2.50 ea)")
-
-**Note:** Personalization is automatically enabled for products that support it. The SDK handles all UI, validation, and state management.
-
-### Gift Options
-
-Allow orders to be marked as gifts with custom messages:
-
-```js
-// Enable via theme
-customTheme: {
-  checkout: {
-    layout: {
-      allowGiftOptions: true
-    }
-  }
-}
-
-// Toggle gift mode programmatically
-await client.actions.checkout.toggleIsGift(true);
-
-// Set gift message
-await client.actions.checkout.updateGiftInfo({
-  recipientName: 'John Doe',
-  message: 'Happy Birthday!'
-});
-
-// Listen for gift toggles
-window.addEventListener('lce:actions.checkout_is_gift_toggled', (event) => {
-  const { isGift } = event.detail.data;
-  console.log('Order is gift:', isGift);
-});
-```
-
-### Tips (On-Demand Delivery)
-
-Allow customers to tip delivery drivers:
-
-```js
-// Tips are automatically enabled for onDemand fulfillment types
-
-// Listen for tip updates
-window.addEventListener('lce:actions.checkout_tip_updated', (event) => {
-  const { tipAmount, total } = event.detail.data;
-  console.log(`Customer tipped $${tipAmount}`);
-});
-```
-
-Tips are calculated as a percentage or fixed amount and added to the order total.
-
-### Gift Cards
-
-Accept gift card payments at checkout:
-
-```js
-// Enable via theme
-customTheme: {
-  checkout: {
-    layout: {
-      allowGiftCards: true
-    }
-  }
-}
-
-// Apply gift card programmatically
-await client.actions.checkout.applyGiftCard('GIFT-1234-5678-9012');
-
-// Remove gift card
-await client.actions.checkout.removeGiftCard('GIFT-1234-5678-9012');
-
-// Listen for gift card events
-window.addEventListener('lce:actions.checkout_gift_card_applied', (event) => {
-  const { newTotal } = event.detail.data;
-  console.log(`Gift card applied! New total: $${newTotal}`);
-});
-
-window.addEventListener('lce:actions.checkout_gift_card_failed', (event) => {
-  const { error } = event.detail.data;
-  console.log('Gift card failed:', error);
-});
-```
-
-### Promo Codes
-
-Apply promotional discount codes:
-
-```js
-// Apply to cart
-await client.actions.cart.applyPromoCode('SUMMER20');
-
-// Apply to checkout
-await client.actions.checkout.applyPromoCode('SAVE10');
-
-// Remove promo code
-await client.actions.cart.removePromoCode();
-
-// Listen for promo events
-window.addEventListener('lce:actions.cart_promo_code_applied', (event) => {
-  const { discount, newTotal } = event.detail.data;
-  console.log(`Promo applied! Saved $${discount}! New total: $${newTotal}`);
-});
-
-window.addEventListener('lce:actions.cart_promo_code_failed', (event) => {
-  const { error } = event.detail.data;
-  console.log('Promo failed:', error);
-});
-```
-
-### Promo Ticker
-
-Display rotating promotional messages at the top of your site:
-
-```js
-// Via initialization config
-const client = await Elements('YOUR_API_KEY', {
-  promoTicker: [
-    {
-      promoCode: 'FREESHIP',
-      text: ['Free Shipping Today!', 'Use code FREESHIP'],
-      separator: '•',
-      activeFrom: '2025-01-01T00:00:00Z',
-      activeUntil: '2025-12-31T23:59:59Z'
-    },
-    {
-      promoCode: 'SAVE20',
-      text: ['20% Off Sitewide', 'Limited Time Only'],
-      separator: '|',
-      activeFrom: '2025-06-01T00:00:00Z',
-      activeUntil: '2025-06-30T23:59:59Z'
-    }
-  ]
-});
-
-// Via auto-init
-<script
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  data-promo-code="FREESHIP"
-  data-promo-text="Free Shipping Today!|Use code FREESHIP"
-  data-promo-separator="•"
-  data-promo-active-from="2025-01-01T00:00:00Z"
-  data-promo-active-until="2025-12-31T23:59:59Z"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-The ticker automatically rotates messages and only shows active promotions.
-
-### Marketing Preferences
-
-Allow customers to opt-in to email and SMS marketing:
-
-```js
-// Set defaults via theme
-customTheme: {
-  checkout: {
-    layout: {
-      emailOptIn: { checked: false, visible: true },
-      smsOptIn: { checked: false, visible: true }
-    }
-  }
-}
-
-// Update preferences programmatically
-await client.actions.checkout.toggleMarketingPreferences('canEmail', true);
-await client.actions.checkout.toggleMarketingPreferences('canSms', true);
-
-// Listen for preference changes
-window.addEventListener('lce:actions.checkout_marketing_preferences_toggled', (event) => {
-  const { field, value } = event.detail.data;
-  console.log(`Customer ${value ? 'opted-in' : 'opted-out'} of ${field}`);
-});
-```
-
-### Purchase Minimum Alerts
-
-Automatically displays alerts when a retailer has minimum purchase requirements. No configuration needed - the SDK handles this automatically based on retailer rules.
-
-### Age Verification
-
-For age-restricted products (alcohol, tobacco, etc.), the SDK automatically displays age verification prompts during checkout. This is handled based on product metadata and cannot be disabled for restricted items.
-
-### Pre-Sale Countdown
-
-For pre-sale or upcoming products, the SDK automatically displays a countdown timer until the product becomes available. Customers can add pre-sale items to cart, and the SDK handles the special fulfillment flow.
-
-```js
-// Listen for when product is added to cart
-window.addEventListener('lce:actions.product_add_to_cart', (event) => {
-  const { productId } = event.detail.data;
-  console.log(`Product ${productId} added to cart`);
-});
-```
-
-### Product List
-
-Display a filtered, paginated product catalog with infinite scroll. Perfect for category pages, catalog pages, and search results.
-
-#### Auto-Initialization
-
-Add a product list to any page with data attributes:
-
-```html
-<div data-liquid-commerce-elements-products-list
-     data-rows="3"
-     data-columns="4"
-     data-filters="engraving,presale,fulfillment,price,brands"
-     data-product-url="/product/{upc}">
-</div>
-```
-
-You can also add separate search and filter containers:
-
-```html
-<!-- Search bar -->
-<div data-search-container></div>
+[![Zero Dependencies](https://img.shields.io/badge/Dependencies-Zero-brightgreen)](./package.json)
+[![Browser Support](https://img.shields.io/badge/Browsers-2018+-4285F4?logo=googlechrome&logoColor=white)](./docs/browser-support.md)
 
-<!-- Sidebar filters -->
-<div data-filters-container></div>
+**Add product displays, shopping carts, and checkout flows to any website**
 
-<!-- Product grid -->
-<div data-liquid-commerce-elements-products-list
-     data-rows="4"
-     data-columns="4"
-     data-filters="price,brands,categories,variety"
-     data-product-url="/product/{upc}">
 </div>
-```
-
-#### Programmatic Injection
-
-```js
-await client.injectProductList({
-  containerId: 'product-list-container',
-  rows: 3,
-  columns: 4,
-  filters: ['engraving', 'presale', 'fulfillment', 'price', 'brands'],
-  productUrl: '/product/{upc}'
-});
-
-// Optional: inject search and filters in separate containers
-await client.injectProductListSearch({
-  containerId: 'search-container'
-});
-
-await client.injectProductListFilters({
-  containerId: 'filters-sidebar',
-  filters: ['price', 'brands', 'categories', 'variety']
-});
-```
 
-#### Features
-
-**Filtering (14 filter types):**
-- **engraving** - Show only products that support engraving/personalization
-- **presale** - Show only pre-order products
-- **fulfillment** - Filter by delivery type (shipping, onDemand)
-- **price** - Filter by price range
-- **brands** - Filter by brand
-- **categories** - Filter by category
-- **flavor** - Filter by flavor profile
-- **region** - Filter by region
-- **variety** - Filter by variety (e.g., Cabernet Sauvignon)
-- **vintage** - Filter by vintage year
-- **country** - Filter by country of origin
-- **appellation** - Filter by appellation
-- **materials** - Filter by material type
-- **sizes** - Filter by product size
-
-**Smart Filter Logic:**
-- When "Same-Day Delivery" is selected, engraving and presale filters are automatically disabled
-- When engraving or presale is enabled, same-day delivery is automatically disabled
-- Filters work together intelligently to show only compatible product combinations
-
-**Infinite Scroll:**
-- Automatically loads more products as you scroll
-- Shows loading states during pagination
-- Handles "no more products" gracefully
-
-**Address-Aware:**
-- Automatically reloads when address changes
-- Shows availability based on current location
-- Updates product pricing and fulfillment options dynamically
-
-**Product Cards:**
-- Display product image, name, size, and price
-- Show availability status based on location
-- "Add to Cart" button (disabled if unavailable)
-- Clickable product links (if `productUrl` is provided)
-- Presale product support with special handling
-
-**Analytics Tracking:**
-- Automatically tracks `view_item_list` when products load
-- Tracks `select_item` when user clicks a product link
-- GTM integration for e-commerce events
+---
 
-**Loading States:**
-- Shows skeleton loading cards during initial load
-- Displays loading indicator during infinite scroll
-- Error handling with user-friendly messages
+## Installation
 
-**Product URL Templates:**
-- Use `{upc}` placeholder for UPC-based URLs: `/product/{upc}`
-- Use `{grouping}` placeholder for Salsify grouping IDs: `/product/{grouping}`
-- Links open in new tab with proper security attributes
+### CDN
 
-#### Example: Category Page
+Add a single script tag to your page's `<head>` section:
 
 ```html
-<div id="category-products"
-     data-liquid-commerce-elements-products-list
-     data-rows="4"
-     data-columns="4"
-     data-filters="engraving,fulfillment,price,brands"
-     data-product-url="/products/{upc}">
-</div>
-
 <script
+  defer
+  type="text/javascript"
   data-liquid-commerce-elements
   data-token="YOUR_API_KEY"
   data-env="production"
@@ -1931,891 +35,212 @@ await client.injectProductListFilters({
 ></script>
 ```
 
-#### Example: Search Results with Sidebar Filters
-
-```js
-const client = await Elements('YOUR_API_KEY', {
-  env: 'production'
-});
-
-// Inject search bar
-await client.injectProductListSearch({
-  containerId: 'search-bar'
-});
-
-// Inject product grid
-await client.injectProductList({
-  containerId: 'search-results',
-  rows: 6,
-  columns: 3,
-  filters: ['fulfillment', 'price', 'brands', 'categories'],
-  productUrl: '/search?q={grouping}'
-});
-
-// Inject sidebar filters
-await client.injectProductListFilters({
-  containerId: 'filters-sidebar',
-  filters: ['price', 'brands', 'categories', 'variety']
-});
-```
-
-**Use cases:**
-- Category pages
-- Catalog pages
-- Search results
-- Filtered product browsing
-- Personalized product recommendations
-- Pre-order product showcases
-
----
-
-## 🔧 Core Capabilities
-
-The SDK includes several built-in services that work behind the scenes to provide a robust, production-ready experience.
-
-### State Management
-
-The SDK uses a centralized store for all state management. Access state data via actions:
-
-```js
-// Get current cart state
-const cart = await client.actions.cart.getDetails();
-console.log(cart.itemCount, cart.amounts.total, cart.amounts.giftCardTotal);
-
-// Get current checkout state
-const checkout = await client.actions.checkout.getDetails();
-console.log(checkout.amounts.total, checkout.isGift, checkout.acceptedAccountCreation);
-console.log(checkout.billingSameAsShipping, checkout.marketingPreferences);
-
-// Get current address
-const address = await client.actions.address.getDetails();
-console.log(address.formattedAddress, address.coordinates);
-
-// Get product details
-const product = await client.actions.product.getDetails('00619947000020');
-console.log(product.name, product.region, product.variety, product.vintage);
-console.log(product.description, product.tastingNotes);
-```
-
-**State is persistent:** Cart and address data persist across page reloads using localStorage.
-
-### Event System (PubSub)
-
-All SDK interactions emit events through a centralized event system:
-
-```js
-// Subscribe to specific event
-window.addEventListener('lce:actions.cart_updated', (event) => {
-  const { previous, current } = event.detail.data;
-  console.log('Cart changed from', previous.amounts.total, 'to', current.amounts.total);
-});
-
-// Subscribe to all action events
-if (window.elements) {
-  window.elements.onAllActions((data, metadata) => {
-    console.log('Action:', metadata.eventName, data);
-  });
-}
-
-// Subscribe to all form events
-if (window.elements) {
-  window.elements.onAllForms((data, metadata) => {
-    console.log('Form:', metadata.eventName, data);
-  });
-}
-```
-
-**Event format:**
-```js
-{
-  detail: {
-    data: { /* event-specific payload */ },
-    metadata: {
-      eventName: 'lce:actions.cart_updated',
-      timestamp: 1699564800000,
-      source: 'sdk'
-    }
-  }
-}
-```
-
-### Telemetry & Analytics
-
-The SDK automatically tracks user interactions and performance metrics:
-
-- **User interactions:** Add to cart, checkout started, checkout completed
-- **Performance metrics:** Component load times, API response times
-- **Error tracking:** Failed API calls, validation errors
-
-**Note:** The SDK includes automatic Google Tag Manager (GTM) integration that tracks e-commerce events. GTM configuration is managed through your LiquidCommerce dashboard, not the client initialization.
-
-**Custom Analytics:**
-
-```js
-// Listen to events for custom analytics tracking
-window.addEventListener('lce:actions.product_add_to_cart', (event) => {
-  const { productId, price, quantity } = event.detail.data;
-  
-  // Track with your analytics provider
-  gtag('event', 'add_to_cart', {
-    currency: 'USD',
-    value: price * quantity,
-    items: [{ item_id: productId, quantity }]
-  });
-  
-  // Or Segment
-  analytics.track('Product Added', {
-    product_id: productId,
-    price,
-    quantity
-  });
-});
-```
-
-### Fingerprinting
-
-The SDK generates a unique device fingerprint for fraud prevention and analytics:
-
-```js
-// Automatically tracked:
-// - Browser fingerprint
-// - Device characteristics
-// - Session information
-
-// Used for:
-// - Fraud detection
-// - Cart persistence across devices
-// - Personalization
-```
-
-Fingerprinting is handled automatically and requires no configuration.
-
-### Authentication
-
-The SDK handles authentication automatically using your API key:
-
-```js
-const client = await Elements('YOUR_API_KEY', {
-  env: 'production'
-});
-
-// All API requests include:
-// - API key authentication
-// - CORS headers
-// - Request signing (when required)
-```
-
-**Token refresh:** The SDK automatically handles token expiration and refresh.
-
-### Logger
-
-Built-in logging system with configurable levels:
-
-```js
-const client = await Elements('YOUR_API_KEY', {
-  debugMode: 'console'  // 'none' | 'console' | 'panel'
-});
-
-// Debug mode options:
-// - 'none': No logging (production default)
-// - 'console': Logs to browser console
-// - 'panel': Shows visual debug panel + console logs
-```
-
-**Console debug output:**
-```
-[LCE SDK] Product loaded: product-123
-[LCE SDK] Cart updated: 3 items, $45.99
-[LCE SDK] Checkout started
-[LCE SDK] API call: POST /cart/add (152ms)
-```
-
-**Debug panel:**
-- Real-time event stream
-- API call inspector
-- State viewer
-- Performance metrics
-
-### Command Pattern
-
-The SDK uses a command pattern for all operations:
-
-```js
-// Commands are:
-// - Queued for execution
-// - Retried on failure
-// - Logged for debugging
-// - Cancelable
-
-// Example: Adding to cart
-// 1. Command created: AddToCartCommand
-// 2. Command queued
-// 3. Command executed
-// 4. Success event emitted
-// 5. UI updated
-
-// This ensures:
-// - Consistent error handling
-// - Automatic retries
-// - Full audit trail
-```
-
-### Component Factory
-
-Components are created on-demand using a factory pattern:
-
-```js
-// When you call:
-const components = await client.injectProductElement([
-  { containerId: 'pdp-1', identifier: 'product-123' }
-]);
-// Returns: IInjectedComponent[] - Array of component wrappers
-
-// The SDK:
-// 1. Creates a ProductComponent instance
-// 2. Registers it with the factory
-// 3. Injects it into the DOM
-// 4. Attaches event listeners
-// 5. Loads product data
-// 6. Renders the component
-
-// Components are:
-// - Lazily loaded
-// - Automatically cleaned up
-// - Reusable across pages
-```
-
-### Singleton Manager
-
-Core services are managed as singletons:
-
-```js
-// These services are initialized once and reused:
-// - ApiClient
-// - Store
-// - PubSub
-// - Logger
-// - Telemetry
-// - Fingerprint
-// - Auth
-
-// This ensures:
-// - Consistent state
-// - Efficient memory usage
-// - No duplicate API calls
-```
-
----
-
-## 🏗️ Integration Patterns
-
-### React Integration
-
-```jsx
-import { useEffect, useState } from 'react';
-import { Elements } from '@liquidcommerce/elements-sdk';
-
-function ProductPage({ productId }) {
-  const [client, setClient] = useState(null);
-
-  useEffect(() => {
-    async function initSDK() {
-      const elementsClient = await Elements(process.env.REACT_APP_LCE_API_KEY, {
-        env: 'production'
-      });
-      setClient(elementsClient);
-
-      // Inject product
-      await elementsClient.injectProductElement([
-        { containerId: 'product-container', identifier: productId }
-      ]);
-
-      // Create cart button
-      elementsClient.ui.cartButton('cart-button', true);
-    }
+> **Tip:** While we recommend the `<head>` section, the script works anywhere on your page—place it wherever fits your setup best.
+>
+> **About `defer`:** The script is optimized to load without blocking your page content, keeping your site fast no matter where you place it.
 
-    initSDK();
+### NPM
 
-    // Cleanup
-    return () => {
-      // SDK handles cleanup automatically
-    };
-  }, [productId]);
-
-  return (
-    <div>
-      <div id="cart-button"></div>
-      <div id="product-container"></div>
-    </div>
-  );
-}
+```bash
+npm install @liquidcommerce/elements-sdk
 ```
 
-### Vue Integration
-
-```vue
-<template>
-  <div>
-    <div ref="cartButton"></div>
-    <div ref="productContainer"></div>
-  </div>
-</template>
-
-<script>
+```javascript
 import { Elements } from '@liquidcommerce/elements-sdk';
 
-export default {
-  name: 'ProductPage',
-  props: ['productId'],
-  async mounted() {
-    this.client = await Elements(process.env.VUE_APP_LCE_API_KEY, {
-      env: 'production'
-    });
-
-    await this.client.injectProductElement([
-      { containerId: this.$refs.productContainer.id, identifier: this.productId }
-    ]);
-
-    this.client.ui.cartButton(this.$refs.cartButton.id, true);
-  }
-}
-</script>
-```
-
-### Next.js Integration
-
-```tsx
-'use client';
-
-import { useEffect } from 'react';
-
-export default function ProductPage({ productId }: { productId: string }) {
-  useEffect(() => {
-    // Load SDK script
-    const script = document.createElement('script');
-    script.src = 'https://assets-elements.liquidcommerce.us/all/elements.js';
-    script.async = true;
-    script.onload = async () => {
-      const client = await (window as any).Elements(process.env.NEXT_PUBLIC_LCE_API_KEY, {
-        env: 'production'
-      });
-
-      const components = await client.injectProductElement([
-        { containerId: 'product-container', identifier: productId }
-      ]);
-
-      client.ui.floatingCartButton(true);
-    };
-    document.body.appendChild(script);
-
-    return () => {
-      document.body.removeChild(script);
-    };
-  }, [productId]);
-
-  return <div id="product-container"></div>;
-}
-```
-
-### WordPress Integration
-
-```html
-<!-- In your theme's header.php or functions.php -->
-<script
-  data-liquid-commerce-elements
-  data-token="<?php echo get_option('lce_api_key'); ?>"
-  data-env="production"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-
-<!-- In your product template -->
-<div data-lce-product="<?php echo get_post_meta(get_the_ID(), 'product_upc', true); ?>"></div>
-```
-
-### Shopify Integration
-
-```html
-<!-- In theme.liquid -->
-<script
-  data-liquid-commerce-elements
-  data-token="{{ settings.lce_api_key }}"
-  data-env="production"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-
-<!-- In product template -->
-<div data-lce-product="{{ product.barcode }}"></div>
-```
-
-### Multi-Page Applications
-
-For SPAs and multi-page apps, initialize once and reuse:
-
-```js
-// app.js (initialize once)
-let elementsClient = null;
-
-async function getElementsClient() {
-  if (!elementsClient) {
-    elementsClient = await Elements('YOUR_API_KEY', {
-      env: 'production'
-    });
-  }
-  return elementsClient;
-}
-
-// product-page.js
-const client = await getElementsClient();
-await client.injectProductElement([
-  { containerId: 'pdp-1', identifier: productId }
-]);
-
-// cart-page.js
-const client = await getElementsClient();
-const cartComponent = await client.injectCartElement('cart-container');
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
 ```
 
 ---
 
-## 🚨 Error Handling
-
-### Initialization Errors
-
-```js
-try {
-  const client = await Elements('YOUR_API_KEY', {
-    env: 'production'
-  });
-} catch (error) {
-  if (error.message.includes('Invalid API key')) {
-    console.error('Authentication failed');
-  } else if (error.message.includes('Network')) {
-    console.error('Network error - check connectivity');
-  } else {
-    console.error('SDK initialization failed:', error);
-  }
-}
-```
-
-### Action Errors
-
-All actions emit failure events with detailed error information:
-
-```js
-// Product loaded successfully
-window.addEventListener('lce:actions.product_loaded', (event) => {
-  const { identifier, productData } = event.detail.data;
-  console.log(`Product ${identifier} loaded successfully`);
-});
-
-// Cart action failure
-window.addEventListener('lce:actions.cart_product_add_failed', (event) => {
-  const { identifiers, error } = event.detail.data;
-  console.error('Failed to add products:', error);
-  
-  // Show user-friendly message
-  showNotification('Could not add to cart. Please try again.', 'error');
-});
-
-// Checkout failure
-window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
-  const { error, reason } = event.detail.data;
-  console.error('Checkout failed:', reason);
-  
-  // Handle specific errors
-  if (reason.includes('payment')) {
-    showNotification('Payment declined. Please check your card details.', 'error');
-  } else if (reason.includes('inventory')) {
-    showNotification('Some items are no longer available.', 'warning');
-  } else {
-    showNotification('Checkout failed. Please try again.', 'error');
-  }
-});
-
-// Address validation failure
-window.addEventListener('lce:actions.address_failed', (event) => {
-  const { error } = event.detail.data;
-  console.error('Address validation failed:', error);
-  showNotification('Please enter a valid address.', 'error');
-});
-
-// Promo code failure
-window.addEventListener('lce:actions.cart_promo_code_failed', (event) => {
-  const { code, error } = event.detail.data;
-  console.error(`Promo code ${code} failed:`, error);
-  
-  if (error.includes('expired')) {
-    showNotification('This promo code has expired.', 'warning');
-  } else if (error.includes('invalid')) {
-    showNotification('Invalid promo code.', 'error');
-  } else if (error.includes('minimum')) {
-    showNotification('Cart minimum not met for this promo.', 'warning');
-  }
-});
-```
-
-### Network Error Recovery
-
-```js
-let retryCount = 0;
-const maxRetries = 3;
-
-async function addProductWithRetry(productParams) {
-  try {
-    await client.actions.cart.addProduct(productParams);
-  } catch (error) {
-    if (retryCount < maxRetries && error.message.includes('Network')) {
-      retryCount++;
-      console.log(`Retrying... Attempt ${retryCount}/${maxRetries}`);
-      setTimeout(() => addProductWithRetry(productParams), 1000 * retryCount);
-    } else {
-      console.error('Failed after retries:', error);
-      showNotification('Network error. Please check your connection.', 'error');
-    }
-  }
-}
-```
-
-### Global Error Handler
-
-```js
-// Listen to all failed events
-window.addEventListener('lce:actions.cart_failed', handleError);
-window.addEventListener('lce:actions.checkout_failed', handleError);
-window.addEventListener('lce:actions.address_failed', handleError);
-window.addEventListener('lce:actions.cart_product_add_failed', handleError);
-
-function handleError(event) {
-  const { error, context } = event.detail.data;
-  
-  // Log to error tracking service
-  if (window.Sentry) {
-    Sentry.captureException(error, {
-      tags: { sdk: 'liquid-commerce' },
-      extra: context
-    });
-  }
-  
-  // Show user notification
-  showNotification('Something went wrong. Please try again.', 'error');
-}
+## SDK Architecture
+
+The SDK attaches to the window object, providing methods for injection, UI helpers, and actions:
+
+```
+window.elements
+├── injectProductElement(params[])
+├── injectAddressElement(containerId, options?)
+├── injectCartElement(containerId)
+├── injectCheckoutElement(params)
+├── injectProductList(params)
+├── injectProductListSearch(params)
+├── injectProductListFilters(params)
+├── getInjectedComponents()
+│
+├── ui
+│   ├── cartButton(containerId, showCount?)
+│   ├── floatingCartButton(showCount?)
+│   ├── cartSubtotal(elementId)
+│   └── cartItemsCount(elementId, options?)
+│
+└── actions
+    ├── product
+    │   └── getDetails(identifier)
+    │
+    ├── address
+    │   ├── setAddressByPlacesId(placesId)
+    │   ├── setAddressManually(address, coords)
+    │   ├── getDetails()
+    │   └── clear()
+    │
+    ├── cart
+    │   ├── openCart()
+    │   ├── closeCart()
+    │   ├── toggleCart()
+    │   ├── addProduct(items[], openCart?)
+    │   ├── applyPromoCode(code)
+    │   ├── removePromoCode()
+    │   ├── resetCart()
+    │   └── getDetails()
+    │
+    └── checkout
+        ├── openCheckout()
+        ├── closeCheckout()
+        ├── toggleCheckout()
+        ├── exitCheckout()
+        ├── addProduct(items[], openCheckout?)
+        ├── applyPromoCode(code)
+        ├── removePromoCode()
+        ├── applyGiftCard(code)
+        ├── removeGiftCard(code)
+        ├── toggleIsGift(active?)
+        ├── toggleBillingSameAsShipping(active?)
+        ├── toggleMarketingPreferences(field, active)
+        ├── updateCustomerInfo(params)
+        ├── updateBillingInfo(params)
+        ├── updateGiftInfo(params)
+        └── getDetails()
 ```
 
 ---
 
-## ⚡ Performance & Best Practices
-
-### Lazy Loading Components
-
-Only inject components when needed:
-
-```js
-// ❌ Don't inject all components upfront
-await client.injectProductElement([/* 50 products */]);
-await client.injectCartElement('cart');
-await client.injectCheckoutElement({ containerId: 'checkout' });
-
-// ✅ Inject components as user navigates
-// On product page:
-await client.injectProductElement([{ containerId: 'pdp', identifier: productId }]);
-
-// On cart page (when user clicks cart):
-await client.injectCartElement('cart');
-
-// On checkout (when user proceeds):
-await client.injectCheckoutElement({ containerId: 'checkout' });
-```
-
-### Reuse Client Instance
-
-Initialize once, use everywhere:
-
-```js
-// ❌ Don't create multiple clients
-// page1.js
-const client1 = await Elements('KEY', { env: 'production' });
-// page2.js
-const client2 = await Elements('KEY', { env: 'production' });
-
-// ✅ Create once, reuse
-// app.js
-window.lceClient = await Elements('KEY', { env: 'production' });
-
-// page1.js
-const client = window.lceClient;
-await client.injectProductElement([...]);
+## Components
 
-// page2.js
-const client = window.lceClient;
-await client.injectCartElement('cart');
-```
-
-### Batch Product Injections
-
-Group product injections together:
-
-```js
-// ❌ Don't inject products one by one
-await client.injectProductElement([{ containerId: 'p1', identifier: 'id1' }]);
-await client.injectProductElement([{ containerId: 'p2', identifier: 'id2' }]);
-await client.injectProductElement([{ containerId: 'p3', identifier: 'id3' }]);
-
-// ✅ Inject all products at once
-await client.injectProductElement([
-  { containerId: 'p1', identifier: 'id1' },
-  { containerId: 'p2', identifier: 'id2' },
-  { containerId: 'p3', identifier: 'id3' }
-]);
-```
+### [Product](docs/product.md)
+Display product details with variants, pricing, and add-to-cart functionality. Automatically adapts to customer's delivery location.
 
-### Optimize Event Listeners
+### [Address](docs/address.md)
+Manage delivery location for availability and pricing. Embedded in product by default - standalone injection only needed for dedicated address pages.
 
-Use event delegation instead of multiple listeners:
+### [Cart](docs/cart.md)
+Shopping cart drawer with real-time updates, quantity controls, and promo codes. Syncs across tabs and persists between sessions.
 
-```js
-// ❌ Don't listen to every event
-window.addEventListener('lce:actions.product_loaded', handler);
-window.addEventListener('lce:actions.product_add_to_cart', handler);
-window.addEventListener('lce:actions.cart_updated', handler);
-// ... 20 more listeners
+### [Checkout](docs/checkout.md)
+Complete purchase flow with customer info, payment, and order confirmation. Available as drawer or hosted page.
 
-// ✅ Use consolidated listeners
-window.elements.onAllActions((data, metadata) => {
-  switch (metadata.eventName) {
-    case 'lce:actions.product_loaded':
-      handleProductLoad(data);
-      break;
-    case 'lce:actions.product_add_to_cart':
-      handleAddToCart(data);
-      break;
-    case 'lce:actions.cart_updated':
-      handleCartUpdate(data);
-      break;
-  }
-});
-```
-
-### Defer Non-Critical Operations
-
-Load SDK after critical page content:
+### [Product List](docs/product-list.md)
+Filterable, searchable product catalog with infinite scroll. Perfect for category pages and search results.
 
-```html
-<!-- ❌ Don't load SDK in <head> -->
-<head>
-  <script src="https://assets-elements.liquidcommerce.us/all/elements.js"></script>
-</head>
-
-<!-- ✅ Load SDK with defer or at end of body -->
-<head>
-  <script defer src="https://assets-elements.liquidcommerce.us/all/elements.js"></script>
-</head>
+---
 
-<!-- Or -->
-<body>
-  <!-- Your page content -->
-  <script src="https://assets-elements.liquidcommerce.us/all/elements.js"></script>
-</body>
-```
+## Getting Started
 
-### Use Auto-Init for Simple Cases
+### Declarative Setup (HTML Attributes)
 
-Auto-init is optimized for performance:
+Add products with zero JavaScript using data attributes:
 
 ```html
-<!-- ✅ Auto-init is the fastest way for simple setups -->
-<div data-lce-product="00619947000020"></div>
-<div data-lce-product="00832889005513"></div>
-
+<!-- Method 1: Direct attributes -->
+<div id="product-1"></div>
 <script
+  defer
+  type="text/javascript"
   data-liquid-commerce-elements
   data-token="YOUR_API_KEY"
-  data-env="production"
+  data-container-1="product-1"
+  data-product-1="00619947000020"
   src="https://assets-elements.liquidcommerce.us/all/elements.js"
 ></script>
-```
-
-### Avoid Unnecessary Re-renders
 
-Don't repeatedly inject the same component:
-
-```js
-// ❌ Don't re-inject on every state change
-function updateProduct() {
-  setProductId(newId);
-  await client.injectProductElement([{ containerId: 'pdp', identifier: newId }]);
-}
-
-// ✅ Components update automatically on state changes
-// Just inject once
-useEffect(() => {
-  client.injectProductElement([{ containerId: 'pdp', identifier: productId }]);
-}, []); // Empty deps - inject once
+<!-- Method 2: JSON configuration -->
+<script data-liquid-commerce-elements-products type="application/json">
+[{ "containerId": "product-1", "identifier": "00619947000020" }]
+</script>
 
-// Product will auto-update when you call actions
-await client.actions.cart.addProduct([...]);
+<!-- Method 3: Annotated elements -->
+<div data-lce-product="00619947000020"></div>
 ```
 
-### Cache Frequently Accessed Data
-
-```js
-// ❌ Don't repeatedly fetch the same data
-async function showCartTotal() {
-  const cart = await client.actions.cart.getDetails();
-  return cart.amounts.total;
-}
+See [Product documentation](docs/product.md) for all declarative options.
 
-// ✅ Use UI helpers that auto-update
-client.ui.cartSubtotal('cart-total-display');
-client.ui.cartItemsCount('cart-count-display');
-
-// Or cache and listen to updates
-let cachedCart = await client.actions.cart.getDetails();
-window.addEventListener('lce:actions.cart_updated', (event) => {
-  cachedCart = event.detail.data.current;
-});
-```
+### Programmatic Setup (JavaScript API)
 
-### Use CDN for Production
+Full control with the client instance:
 
-Always use CDN in production for optimal caching:
+```javascript
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
 
-```js
-// ✅ CDN (recommended)
-<script src="https://assets-elements.liquidcommerce.us/all/elements.js"></script>
+// Inject products
+await client.injectProductElement([
+  { containerId: 'pdp-1', identifier: '00619947000020' }
+]);
 
-// ❌ Don't self-host unless necessary
-<script src="/static/elements.js"></script>
+// Use actions
+client.actions.cart.openCart();
+await client.actions.cart.addProduct([
+  { identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }
+]);
 ```
 
-### Minimize Theme Complexity
+See component docs for complete programmatic APIs.
 
-Simpler themes = faster rendering:
+### TypeScript Support
 
-```js
-// ❌ Don't override every style property
-customTheme: {
-  global: {
-    colors: { /* 20 color overrides */ },
-    typography: { /* 15 typography overrides */ },
-    shadows: { /* 10 shadow overrides */ },
-    // ... 100 more overrides
-  }
-}
+For TypeScript projects, import types directly from the package:
 
-// ✅ Override only what's necessary
-customTheme: {
-  global: {
-    colors: {
-      primary: '#007bff',
-      secondary: '#6c757d'
-    }
+```typescript
+import { Elements } from '@liquidcommerce/elements-sdk';
+import type {
+  ILiquidCommerceElementsClient,
+  ILiquidCommerceElementsConfig,
+  IInjectProductElement,
+  IInjectCheckoutParams,
+  IInjectedComponent,
+  IAddProductParams
+} from '@liquidcommerce/elements-sdk';
+
+const config: ILiquidCommerceElementsConfig = {
+  env: 'production',
+  customTheme: {
+    global: { colors: { primary: '#007bff' } }
   }
-}
-```
-
-### Monitor Performance
-
-Track SDK performance in production:
-
-```js
-// Measure initialization time
-const start = performance.now();
-const client = await Elements('YOUR_API_KEY', { env: 'production' });
-console.log(`SDK initialized in ${performance.now() - start}ms`);
-
-// Track component load times
-window.addEventListener('lce:actions.product_loaded', (event) => {
-  const { loadTime } = event.detail.metadata;
-  console.log(`Product loaded in ${loadTime}ms`);
-  
-  // Send to analytics
-  analytics.track('SDK Component Load', {
-    component: 'product',
-    duration: loadTime
-  });
-});
-```
-
-### Production Checklist
+};
 
-Before going live:
-
-- ✅ Set `env: 'production'`
-- ✅ Set `debugMode: 'none'` (or omit)
-- ✅ Use CDN script URL
-- ✅ Pin to specific version (optional but recommended)
-- ✅ Configure proxy if using ad blockers
-- ✅ Test error handling
-- ✅ Verify event tracking
-- ✅ Check cart persistence
-- ✅ Test on target browsers
-- ✅ Measure performance metrics
-
-**Production-ready init:**
-
-```js
-const client = await Elements('YOUR_PRODUCTION_API_KEY', {
-  env: 'production',
-  debugMode: 'none',
-  customTheme: { /* minimal overrides */ },
-  proxy: { baseUrl: 'https://yourdomain.com/api/proxy' }
-});
+const client: ILiquidCommerceElementsClient = await Elements('YOUR_API_KEY', config);
 ```
 
-**📖 For debugging and troubleshooting:** See [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) for comprehensive problem-solving guide.
-
 ---
 
-## 🔒 Proxy Configuration
-
-Route API requests through your server to avoid ad blockers:
-
-```js
-const client = await Elements('YOUR_API_KEY', {
-  env: 'production',
-  proxy: {
-    baseUrl: 'https://yourdomain.com/api/liquidcommerce',
-    headers: {
-      'X-Custom-Header': 'value'
-    }
-  }
-});
-```
-
-The SDK automatically handles routing and required headers. See [`docs/PROXY.md`](docs/PROXY.md) for complete proxy setup guide with Next.js examples.
+## Documentation
 
-## 📚 Documentation
+### Component Guides
+- [Product](docs/product.md) - Product display and add-to-cart
+- [Address](docs/address.md) - Delivery location management
+- [Cart](docs/cart.md) - Shopping cart functionality
+- [Checkout](docs/checkout.md) - Purchase flow
+- [Product List](docs/product-list.md) - Catalog browsing
 
-**📖 Complete Documentation:**
+### Reference
+- [Actions](docs/actions.md) - Programmatic control
+- [Events](docs/events.md) - Event system
+- [Theming](docs/theming.md) - Customization
 
-- **[Documentation Index](docs/DOCUMENTATION_INDEX.md)** - Complete guide to all documentation
-- **[Configuration Reference](docs/CONFIGURATION.md)** - All configuration options with TypeScript types
-- **[Theming Guide](docs/THEMING.md)** - Complete customization reference
-- **[Actions Reference](docs/ACTIONS.md)** - Programmatic control with business use cases
-- **[Events Reference](docs/EVENTS.md)** - Event system and tracking guide
-- **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)** - Common issues and solutions
-- **[Browser Support](docs/BROWSER_SUPPORT.md)** - Detailed browser compatibility
-- **[Proxy Setup](docs/PROXY.md)** - Ad blocker avoidance configuration
+### Technical
+- [Proxy Setup](docs/proxy.md) - Ad blocker avoidance
+- [Browser Support](docs/browser-support.md) - Compatibility
+- [Troubleshooting](docs/troubleshooting.md) - Common issues
 
 ---
 
-## 🏷️ Versioning
-
-This project uses Semantic Versioning. Two CDN environments are available:
+## Browser Support
 
-- **Production:** `https://assets-elements.liquidcommerce.us/all/elements.js` (stable)
-- **Beta:** `https://assets-elements.liquidcommerce.us/all/beta/elements.js` (pre-release)
+Supports 2018+ browsers: Chrome 66+, Firefox 60+, Safari 12+, Edge 79+.
 
-## 💬 Support
-
-If you need help with your API key, environment selection, or implementation, contact your LiquidCommerce representative.
+See [Browser Support](docs/browser-support.md) for details.
 
 ---
 
-<div align="center">
-
-**Built with ❤️ by the LiquidCommerce Team**
-
-[Actions Reference](docs/ACTIONS.md) • [Events Guide](docs/EVENTS.md) • [Browser Support](docs/BROWSER_SUPPORT.md) • [Proxy Setup](docs/PROXY.md)
+## Support
 
-</div>
+Contact your LiquidCommerce representative for assistance.