@liquidcommerce/elements-sdk 2.7.24 → 2.7.26

package/dist/types/static/icon/close.icon.d.ts

@@ -1,2 +1,2 @@
 import type { IconProps } from './icon.types';
-export declare const CloseIcon: ({ width, height, className, color }: IconProps) => string;
+export declare const CloseIcon: ({ width, height, className, color, label }: IconProps) => string;

package/dist/types/static/icon/error-info.icon.d.ts

@@ -1,2 +1,2 @@
 import type { IconProps } from './icon.types';
-export declare const ErrorInfoIcon: ({ width, height, className, color }: IconProps) => string;
+export declare const ErrorInfoIcon: ({ width, height, className, color, label }: IconProps) => string;

package/dist/types/static/icon/filter.icon.d.ts

@@ -1,2 +1,2 @@
 import type { IconProps } from './icon.types';
-export declare const FilterIcon: ({ width, height, className, color }: IconProps) => string;
+export declare const FilterIcon: ({ width, height, className, color, label }: IconProps) => string;

package/dist/types/static/icon/icon.a11y.d.ts

@@ -0,0 +1 @@
+export declare function iconA11yAttributes(label?: string): string;

package/dist/types/static/icon/icon.types.d.ts

@@ -3,4 +3,5 @@ export interface IconProps {
     height?: number;
     className?: string;
     color?: string | null;
+    label?: string;
 }

package/dist/types/static/icon/index.d.ts

@@ -7,6 +7,7 @@ export * from './chevron-left.icon';
 export * from './chevron-up.icon';
 export * from './close.icon';
 export * from './error-info.icon';
+export * from './icon.a11y';
 export * from './icon.types';
 export * from './info.icon';
 export * from './loading-spinner.icon';

package/dist/types/static/icon/info.icon.d.ts

@@ -1,2 +1,2 @@
 import type { IconProps } from './icon.types';
-export declare const InfoIcon: ({ width, height, className, color }: IconProps) => string;
+export declare const InfoIcon: ({ width, height, className, color, label }: IconProps) => string;

package/dist/types/static/icon/loading-spinner.icon.d.ts

@@ -1,2 +1,2 @@
 import type { IconProps } from './icon.types';
-export declare const LoadingSpinnerIcon: ({ width, height, className, color }: IconProps) => string;
+export declare const LoadingSpinnerIcon: ({ width, height, className, color, label }: IconProps) => string;

package/dist/types/static/icon/search.icon.d.ts

@@ -1,2 +1,2 @@
 import type { IconProps } from './icon.types';
-export declare const SearchIcon: ({ width, height, className, color }: IconProps) => string;
+export declare const SearchIcon: ({ width, height, className, color, label }: IconProps) => string;

package/dist/types/static/icon/success.icon.d.ts

@@ -1,2 +1,2 @@
 import type { IconProps } from './icon.types';
-export declare const SuccessIcon: ({ width, height, className, color }: IconProps) => string;
+export declare const SuccessIcon: ({ width, height, className, color, label }: IconProps) => string;

package/dist/types/static/icon/trash.icon.d.ts

@@ -1,2 +1,2 @@
 import type { IconProps } from './icon.types';
-export declare const TrashIcon: ({ width, height, className, color }: IconProps) => string;
+export declare const TrashIcon: ({ width, height, className, color, label }: IconProps) => string;

package/dist/types/static/icon/warning.icon.d.ts

@@ -1,2 +1,2 @@
 import type { IconProps } from './icon.types';
-export declare const WarningIcon: ({ width, height, className, color }: IconProps) => string;
+export declare const WarningIcon: ({ width, height, className, color, label }: IconProps) => string;

package/dist/types/utils/color-contrast.d.ts

