@liquidcommerce/elements-sdk 2.6.0-beta.93 → 2.6.0-beta.95

package/dist/types/core/a11y/announcer.service.d.ts

@@ -0,0 +1,16 @@
+export type AnnouncementPoliteness = 'polite' | 'assertive';
+export declare class AnnouncerService {
+    private politeRegion;
+    private assertiveRegion;
+    private pendingTimeouts;
+    private readonly queues;
+    private readonly draining;
+    private lastMessage;
+    private lastMessageAt;
+    static getInstance(): AnnouncerService;
+    announce(message: string, politeness?: AnnouncementPoliteness): void;
+    private drain;
+    clear(): void;
+    destroy(): void;
+    private ensureRegion;
+}

package/dist/types/core/a11y/focus-manager.service.d.ts

@@ -0,0 +1,21 @@
+export declare const A11Y_PERSIST_ATTRIBUTE = "data-lce-a11y-persist";
+export type FocusScope = 'drawer' | 'product-drawer';
+export declare class FocusManagerService {
+    private readonly triggerStacks;
+    private hiddenBackground;
+    static getInstance(): FocusManagerService;
+    captureTrigger(scope: FocusScope, trigger?: Element | null, fallback?: () => HTMLElement | null): void;
+    restoreFocus(scope: FocusScope): boolean;
+    releaseTrigger(scope: FocusScope): void;
+    hasTrigger(scope: FocusScope): boolean;
+    hasRestorableTrigger(scope: FocusScope): boolean;
+    private resolveTrigger;
+    focusInitial(container: HTMLElement, preferredSelector?: string): boolean;
+    restoreFocusWhenReady(root: ParentNode, selector: string, maxFrames?: number): () => void;
+    containsFocus(container: HTMLElement): boolean;
+    trapFocus(container: HTMLElement): () => void;
+    private getDeepActiveElement;
+    hideBackground(overlayRoot: Element | null): void;
+    showBackground(): void;
+    destroy(): void;
+}

package/dist/types/core/a11y/focusable.d.ts

@@ -0,0 +1,5 @@
+export declare function isVisible(element: HTMLElement): boolean;
+export declare function isFocusable(element: HTMLElement, root?: ParentNode): boolean;
+export declare function getFocusableElements(root: ParentNode): HTMLElement[];
+export declare function isFocusTarget(element: HTMLElement): boolean;
+export declare function safeFocus(element: HTMLElement | null | undefined): boolean;

package/dist/types/core/a11y/index.d.ts

@@ -0,0 +1,3 @@
+export { type AnnouncementPoliteness, AnnouncerService } from '@/core/a11y/announcer.service';
+export { A11Y_PERSIST_ATTRIBUTE, FocusManagerService } from '@/core/a11y/focus-manager.service';
+export { getFocusableElements, isFocusable, isVisible, safeFocus } from '@/core/a11y/focusable';

package/dist/types/core/base-component.service.d.ts

@@ -1,3 +1,4 @@
+import { AnnouncerService } from '@/core/a11y';
 import { ClientConfigService } from '@/core/client/client-config.service';
 import { LoggerFactory } from '@/core/logger/logger-factory';
 import { PubSubService } from '@/core/pubsub/pubsub.service';
@@ -34,6 +35,7 @@ export declare abstract class BaseComponent<TParams = Record<string, any>, TConf
     protected readonly logger: ReturnType<typeof LoggerFactory.get>;
     protected readonly clientConfig: ClientConfigService;
     protected readonly telemetry: TelemetryService;
+    protected readonly announcer: AnnouncerService;
     private initialized;
     private isDestroyed;
     private renderScheduled;

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

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

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

