@liquidcommerce/elements-sdk 2.7.21 → 2.7.23

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

@@ -45,13 +45,12 @@ Configure checkout to load from URL parameter:
   data-liquid-commerce-elements
   data-token="YOUR_API_KEY"
   data-env="production"
-  data-checkout-container="checkout"
   data-checkout-param="lce_checkout"
   type="text/javascript"
   src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 
-<div id="checkout"></div>
+<div data-lce-checkout></div>
 ```
 
 Visit `https://yoursite.com/checkout?lce_checkout=checkout_abc123` to load that checkout.
@@ -208,7 +207,7 @@ window.LiquidCommerce.elements.actions.checkout.updateCustomerInfo({
   lastName: 'Doe',
   email: 'john@example.com',
   phone: '+15551234567',
-  birthDate: '123 Main St',
+  birthDate: '1990-01-15',
   addressTwo: 'Apt 4',
   company: 'Acme Corp'
 });
@@ -274,7 +273,7 @@ console.log(checkoutData);
 // {
 //   token: 'abc123xyz',
 //   cartId: 'cart_abc123',
-//   items: [...],
+//   items: { 'cart_item_id': { ... } },
 //   amounts: {
 //     subtotal: 9998,
 //     tax: 800,
@@ -282,8 +281,6 @@ console.log(checkoutData);
 //     tip: 200,
 //     total: 11498
 //   },
-//   customer: { ... },
-//   shippingAddress: { ... },
 //   isGift: false,
 //   ...
 // }
