@liquidcommerce/elements-sdk 2.2.1 → 2.3.0

package/README.md

@@ -28,48 +28,20 @@ Elements SDK
 <summary>Click to expand</summary>
 
 - [Overview](#-overview)
-  - [Latest Features](#-latest-features)
-  - [Key Features](#-key-features)
-- [Architecture](#-architecture)
-  - [System Architecture](#system-architecture)
-  - [Component Architecture](#component-architecture)
-  - [Event Flow](#event-flow)
-- [Features](#-features)
-- [Installation](#-installation)
-  - [CDN Usage](#option-a--use-the-cdn)
-  - [NPM Installation](#option-b--install-from-npm)
-- [Browser Support](#-browser-support)
 - [Quick Start](#-quick-start)
-  - [Auto-initialization](#step-1--auto-initialization-easiest)
-  - [Product Mapping](#step-2--map-products-to-containers)
-  - [Programmatic Control](#step-3--programmatic-control-advanced)
+- [Advanced Usage](#-advanced-usage)
+- [Browser Support](#-browser-support)
+- [Configuration](#-configuration)
 - [SDK Methods & API](#-sdk-methods--api)
-  - [Core Client Methods](#core-client-methods)
-  - [UI Methods](#ui-methods)
-  - [Builder Methods](#builder-methods-development-mode)
 - [Actions](#-actions)
-  - [Product Actions](#product-actions)
-  - [Address Actions](#address-actions)
-  - [Cart Actions](#cart-actions)
-  - [Checkout Actions](#checkout-actions)
 - [Events](#-events)
-  - [Event Listening](#event-listening)
-  - [Available Events](#available-events)
-- [Configuration](#-configuration)
-  - [Module Options](#module-options)
-  - [Environment Options](#environment-options)
-  - [Auto-init Attributes](#auto-init-data-attributes)
 - [Themes & Customization](#-themes--customization)
-  - [Theme Configuration](#theme-configuration)
-  - [Dynamic Updates](#dynamic-theme-updates)
+- [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)
-- [Demo Pages](#-demo-pages)
-  - [Simple Demo](#simple-demo-demosimplehtml)
-  - [Advanced Demo](#advanced-demo-demoadvancedhtml)
-- [Development Scripts](#-development-scripts)
-  - [Build Commands](#build-commands)
-  - [Code Quality](#code-quality-commands)
-  - [Maintenance](#maintenance-commands)
 - [Documentation](#-documentation)
 - [Versioning](#-versioning)
 - [Support](#-support)
@@ -80,14 +52,6 @@ Elements SDK
 
 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.
 
-### 🆕 Latest Features
-
-- **Builder Mode**: Dynamic theme customization for development environments
-- **Action Feedback Events**: All actions now emit success/failure events for better UX
-- **Proxy Support**: Route API requests through your server to avoid ad blockers
-- **Enhanced CLI**: Improved development scripts with parallel builds and better error handling
-- **TypeScript Support**: Full TypeScript definitions for better IDE experience
-
 ### ✨ Key Features
 
 <table>
@@ -133,399 +97,550 @@ The LiquidCommerce Elements SDK is a **production-ready JavaScript library** tha
 </tr>
 </table>
 
-## 🏗️ Architecture
-
-### System Architecture
-
-```mermaid
-graph TB
-    subgraph "Your Website"
-        HTML[HTML Page]
-        JS[JavaScript]
-        INIT[Elements SDK]
-    end
-    
-    subgraph "Elements SDK Core"
-        CLIENT[Elements Client]
-        
-        subgraph "Components"
-            PROD[Product Component]
-            CART[Cart Component]
-            CHECK[Checkout Component]
-            ADDR[Address Component]
-        end
-        
-        subgraph "Services"
-            ACT[Actions Service]
-            EVT[Events Service]
-            API[API Client]
-            THEME[Theme Provider]
-        end
-        
-        subgraph "UI Layer"
-            BTN[Cart Button]
-            FLOAT[Floating Cart]
-            DISP[Live Displays]
-        end
-    end
-    
-    subgraph "LiquidCommerce API"
-        PAPI[Products API]
-        CAPI[Cart API]
-        OAPI[Orders API]
-        AAPI[Address API]
-    end
-    
-    HTML --> INIT
-    JS --> CLIENT
-    
-    CLIENT --> PROD
-    CLIENT --> CART
-    CLIENT --> CHECK
-    CLIENT --> ADDR
-    
-    PROD --> API
-    CART --> API
-    CHECK --> API
-    ADDR --> API
-    
-    API --> PAPI
-    API --> CAPI
-    API --> OAPI
-    API --> AAPI
-    
-    ACT --> EVT
-    CLIENT --> ACT
-    CLIENT --> THEME
-```
-
-### Component Architecture
-
-```mermaid
-graph LR
-    subgraph "Product Component"
-        PD[Product Display]
-        PS[Size Selector]
-        PQ[Quantity Control]
-        PA[Add to Cart]
-    end
-    
-    subgraph "Cart Component"
-        CI[Cart Items]
-        CQ[Quantity Update]
-        CP[Promo Code]
-        CT[Cart Total]
-    end
-    
-    subgraph "Checkout Component"
-        CS[Shipping Info]
-        CB[Billing Info]
-        PM[Payment Method]
-        OS[Order Summary]
-    end
-    
-    PD --> PS
-    PS --> PQ
-    PQ --> PA
-    
-    CI --> CQ
-    CQ --> CT
-    CP --> CT
-    
-    CS --> CB
-    CB --> PM
-    PM --> OS
-```
-
-### Event Flow
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant SDK
-    participant Actions
-    participant Events
-    participant API
-    participant Website
-    
-    User->>SDK: Add to Cart
-    SDK->>Actions: cart.addProduct()
-    Actions->>API: POST /cart/items
-    API-->>Actions: Response
-    Actions->>Events: Emit Success/Failure
-    Events->>Website: lce:actions.cart_product_add_success
-    Website->>User: Show Feedback
-```
-
-## 🚀 Features
-
-- **🎯 Auto-initialization**: Single script tag with data attributes
-- **📦 Zero Dependencies**: Everything bundled, no peer dependencies
-- **🌐 CDN Ready**: No build step required for basic usage
-- **⚡ Lightweight**: ~150KB minified bundle size
-- **🔧 Framework Agnostic**: Works with React, Vue, Angular, or vanilla JS
-- **📱 Responsive**: Mobile-first design approach
-- **♿ Accessible**: WCAG 2.1 AA compliant components
-- **🎨 Themeable**: Comprehensive customization system
-- **🔐 Secure**: PCI compliant checkout flow
-- **📊 Analytics Ready**: Built-in event system for tracking
-- **🌍 Multi-environment**: Support for dev, staging, and production
-- **🧪 Well Tested**: Comprehensive test coverage
-
-## 📦 Installation
-
-### Choose how to include the SDK
-
-- **Use our CDN** (no build step required)
-- **Install from NPM** (for bundlers like Vite, Webpack, etc.)
-
-### Option A — Use the CDN
-
-Include the script on your page. Use the production or beta URL:
+## 🚀 Quick Start
 
-```html
-<!-- Production (latest) -->
-<script src="https://assets-elements.liquidcommerce.us/all/elements.js"></script>
+The fastest way to add e-commerce to your site is with **auto-initialization** - a single script tag that does everything.
 
-<!-- Beta (latest) -->
-<script src="https://assets-elements.liquidcommerce.us/all/beta/elements.js"></script>
-```
+### The Simplest Setup (30 seconds)
 
-You can also pin to a specific version:
+Add this single script tag to your page:
 
 ```html
-<script src="https://assets-elements.liquidcommerce.us/all/1.2.3/elements.js"></script>
+<script
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
 ```
 
-### Option B — Install from NPM
+That's it! You now have:
+- ✅ A floating cart button (bottom right)
+- ✅ Full cart functionality
+- ✅ Complete checkout flow
+- ✅ Ready to add products
 
-```bash
-npm install @liquidcommerceteam/elements-sdk
-# or
-pnpm add @liquidcommerceteam/elements-sdk
+### 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>
 ```
 
-Then import and initialize in your app code:
+**Use case:** Static HTML pages with known products
 
-```js
-import { Elements } from '@liquidcommerceteam/elements-sdk';
+#### Method 2: JSON Configuration (Best for CMS/dynamic content)
 
-const client = await Elements('YOUR_API_KEY', {
-  env: 'production',
-});
+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>
 ```
 
-## 🌐 Browser Support
+**Use case:** CMS platforms, templating engines, server-side rendering
 
-⚠️ **Important**: This SDK is designed for browser environments only. It will not work in server-side rendering, Node.js, or other non-browser environments. The SDK includes built-in safety measures to prevent errors when accidentally imported in these environments.
+#### Method 3: Annotated Elements (Best for grids/lists)
 
-### Supported Browsers
+Mark any div with a data attribute:
 
-The SDK supports **2018+ browsers** with comprehensive polyfills:
+```html
+<div class="product-grid">
+  <div data-lce-product="00619947000020"></div>
+  <div data-lce-product="00832889005513"></div>
+  <div data-lce-product="00851468007252"></div>
+</div>
 
-| 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 |
+<script
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
 
-📖 See [`docs/BROWSER_SUPPORT.md`](docs/BROWSER_SUPPORT.md) for detailed version compatibility and polyfill information.
+**Use case:** Product grids, category pages, search results
 
-## 🚀 Quick Start
+### Customizing the Cart Button
 
-### Step 1 — Auto-initialization (Easiest)
+By default, you get a floating cart button. Here's how to customize it:
 
-This single script both loads the SDK and initializes it automatically. Place it:
-- At the end of the `<body>` (recommended), or
-- In the `<head>` with `defer` so it doesn't block rendering.
+#### Option 1: Cart Button in a Specific Container
 
 ```html
-<!-- Body footer (recommended) -->
+<nav>
+  <div id="header-cart"></div>
+</nav>
+
 <script
   data-liquid-commerce-elements
   data-token="YOUR_API_KEY"
   data-env="production"
-  data-cart-id="buttons-container"
+  data-cart-id="header-cart"
   data-show-cart-items
   src="https://assets-elements.liquidcommerce.us/all/elements.js"
 ></script>
+```
+
+#### Option 2: No Cart Button (Manual Control)
 
-<!-- OR: Head with defer -->
+```html
 <script
-  defer
   data-liquid-commerce-elements
   data-token="YOUR_API_KEY"
   data-env="production"
-  data-cart-id="buttons-container"
-  data-show-cart-items
+  data-hide-cart-floating-button
   src="https://assets-elements.liquidcommerce.us/all/elements.js"
 ></script>
 ```
 
-**Available data attributes:**
-- `data-token="YOUR_API_KEY"` - Your API key (required)
-- `data-env="production|development"` - Environment (default: production)
-- `data-cart-id="container-id"` - ID for cart button container (optional, creates floating button if omitted)
-- `data-show-cart-items` - Show items count badge on cart button (optional)
-- `data-enable-debugging` - Enable debug logging in development (optional)
+### Advanced Auto-Init Features
 
-Add containers where you want elements to render:
+#### Add Product via URL (Marketing Links)
+
+Enable "add to cart" via URL parameters for email campaigns and ads:
 
 ```html
-<div id="buttons-container"></div>
-<div id="pdp-1"></div>
-<div id="pdp-2"></div>
+<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
 ```
 
-### Step 2 — Map products to containers
+**Use case:** Email campaigns, social media ads, QR codes
 
-Choose one or combine multiple methods:
+#### Apply Promo Code via URL (Campaign Tracking)
 
-#### 1) Attribute pairs on the main script
+Auto-apply promo codes from URL parameters:
 
 ```html
 <script
   data-liquid-commerce-elements
   data-token="YOUR_API_KEY"
   data-env="production"
-  data-container-1="pdp-1"
-  data-product-1="00619947000020"
-  data-container-2="pdp-2"
-  data-product-2="00832889005513"
+  data-promo-code-param="lce_promo"
   src="https://assets-elements.liquidcommerce.us/all/elements.js"
 ></script>
 ```
 
-#### 2) JSON configuration 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-products type="application/json">
-  [
-    { "containerId": "pdp-1", "identifier": "00619947000020" },
-    { "containerId": "pdp-2", "identifier": "00832889005513" }
-  ]
-</script>
+<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>
 ```
 
-#### 3) Annotated elements
+**Use case:** Time-sensitive promotions, holiday sales, flash deals
+
+#### Debug Mode (Development)
+
+Enable debug logging during development:
 
 ```html
-<div data-lce-product="00619947000020"></div>
-<div data-lce-product="00832889005513"></div>
+<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 -->
+  data-cart-id="container-id"
+  data-show-cart-items
+  data-hide-cart-floating-button
+  
+  <!-- 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"
+  
+  <!-- Debugging (dev only) -->
+  data-debug-mode="console|panel"
+  
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
 ```
 
-### Step 3 — Programmatic Control (Advanced)
+**📖 For complete auto-init options:** See [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) for all data attributes and configuration details.
 
-Initialize the SDK yourself for full control:
+---
+
+## 🔧 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',
-      enableDebugging: false, // only for development
-      customTheme: { /* optional theming overrides */ }
-    });
+(async () => {
+  const client = await window.Elements('YOUR_API_KEY', {
+    env: 'production',
+    debugMode: 'none',
+    customTheme: { /* theming overrides */ },
+    proxy: { /* proxy config */ }
+  });
 
-    // Your implementation here...
-  })();
+  // Inject 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>
 ```
 
-## 📖 SDK Methods & API
+**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.
 
-### Core Client Methods
+### Supported Browsers (2018+)
 
-Once initialized, the client provides these core methods:
+| 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 |
 
-#### Product Injection
+📖 See [`docs/BROWSER_SUPPORT.md`](docs/BROWSER_SUPPORT.md) for detailed compatibility.
 
-**`injectProductElement(params: IInjectProductElement[]): Promise<void>`**
+## ⚙️ Configuration
 
-Inject product components into containers:
+### Basic Configuration
 
 ```js
-await client.injectProductElement([
-  { containerId: 'pdp-1', identifier: '00619947000020' },
-  { containerId: 'pdp-2', identifier: '00832889005513' }
-]);
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',           // Environment
+  debugMode: 'none',           // Debug mode
+  customTheme: { },            // Theme overrides
+  proxy: { },                  // Proxy configuration
+  promoTicker: [ ]             // Promotional messages
+});
 ```
 
-#### Cart Injection
+### Environment Options
 
-**`injectCartElement(containerId: string): Promise<void>`**
+```js
+env: 'production'    // Live environment (default)
+env: 'staging'       // Pre-production testing
+env: 'development'   // Development with extra logging
+env: 'local'         // Local development
+```
 
-Inject a cart component:
+### Debug Modes
 
 ```js
-await client.injectCartElement('cart-container');
+debugMode: 'none'     // No debugging (production default)
+debugMode: 'console'  // Console logs only
+debugMode: 'panel'    // Visual debug panel + console logs
 ```
 
-#### Checkout Injection
+**Note:** Debug mode is automatically disabled in production environment for security.
 
-**`injectCheckoutElement(containerId: string): Promise<void>`**
+### Custom Theme
 
-Inject a checkout component:
+Override default styles and layouts:
 
 ```js
-await client.injectCheckoutElement('checkout-container');
+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' }
+    }
+  }
+}
 ```
 
-#### Address Injection
+**📖 For complete theming options:** See [`docs/THEMING.md`](docs/THEMING.md)
 
-**`injectAddressElement(containerId: string): Promise<void>`**
+### Proxy Configuration
 
-Inject an address form component:
+Route API requests through your server to avoid ad blockers:
 
 ```js
-await client.injectAddressElement('address-container');
+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'
+  }
+]
 ```
 
-### UI Methods
+**📖 For all configuration options:** See [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) for complete reference with TypeScript types.
+
+---
+
+## 📖 SDK Methods & API
+
+### Component Injection
 
-#### Cart Buttons
+Inject SDK components into your page containers.
+
+#### Products
+
+```js
+await client.injectProductElement([
+  { containerId: 'pdp-1', identifier: '00619947000020' },
+  { containerId: 'pdp-2', identifier: '00832889005513' }
+]);
+```
 
-**`ui.cartButton(containerId: string, showItemsCount?: boolean): void`**
+**Identifier types:** UPC, product ID, or Salsify grouping ID
 
-Create an "open cart" button in a specific container:
+#### Cart
 
 ```js
-client.ui.cartButton('buttons-container');
+await client.injectCartElement('cart-container');
+```
+
+**Use case:** Dedicated cart page
+
+#### Checkout
 
-// With items count badge
-client.ui.cartButton('buttons-container', true);
+```js
+await client.injectCheckoutElement('checkout-container');
 ```
 
-**`ui.floatingCartButton(showItemsCount?: boolean): void`**
+**Use case:** Dedicated checkout page
 
-Automatically inject a floating cart button:
+#### Address
 
 ```js
-client.ui.floatingCartButton();
+await client.injectAddressElement('address-container');
+```
 
-// With items count badge
-client.ui.floatingCartButton(true);
+**Use case:** Shipping address collection page
+
+### UI Helpers
+
+Create standalone UI elements that integrate with the SDK.
+
+#### Cart Button (in container)
+
+```js
+client.ui.cartButton('header-cart', true);
 ```
 
-#### Live Cart Display
+**Parameters:**
+- `containerId` - Where to place the button
+- `showItemsCount` - Show item count badge (optional)
 
-**`ui.cartTotal(elementId: string): void`**
+**Use case:** Header navigation, sidebar
 
-Bind an element to display the live cart total (automatically updates when cart changes):
+#### Floating Cart Button
 
 ```js
-client.ui.cartTotal('cart-total-display');
+client.ui.floatingCartButton(true);
 ```
 
-**`ui.cartItemsCount(elementId: string): void`**
+**Parameters:**
+- `showItemsCount` - Show item count badge (optional)
+
+**Use case:** Always-visible cart access (bottom-right corner)
 
-Bind an element to display the live cart items count (automatically updates when cart changes):
+#### Live Cart Data Display
+
+Bind elements to auto-update with cart data:
 
 ```js
-client.ui.cartItemsCount('cart-items-badge');
+// Show live subtotal
+client.ui.cartSubtotal('cart-total-display');
+
+// Show live item count
+client.ui.cartItemsCount('cart-badge');
+```
+
+**Example:**
+```html
+<nav>
+  <span>Cart: $<span id="cart-total-display">0.00</span></span>
+  <span>(<span id="cart-badge">0</span> items)</span>
+</nav>
 ```
 
 ### Builder Methods (Development Mode)
@@ -815,359 +930,1295 @@ window.elements.onAllActions((data, metadata) => {
 
 See [`docs/EVENTS.md`](docs/EVENTS.md) for complete event reference with implementation examples.
 
-## ⚙️ Configuration
-
-Configure the SDK when initializing:
-
-```js
-const client = await Elements('YOUR_API_KEY', {
-  env: 'production', // 'local' | 'development' | 'staging' | 'production'
-  enableDebugging: false, // Enable console logging (development only)
-  isBuilder: false, // Enable builder methods (development only)
-  customTheme: { /* theme overrides */ },
-  proxy: { /* proxy configuration */ }
-});
-```
-
-### Environment Options
-
-- **`production`**: Live environment for customer-facing sites
-- **`staging`**: Pre-production testing environment  
-- **`development`**: Development environment with additional debugging
-- **`local`**: Local development environment
-
-### Auto-init Data Attributes
-
-When using auto-initialization, configure via data attributes:
-
-- `data-liquid-commerce-elements`: Required flag to enable auto-init
-- `data-token`: Your API key (required)
-- `data-env`: Environment (defaults to production)
-- `data-cart-id`: Container ID for cart button
-- `data-enable-debugging`: Enable debugging mode
-- `data-container-X` / `data-product-X`: Product mapping pairs
-
 ## 🎨 Themes & Customization
 
-Customize the appearance of SDK components using the theme system:
+The SDK provides a theming system that lets you match components to your brand.
+
+### Global Theming
 
 ```js
 const client = await Elements('YOUR_API_KEY', {
-  env: 'production',
   customTheme: {
     global: {
-      colors: {
-        primary: '#007bff',
-        secondary: '#6c757d'
-      },
-      typography: {
-        fontFamily: 'Roboto, sans-serif',
-        fontSize: '16px'
-      }
-    },
-    product: {
-      layout: {
-        imagePosition: 'left',
-        showDescription: true
+      theme: {
+        primaryColor: '#007bff',
+        accentColor: '#6c757d',
+        successColor: '#28a745',
+        errorColor: '#dc3545',
+        warningColor: '#ffc107',
+        defaultTextColor: '#212529',
+        selectedTextColor: '#ffffff',
+        drawerBackgroundColor: '#ffffff',
+        buttonCornerRadius: '8px',
+        cardCornerRadius: '12px',
+        headingFont: {
+          name: 'Inter',
+          weights: [600, 700]
+        },
+        paragraphFont: {
+          name: 'Inter',
+          weights: [400, 500]
+        }
       },
-      colors: {
-        price: '#28a745',
-        sale: '#dc3545'
-      }
-    },
-    cart: {
-      layout: {
-        showRetailerLogos: true,
-        compactMode: false
-      }
-    },
-    checkout: {
       layout: {
-        singlePage: true,
-        showOrderSummary: true
+      enablePersonalization: true,
+      personalizationText: 'Customize your product',
+      personalizationCardStyle: 'outlined',
+      allowPromoCodes: true,
+      inputFieldStyle: 'outlined',
+      poweredByMode: 'light'
       }
     }
   }
 });
 ```
 
-In builder mode, themes can be updated dynamically:
+### Component-Specific Theming
+
+#### Product Component
 
 ```js
-// Update themes in real-time (builder mode only)
-await client.builder.updateComponentGlobalConfigs({
-  colors: { primary: '#ff6b6b' }
+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: { imagePosition: 'right' }
+  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' }
 });
 ```
 
-## 🔒 Proxy Configuration
+**📖 For complete theming documentation:** See [`docs/THEMING.md`](docs/THEMING.md)
 
-Route API requests through your server to avoid ad blockers:
+---
+
+## 🎁 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 { code, appliedAmount, remainingBalance } = event.detail.data;
+  console.log(`Applied $${appliedAmount}, Remaining: $${remainingBalance}`);
+});
+
+window.addEventListener('lce:actions.checkout_gift_card_failed', (event) => {
+  const { code, 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 { code, discountAmount, newTotal } = event.detail.data;
+  console.log(`${code} saved $${discountAmount}! New total: $${newTotal}`);
+});
+
+window.addEventListener('lce:actions.cart_promo_code_failed', (event) => {
+  const { code, error } = event.detail.data;
+  console.log('Promo failed:', error.message);
+});
+```
+
+### Promo Ticker
+
+Display rotating promotional messages at the top of your site:
+
+```js
+// Via initialization config
 const client = await Elements('YOUR_API_KEY', {
-  env: 'production',
-  proxy: {
-    baseUrl: 'https://yourdomain.com/api/liquidcommerce',
-    headers: {
-      'X-Custom-Header': 'value'
+  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}`);
 });
 ```
 
-The SDK automatically handles routing and required headers. See [`docs/PROXY.md`](docs/PROXY.md) for complete proxy setup guide with Next.js examples.
+### Purchase Minimum Alerts
 
-## 📚 Documentation
+Automatically displays alerts when a retailer has minimum purchase requirements. No configuration needed - the SDK handles this automatically based on retailer rules.
 
-For detailed guides and advanced usage:
+### Age Verification
 
-- [`docs/ACTIONS.md`](docs/ACTIONS.md) - Complete actions reference with business use cases
-- [`docs/EVENTS.md`](docs/EVENTS.md) - Events guide with implementation examples  
-- [`docs/BROWSER_SUPPORT.md`](docs/BROWSER_SUPPORT.md) - Detailed browser compatibility
-- [`docs/PROXY.md`](docs/PROXY.md) - Proxy configuration for ad blocker avoidance
+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.
 
-## 🏷️ Versioning
+### 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`);
+});
+```
+
+---
 
-This project uses Semantic Versioning. The SDK is available in two environments:
+## 🔧 Core Capabilities
 
-### Beta Environment
-- Branch: `beta`
-- Base URL: `https://assets-elements.liquidcommerce.us/all/beta/`
-- Purpose: Testing and pre-release features
+The SDK includes several built-in services that work behind the scenes to provide a robust, production-ready experience.
 
-### Production Environment  
-- Branch: `main`
-- Base URL: `https://assets-elements.liquidcommerce.us/all/`
-- Purpose: Stable releases for production use
+### 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.items, cart.subtotal, cart.itemCount);
 
-### CDN Path Structure
+// Get current checkout state
+const checkout = await client.actions.checkout.getDetails();
+console.log(checkout.total, checkout.customerInfo, checkout.isGift);
 
+// 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.price, product.variants);
 ```
-elements-sdk/
-└── all/
-    ├── beta/
-    │   ├── 1.2.3/elements.js
-    │   ├── 1.2.4/elements.js
-    │   └── elements.js  (beta latest)
-    ├── 1.2.2/elements.js  (production)
-    ├── 1.2.3/elements.js  (production)
-    └── elements.js  (production latest)
+
+**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 cartData = event.detail.data;
+  console.log('Cart changed:', cartData);
+});
+
+// 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
+  });
+});
 ```
 
-## 🎭 Demo Pages
+### Circuit Breaker
 
-The SDK includes ready-to-use demo pages in the `demo/` folder that showcase different implementation approaches:
+The SDK includes a circuit breaker pattern to prevent cascading failures:
 
-### Simple Demo (`demo/simple.html`)
+```js
+// Automatically handles API failures
+// - After 5 consecutive failures, circuit opens
+// - Requests fail fast without hitting the API
+// - After 30 seconds, circuit half-opens
+// - Next successful request closes the circuit
+```
+
+**Circuit states:**
+- **Closed:** Normal operation, all requests go through
+- **Open:** API is failing, requests fail fast
+- **Half-Open:** Testing if API recovered, limited requests allowed
+
+This protects your site from slowdowns when the API is experiencing issues.
+
+### 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
 
-Demonstrates **auto-initialization** using data attributes - the easiest way to get started:
+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:
+await client.injectProductElement([
+  { containerId: 'pdp-1', identifier: 'product-123' }
+]);
+
+// 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
+// - CircuitBreaker
+// - 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);
+    }
+
+    initSDK();
+
+    // Cleanup
+    return () => {
+      // SDK handles cleanup automatically
+    };
+  }, [productId]);
+
+  return (
+    <div>
+      <div id="cart-button"></div>
+      <div id="product-container"></div>
+    </div>
+  );
+}
+```
+
+### Vue Integration
+
+```vue
+<template>
+  <div>
+    <div ref="cartButton"></div>
+    <div ref="productContainer"></div>
+  </div>
+</template>
+
+<script>
+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'
+      });
+
+      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
-<!-- Auto-init with data attributes -->
+<!-- In your theme's header.php or functions.php -->
 <script
   data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  data-env="development"
-  data-enable-debugging
-  src="../umd/elements.js"
+  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>
 ```
 
-**Features shown:**
-- Auto-initialization with data attributes
-- Multiple product mapping methods (data attributes, JSON script, annotated elements)
-- Event listening for actions and forms
-- Basic container setup for products, cart, and checkout
+### 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>
 
-**Best for:** Quick prototyping, simple integrations, getting familiar with the SDK
+<!-- In product template -->
+<div data-lce-product="{{ product.barcode }}"></div>
+```
 
-### Advanced Demo (`demo/advanced.html`)
+### Multi-Page Applications
 
-Demonstrates **programmatic initialization** for full control:
+For SPAs and multi-page apps, initialize once and reuse:
 
-```javascript
-const client = await window.Elements(API_KEY, {
-  env: "development",
-  enableDebugging: true,
-  customTheme: { /* theme config */ }
-});
+```js
+// app.js (initialize once)
+let elementsClient = null;
+
+async function getElementsClient() {
+  if (!elementsClient) {
+    elementsClient = await Elements('YOUR_API_KEY', {
+      env: 'production'
+    });
+  }
+  return elementsClient;
+}
 
-// Programmatic component injection
-client.buttons.openCart("buttons-container");
+// product-page.js
+const client = await getElementsClient();
 await client.injectProductElement([
-  { containerId: "pdp-container", identifier: '00619947000020' }
+  { containerId: 'pdp-1', identifier: productId }
 ]);
-await client.injectCheckoutElement("checkout-container");
+
+// cart-page.js
+const client = await getElementsClient();
+await client.injectCartElement('cart-container');
 ```
 
-**Features shown:**
-- Manual client initialization with full configuration
-- Programmatic component injection
-- Builder methods for theme updates (commented examples)
-- Advanced event handling
-- Dynamic theme updates
+---
+
+## 🚨 Error Handling
+
+### Initialization Errors
 
-**Best for:** Complex integrations, custom workflows, theme customization, production implementations
+```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);
+  }
+}
+```
 
-### Running the Demos
+### Action Errors
 
-1. **Clone the repository**
-2. **Open demo files** in your browser
-3. **Update API keys** with your own credentials
-4. **Modify environment** settings as needed (`development`, `staging`, `production`)
+All actions emit failure events with detailed error information:
 
-The demos use local UMD builds (`../umd/elements.js`) but can be easily switched to CDN URLs for testing.
+```js
+// Product loaded successfully
+window.addEventListener('lce:actions.product_loaded', (event) => {
+  const { identifier, productData } = event.detail.data;
+  console.log(`Product ${identifier} loaded successfully`);
+});
 
-## 🛠️ Development Scripts
+// 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');
+});
 
-For SDK development and maintenance, the following npm/pnpm scripts are available:
+// 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');
+  }
+});
 
-### Build Commands
+// 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');
+});
 
-**`build`** - Production build
-```bash
-pnpm run build
+// 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');
+  }
+});
 ```
-- Creates optimized ESM and UMD bundles for production
-- Generates TypeScript declarations
-- Enables minification and compression
-- Removes console logs and debugging code
-- **Output:** `dist/index.esm.js` (ESM) + `umd/elements.js` (UMD)
 
-**`build:dev`** - Development build
-```bash
-pnpm run build:dev
+### 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');
+    }
+  }
+}
 ```
-- Creates unminified bundles with source maps
-- Preserves console logs and debugging code
-- Faster build times for development
-- **Output:** Same as build but with debugging enabled
 
-**`dev`** - Development with watch mode
-```bash
-pnpm run dev
+### 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');
+}
 ```
-- Same as `build:dev` but watches for file changes
-- Automatically rebuilds on source code changes
-- **Best for:** Active development
 
-### Code Quality Commands
+---
 
-**`lint`** - Lint and auto-fix code
-```bash
-pnpm run lint
+## ⚡ 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('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('checkout');
 ```
-- Uses Biome to lint TypeScript/JavaScript files
-- Automatically fixes fixable issues
-- Enforces code style and catches common errors
 
-**`format`** - Format code
-```bash
-pnpm run format
+### 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([...]);
+
+// page2.js
+const client = window.lceClient;
+await client.injectCartElement('cart');
 ```
-- Uses Biome to format all source files
-- Ensures consistent code formatting
-- Applies formatting rules defined in `biome.json`
 
-**`check`** - Combined linting and formatting
-```bash
-pnpm run check
+### 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' }
+]);
 ```
-- Runs both linting and formatting in one command
-- Auto-fixes issues and formats code
-- **Recommended before commits**
 
-**`fl`** - Format, lint, and build (Fast Loop)
-```bash
-pnpm run fl
+### Optimize Event Listeners
+
+Use event delegation instead of multiple listeners:
+
+```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
+
+// ✅ 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;
+  }
+});
 ```
-- Combines `check` + `build:dev`
-- Complete code quality check + development build
-- **Perfect for:** Pre-commit workflow
 
-### Maintenance Commands
+### Defer Non-Critical Operations
 
-**`clean`** - Clean build outputs
-```bash
-pnpm run clean
+Load SDK after critical page content:
+
+```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>
 ```
-- Removes `dist/` and `umd/` directories
-- **Use when:** Build artifacts are corrupted
 
-**`clean:hard`** - Complete reset
-```bash
-pnpm run clean:hard
+### Use Auto-Init for Simple Cases
+
+Auto-init is optimized for performance:
+
+```html
+<!-- ✅ Auto-init is the fastest way for simple setups -->
+<div data-lce-product="00619947000020"></div>
+<div data-lce-product="00832889005513"></div>
+
+<script
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
 ```
-- Removes build outputs AND `node_modules/`
-- Reinstalls all dependencies with `pnpm install`
-- Runs a fresh production build
-- **Use when:** Dependency issues or major updates
 
-**`changelog`** - Generate changelog
-```bash
-pnpm run changelog
+### 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
+
+// Product will auto-update when you call actions
+await client.actions.cart.addProduct([...]);
 ```
-- Generates `CHANGELOG.md` from conventional commits
-- Uses Angular commit convention
-- **Use when:** Preparing releases
 
-### Build Configuration
+### Cache Frequently Accessed Data
 
-The build system uses **Rollup** with different configurations:
+```js
+// ❌ Don't repeatedly fetch the same data
+async function showCartTotal() {
+  const cart = await client.actions.cart.getDetails();
+  return cart.total;
+}
+
+// ✅ 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;
+});
+```
 
-#### ESM Build (`dist/index.esm.js`)
-- **Target:** Modern bundlers (Vite, Webpack, etc.)
-- **Format:** ES Modules
-- **Optimizations:** Tree shaking, modern syntax
-- **Use case:** NPM package imports
+### Use CDN for Production
 
-#### UMD Build (`umd/elements.js`)
-- **Target:** Direct browser usage
-- **Format:** Universal Module Definition
-- **Global:** `window.LiquidCommerceElements`
-- **Optimizations:** Maximum browser compatibility
-- **Use case:** CDN distribution, `<script>` tags
+Always use CDN in production for optimal caching:
 
-#### Development vs Production
-- **Development:** Source maps, preserved logging, faster builds
-- **Production:** Minified, compressed, optimized for size
+```js
+// ✅ CDN (recommended)
+<script src="https://assets-elements.liquidcommerce.us/all/elements.js"></script>
 
-### Recommended Workflows
+// ❌ Don't self-host unless necessary
+<script src="/static/elements.js"></script>
+```
 
-**Development Workflow:**
-```bash
-# Start development
-pnpm run dev
+### Minimize Theme Complexity
 
-# Before committing
-pnpm run fl
+Simpler themes = faster rendering:
+
+```js
+// ❌ Don't override every style property
+customTheme: {
+  global: {
+    colors: { /* 20 color overrides */ },
+    typography: { /* 15 typography overrides */ },
+    shadows: { /* 10 shadow overrides */ },
+    // ... 100 more overrides
+  }
+}
+
+// ✅ Override only what's necessary
+customTheme: {
+  global: {
+    colors: {
+      primary: '#007bff',
+      secondary: '#6c757d'
+    }
+  }
+}
 ```
 
-**Release Workflow:**
-```bash
-# Clean and build for release
-pnpm run clean:hard
+### 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
 
-# Generate changelog
-pnpm run changelog
+**Production-ready init:**
 
-# Build is run automatically on publish
+```js
+const client = await Elements('YOUR_PRODUCTION_API_KEY', {
+  env: 'production',
+  debugMode: 'none',
+  customTheme: { /* minimal overrides */ },
+  proxy: { baseUrl: 'https://yourdomain.com/api/proxy' }
+});
 ```
 
-**Troubleshooting:**
-```bash
-# If builds are failing
-pnpm run clean:hard
+**📖 For debugging and troubleshooting:** See [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) for comprehensive problem-solving guide.
+
+---
 
-# For code quality issues
-pnpm run check
+## 🔒 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
+
+**📖 Complete Documentation:**
+
+- **[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
+
+---
+
+## 🏷️ Versioning
+
+This project uses Semantic Versioning. Two CDN environments are available:
+
+- **Production:** `https://assets-elements.liquidcommerce.us/all/elements.js` (stable)
+- **Beta:** `https://assets-elements.liquidcommerce.us/all/beta/elements.js` (pre-release)
+
 ## 💬 Support
 
 If you need help with your API key, environment selection, or implementation, contact your LiquidCommerce representative.