@@ -23,6 +23,8 @@ export interface IGlobalTheme {
     warningColor: string;
     successColor: string;
     drawerBackgroundColor: string;
+    inputBorderColor?: string;
+    focusRingColor?: string;
 }
 export interface IPromoTicker {
     promoCode: string;

package/dist/types/modules/address/address-input.component.d.ts

@@ -25,10 +25,19 @@ export declare class AddressInputComponent extends BaseComponent<IAddressInputCo
     private handleCancel;
     private handleCheckAvailability;
     private handleSuggestionClick;
-    private handleDocumentClick;
+    private suggestionsStatus;
+    private activeSuggestionIndex;
+    private handleRootClick;
+    private handleFocusOut;
     private searchAddresses;
     private updateErrorDisplay;
     private updateSuggestionsDisplay;
+    private updateSuggestionsStatus;
+    private getSuggestionOptions;
+    private moveActiveSuggestion;
+    private setActiveSuggestion;
+    private isSuggestionListOpen;
+    private handleComboboxKeydown;
     private showSuggestions;
     private hideSuggestions;
     private createElement;

package/dist/types/modules/cart/components/cart-body.component.d.ts

@@ -10,6 +10,7 @@ export declare class CartBodyComponent extends BaseComponent<null, ICartComponen
     private getRetailerElementById;
     private getLoadingElement;
     private showEmptyCartState;
+    private preserveDialogFocus;
     private addLoadingOverlay;
     private removeLoadingOverlay;
     private setupEmptyCartListeners;

package/dist/types/modules/cart/components/cart-item-quantity-price.component.d.ts

@@ -7,14 +7,19 @@ export declare class CartItemQuantityPriceComponent extends BaseComponent<ICartI
     private qtyIncreaseButton;
     private qtyDecreaseButton;
     private quantitySpan;
+    private priceElement;
+    private unitPriceElement;
     get hostClasses(): string[];
     constructor();
+    onStoreChanged(changes: IOnStoreChanged[]): boolean;
     onStoreWatch(changes: IOnStoreChanged[]): void;
     private getItemStore;
     private calculateQuantityLimits;
     private getAvailableQuantity;
     private updateButtonStates;
     private handleQuantityChange;
+    private updatePriceText;
+    private applyUnitPrice;
     private createQuantityContainer;
     private createPriceContainer;
     protected template(): HTMLElement[];

package/dist/types/modules/cart/components/cart-item.component.d.ts

@@ -6,6 +6,12 @@ export declare class CartItemComponent extends BaseComponent<ICartItemComponentP
     get hostClasses(): string[];
     get hostAttributes(): Record<string, string>;
     constructor();
+    private lastFocusedKey;
+    private cancelFocusRestore;
+    protected connected(): void;
+    protected disconnected(): void;
+    private readonly handleFocusIn;
+    protected afterRender(): void;
     private handleOpenEngravingForm;
     protected template(): HTMLElement[];
 }

package/dist/types/modules/checkout/components/checkout-completed.component.d.ts

@@ -12,5 +12,7 @@ export interface ICheckoutCompletedComponentParams {
 }
 export declare class CheckoutCompletedComponent extends BaseComponent<ICheckoutCompletedComponentParams, ICheckoutComponent> {
     get hostClasses(): string[];
+    private hasAnnouncedCompletion;
+    protected afterRender(): void;
     protected template(): HTMLElement[];
 }

package/dist/types/modules/checkout/components/checkout-item-quantity.component.d.ts

@@ -14,6 +14,7 @@ export declare class CheckoutItemQuantityComponent extends BaseComponent<IChecko
     private getProductStoreByLiquidId;
     private getAvailableQuantity;
     private calculateQuantityLimits;
+    private get itemName();
     private updateButtonStates;
     private handleQuantityChange;
     protected template(): HTMLElement[];

package/dist/types/modules/checkout/components/checkout-payment.component.d.ts

@@ -21,6 +21,7 @@ export declare class CheckoutPaymentComponent extends BaseComponent<ICheckoutSen
     private handleBillingSameAsShippingChange;
     afterRender(): Promise<void>;
     private updateSaveButtonState;
+    private lastAnnouncedPaymentError;
     private updateErrorMessage;
     private showError;
     protected template(): HTMLElement[];

package/dist/types/modules/checkout/components/checkout-place-order-button.component.d.ts

@@ -4,6 +4,8 @@ export declare class CheckoutPlaceOrderButtonComponent extends BaseComponent<nul
     private placeOrderButton;
     private errorContainer;
     private errorTimeoutId;
+    private lastButtonState;
+    private lastAnnouncedError;
     get hostClasses(): string[];
     constructor();
     afterRender(): void;

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

@@ -8,12 +8,18 @@ export declare class ProductDrawerComponent extends BaseComponent<IProductDrawer
     private isOpen;
     private contentContainer;
     private currentContentType;
+    private focusEntryFrame;
+    private readonly focusManager;
+    private readonly boundHandleKeydown;
     constructor();
+    private handleKeydown;
+    disconnected(): void;
     private getProductId;
     onStoreChanged(changes: IOnStoreChanged[]): boolean;
     private openWithContent;
     private open;
     private close;
+    private moveFocusIntoPanel;
     private updateDrawerState;
     protected template(): HTMLElement;
 }

package/dist/types/modules/product/product.commands.d.ts