@@ -0,0 +1,16 @@
+export interface IRgbColor {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+export declare const TEXT_CONTRAST_MIN = 4.5;
+export declare const NON_TEXT_CONTRAST_MIN = 3;
+export declare function parseColor(value: string | null | undefined): IRgbColor | null;
+export declare function toHexColor({ r, g, b }: IRgbColor): string;
+export declare function compositeOver(foreground: IRgbColor, background: IRgbColor): IRgbColor;
+export declare function relativeLuminance({ r, g, b }: IRgbColor): number;
+export declare function contrastRatio(foreground: IRgbColor, background: IRgbColor): number;
+export declare function meetsContrast(foreground: IRgbColor, background: IRgbColor, minRatio: number): boolean;
+export declare function ensureContrast(foreground: IRgbColor, background: IRgbColor, minRatio: number): IRgbColor;
+export declare function ensureContrastAgainstAll(foreground: IRgbColor, backgrounds: IRgbColor[], minRatio: number): IRgbColor;

package/docs/v1/README.md

@@ -32,6 +32,7 @@ In-depth guides for each major component:
 - **[Address Component](./guides/address-component.md)** - Delivery location management
 - **[Product List Component](./guides/product-list-component.md)** - Filterable product catalogs
 - **[Theming](./guides/theming.md)** - Customize appearance and branding
+- **[Accessibility](./guides/accessibility.md)** - Keyboard, screen reader, contrast and focus behaviour
 - **[Events](./guides/events.md)** - Event system and subscriptions
 - **[Best Practices](./guides/best-practices.md)** - Patterns, tips, and recommendations
 
@@ -83,6 +84,8 @@ Technical reference and troubleshooting:
 - **[Troubleshooting](./reference/troubleshooting.md)** - Common issues and solutions
 - **[Error Handling](./reference/error-handling.md)** - Error types and debugging
 - **[Performance](./reference/performance.md)** - Optimization tips and best practices
+- **[Analytics](./reference/analytics.md)** - Google Tag Manager / GA4 integration
+- **[Telemetry](./reference/telemetry.md)** - What the SDK reports and how to control it
 
 ### Examples
 

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

@@ -275,7 +275,7 @@ window.addEventListener('lce:actions.client_ready', () => {
     // Prompt for address on first visit
     showAddressModal();
   }
-});
+}, { once: true });
 ```
 
 ## See Also

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

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

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

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

package/docs/v1/api/client.md

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

package/docs/v1/api/configuration.md

@@ -30,6 +30,8 @@ interface ILiquidCommerceElementsConfig {
 | `proxy` | `IElementsProxyConfig` | No | Proxy configuration for API requests |
 | `development` | `ILiquidCommerceElementsDevelopmentConfig` | No | Development/testing options |
 
+> **Note:** `debugMode` (`'console'` or `'panel'`) is **ignored in production** -- it is forced off when `env` is `'production'`. It only takes effect in non-production environments (`'development'` / `'staging'`).
+
 ---
 
 ## Theme Configuration
@@ -72,9 +74,22 @@ interface IGlobalTheme {
   warningColor: string;
   successColor: string;
   drawerBackgroundColor: string;
+
+  /**
+   * Boundary color for form fields. Optional; defaults to a neutral that clears the 3:1
+   * contrast required by WCAG 1.4.11.
+   */
+  inputBorderColor?: string;
+
+  /** Keyboard focus ring color. Must reach 3:1 against the surface behind the control. */
+  focusRingColor?: string;
 }
 ```
 
+> `inputBorderColor` and `focusRingColor` are optional. If you omit them — or supply a value that
+> fails contrast — the runtime contrast guard substitutes a compliant color. Set them explicitly to
+> keep those two details on-brand. See [Accessibility](../guides/accessibility.md).
+
 | Property | Type | Description |
 |----------|------|-------------|
 | `buttonCornerRadius` | `string` | CSS border-radius for buttons (e.g., `'8px'`) |
@@ -100,6 +115,8 @@ interface IFontFamily {
 }
 ```
 
+> **Note:** Only Google Fonts are supported -- `name` must be a valid Google Fonts family. `Poppins` is always injected as the default font family in addition to any fonts you specify. Font loading requires network access to `fonts.googleapis.com` and `fonts.gstatic.com`; if you run behind a CSP or proxy, allow these hosts.
+
 #### IGlobalLayout
 
 ```typescript
@@ -109,6 +126,8 @@ interface IGlobalLayout {
   personalizationCardStyle: 'outlined' | 'filled';
   allowPromoCodes: boolean;
   inputFieldStyle: 'outlined' | 'filled';
+  enableOrderedProductSizes: boolean;
+  orderedProductSizes: string[];
   showPoweredBy: boolean;
   poweredByMode: 'light' | 'dark';
 }