@@ -307,7 +304,7 @@ window.addEventListener('lce:actions.checkout_closed', (event) => {
 });
 
 window.addEventListener('lce:actions.checkout_failed', (event) => {
-  console.error('Checkout failed:', event.detail.data.error);
+  console.error('Checkout failed:', event.detail.data.message);
 });
 ```
 
@@ -315,8 +312,8 @@ window.addEventListener('lce:actions.checkout_failed', (event) => {
 
 ```javascript
 window.addEventListener('lce:actions.checkout_customer_information_updated', (event) => {
-  const { email, phone } = event.detail.data;
-  console.log('Customer info updated:', email);
+  const { cartId } = event.detail.data;
+  console.log('Customer info updated for cart:', cartId);
 });
 ```
 
@@ -324,8 +321,8 @@ window.addEventListener('lce:actions.checkout_customer_information_updated', (ev
 
 ```javascript
 window.addEventListener('lce:actions.checkout_is_gift_toggled', (event) => {
-  const { isGift } = event.detail.data;
-  console.log('Gift mode:', isGift ? 'enabled' : 'disabled');
+  const { isActive } = event.detail.data;
+  console.log('Gift mode:', isActive ? 'enabled' : 'disabled');
 });
 
 window.addEventListener('lce:actions.checkout_gift_information_updated', (event) => {
@@ -337,8 +334,8 @@ window.addEventListener('lce:actions.checkout_gift_information_updated', (event)
 
 ```javascript
 window.addEventListener('lce:actions.checkout_billing_same_as_shipping_toggled', (event) => {
-  const { billingSameAsShipping } = event.detail.data;
-  console.log('Billing same as shipping:', billingSameAsShipping);
+  const { isActive } = event.detail.data;
+  console.log('Billing same as shipping:', isActive);
 });
 
 window.addEventListener('lce:actions.checkout_billing_information_updated', (event) => {
@@ -350,8 +347,8 @@ window.addEventListener('lce:actions.checkout_billing_information_updated', (eve
 
 ```javascript
 window.addEventListener('lce:actions.checkout_marketing_preferences_toggled', (event) => {
-  const { field, active } = event.detail.data;
-  console.log(`Marketing ${field}:`, active);
+  const { fieldName, isActive } = event.detail.data;
+  console.log(`Marketing ${fieldName}:`, isActive);
 });
 ```
 
@@ -359,18 +356,18 @@ window.addEventListener('lce:actions.checkout_marketing_preferences_toggled', (e
 
 ```javascript
 window.addEventListener('lce:actions.checkout_item_removed', (event) => {
-  const { itemId } = event.detail.data;
-  console.log('Item removed:', itemId);
+  const { cartItemId } = event.detail.data;
+  console.log('Item removed:', cartItemId);
 });
 
 window.addEventListener('lce:actions.checkout_item_quantity_increase', (event) => {
-  const { itemId, newQuantity } = event.detail.data;
-  console.log(`Item ${itemId} quantity: ${newQuantity}`);
+  const { cartItemId, quantity } = event.detail.data;
+  console.log(`Item ${cartItemId} quantity: ${quantity}`);
 });
 
 window.addEventListener('lce:actions.checkout_item_quantity_decrease', (event) => {
-  const { itemId, newQuantity } = event.detail.data;
-  console.log(`Item ${itemId} quantity: ${newQuantity}`);
+  const { cartItemId, quantity } = event.detail.data;
+  console.log(`Item ${cartItemId} quantity: ${quantity}`);
 });
 ```
 
@@ -378,8 +375,9 @@ window.addEventListener('lce:actions.checkout_item_quantity_decrease', (event) =
 
 ```javascript
 window.addEventListener('lce:actions.checkout_tip_updated', (event) => {
-  const { tip } = event.detail.data;
-  console.log('Tip amount:', tip / 100);
+  const { deliveryTips } = event.detail.data;
+  const total = deliveryTips.reduce((sum, t) => sum + t.tip, 0);
+  console.log('Tip amount:', total / 100);
 });
 ```
 
@@ -392,14 +390,14 @@ window.addEventListener('lce:actions.checkout_submit_started', (event) => {
 });
 
 window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
-  const { orderId } = event.detail.data;
-  console.log('Order completed:', orderId);
+  const { orderNumber } = event.detail.data;
+  console.log('Order completed:', orderNumber);
   // Redirect to confirmation page
 });
 
 window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
-  const { error } = event.detail.data;
-  console.error('Payment failed:', error);
+  const { message } = event.detail.data;
+  console.error('Payment failed:', message);
   // Show error message
 });
 ```
@@ -566,8 +564,8 @@ window.addEventListener('lce:actions.checkout_customer_information_updated', ()
 
 window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
   gtag('event', 'purchase', {
-    transaction_id: event.detail.data.orderId,
-    value: event.detail.data.total / 100,
+    transaction_id: event.detail.data.orderNumber,
+    value: event.detail.data.orderTotal / 100,
     currency: 'USD'
   });
 });

package/docs/v1/guides/events.md

@@ -64,7 +64,7 @@ window.addEventListener('lce:actions.client_ready', (event) => {
 
 Fires when a product component finishes loading and product data is available.
 
-**Data includes:** `identifier`, `name`, `price`, `selectedSizeId`, `selectedFulfillmentType`.
+**Data includes:** `identifier`, `name`, `priceInfo`, `selectedSizeId`, `selectedFulfillmentType`.
 
 **Example**
 
@@ -819,7 +819,7 @@ window.addEventListener('lce:actions.checkout_gift_card_failed', (event) => {
 
 Fires when products are added to checkout via the actions API.
 
-**Data includes:** `cartId`, `itemsAdded`, `identifiers`, `isPresale`.
+**Data includes:** `cartId`, `itemsAdded`, `identifiers`.
 
 **Example**
 
@@ -834,7 +834,7 @@ window.addEventListener('lce:actions.checkout_product_add_success', (event) => {
 
 Fires when adding products to checkout via the actions API fails.
 
-**Data includes:** `cartId`, `identifiers`, `error`, `isPresale`.
+**Data includes:** `cartId`, `identifiers`, `error`.
 
 **Example**
 
@@ -904,7 +904,7 @@ window.addEventListener('lce:actions.product_loaded', (event) => {
     items: [{
       item_id: data.identifier,
       item_name: data.name,
-      price: data.price / 100
+      price: data.priceInfo?.minimum / 100
     }]
   });
 });

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

@@ -157,6 +157,28 @@ For products with multiple sizes:
 - Availability checking per size
 - Out-of-stock indication
 
+#### Preselect a Size via URL
+
+Use the `lce_size` query parameter to preselect a size when the product page loads:
+
+```
+https://yoursite.com/products/buffalo-trace?lce_size=750ml
+```
+
+- The value is compared against each size's full label as shown on the page.
+- Matching is case-insensitive and ignores spacing and punctuation — only letters, digits, and decimal points are compared — so `750 ML`, `750ml`, and `750ML` all select a `750ml` size, while decimals are kept so `1.0L` and `1.75L` stay distinct.
+- If the value matches no size, the default size selection is used.
+
+**Pack sizes:** the label includes the pack description when present (e.g. `50 ML (12PK)`). To select that size, include the pack in the value:
+
+```
+https://yoursite.com/products/mini-bottles?lce_size=50ml(12pk)
+```
+
+Both `50ml(12pk)` and `50ml12pk` match `50 ML (12PK)` (punctuation is ignored). A value of just `50ml` only matches a size whose label is `50 ML` with no pack.
+
+`lce_size` is a fixed parameter name (not configured through a script attribute) and only applies to the product page.
+
 ### Fulfillment Types
 
 Two fulfillment options:
@@ -183,7 +205,7 @@ For products with multiple retailers:
 - Select with one tap
 
 **Popup View**
-- "Choose Retailer" button
+- "See Delivery Options" button (shows the available fulfillment count, e.g. "See Delivery Options (3)")
 - Modal with full retailer list
 - Filter and search capabilities
 
@@ -218,17 +240,38 @@ console.log(productData);
 // {
 //   identifier: '00619947000020',
 //   name: 'Premium Whiskey',
-//   price: 4999,
-//   selectedSize: { id: '750ml', upc: '00619947000020', ... },
+//   priceInfo: { currency: 'USD', minimum: 4999, average: 4999, maximum: 4999 },
+//   selectedSizeId: '750ml',
 //   selectedFulfillmentType: 'shipping',
-//   selectedRetailer: { id: 'retailer_123', name: 'Spirits Shop', ... },
-//   quantity: 1,
+//   selectedFulfillmentId: 'fulfillment_123',
+//   productHasAvailability: true,
+//   fulfillmentHasAvailability: true,
+//   sizes: { '750ml': { ... } },
 //   ...
 // }
 ```
 
 **Note:** The product must be injected and loaded before calling `getDetails()`. If the product hasn't been loaded, an error is thrown.
 
+### Get Product Availability by State
+
+Check availability for one or more products in a given state. Returns a `Promise<IProductAvailabilityResponse>`:
+
+```javascript
+const availability = await window.LiquidCommerce.elements.actions.product.getProductAvailabilityByState(
+  ['00619947000020', '08504405135'],
+  'NY'
+);
+
+console.log(availability);
+// {
+//   products: [...],
+//   retailers: { ... }
+// }
+```
+
+The `state` argument is optional; at least one product identifier is required.
+
 ## Events
 
 Listen for product-related events:
@@ -239,8 +282,8 @@ Fired when product data is successfully loaded:
 
 ```javascript
 window.addEventListener('lce:actions.product_loaded', (event) => {
-  const { identifier, name, price } = event.detail.data;
-  console.log(`Product loaded: ${name} - $${price / 100}`);
+  const { identifier, name, priceInfo } = event.detail.data;
+  console.log(`Product loaded: ${name} - $${priceInfo.minimum / 100}`);
 });
 ```
 
@@ -250,8 +293,8 @@ Fired when user clicks "Add to Cart":
 
 ```javascript
 window.addEventListener('lce:actions.product_add_to_cart', (event) => {
-  const { identifier, quantity, fulfillmentType } = event.detail.data;
-  console.log(`Adding ${quantity}x ${identifier} (${fulfillmentType})`);
+  const { identifier, quantity, fulfillmentId } = event.detail.data;
+  console.log(`Adding ${quantity}x ${identifier} (${fulfillmentId})`);
 });
 ```
 
@@ -261,8 +304,8 @@ Fired when user selects a different size:
 
 ```javascript
 window.addEventListener('lce:actions.product_size_changed', (event) => {
-  const { identifier, selectedSize, price } = event.detail.data;
-  console.log(`Size changed to ${selectedSize.name}: $${price / 100}`);
+  const { identifier, selectedSizeId, selectedSize } = event.detail.data;
+  console.log(`Size changed to ${selectedSize} (${selectedSizeId})`);
 });
 ```
 
@@ -272,8 +315,8 @@ Fired when user switches between shipping and on-demand:
 
 ```javascript
 window.addEventListener('lce:actions.product_fulfillment_type_changed', (event) => {
-  const { identifier, fulfillmentType } = event.detail.data;
-  console.log(`Fulfillment type changed to: ${fulfillmentType}`);
+  const { identifier, selectedFulfillmentType } = event.detail.data;
+  console.log(`Fulfillment type changed to: ${selectedFulfillmentType}`);
 });
 ```
 
@@ -283,8 +326,8 @@ Fired when user selects a different retailer:
 
 ```javascript
 window.addEventListener('lce:actions.product_fulfillment_changed', (event) => {
-  const { identifier, selectedRetailer, price } = event.detail.data;
-  console.log(`Retailer changed to ${selectedRetailer.name}: $${price / 100}`);
+  const { identifier, selectedFulfillmentId, selectedFulfillmentType } = event.detail.data;
+  console.log(`Fulfillment changed to ${selectedFulfillmentId} (${selectedFulfillmentType})`);
 });
 ```
 
@@ -397,7 +440,8 @@ await window.LiquidCommerce.elements.actions.address.setAddressManually(
     two: 'Apt 4',
     city: 'New York',
     state: 'NY',
-    zip: '10001'
+    zip: '10001',
+    country: 'US'
   },
   {
     latitude: 40.7128,
@@ -458,8 +502,9 @@ console.log(container); // <div id="product-1">...</div>
 If a product identifier doesn't exist:
 
 ```javascript
-// An error view is shown in the container
-// Console logs: [LiquidCommerce Elements] Product not found: invalid_id
+// An error view is shown in the container, and the store entry's `error`
+// is set to 'Product data not found'. In debug/logging mode the SDK warns:
+// "No product data found for the provided product IDs."
 ```
 
 ### No Availability
@@ -535,7 +580,7 @@ window.addEventListener('lce:actions.product_loaded', (event) => {
     items: [{
       item_id: event.detail.data.identifier,
       item_name: event.detail.data.name,
-      price: event.detail.data.price / 100
+      price: event.detail.data.priceInfo.minimum / 100
     }]
   });
 });

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

@@ -39,7 +39,7 @@ Use data attributes to configure the product list:
 
 **Attributes:**
 - `data-liquid-commerce-elements-products-list`: Product list container; value is the collection slug
-- `data-rows`: Number of rows to display (default: 3)
+- `data-rows`: Number of rows to display (default: 4)
 - `data-columns`: Number of columns (default: 4)
 - `data-filters`: Comma-separated filter types
 - `data-product-url`: URL pattern for product detail pages (optional)
@@ -138,8 +138,8 @@ Only filter keys that are configured for the list are honored — anything else
 
 1. `data-filters` on `<div data-liquid-commerce-elements-products-list>` (use this when the page does **not** mount a filters UI but you still want URL filtering — e.g. a curated category page).
 2. `data-filters` on the matching `<... -products-list-filters>` container (the common case when a filters panel is mounted).
-3. `availableFilters` from the theme config for the list slug.
-4. `filters` array passed to `injectProductList(...)` programmatically.
+3. `filters` array passed to `injectProductList(...)` programmatically.
+4. `availableFilters` from the theme config for the list slug (fallback only).
 
 ### Supported formats
 
@@ -190,10 +190,9 @@ The search component provides full-text search across:
 
 ### Search Behavior
 
-- Real-time search as user types (debounced)
-- Minimum 2 characters to trigger search
-- Highlights matching terms in results
-- Shows result count
+- Real-time search as user types (500ms debounce; fires on any non-empty input — no minimum character count)
+- Input is limited to 100 characters; allowed characters: letters, numbers, spaces, and `- _ ' . , & ( )`
+- Server-side filtering by the search term
 - "Clear search" button appears when active
 
 ### Programmatic Search
@@ -262,7 +261,7 @@ Each product card shows:
 - Brand
 - Price (or price range for multiple sizes)
 - Rating (if available)
-- "Quick View" or "View Details" button
+- Clickable image/card linking to the product detail page (when `productUrl` is configured)
 - "Add to Cart" button (optional)
 - Availability indicator
 
@@ -619,7 +618,7 @@ await client.injectProductList({
 
 ### Search Not Finding Products
 
-1. Verify minimum character count is met (2 chars)
+1. Verify the input uses allowed characters and is under the 100-character limit
 2. Check search is not case-sensitive (it shouldn't be)
 3. Ensure products have searchable text fields
 4. Look for API errors in network tab

package/docs/v1/guides/theming.md

@@ -77,8 +77,7 @@ customTheme: {
       personalizationCardStyle: 'outlined',  // or 'filled'
       allowPromoCodes: true,
       inputFieldStyle: 'outlined',  // or 'filled'
-      showPoweredBy: true,
-      poweredByMode: 'light'  // or 'dark'
+      poweredByMode: 'light'  // or 'dark'  (note: showPoweredBy is controlled server-side and cannot be overridden via customTheme)
     }
   }
 }
@@ -152,16 +151,15 @@ customTheme: {
         text: 'Receive SMS updates about your order and exclusive deals.'
       },
       allowGiftCards: true,
-      legalMessage: 'By placing your order, you agree to our Terms of Service and Privacy Policy.',
+      legalMessage: { show: true, text: 'By placing your order, you agree to our Terms of Service and Privacy Policy.' },
       continueShoppingUrl: 'https://yoursite.com/shop',
       exitUrl: 'https://yoursite.com',
       thankYouButtonText: 'Continue Shopping',
       drawerHeaderText: 'Checkout',
       placeOrderButtonText: 'Place Order',
       checkoutCompleted: {
-          customLogo: 'https://yoursite.com/logo.png',
-          customText: 'Thank you for your purchase! Your order has been received.'
-        }
+        customLogo: 'https://yoursite.com/logo.png',
+        customText: 'Thank you for your purchase! Your order has been received.'
       }
     }
   }
@@ -191,8 +189,7 @@ const client = await Elements('YOUR_API_KEY', {
       },
       layout: {
         allowPromoCodes: true,
-        inputFieldStyle: 'outlined',
-        showPoweredBy: false
+        inputFieldStyle: 'outlined'
       }
     },
     product: {
@@ -203,7 +200,7 @@ const client = await Elements('YOUR_API_KEY', {
     },
     cart: {
       layout: {
-        checkoutButtonText: 'Checkout Now'
+        goToCheckoutButtonText: 'Checkout Now'
       }
     }
   }

package/docs/v1/integration/proxy-setup.md

@@ -12,7 +12,12 @@ import { Elements } from '@liquidcommerce/elements-sdk';
 const client = await Elements('YOUR_API_KEY', {
   env: 'production',
   proxy: {
-    baseUrl: 'https://yoursite.com/api/elements-proxy'
+    // Must be an ABSOLUTE URL ending with a trailing slash — the SDK resolves
+    // each request as `new URL('api' + path, baseUrl)`, so a missing trailing
+    // slash drops the last path segment.
+    baseUrl: 'https://yoursite.com/api/elements-proxy/',
+    // Optional: extra headers merged into every proxied request (e.g. credentials)
+    headers: { 'X-My-Auth': '...' }
   }
 });
 ```
@@ -30,7 +35,8 @@ export default function ProductPage() {
     (async () => {
       const client = await Elements('YOUR_API_KEY', {
         env: 'production',
-        proxy: { baseUrl: '/api/elements-proxy' }
+        // Absolute URL with a trailing slash (see note above)
+        proxy: { baseUrl: 'https://yoursite.com/api/elements-proxy/' }
       });
 
       await client.injectProductElement([
@@ -47,6 +53,8 @@ export default function ProductPage() {
 
 Your endpoint should forward requests to the LiquidCommerce Elements API, preserving method, headers, and body.
 
+The SDK does not hardcode the upstream host in the proxy path. Instead, it sends the correct environment-specific upstream base URL in the `X-Liquid-Proxy-Target` request header (along with `X-Liquid-Proxy: true`). Forward to that header value rather than to a literal host — this keeps the proxy environment-agnostic. The SDK calls your proxy at `<baseUrl>/api/<endpoint>`, so the path captured after your proxy mount is exactly the `api/<endpoint>` to append to the target.
+
 ### Minimal Express Example
 
 ```javascript
@@ -56,15 +64,24 @@ import fetch from 'node-fetch';
 const app = express();
 app.use(express.json());
 
+// Proxy is mounted at the path of your proxy.baseUrl ('/api/elements-proxy/').
 app.all('/api/elements-proxy/*', async (req, res) => {
-  const targetPath = req.params[0];
-  const targetUrl = `https://api.liquidcommerce.us/${targetPath}`;
+  // Upstream base URL the SDK wants this request forwarded to
+  // (e.g. https://elements-services-production-948630220003.us-central1.run.app)
+  const upstream = req.headers['x-liquid-proxy-target'];
+  if (!upstream) {
+    return res.status(400).send('Missing X-Liquid-Proxy-Target header');
+  }
+
+  // Everything after the proxy mount, e.g. 'api/auth/authenticate'
+  const forwardedPath = req.params[0];
+  const targetUrl = `${upstream}/${forwardedPath}`;
 
   const response = await fetch(targetUrl, {
     method: req.method,
     headers: {
       ...req.headers,
-      host: 'api.liquidcommerce.us'
+      host: new URL(upstream).host
     },
     body: ['GET', 'HEAD'].includes(req.method) ? undefined : JSON.stringify(req.body)
   });

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

@@ -15,7 +15,8 @@ The Elements SDK requires modern browser features (Web Components + Shadow DOM).
 - Shadow DOM
 - ES2018 JavaScript
 - Fetch API
-- LocalStorage
+
+**LocalStorage (optional, recommended):** used as a fast path for session persistence (cart/address). When unavailable (incognito, Safari/Firefox private mode, in-app webviews, cross-origin iframes), the SDK falls back to a generated device fingerprint plus server-side session persistence, so functionality is preserved.
 
 ## Server-Side Rendering (SSR)
 

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

@@ -19,9 +19,9 @@ class SDKError extends Error {
 
 ```javascript
 try {
-  await window.LiquidCommerce.elements.injectProductElement([
-    { containerId: 'product', identifier: 'invalid_id' }
-  ]);
+  // Structural input errors throw a catchable SDKError — e.g. a non-array
+  // argument or an empty array:
+  await window.LiquidCommerce.elements.injectProductElement([]);
 } catch (error) {
   if (error.name === 'SDKError') {
     console.error('SDK Error:', error);
@@ -29,13 +29,18 @@ try {
 }
 ```
 
+> A well-formed entry with an invalid product identifier does **not** throw — it renders an error view inside the component and sets an error in the store. `try/catch` here only catches structural input errors (a non-array argument or an empty array).
+
 ## Error Isolation
 
-The SDK catches and contains its own errors so your app keeps running:
+Component failures are contained — a component that fails to load renders an error view and logs to the console without crashing your page. Action methods (like `cart.addProduct`) emit a `*_FAILED` event on failure, and re-throw only on an unexpected error; several soft-failure paths (e.g. no product found, no items added) emit the failure event but still resolve. Wrap calls in try/catch **and** listen for the corresponding `*_failed` event to reliably detect failures:
 
 ```javascript
-window.LiquidCommerce.elements.actions.cart.addProduct([/* invalid */]);
-console.log('App still working');
+try {
+  await window.LiquidCommerce.elements.actions.cart.addProduct([/* invalid */]);
+} catch (error) {
+  console.log('Handled add-to-cart failure');
+}
 ```
 
 ## Error Events
@@ -55,7 +60,7 @@ window.addEventListener('lce:actions.address_failed', (event) => {
 
 // Checkout submit failed
 window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
-  console.error('Checkout failed:', event.detail.data.error);
+  console.error('Checkout failed:', event.detail.data.message);
 });
 ```
 

package/docs/v1/reference/performance.md

@@ -44,9 +44,7 @@ setTimeout(async () => {
 ## 5) Let the SDK Handle Media Optimization
 
 The SDK automatically:
-- Lazy loads images
-- Uses responsive image sizes
-- Virtualizes carousel images
+- Lazy loads carousel/thumbnail images (native `loading="lazy"`)
 
 ## Related Docs
 

package/docs/v1/reference/troubleshooting.md

@@ -60,7 +60,7 @@ Common setup issues and how to resolve them.
 
 **Symptoms:** Console warning "This SDK is designed for the browser. Calls made during SSR return null."
 
-This is expected behavior. The SDK ships an SSR stub that is automatically resolved when bundled for Node.js (via the `node` export condition in `package.json`). The stub exports all types and enums for TypeScript compatibility and returns `null` from factory functions (`Elements`, `ElementsBuilder`, `ElementsCheckout`).
+This is expected behavior. The SDK ships SSR stubs that are automatically resolved when bundled for Node.js (via the `node` export condition in `package.json`). There are two: the main build's stub (the `.` export) provides `Elements` and `ElementsBuilder` and warns with the `[LiquidCommerce Elements]` prefix; the checkout build's stub (the `./checkout` export) provides `ElementsCheckout` and warns with the `[LiquidCommerce Checkout]` prefix. Both re-export their types and enums for TypeScript compatibility and return `null` from the factory functions.
 
 **No action required** — initialize the SDK in a client-only lifecycle hook (`useEffect`, `onMounted`, etc.) and the real client will activate in the browser.
 
@@ -72,8 +72,8 @@ This is expected behavior. The SDK ships an SSR stub that is automatically resol
 
 **Fixes:**
 - Use `customTheme` in the client configuration to style components -- external CSS cannot penetrate Shadow DOM.
-- For debugging, enable `development.openShadowDom: true` to disable Shadow DOM temporarily.
-- Use the debug panel (`debugMode: 'panel'`) to inspect component state.
+- For debugging, enable `development.openShadowDom: true` to make the shadow root open (`mode: 'open'`) so you can inspect component internals in DevTools (via `element.shadowRoot`). This does **not** disable style isolation — external CSS still cannot reach the components; use `customTheme` to style them. (Forced off in production.)
+- Use the debug panel (`debugMode: 'panel'`) to inspect SDK logs, events, and GTM activity in real time — it surfaces a live stream of logger output and pubsub/GTM events (not component internal state), and auto-enables only in non-production environments.
 
 ## Component Not Updating After Data Changes