@@ -19,10 +19,10 @@ export declare class ProductCommands extends BaseCommand {
     updateQuantity(productId: string, delta: number): Promise<void>;
     changeFulfillmentType(productId: string, newFulfillmentType: FulfillmentType): Promise<void>;
     removeProduct(productId: string): Promise<void>;
-    openProductDrawer(productId: string, contentType: IProductDrawerContentConfig['type'], data?: Record<string, any>): Promise<void>;
+    openProductDrawer(productId: string, contentType: IProductDrawerContentConfig['type'], data?: Record<string, any>, trigger?: HTMLElement | null): Promise<void>;
     closeProductDrawer(productId: string): Promise<void>;
     rerenderAllProducts(): Promise<void>;
-    addToCart(productId: string, params: AddItemParams): Promise<void>;
+    addToCart(productId: string, params: AddItemParams, trigger?: HTMLElement | null): Promise<void>;
     addPresaleToCart(productId: string, params: AddItemParams): Promise<void>;
     productDataForEventFromStore(identifier: string): IBaseProductEventData;
 }

package/dist/types/modules/product-list/components/card-components/product-price-and-personalization.d.ts

@@ -8,6 +8,7 @@ export interface IPricePersonalizationSectionParams {
     priceClassName?: string;
     personalizeClassName?: string;
     personalizeText?: string;
+    productName?: string;
     onPersonalizeClick?: () => void;
 }
-export declare const createPricePersonalizationSection: ({ price, showPrice, hasPersonalization, showPersonalization, hasAddress, wrapperClassName, priceClassName, personalizeClassName, personalizeText, onPersonalizeClick, }: IPricePersonalizationSectionParams) => HTMLElement | null;
+export declare const createPricePersonalizationSection: ({ price, showPrice, hasPersonalization, showPersonalization, hasAddress, wrapperClassName, priceClassName, personalizeClassName, personalizeText, productName, onPersonalizeClick, }: IPricePersonalizationSectionParams) => HTMLElement | null;

package/dist/types/modules/product-list/components/card-components/product-sizes-list.d.ts