@@ -121,9 +140,13 @@ interface IGlobalLayout {
 | `personalizationCardStyle` | `'outlined' \| 'filled'` | Visual style for personalization cards |
 | `allowPromoCodes` | `boolean` | Show promo code inputs in cart/checkout |
 | `inputFieldStyle` | `'outlined' \| 'filled'` | Visual style for input fields |
+| `enableOrderedProductSizes` | `boolean` | Enable a fixed display order for product/PLC size selectors (defined by `orderedProductSizes`) instead of the default ordering |
+| `orderedProductSizes` | `string[]` | Ordered list of size values controlling the sequence in which size selectors are rendered; changes trigger targeted rerenders of the affected size selectors |
 | `showPoweredBy` | `boolean` | Show "Powered by LiquidCommerce" badge |
 | `poweredByMode` | `'light' \| 'dark'` | Color mode for the powered-by badge |
 
+> **Note:** `showPoweredBy` is a server/plan-controlled setting and **cannot** be overridden by hosts. Any value supplied via `customTheme` (or a later config update) is stripped and the server value is restored. Only `poweredByMode` (`'light' \| 'dark'`) is host-overridable.
+
 **Example:**
 
 ```javascript

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

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

package/docs/v1/api/ui-helpers.md

@@ -136,7 +136,7 @@ window.LiquidCommerce.elements.ui.cartItemsCount('items-count', { hideZero: fals
 <script>
 window.addEventListener('lce:actions.client_ready', () => {
   window.LiquidCommerce.elements.ui.cartButton('cart-btn', true);
-});
+}, { once: true });
 </script>
 ```
 
@@ -153,7 +153,7 @@ window.addEventListener('lce:actions.client_ready', () => {
 window.addEventListener('lce:actions.client_ready', () => {
   window.LiquidCommerce.elements.ui.cartItemsCount('item-count');
   window.LiquidCommerce.elements.ui.cartSubtotal('cart-total');
-});
+}, { once: true });
 </script>
 ```
 

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

@@ -96,11 +96,11 @@ The SDK uses a two-phase initialization strategy for optimal performance:
 - Store initialization
 - Theme setup
 - Core component registration
-- Telemetry / logger wiring
+- Telemetry / logger wiring (see [Telemetry & Privacy](../reference/telemetry.md))
 - Debug panel (if enabled)
 
 **Phase 2: Deferred Services (next macrotask, via `setTimeout(…, 0)`)**
-- Analytics (Google Tag Manager)
+- Analytics (Google Tag Manager — see [Analytics (GTM/GA4)](../reference/analytics.md))
 - Cart pre-loading
 - Heavy component registration
 
@@ -117,7 +117,7 @@ window.addEventListener('lce:actions.client_ready', (event) => {
   
   // Safe to use client
   window.LiquidCommerce.elements.actions.cart.openCart();
-});
+}, { once: true });
 ```
 
 ## Declarative vs Programmatic
@@ -197,7 +197,7 @@ window.addEventListener('lce:actions.client_ready', async () => {
   await window.LiquidCommerce.elements.injectProductElement([
     { containerId: 'dynamic-product', identifier: selectedProductId }
   ]);
-});
+}, { once: true });
 </script>
 ```
 
@@ -327,20 +327,37 @@ The SDK is designed to fail gracefully and not crash your site.
 
 ### Error Isolation
 
-SDK errors are logged and also emitted as a `*_FAILED` event, then re-thrown so your code can catch them:
+Most action failures are **not** thrown. Action methods take one of three paths, so `try/catch`
+alone is not enough to detect failure:
+
+| Situation | Behaviour |
+|---|---|
+| Malformed argument (missing `identifier`, invalid `fulfillmentType`, `quantity < 1`) | Throws `SDKError` — `try/catch` catches it |
+| Empty array or no arguments | Logs a warning and **resolves**. No event, no throw. |
+| Valid input that fails at runtime (product not found, unavailable variant, API error) | Publishes `lce:actions.cart_product_add_failed` and **resolves** |
+
+So listen for the `*_failed` event **and** wrap the call in `try/catch`:
 
 ```javascript
-// The SDK emits CART_PRODUCT_ADD_FAILED and re-throws, so this catch runs
+window.addEventListener('lce:actions.cart_product_add_failed', (event) => {
+  console.log('Add to cart failed:', event.detail.data);
+});
+
 try {
-  await window.LiquidCommerce.elements.actions.cart.addProduct([/* invalid data */]);
+  // Throws only if the argument itself is malformed.
+  await window.LiquidCommerce.elements.actions.cart.addProduct([
+    { identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }
+  ]);
 } catch (error) {
-  console.log('This error is re-thrown by the SDK and caught here');
+  console.log('Malformed input rejected by the SDK');
 }
 
-// Your page keeps working
+// Either way, your page keeps working
 console.log('Page still functional');
 ```
 
+See [Error Handling](../reference/error-handling.md) for the full matrix.
+
 ### Error Types
 
 The SDK uses a custom `SDKError` class for all errors:
@@ -368,10 +385,12 @@ const client = await Elements('YOUR_API_KEY', {
 ```
 
 **Debug Modes:**
-- `'none'` - No debug output (production default)
+- `'none'` - No debug output (default)
 - `'console'` - Log to browser console
 - `'panel'` - Show debug panel on page
 
+> **Production note:** `debugMode` has no effect when `env` is `'production'`. All debug output — console logging and the debug panel — is disabled in production regardless of the `debugMode` you pass. `'console'` and `'panel'` only take effect in non-production environments.
+
 ## Security & API Keys
 
 ### API Key Protection

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

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

package/docs/v1/getting-started/quick-start.md

@@ -165,7 +165,7 @@ If you prefer JavaScript over HTML attributes:
           identifier: '00619947000020'
         }
       ]);
-    });
+    }, { once: true });
   </script>
 </head>
 <body>
@@ -181,10 +181,15 @@ Or with NPM:
 import { Elements } from '@liquidcommerce/elements-sdk';
 
 async function initProduct() {
+  // Elements() resolves to `null` if initialization fails — it never throws.
   const client = await Elements('YOUR_API_KEY', {
     env: 'production'
   });
-  
+
+  if (!client) {
+    return;
+  }
+
   await client.injectProductElement([
     {
       containerId: 'product-display',
@@ -256,7 +261,7 @@ window.addEventListener('lce:actions.client_ready', async () => {
   
   // You can customize after initialization
   // See Theming Guide for more options
-});
+}, { once: true });
 </script>
 ```