@@ -7,6 +7,7 @@ export interface IProductListSizeSelectorParams {
 }
 export declare class ProductListSizeSelectorComponent extends BaseComponent<IProductListSizeSelectorParams> {
     private onOutsideClick;
+    private readonly uid;
     get hostClasses(): string[];
     protected disconnected?(): void;
     protected template(): HTMLElement[];

package/dist/types/modules/product-list/components/filter-components/product-list-fulfillment-filter.d.ts

@@ -11,4 +11,5 @@ export declare function createFulfillmentFilter(params: ICreateFulfillmentFilter
     elements: HTMLElement[];
     chevronContainer: HTMLElement;
     fulfillmentList: HTMLElement;
+    headerButton: HTMLButtonElement;
 };

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

@@ -50,6 +50,7 @@ export declare class ProductListFiltersComponent extends BaseComponent<IProductL
     private isEngravingCurrentlyDisabled;
     private buildEngravingFilterElements;
     private isSameDayDeliveryCurrentlyDisabled;
+    private fulfillmentFilterHeaderButton;
     private toggleFulfillmentFilterCollapse;
     private buildFulfillmentFilterElements;
     private togglePriceFilterCollapse;

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

@@ -19,9 +19,11 @@ export declare class ProductListProductPreCartComponent extends BaseComponent<IP
     constructor();
     private getListConfig;
     protected connected?(): void;
+    private pendingViewFocus;
     private handleRetailersBack;
     private handleEngravingBack;
     private handleEngravingEdit;
+    protected afterRender(): void;
     protected disconnected?(): void;
     private getSelectedSize;
     onStoreWatch(changes: IOnStoreChanged[]): void;

package/dist/types/modules/product-list/product-list.commands.d.ts

@@ -22,7 +22,7 @@ export declare class ProductListCommands extends BaseCommand {
     getItemsPerPage(slug: string): number;
     updatePagination(navigation: INavigationResponse | undefined): IPagination;
     createInitialPagination(): IPagination;
-    addToCart(slug: string, productId: string, params: AddItemParams): Promise<void>;
+    addToCart(slug: string, productId: string, params: AddItemParams, trigger?: HTMLElement | null): Promise<void>;
     selectSize(slug: string, productId: string, sizeId: string): Promise<void>;
     changeFulfillmentType: (slug: string, productId: string, newFulfillmentType: FulfillmentType) => Promise<void>;
     selectFulfillment: (slug: string, productId: string, selectedFulfillmentId: string) => Promise<void>;

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

@@ -31,7 +31,10 @@ export declare class ProductListComponent extends BaseComponent<IProductListComp
     private loadMoreProducts;
     private createCardsContainer;
     private renderLoadingState;
+    private hasRenderedProductsOnce;
+    private lastAnnouncedSentinelState;
     private renderProducts;
+    private announceResultCount;
     private appendNewProducts;
     private setupInfiniteScroll;
     private createScrollSentinel;

package/dist/types/modules/ui-components/alert/alert.component.d.ts

@@ -9,8 +9,8 @@ export interface IAlertComponentParams {
 export declare class AlertComponent extends BaseComponent<IAlertComponentParams, null> {
     private hideTimeout;
     private elements;
+    private lastAnnouncedKey;
     get hostClasses(): string[];
-    get hostAttributes(): Record<string, string>;
     beforeSetupStoreWatchers(): void;
     afterRender(): void;
     onStoreWatch(changes: IOnStoreChanged[]): void;

package/dist/types/modules/ui-components/buttons/buttons-open-cart.component.d.ts

@@ -5,7 +5,12 @@ export interface IButtonsOpenCartComponentParams {
 }
 export declare class ButtonsOpenCartComponent extends BaseComponent<IButtonsOpenCartComponentParams, null> {
     get hostClasses(): string[];
+    private buttonElement;
+    private badgeElement;
+    private unwatchQuantity;
     protected template(): HTMLElement[];
     protected afterRender(): void;
+    protected disconnected(): void;
     private setupCartBadge;
+    private applyCartQuantity;
 }

package/dist/types/modules/ui-components/drawer/drawer.component.d.ts

@@ -8,7 +8,14 @@ export declare class DrawerComponent extends BaseComponent {
     private currentContentType;
     private mode;
     private isTransitioning;
+    private readonly focusManager;
+    private releaseFocusTrap;
+    private focusEntryFrame;
+    private contentTeardownTimeout;
+    private previousBodyOverflow;
+    private pendingFocusKey;
     private readonly boundHandleKeydown;
+    private readonly boundHandleBackdropClick;
     constructor();
     disconnected(): void;
     onStoreChanged(changes: IOnStoreChanged[]): boolean;
@@ -16,6 +23,13 @@ export declare class DrawerComponent extends BaseComponent {
     private animateContentSwap;
     private open;
     private close;
+    private applyDialogSemantics;
+    private setupOverlaySemantics;
+    private teardownOverlaySemantics;
+    private moveFocusIntoDrawer;
+    private getTopLevelHost;
+    private scheduleContentTeardown;
+    private cancelPendingContentTeardown;
     private cleanupCurrentContent;
     private handleBackdropClick;
     private handleKeydown;

package/dist/types/modules/ui-components/engraving/engraving-form.component.d.ts

@@ -10,6 +10,7 @@ export interface IEngravingFormComponentParams {
     fee: number;
     location?: string;
     displayMode?: DisplayModeType;
+    returnFocusKey?: string;
 }
 export declare class EngravingFormComponent extends BaseComponent<IEngravingFormComponentParams, null> {
     get hostClasses(): string[];
@@ -26,6 +27,7 @@ export declare class EngravingFormComponent extends BaseComponent<IEngravingForm
     private getFulfillmentData;
     private retailersSection;
     private engravingLinesSection;
+    private returnToCart;
     private actionButtonsSection;
     protected template(): HTMLElement[];
 }

package/dist/types/modules/ui-components/engraving/engraving-view.component.d.ts

@@ -13,6 +13,7 @@ export declare class EngravingViewComponent extends BaseComponent<IEngravingView
     private engravingQuantityFee;
     private engravingLines;
     private isEngravingRequired;
+    private get editFocusKey();
     private handleEdit;
     private handleRemove;
     protected template(): HTMLElement | HTMLElement[] | string;

package/dist/types/modules/ui-components/input/input.component.d.ts

@@ -25,10 +25,14 @@ export interface IInputComponentParams {
     disabled?: boolean;
 }
 export declare class InputComponent extends BaseComponent<IInputComponentParams, null> {
+    private readonly uid;
     get hostClasses(): string[];
+    private get controlId();
+    private get errorContainerId();
     private inputElement;
     private errorContainer;
     private validationTimeout;
+    private announceNextErrors;
     private handlePhoneKeydown;
     private formatPhoneNumber;
     private formatDate;

package/dist/types/modules/ui-components/ui.commands.d.ts

@@ -2,10 +2,12 @@ import { BaseCommand } from '@/core/command/base-command.service';
 import type { IDrawerContentConfig } from '@/core/store/interfaces/core.interface';
 export declare class UICommands extends BaseCommand {
     static getInstance(): UICommands;
-    openDrawer({ mode, contentType, data, }: {
+    openDrawer({ mode, contentType, data, trigger, triggerFallback, }: {
         mode?: 'drawer' | 'modal';
         contentType: IDrawerContentConfig['type'];
         data?: Record<string, any>;
+        trigger?: HTMLElement | null;
+        triggerFallback?: () => HTMLElement | null;
     }): void;
     closeDrawer(): void;
 }

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

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

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

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

package/docs/v1/api/client.md

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

package/docs/v1/api/configuration.md

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