@snowcone-app/sdk 0.1.10

package/dist/index.d.ts

@@ -0,0 +1,2437 @@
+export { createDevFetcher } from './dev-fetcher.js';
+import { O as OptionAttribute, a as OptionSelection, C as Combination, b as ComponentProps, F as FrameworkAdapter, c as ComponentDescriptor, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, g as FrameworkUtilities } from './websocket-B8_XAwWx.js';
+export { A as AdapterRegistry, M as MockupResult, P as ProductComponentContext, n as RealtimeMockupCallbacks, k as RealtimeMockupService, m as RealtimeMockupState, R as RenderResult, W as WebSocketConfig, l as WebSocketMessage, j as adapterRegistry, o as computeDisabledChoices, h as createComponent, i as defineComponent, p as deriveDefaultSelection, s as findBestCombination, q as getPricePreview, t as isOptionAvailable, r as resolveBestCombination } from './websocket-B8_XAwWx.js';
+
+interface CatalogProduct$2 {
+    id: string;
+    name: string;
+    slug: string;
+    tags?: string[];
+    /**
+     * Price in minor units (cents)
+     */
+    price: number;
+    lowestPrice?: number;
+    highestPrice?: number;
+    mockups?: {
+        id: string;
+        ar: number;
+        gvids: string[];
+    }[];
+    options?: {
+        selected?: {
+            [k: string]: string | number | null;
+        };
+        attributes?: {
+            [k: string]: {
+                type?: string;
+                affectsCombinations?: boolean;
+                choices?: {
+                    label: string;
+                    hex?: string;
+                    imageUrl?: string;
+                }[];
+            };
+        };
+        combinations?: {
+            price: number;
+            variantId: string;
+        }[];
+        attributesList?: string[];
+    };
+    care_guide?: string[];
+    description?: string[];
+    key_features?: string[];
+    days_to_deliver?: string | number;
+    size_chart_data?: {
+        [k: string]: unknown;
+    };
+    ships_from_country?: string;
+    variants?: {
+        gvid: string;
+        gvidForMockup?: string | null;
+        placements: {
+            label: string;
+            width: number | null;
+            height: number | null;
+        }[];
+    }[];
+    placements?: {
+        label: string;
+        type: 'image' | 'color';
+        width: number;
+        height: number;
+        defaultScaleMode?: 'fill' | 'fit';
+        fitMarginTop?: number;
+        fitMarginRight?: number;
+        fitMarginBottom?: number;
+        fitMarginLeft?: number;
+        fitAlign?: string;
+        align?: string;
+        scale?: number;
+        offsetX?: number;
+        offsetY?: number;
+    }[];
+    defaultGvid?: string;
+}
+
+/**
+ * Mockup service types and interfaces
+ */
+type ImageAlignment$1 = "center" | "top" | "far-top" | "bottom" | "far-bottom" | "left" | "far-left" | "right" | "far-right";
+type TileCount = 0.25 | 0.5 | 1 | 2 | 4;
+interface ImageDesignElement {
+    type: "image";
+    imageUrl: string;
+    placement: string;
+    width: number;
+    height: number;
+    alignment: ImageAlignment$1;
+    tiles?: TileCount;
+}
+interface ColorDesignElement {
+    type: "color";
+    hex: string;
+    placement: string;
+    width: number;
+    height: number;
+    alignment: ImageAlignment$1;
+    imageUrl: "";
+}
+type DesignElement$1 = ImageDesignElement | ColorDesignElement;
+interface ProductSpec {
+    productId: string;
+    mockupId: string;
+    variantId: string;
+    width: number;
+    optionSelections?: Record<string, string>;
+}
+interface Effects {
+    grain?: 1 | 2;
+}
+/** Supported aspect ratios */
+type AspectRatio = '16:9' | '2:3';
+/**
+ * Blend configuration for mockup masks
+ * Controls how artwork blends with the background texture
+ */
+interface BlendConfig {
+    surface?: "glossy" | "matte" | "fabric" | "metal";
+    multiplyAlpha?: number;
+    multiplyContrast?: number;
+    highlightAlpha?: number;
+    highlightGamma?: number;
+    highlightSaturation?: number;
+    highlightBlend?: "add" | "screen" | "lighten" | "overlay";
+    colorBrightness?: number;
+    colorSaturation?: number;
+}
+/**
+ * Override configuration for a specific mask
+ * Use this for live preview/calibration of blend settings
+ */
+interface MaskOverride {
+    id: string;
+    blendConfig?: BlendConfig;
+}
+interface GetMockupUrlOptions {
+    design: DesignElement$1[];
+    product: ProductSpec;
+    effects?: Effects;
+    /** Aspect ratio (default: '16:9') */
+    ar?: AspectRatio;
+    /** Mask overrides for live preview/calibration (not cached) */
+    maskOverrides?: MaskOverride[];
+}
+interface MockupServiceConfig {
+    imageUrl?: string;
+    signerUrl?: string;
+    accountId?: string;
+}
+interface MockupService {
+    getMockupUrl(options: GetMockupUrlOptions): Promise<string>;
+    getConfig(): MockupServiceConfig;
+}
+interface SignedUrlResponse {
+    url: string;
+}
+interface RateLimitState {
+    perMinute: {
+        count: number;
+        resetTime: number;
+    };
+    perSecond: {
+        count: number;
+        resetTime: number;
+    };
+}
+
+/**
+ * Framework-agnostic state management utilities
+ * Provides consistent state management patterns for React and Web Components
+ */
+type StateUpdater<T> = T | ((prevState: T) => T);
+type StateSubscriber<T> = (state: T, prevState?: T) => void;
+type StateSelector<T, R> = (state: T) => R;
+interface StateManagerOptions<T> {
+    initialState: T;
+    debug?: boolean;
+    persist?: {
+        key: string;
+        storage?: Storage;
+    };
+    middleware?: StateMiddleware<T>[];
+}
+interface StateMiddleware<T> {
+    name: string;
+    beforeUpdate?: (state: T, update: Partial<T>) => Partial<T>;
+    afterUpdate?: (state: T, prevState: T) => void;
+}
+/**
+ * Generic state manager that works across frameworks
+ */
+declare class StateManager<T extends Record<string, any>> {
+    private options;
+    private state;
+    private prevState?;
+    private subscribers;
+    private selectorSubscribers;
+    private updateQueue;
+    private isUpdating;
+    private middleware;
+    constructor(options: StateManagerOptions<T>);
+    /**
+     * Get current state
+     */
+    getState(): T;
+    /**
+     * Update state with partial updates or updater function
+     */
+    setState(updater: StateUpdater<Partial<T>>): void;
+    /**
+     * Subscribe to all state changes
+     */
+    subscribe(callback: StateSubscriber<T>): () => void;
+    /**
+     * Subscribe to specific state selections (computed values)
+     */
+    subscribeToSelector<R>(selector: StateSelector<T, R>, callback: (value: R, prevValue?: R) => void): () => void;
+    /**
+     * Reset state to initial value
+     */
+    reset(): void;
+    /**
+     * Get a derived value from state
+     */
+    select<R>(selector: StateSelector<T, R>): R;
+    private processUpdateQueue;
+    private notifySubscribers;
+    private hasStateChanged;
+    private getStateDiff;
+    private persistState;
+    private loadPersistedState;
+}
+/**
+ * Create a simple state store
+ */
+declare function createStateStore<T extends Record<string, any>>(initialState: T, options?: Omit<StateManagerOptions<T>, 'initialState'>): StateManager<T>;
+/**
+ * Hook-like pattern for using state (works in any context)
+ */
+declare function createStateHook<T extends Record<string, any>>(store: StateManager<T>): {
+    getState: () => T;
+    setState: (updater: StateUpdater<Partial<T>>) => void;
+    subscribe: (callback: StateSubscriber<T>) => () => void;
+    select: <R>(selector: StateSelector<T, R>) => R;
+    reset: () => void;
+};
+
+/**
+ * Base rendering descriptor types that all components can use
+ */
+type TagName = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span' | 'div';
+interface BaseDescriptor {
+    type: string;
+}
+interface TextDescriptor extends BaseDescriptor {
+    type: 'text';
+    content: string;
+    tag: TagName;
+    className?: string;
+}
+interface ContainerDescriptor extends BaseDescriptor {
+    type: 'container';
+    children: Descriptor[];
+    tag: TagName;
+    className?: string;
+}
+type Descriptor = TextDescriptor | ContainerDescriptor;
+
+interface ProductData {
+    name: string;
+    description?: string;
+    price: number;
+    category: string;
+}
+interface ProductTitleDescriptor {
+    type: "product-title";
+    product: ProductData;
+    showPrice?: boolean;
+    showDescription?: boolean;
+    size?: "sm" | "md" | "lg";
+    className?: string;
+}
+interface ProductTitleOptions {
+    product: ProductData;
+    showPrice?: boolean;
+    showDescription?: boolean;
+    size?: "sm" | "md" | "lg";
+    className?: string;
+}
+/**
+ * Creates a descriptor for rendering a product title component.
+ * This component displays product name, description, price, and category.
+ */
+declare function describeProductTitle(options: ProductTitleOptions): ProductTitleDescriptor;
+
+interface ProductPriceDescriptor extends BaseDescriptor {
+    type: 'price';
+    price: number;
+    currency: string;
+    locale: string;
+    showCurrency: boolean;
+    className?: string;
+}
+interface ProductPriceOptions {
+    price?: number;
+    currency?: string;
+    locale?: string;
+    showCurrency?: boolean;
+    className?: string;
+}
+/**
+ * Formats a price value for display
+ */
+declare function formatPrice(cents: number, locale: string, currency: string, showCurrency: boolean): string;
+/**
+ * Creates a descriptor for rendering a product price.
+ */
+declare function describeProductPrice(options: ProductPriceOptions, contextPrice?: number): ProductPriceDescriptor | null;
+
+interface ProductImageDescriptor extends BaseDescriptor {
+    type: 'image';
+    src: string;
+    alt: string;
+    width?: number;
+    height?: number;
+    aspectRatio?: string;
+    className?: string;
+}
+interface ProductImageOptions {
+    src?: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+    aspectRatio?: string;
+    className?: string;
+}
+/**
+ * Creates a descriptor for rendering a product image.
+ */
+declare function describeProductImage(options: ProductImageOptions, contextImage?: {
+    src?: string;
+    alt?: string;
+}): ProductImageDescriptor | null;
+
+interface ProductOptionChoice {
+    id: string;
+    name: string;
+    available: boolean;
+    color?: string;
+    price?: number;
+}
+interface ProductOptionData {
+    name: string;
+    type: "select" | "color" | "radio" | "checkbox";
+    required: boolean;
+    choices: ProductOptionChoice[];
+}
+interface ProductOptionsDescriptor {
+    type: "product-options";
+    options: ProductOptionData[];
+    selectedOptions: Record<string, string>;
+    className?: string;
+}
+interface ProductOptionsOptions {
+    options: ProductOptionData[];
+    selectedOptions?: Record<string, string>;
+    className?: string;
+}
+/**
+ * Creates a descriptor for rendering a product options component.
+ * This component allows users to select product variants like size, color, material, etc.
+ */
+declare function describeProductOptions(options: ProductOptionsOptions): ProductOptionsDescriptor;
+
+type ImageAlignment = "center" | "top" | "far-top" | "bottom" | "far-bottom" | "left" | "far-left" | "right" | "far-right";
+interface ProductArtAlignmentDescriptor {
+    type: 'art-alignment';
+    src: string;
+    artworkAspectRatio: number;
+    maskAspectRatio: number;
+    effectiveAlignment: 'vertical' | 'horizontal';
+    alignment: ImageAlignment;
+    className?: string;
+}
+interface ProductArtAlignmentOptions {
+    src?: string;
+    artworkAspectRatio?: number;
+    maskAspectRatio?: number;
+    placement?: string;
+    alignment?: ImageAlignment;
+    className?: string;
+}
+interface ProductArtAlignmentContext {
+    product?: {
+        mockupUrl?: string;
+        aspectRatio?: number;
+        placements?: Array<{
+            label: string;
+            width: number;
+            height: number;
+            type?: 'image' | 'color';
+        }>;
+    };
+    selection?: {
+        alignment?: ImageAlignment;
+    };
+}
+/**
+ * Calculates the snap points for the mask based on container size and mask dimensions.
+ * Returns 3 snap points when aspect ratios are similar (limited movement space),
+ * or 5 snap points when there's significant movement space available.
+ */
+declare function getSnapPoints(containerSize: {
+    width: number;
+    height: number;
+}, maskDimensions: {
+    width: number;
+    height: number;
+}, effectiveAlignment: 'horizontal' | 'vertical'): {
+    center: number;
+    'far-left'?: undefined;
+    'far-right'?: undefined;
+    left?: undefined;
+    right?: undefined;
+    'far-top'?: undefined;
+    'far-bottom'?: undefined;
+    top?: undefined;
+    bottom?: undefined;
+} | {
+    'far-left': number;
+    center: number;
+    'far-right': number;
+    left?: undefined;
+    right?: undefined;
+    'far-top'?: undefined;
+    'far-bottom'?: undefined;
+    top?: undefined;
+    bottom?: undefined;
+} | {
+    'far-left': number;
+    left: number;
+    center: number;
+    right: number;
+    'far-right': number;
+    'far-top'?: undefined;
+    'far-bottom'?: undefined;
+    top?: undefined;
+    bottom?: undefined;
+} | {
+    'far-top': number;
+    center: number;
+    'far-bottom': number;
+    'far-left'?: undefined;
+    'far-right'?: undefined;
+    left?: undefined;
+    right?: undefined;
+    top?: undefined;
+    bottom?: undefined;
+} | {
+    'far-top': number;
+    top: number;
+    center: number;
+    bottom: number;
+    'far-bottom': number;
+    'far-left'?: undefined;
+    'far-right'?: undefined;
+    left?: undefined;
+    right?: undefined;
+};
+/**
+ * Determines the effective alignment (horizontal or vertical) based on aspect ratios
+ */
+declare function getEffectiveAlignment(artworkAspectRatio: number, maskAspectRatio: number): 'horizontal' | 'vertical';
+/**
+ * Creates a descriptor for rendering a product art alignment component.
+ * This is the single source of truth for how product art alignment should be rendered.
+ */
+declare function describeProductArtAlignment(options: ProductArtAlignmentOptions, context?: ProductArtAlignmentContext): ProductArtAlignmentDescriptor | null;
+/**
+ * Finds the closest snap point for a given position
+ */
+declare function findClosestSnapPoint(position: number, containerSize: {
+    width: number;
+    height: number;
+}, maskDimensions: {
+    width: number;
+    height: number;
+}, effectiveAlignment: 'horizontal' | 'vertical'): ImageAlignment;
+
+type RegularArtwork = {
+    type: "regular";
+    src: string;
+};
+type SeamlessPattern = {
+    type: "pattern";
+    src: string;
+    tileCount: 0.25 | 0.5 | 1 | 2 | 4;
+};
+type ArtworkData = RegularArtwork | SeamlessPattern;
+interface ArtSelectorDescriptor {
+    type: "art-selector";
+    artworks: ArtworkData[];
+    selectedArtwork: ArtworkData | null;
+    className?: string;
+}
+interface ArtSelectorOptions {
+    artworks?: string[];
+    className?: string;
+}
+interface ArtSelectorContext {
+    selectedArtwork?: ArtworkData;
+}
+/**
+ * Creates a descriptor for rendering an art selector component.
+ * This component allows users to select from a list of artwork images.
+ */
+declare function describeArtSelector(options: ArtSelectorOptions, context?: ArtSelectorContext): ArtSelectorDescriptor;
+
+/**
+ * Option selection rendering logic
+ * Shared between all framework implementations
+ */
+
+interface OptionChoice {
+    label: string;
+    hex?: string;
+    imageUrl?: string;
+    value?: string;
+}
+interface OptionRenderData {
+    key: string;
+    label: string;
+    type: 'select' | 'color-picker' | 'swatch';
+    value: string;
+    choices: OptionChoiceRenderData[];
+    required: boolean;
+}
+interface OptionChoiceRenderData {
+    value: string;
+    label: string;
+    disabled: boolean;
+    selected: boolean;
+    hex?: string;
+    imageUrl?: string;
+}
+/**
+ * Determines the render type for an option attribute
+ */
+declare function getOptionRenderType(attr: OptionAttribute): 'select' | 'color-picker' | 'swatch';
+/**
+ * Normalizes a choice value to a consistent format
+ */
+declare function normalizeChoice(choice: string | OptionChoice): OptionChoice;
+/**
+ * Prepares option data for rendering
+ */
+declare function prepareOptionRenderData(attributes: Record<string, OptionAttribute>, selection: OptionSelection, combinations: Combination[]): OptionRenderData[];
+/**
+ * Handles option selection change
+ */
+declare function handleOptionChange(optionKey: string, newValue: string, currentSelection: OptionSelection, attributes: Record<string, OptionAttribute>): OptionSelection;
+/**
+ * Validates if all required options are selected
+ */
+declare function validateRequiredOptions(selection: OptionSelection, attributes: Record<string, OptionAttribute>): {
+    valid: boolean;
+    missing: string[];
+};
+/**
+ * Gets display text for current selection
+ */
+declare function getSelectionDisplayText(selection: OptionSelection, attributes: Record<string, OptionAttribute>): string;
+/**
+ * Color picker specific utilities
+ */
+declare const ColorPickerUtils: {
+    /**
+     * Validates a hex color
+     */
+    isValidHex(hex: string): boolean;
+    /**
+     * Converts hex to RGB
+     */
+    hexToRgb(hex: string): {
+        r: number;
+        g: number;
+        b: number;
+    } | null;
+    /**
+     * Gets contrast color for text on background
+     */
+    getContrastColor(hex: string): "white" | "black";
+};
+/**
+ * Swatch rendering utilities
+ */
+declare const SwatchUtils: {
+    /**
+     * Gets swatch style object
+     */
+    getSwatchStyle(choice: OptionChoiceRenderData): Record<string, string>;
+    /**
+     * Gets swatch class names
+     */
+    getSwatchClasses(choice: OptionChoiceRenderData): string[];
+};
+
+/**
+ * Represents a design element for mockup generation
+ */
+interface DesignElement {
+    type?: 'image' | 'color';
+    imageUrl?: string;
+    text?: string;
+    hex?: string;
+    placement?: string;
+    position?: {
+        x: number;
+        y: number;
+    };
+    size?: {
+        width: number;
+        height: number;
+    };
+    alignment?: ImageAlignment;
+    tiles?: 0.25 | 0.5 | 1 | 2 | 4;
+    width?: number;
+    height?: number;
+}
+/**
+ * Placement configuration from product data
+ */
+interface Placement {
+    label: string;
+    type?: 'image' | 'color' | null;
+    width?: number;
+    height?: number;
+}
+/**
+ * Design configuration for a specific placement
+ */
+interface PlacementDesign {
+    imageUrl?: string;
+    alignment?: ImageAlignment;
+    tiles?: 0.25 | 0.5 | 1 | 2 | 4;
+}
+/**
+ * Context for design generation
+ */
+interface DesignGenerationContext {
+    selection?: Record<string, any>;
+    attributes?: Record<string, any>;
+    artworkSrc?: string;
+    placementDesigns?: Record<string, PlacementDesign>;
+    defaultImageUrl?: string;
+    tiles?: 0.25 | 0.5 | 1 | 2 | 4;
+}
+
+/**
+ * Default values for mockup generation
+ */
+declare const DEFAULT_ARTWORK_URL = "https://images.unsplash.com/photo-1533738363-b7f9aef128ce?q=80&w=2670&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D";
+declare const DEFAULT_COLOR = "#000000";
+declare const DEFAULT_PLACEMENT_DIMENSIONS: {
+    width: number;
+    height: number;
+};
+declare const DEFAULT_ASPECT_RATIO = 1;
+
+/**
+ * Creates design elements for each placement in a product.
+ * This is the single source of truth for how mockup designs are generated
+ * across both React and Web Component implementations.
+ *
+ * @param placements - Array of product placements
+ * @param providedImages - Optional array of pre-configured design elements
+ * @param context - Context containing selection, attributes, and other design data
+ * @returns Array of design elements ready for mockup generation
+ */
+declare function createDesignForPlacements(placements: Placement[], providedImages?: DesignElement[], context?: DesignGenerationContext): DesignElement[];
+/**
+ * Helper to filter image placements from all placements
+ * Handles both explicit 'image' type and null type (which defaults to image)
+ */
+declare function filterImagePlacements(placements: Placement[]): Placement[];
+
+/**
+ * Shared mockup URL generation logic for both React and Web Components
+ */
+
+interface MockupConfig {
+    endpoint?: string;
+    mockupUrl?: string;
+    signerUrl?: string;
+    accountId?: string;
+    mode?: "mock" | "live";
+}
+
+interface MockupGenerationOptions {
+    productId: string;
+    mockupId: string;
+    variantId: string;
+    design: DesignElement[];
+    width: number;
+    effects?: {
+        grain?: 1 | 2;
+    };
+    /** Aspect ratio (default: '16:9') */
+    ar?: AspectRatio;
+    /** Mask overrides for live preview/calibration (not cached) */
+    maskOverrides?: MaskOverride[];
+}
+
+/**
+ * User's selected product options
+ * Keys are attribute names (Size, Color, Material, etc.)
+ * Values are the selected option values
+ */
+type UserSelection = Record<string, string>;
+declare function config(overrides?: MockupConfig): MockupConfig;
+/**
+ * @deprecated Use `config` instead
+ */
+declare const resolveMockupConfig: typeof config;
+/**
+ * Creates a mockup URL from the provided options
+ * Uses configuration from config() which reads from environment/window
+ */
+declare function mockupUrl(options: MockupGenerationOptions): string;
+/**
+ * SDK-friendly helper to get variant details from selected options
+ * @param selection User's selected options (e.g. { Size: 'L', Color: 'Blue' })
+ * @param product Product data from API including combinations, mockups, attributes
+ * @returns Object with variantId, mockupId, price, and the full combination
+ */
+declare function getVariant(selection: UserSelection, product: {
+    combinations: Array<{
+        variantId: string;
+        price?: number;
+        [key: string]: any;
+    }>;
+    mockups: Array<{
+        id: string;
+        gvids?: string[];
+    }>;
+    attributes?: Record<string, any>;
+}): {
+    variantId: string | undefined;
+    mockupId: string | undefined;
+    price: number | undefined;
+    combination: any | undefined;
+};
+/**
+ * Internal helper - determines the variant ID based on context and fallbacks
+ * Used by React/Vue/WC components that have context
+ */
+declare function resolveVariantId(context: any, providedGvid?: string, providedVariantId?: string): string;
+/**
+ * Internal helper - determines the mockup ID based on variant and available mockups
+ * Used by React/Vue/WC components that have context
+ */
+declare function resolveMockupId(context: any, variantId: string, providedMockupId?: string): string | null;
+
+/**
+ * Product data transformation utilities
+ * Converts catalog product data to component-friendly formats
+ */
+type CatalogProduct$1 = any;
+
+/**
+ * Transforms product options attributes into the standard OptionAttribute format
+ * @param product - The catalog product from the API
+ * @returns Normalized option attributes with choice objects
+ */
+declare function toOptionAttributes(product?: CatalogProduct$1): Record<string, OptionAttribute>;
+/**
+ * Extracts combinations from product options
+ * @param product - The catalog product from the API
+ * @returns Array of valid combinations
+ */
+declare function toCombinations(product?: CatalogProduct$1): Combination[];
+/**
+ * Extracts product ID from various possible locations in the product data
+ * @param product - The catalog product from the API
+ * @returns The product ID or undefined
+ */
+declare function extractProductId(product?: CatalogProduct$1): string | undefined;
+/**
+ * Gets the default variant ID for a product
+ * @param product - The catalog product from the API
+ * @returns The default variant ID or 'default' as fallback
+ */
+declare function getDefaultVariantId(product?: CatalogProduct$1): string;
+
+/**
+ * Product selection validation utilities
+ * Ensures selections are complete and valid before cart operations
+ */
+
+/**
+ * Validates that a product selection is complete and valid
+ * @param attributes - Product option attributes
+ * @param selection - Current user selection
+ * @param combinations - Valid product combinations
+ * @returns true if selection is valid and complete
+ */
+declare function validateProductSelection(attributes: Record<string, OptionAttribute>, selection: OptionSelection, combinations: Combination[]): boolean;
+/**
+ * Gets the list of missing required selections
+ * @param attributes - Product option attributes
+ * @param selection - Current user selection
+ * @returns Array of attribute keys that are required but not selected
+ */
+declare function getMissingSelections(attributes: Record<string, OptionAttribute>, selection: OptionSelection): string[];
+/**
+ * Checks if a selection is complete (all required options selected)
+ * @param attributes - Product option attributes
+ * @param selection - Current user selection
+ * @returns true if all required options are selected
+ */
+declare function isSelectionComplete(attributes: Record<string, OptionAttribute>, selection: OptionSelection): boolean;
+/**
+ * Creates a user-friendly message for incomplete selections
+ * @param attributes - Product option attributes
+ * @param selection - Current user selection
+ * @returns A message describing what needs to be selected
+ */
+declare function getIncompleteSelectionMessage(attributes: Record<string, OptionAttribute>, selection: OptionSelection): string;
+
+/**
+ * Validation functions for mockup generation parameters
+ */
+
+interface ValidationError {
+    field: string;
+    message: string;
+    value?: any;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+/**
+ * Validates an image URL
+ * NOTE: Relative URLs are now accepted and will be normalized to absolute URLs
+ * by the design generation layer before reaching the mockup API.
+ */
+declare function validateImageUrl(url: string): ValidationResult;
+/**
+ * Validates alignment value
+ */
+declare function validateAlignment(alignment: string): ValidationResult;
+/**
+ * Validates tile count
+ */
+declare function validateTileCount(tiles: number): ValidationResult;
+/**
+ * Validates a design element
+ */
+declare function validateDesignElement(element: DesignElement$1): ValidationResult;
+/**
+ * Validates product specification
+ */
+declare function validateProductSpec(spec: ProductSpec): ValidationResult;
+/**
+ * Validates visual effects
+ */
+declare function validateEffects(effects: Effects): ValidationResult;
+/**
+ * Validates complete mockup URL options
+ */
+declare function validateMockupOptions(options: GetMockupUrlOptions): ValidationResult;
+/**
+ * Helper function to format validation errors as a string
+ */
+declare function formatValidationErrors(errors: ValidationError[]): string;
+/**
+ * Type guard to check if a value is a valid ImageAlignment
+ */
+declare function isValidAlignment(value: string): value is ImageAlignment$1;
+/**
+ * Type guard to check if a value is a valid TileCount
+ */
+declare function isValidTileCount(value: number): value is TileCount;
+
+/**
+ * Cart operation utilities
+ * Shared logic for adding items to cart across implementations
+ */
+
+interface CartDetail {
+    productId: string;
+    variantId?: string;
+    quantity: number;
+    selection: OptionSelection;
+    price?: number;
+    attributes?: Record<string, any>;
+}
+interface AddToCartOptions {
+    productId: string;
+    quantity?: number;
+    selection: OptionSelection;
+    combinations: Combination[];
+    attributes: Record<string, OptionAttribute>;
+}
+/**
+ * Creates cart detail object from selection
+ * @param options - Options for creating cart detail
+ * @returns Cart detail object ready for submission
+ */
+declare function createCartDetail(options: AddToCartOptions): CartDetail | null;
+/**
+ * Finds the variant for a given selection
+ * @param selection - Current selection
+ * @param combinations - Available combinations
+ * @param attributes - Product attributes
+ * @returns The variant ID or undefined
+ */
+declare function findVariantForSelection(selection: OptionSelection, combinations: Combination[], attributes: Record<string, OptionAttribute>): string | undefined;
+/**
+ * Creates an add to cart event detail
+ * @param cartDetail - The cart detail object
+ * @returns Event detail for cart addition
+ */
+declare function createAddToCartEvent(cartDetail: CartDetail): {
+    detail: {
+        productId: string;
+        variantId: string | undefined;
+        quantity: number;
+        selection: OptionSelection;
+        price: number | undefined;
+        timestamp: number;
+    };
+    bubbles: boolean;
+    composed: boolean;
+    cancelable: boolean;
+};
+/**
+ * Simulates adding to cart with loading state
+ * @param duration - Duration of simulated operation in ms
+ * @returns Promise that resolves after duration
+ */
+declare function simulateCartOperation(duration?: number): Promise<void>;
+/**
+ * Creates a handler function for add to cart operations
+ * @param options - Configuration for the handler
+ * @returns Handler function
+ */
+declare function createAddToCartHandler(options: {
+    onValidate?: () => boolean;
+    onStart?: () => void;
+    onSuccess?: (detail: CartDetail) => void;
+    onError?: (error: Error) => void;
+    simulateDelay?: number;
+}): (productId: string, selection: OptionSelection, combinations: Combination[], attributes: Record<string, OptionAttribute>, quantity?: number) => Promise<CartDetail | null>;
+
+/**
+ * Shared error handling utilities for consistent error management
+ * across React and Web Component implementations
+ */
+interface ErrorContext {
+    component: string;
+    operation: string;
+    retryable?: boolean;
+    userMessage?: string;
+    metadata?: Record<string, any>;
+}
+interface ErrorHandler {
+    handle: (error: Error) => void;
+    handleAsync: (error: Error) => Promise<void>;
+    clear: () => void;
+    getLastError: () => Error | null;
+    canRetry: () => boolean;
+}
+declare class ErrorManager {
+    private context;
+    private onError?;
+    private onClear?;
+    private lastError;
+    private errorCount;
+    private readonly maxRetries;
+    constructor(context: ErrorContext, onError?: ((error: Error, context: ErrorContext) => void) | undefined, onClear?: (() => void) | undefined);
+    handle(error: Error): void;
+    handleAsync(error: Error): Promise<void>;
+    clear(): void;
+    getLastError(): Error | null;
+    canRetry(): boolean;
+    getUserMessage(): string;
+}
+/**
+ * Creates an error handler with standard configuration
+ */
+declare function createErrorHandler(context: ErrorContext, callbacks?: {
+    onError?: (error: Error, context: ErrorContext) => void;
+    onClear?: () => void;
+}): ErrorHandler;
+/**
+ * Wraps an async operation with error handling
+ */
+declare function withErrorHandling<T>(operation: () => Promise<T>, errorHandler: ErrorHandler, options?: {
+    retry?: boolean;
+    retryDelay?: number;
+    fallback?: T;
+}): Promise<T | null>;
+/**
+ * Wraps a synchronous operation with error handling
+ */
+declare function withSyncErrorHandling<T>(operation: () => T, errorHandler: ErrorHandler, fallback?: T): T | null;
+/**
+ * Creates a retry mechanism for operations
+ */
+declare function retryOperation<T>(operation: () => Promise<T>, options?: {
+    maxAttempts?: number;
+    delay?: number;
+    backoff?: boolean;
+    onRetry?: (attempt: number, error: Error) => void;
+}): Promise<T>;
+
+/**
+ * Context synchronization utilities for managing state updates
+ * across React and Web Component implementations
+ */
+interface ContextSubscriber<T> {
+    (context: T, previousContext?: T): void;
+}
+interface ContextComparator<T> {
+    (prev: T, next: T): boolean;
+}
+/**
+ * Manages context synchronization with batching and change detection
+ */
+declare class ContextSynchronizer<T> {
+    private options;
+    private subscribers;
+    private currentContext?;
+    private previousContext?;
+    private updateTimer?;
+    private pendingUpdate?;
+    private readonly batchDelay;
+    constructor(options?: {
+        batchDelay?: number;
+        comparator?: ContextComparator<T>;
+        onUpdate?: (context: T) => void;
+        debug?: boolean;
+    });
+    /**
+     * Subscribe to context changes
+     */
+    subscribe(callback: ContextSubscriber<T>): () => void;
+    /**
+     * Update context with optional batching
+     */
+    updateContext(context: T): void;
+    /**
+     * Force immediate context update (bypasses batching)
+     */
+    forceUpdate(context: T): void;
+    /**
+     * Get current context
+     */
+    getContext(): T | undefined;
+    /**
+     * Clear all subscribers
+     */
+    clear(): void;
+    private hasContextChanged;
+    private scheduleBatchedUpdate;
+    private clearPendingUpdate;
+    private applyContextUpdate;
+    private deepEqual;
+}
+/**
+ * Creates a context bridge between different component systems
+ */
+declare class ContextBridge<T> {
+    private synchronizers;
+    /**
+     * Register a synchronizer with a key
+     */
+    register(key: string, synchronizer: ContextSynchronizer<T>): void;
+    /**
+     * Bridge context updates between synchronizers
+     */
+    bridge(fromKey: string, toKey: string): () => void;
+    /**
+     * Broadcast context to all registered synchronizers
+     */
+    broadcast(context: T, excludeKey?: string): void;
+}
+/**
+ * Helper to create a context provider pattern
+ */
+declare function createContextProvider<T>(initialContext?: T, options?: {
+    batchDelay?: number;
+    debug?: boolean;
+}): {
+    subscribe: (callback: ContextSubscriber<T>) => () => void;
+    update: (context: T) => void;
+    get: () => T | undefined;
+    clear: () => void;
+};
+
+/**
+ * Unified event system for cross-framework components
+ * Provides consistent event handling across React, Vue, Svelte, etc.
+ */
+interface EventDefinition {
+    name: string;
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+    passive?: boolean;
+}
+interface EventPayload<T = any> {
+    detail?: T;
+    target?: any;
+    currentTarget?: any;
+    timestamp?: number;
+    [key: string]: any;
+}
+type EventListener<T = any> = (event: EventPayload<T>) => void;
+/**
+ * Cross-framework event emitter
+ */
+declare class EventEmitter {
+    private listeners;
+    private onceListeners;
+    /**
+     * Add event listener
+     */
+    on(event: string, listener: EventListener): () => void;
+    /**
+     * Add one-time event listener
+     */
+    once(event: string, listener: EventListener): () => void;
+    /**
+     * Remove event listener
+     */
+    off(event: string, listener: EventListener): void;
+    /**
+     * Emit event
+     */
+    emit<T = any>(event: string, payload?: EventPayload<T>): boolean;
+    /**
+     * Remove all listeners for an event
+     */
+    removeAllListeners(event?: string): void;
+    /**
+     * Get listener count
+     */
+    listenerCount(event: string): number;
+}
+/**
+ * Event manager for components
+ */
+declare class ComponentEventManager {
+    private emitter;
+    private definitions;
+    private element?;
+    constructor(element?: HTMLElement);
+    /**
+     * Define an event
+     */
+    define(definition: EventDefinition): void;
+    /**
+     * Emit an event (works for both DOM and synthetic events)
+     */
+    emit<T = any>(name: string, detail?: T): boolean;
+    /**
+     * Listen to an event
+     */
+    on(event: string, listener: EventListener): () => void;
+    /**
+     * Listen to an event once
+     */
+    once(event: string, listener: EventListener): () => void;
+    /**
+     * Remove listener
+     */
+    off(event: string, listener: EventListener): void;
+    /**
+     * Set DOM element for event dispatching
+     */
+    setElement(element: HTMLElement): void;
+    /**
+     * Get all defined events
+     */
+    getDefinitions(): EventDefinition[];
+}
+/**
+ * Standard component events
+ */
+declare const StandardEvents: {
+    readonly mounted: {
+        readonly name: "mounted";
+        readonly bubbles: false;
+    };
+    readonly unmounted: {
+        readonly name: "unmounted";
+        readonly bubbles: false;
+    };
+    readonly updated: {
+        readonly name: "updated";
+        readonly bubbles: false;
+    };
+    readonly change: {
+        readonly name: "change";
+        readonly bubbles: true;
+    };
+    readonly input: {
+        readonly name: "input";
+        readonly bubbles: true;
+    };
+    readonly click: {
+        readonly name: "click";
+        readonly bubbles: true;
+    };
+    readonly focus: {
+        readonly name: "focus";
+        readonly bubbles: false;
+    };
+    readonly blur: {
+        readonly name: "blur";
+        readonly bubbles: false;
+    };
+    readonly selectionChange: {
+        readonly name: "selection-change";
+        readonly bubbles: true;
+    };
+    readonly priceUpdate: {
+        readonly name: "price-update";
+        readonly bubbles: true;
+    };
+    readonly addToCart: {
+        readonly name: "add-to-cart";
+        readonly bubbles: true;
+    };
+    readonly variantChange: {
+        readonly name: "variant-change";
+        readonly bubbles: true;
+    };
+    readonly contextRequest: {
+        readonly name: "context-request";
+        readonly bubbles: true;
+    };
+    readonly contextProvide: {
+        readonly name: "context-provide";
+        readonly bubbles: false;
+    };
+    readonly contextUpdate: {
+        readonly name: "context-update";
+        readonly bubbles: true;
+    };
+};
+/**
+ * Event delegation helper for efficient event handling
+ */
+declare class EventDelegator {
+    private element;
+    private handlers;
+    constructor(element: HTMLElement);
+    /**
+     * Add delegated event listener
+     */
+    delegate(eventType: string, selector: string, handler: EventListener): () => void;
+    /**
+     * Remove all delegated listeners
+     */
+    destroy(): void;
+}
+/**
+ * Create event manager for a component
+ */
+declare function createEventManager(element?: HTMLElement): ComponentEventManager;
+
+/**
+ * Product context management
+ * Framework-agnostic product state and context handling
+ */
+
+type CatalogProduct = any;
+/**
+ * Product context interface
+ */
+interface ProductContext {
+    product?: CatalogProduct;
+    optionAttributes: Record<string, OptionAttribute>;
+    combinations: Combination[];
+    selection: OptionSelection;
+    loading?: boolean;
+    error?: any;
+}
+/**
+ * Product context events
+ */
+interface ProductContextEvents {
+    'context-update': ProductContext;
+    'selection-change': OptionSelection;
+    'product-load': CatalogProduct;
+    'product-error': Error;
+    'loading-change': boolean;
+}
+/**
+ * Product context manager
+ */
+declare class ProductContextManager extends EventEmitter {
+    private context;
+    private updateQueue;
+    private updateTimer;
+    /**
+     * Get current context
+     */
+    getContext(): ProductContext;
+    /**
+     * Set product data
+     */
+    setProduct(product: CatalogProduct | undefined): void;
+    /**
+     * Update selection
+     */
+    updateSelection(selection: OptionSelection): void;
+    /**
+     * Set loading state
+     */
+    setLoading(loading: boolean): void;
+    /**
+     * Set error state
+     */
+    setError(error: any): void;
+    /**
+     * Update context with batching
+     */
+    private updateContext;
+    /**
+     * Process batched updates
+     */
+    private processBatchUpdate;
+    /**
+     * Derive complete selection
+     */
+    private deriveSelection;
+    /**
+     * Subscribe to context updates
+     */
+    subscribe(callback: (context: ProductContext) => void): () => void;
+    /**
+     * Reset context
+     */
+    reset(): void;
+}
+/**
+ * Create a product context manager
+ */
+declare function createProductContext(): ProductContextManager;
+/**
+ * Product fetcher interface
+ */
+interface ProductFetcher {
+    getProduct(productId: string, options?: any): Promise<CatalogProduct>;
+    listProducts(options?: any): Promise<{
+        items: CatalogProduct[];
+    }>;
+}
+/**
+ * Product loader with fetching capabilities
+ */
+declare class ProductLoader {
+    private context;
+    private fetcher?;
+    private cache;
+    private currentRequest?;
+    constructor(context: ProductContextManager, fetcher?: ProductFetcher);
+    /**
+     * Load product by ID
+     */
+    loadProduct(productId: string, options?: any): Promise<void>;
+    /**
+     * Fetch product
+     */
+    private fetchProduct;
+    /**
+     * Load first available product
+     */
+    loadFirstProduct(options?: any): Promise<void>;
+    /**
+     * Clear cache
+     */
+    clearCache(): void;
+    /**
+     * Set fetcher
+     */
+    setFetcher(fetcher: ProductFetcher): void;
+}
+/**
+ * Create a product loader
+ */
+declare function createProductLoader(context: ProductContextManager, fetcher?: ProductFetcher): ProductLoader;
+
+/**
+ * Unified context provider pattern
+ * Framework-agnostic context management
+ */
+
+/**
+ * Context provider configuration
+ */
+interface ContextProviderConfig {
+    mode?: 'mock' | 'live' | 'meilisearch';
+    endpoint?: string;
+    productId?: string;
+    autoLoad?: boolean;
+    fetcher?: any;
+}
+/**
+ * Context consumer interface
+ */
+interface ContextConsumer<T = ProductContext> {
+    onContextUpdate(context: T): void;
+    onContextError?(error: any): void;
+    onContextLoading?(loading: boolean): void;
+}
+/**
+ * Universal context provider
+ * Works across React, Vue, Svelte, Web Components
+ */
+declare class UniversalContextProvider extends EventEmitter {
+    private contextManager;
+    private loader;
+    private config;
+    private consumers;
+    private initialized;
+    constructor(config?: ContextProviderConfig);
+    /**
+     * Initialize the provider
+     */
+    initialize(): Promise<void>;
+    /**
+     * Load product data
+     */
+    loadProduct(productId?: string): Promise<void>;
+    /**
+     * Get current context
+     */
+    getContext(): ProductContext;
+    /**
+     * Update selection
+     */
+    updateSelection(selection: Record<string, string>): void;
+    /**
+     * Register a consumer
+     */
+    registerConsumer(consumer: ContextConsumer): () => void;
+    /**
+     * Setup internal subscriptions
+     */
+    private setupSubscriptions;
+    /**
+     * Destroy the provider
+     */
+    destroy(): void;
+}
+/**
+ * Context injection patterns for different frameworks
+ */
+declare class ContextInjector {
+    /**
+     * React context injection
+     */
+    static forReact(provider: UniversalContextProvider): any;
+    /**
+     * Vue context injection
+     */
+    static forVue(provider: UniversalContextProvider): any;
+    /**
+     * Svelte context injection
+     */
+    static forSvelte(provider: UniversalContextProvider): any;
+    /**
+     * Web Components context injection
+     */
+    static forWebComponents(provider: UniversalContextProvider): any;
+}
+/**
+ * Create a universal context provider
+ */
+declare function createUniversalProvider(config?: ContextProviderConfig): UniversalContextProvider;
+/**
+ * HOC/Mixin for consuming context
+ */
+declare function withContext<T extends new (...args: any[]) => any>(Base: T): {
+    new (...args: any[]): {
+        [x: string]: any;
+        context?: ProductContext;
+        contextUnsubscribe?: () => void;
+        connectedCallback(): void;
+        disconnectedCallback(): void;
+        onContextUpdate(context: ProductContext): void;
+        onContextError(error: any): void;
+        onContextLoading(loading: boolean): void;
+        findProvider(): UniversalContextProvider | undefined;
+    };
+} & T;
+
+/**
+ * DOM manipulation utilities
+ * Shared across all framework implementations
+ */
+/**
+ * Class name utilities
+ */
+declare const ClassNames: {
+    /**
+     * Combine class names conditionally
+     */
+    combine(...args: (string | undefined | false | null | Record<string, boolean>)[]): string;
+    /**
+     * Toggle a class on an element
+     */
+    toggle(element: HTMLElement, className: string, force?: boolean): void;
+    /**
+     * Add classes with prefix
+     */
+    withPrefix(prefix: string, ...suffixes: string[]): string;
+};
+/**
+ * Style utilities
+ */
+declare const Styles: {
+    /**
+     * Merge style objects
+     */
+    merge(...styles: (Record<string, any> | undefined)[]): Record<string, any>;
+    /**
+     * Convert style object to CSS string
+     */
+    toCss(style: Record<string, any>): string;
+    /**
+     * Parse CSS string to style object
+     */
+    fromCss(css: string): Record<string, string>;
+};
+/**
+ * Attribute utilities
+ */
+declare const Attributes: {
+    /**
+     * Set attributes on an element
+     */
+    set(element: HTMLElement, attributes: Record<string, any>): void;
+    /**
+     * Get all attributes as an object
+     */
+    getAll(element: HTMLElement): Record<string, string>;
+    /**
+     * Parse JSON attribute safely
+     */
+    parseJson<T>(element: HTMLElement, attributeName: string, defaultValue: T): T;
+};
+/**
+ * Element creation utilities
+ */
+declare const Elements: {
+    /**
+     * Create element with properties
+     */
+    create<K extends keyof HTMLElementTagNameMap>(tag: K, props?: {
+        className?: string;
+        style?: Record<string, any>;
+        attributes?: Record<string, any>;
+        children?: (Node | string)[];
+        text?: string;
+        html?: string;
+    }): HTMLElementTagNameMap[K];
+    /**
+     * Create fragment with children
+     */
+    fragment(...children: (Node | string)[]): DocumentFragment;
+    /**
+     * Replace element's children
+     */
+    replaceChildren(element: HTMLElement, ...children: (Node | string)[]): void;
+};
+/**
+ * Focus management utilities
+ */
+declare const Focus: {
+    /**
+     * Trap focus within an element
+     */
+    trap(container: HTMLElement): () => void;
+    /**
+     * Restore focus to previous element
+     */
+    restore(previousElement?: HTMLElement): void;
+};
+/**
+ * Animation utilities
+ */
+declare const Animations: {
+    /**
+     * Fade in element
+     */
+    fadeIn(element: HTMLElement, duration?: number): Promise<void>;
+    /**
+     * Fade out element
+     */
+    fadeOut(element: HTMLElement, duration?: number): Promise<void>;
+    /**
+     * Slide toggle
+     */
+    slideToggle(element: HTMLElement, duration?: number): Promise<void>;
+};
+
+/**
+ * Component lifecycle management
+ * Provides unified lifecycle handling across frameworks
+ */
+type LifecyclePhase = 'created' | 'mounting' | 'mounted' | 'updating' | 'updated' | 'unmounting' | 'unmounted' | 'error';
+interface LifecycleHook {
+    phase: LifecyclePhase;
+    handler: (context?: any) => void | Promise<void>;
+    priority?: number;
+}
+interface LifecycleTransition {
+    from: LifecyclePhase;
+    to: LifecyclePhase;
+    timestamp: number;
+    duration?: number;
+}
+/**
+ * Manages component lifecycle across different frameworks
+ */
+declare class LifecycleManager {
+    private currentPhase;
+    private hooks;
+    private transitions;
+    private listeners;
+    /**
+     * Register a lifecycle hook
+     */
+    addHook(hook: LifecycleHook): () => void;
+    /**
+     * Transition to a new lifecycle phase
+     */
+    transitionTo(phase: LifecyclePhase, context?: any): Promise<void>;
+    /**
+     * Get current lifecycle phase
+     */
+    getPhase(): LifecyclePhase;
+    /**
+     * Subscribe to lifecycle changes
+     */
+    subscribe(listener: (phase: LifecyclePhase) => void): () => void;
+    /**
+     * Get lifecycle history
+     */
+    getHistory(): LifecycleTransition[];
+    /**
+     * Reset lifecycle state
+     */
+    reset(): void;
+}
+/**
+ * Standard component lifecycle flow
+ */
+declare class ComponentLifecycle {
+    private manager;
+    private mounted;
+    /**
+     * Component creation
+     */
+    create(context?: any): Promise<void>;
+    /**
+     * Component mounting
+     */
+    mount(context?: any): Promise<void>;
+    /**
+     * Component updating
+     */
+    update(context?: any): Promise<void>;
+    /**
+     * Component unmounting
+     */
+    unmount(context?: any): Promise<void>;
+    /**
+     * Handle error
+     */
+    error(error: Error, context?: any): Promise<void>;
+    /**
+     * Add lifecycle hook
+     */
+    onPhase(phase: LifecyclePhase, handler: (context?: any) => void, priority?: number): () => void;
+    /**
+     * Subscribe to lifecycle changes
+     */
+    subscribe(listener: (phase: LifecyclePhase) => void): () => void;
+    /**
+     * Get current phase
+     */
+    getPhase(): LifecyclePhase;
+    /**
+     * Check if mounted
+     */
+    isMounted(): boolean;
+}
+/**
+ * Create a shared lifecycle instance
+ */
+declare function createLifecycle(): ComponentLifecycle;
+
+/**
+ * Property management system for cross-framework components
+ * Handles prop validation, transformation, and binding
+ */
+type PropType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'function' | 'any';
+interface PropDefinition {
+    type: PropType | PropType[];
+    required?: boolean;
+    default?: any;
+    validator?: (value: any) => boolean;
+    transform?: (value: any) => any;
+    attribute?: string;
+    reflect?: boolean;
+}
+interface PropSchema {
+    [key: string]: PropDefinition;
+}
+/**
+ * Property manager for components
+ */
+declare class PropertyManager<T extends Record<string, any> = Record<string, any>> {
+    private schema;
+    private values;
+    private listeners;
+    private transforms;
+    constructor(schema: PropSchema);
+    /**
+     * Initialize default values
+     */
+    private initializeDefaults;
+    /**
+     * Set a property value
+     */
+    set<K extends keyof T>(key: K, value: T[K]): boolean;
+    /**
+     * Get a property value
+     */
+    get<K extends keyof T>(key: K): T[K] | undefined;
+    /**
+     * Get all property values
+     */
+    getAll(): Partial<T>;
+    /**
+     * Validate a property value
+     */
+    validate<K extends keyof T>(key: K, value: any): boolean;
+    /**
+     * Transform a property value
+     */
+    private transform;
+    /**
+     * Subscribe to property changes
+     */
+    subscribe<K extends keyof T>(key: K, listener: (value: T[K]) => void): () => void;
+    /**
+     * Subscribe to all property changes
+     */
+    subscribeAll(listener: (key: keyof T, value: any) => void): () => void;
+    /**
+     * Notify listeners of property change
+     */
+    private notify;
+    /**
+     * Batch update multiple properties
+     */
+    update(props: Partial<T>): void;
+    /**
+     * Reset to default values
+     */
+    reset(): void;
+    /**
+     * Get schema
+     */
+    getSchema(): PropSchema;
+}
+/**
+ * Create a property manager
+ */
+declare function createPropertyManager<T extends Record<string, any>>(schema: PropSchema): PropertyManager<T>;
+/**
+ * Common prop definitions
+ */
+declare const CommonProps: {
+    readonly className: {
+        readonly type: PropType;
+        readonly attribute: "class";
+    };
+    readonly style: {
+        readonly type: PropType;
+    };
+    readonly id: {
+        readonly type: PropType;
+        readonly reflect: true;
+    };
+    readonly disabled: {
+        readonly type: PropType;
+        readonly default: false;
+        readonly reflect: true;
+    };
+    readonly hidden: {
+        readonly type: PropType;
+        readonly default: false;
+        readonly reflect: true;
+    };
+};
+/**
+ * Product component props
+ */
+declare const ProductProps: {
+    readonly className: {
+        readonly type: PropType;
+        readonly attribute: "class";
+    };
+    readonly style: {
+        readonly type: PropType;
+    };
+    readonly id: {
+        readonly type: PropType;
+        readonly reflect: true;
+    };
+    readonly disabled: {
+        readonly type: PropType;
+        readonly default: false;
+        readonly reflect: true;
+    };
+    readonly hidden: {
+        readonly type: PropType;
+        readonly default: false;
+        readonly reflect: true;
+    };
+    readonly productId: {
+        readonly type: PropType;
+        readonly attribute: "product-id";
+        readonly reflect: true;
+    };
+    readonly mode: {
+        readonly type: PropType;
+        readonly default: "mock";
+        readonly validator: (value: string) => boolean;
+    };
+    readonly endpoint: {
+        readonly type: PropType;
+    };
+};
+
+/**
+ * Component template system for cross-framework components
+ * Provides abstract component definitions that can be rendered by any framework
+ */
+
+/**
+ * Template node types
+ */
+type TemplateNodeType = 'element' | 'text' | 'component' | 'fragment' | 'conditional' | 'loop' | 'slot';
+/**
+ * Template node interface
+ */
+interface TemplateNode {
+    type: TemplateNodeType;
+    tag?: string;
+    props?: Record<string, any>;
+    children?: TemplateNode[];
+    text?: string;
+    component?: string;
+    condition?: () => boolean;
+    items?: () => any[];
+    renderItem?: (item: any, index: number) => TemplateNode;
+    name?: string;
+    fallback?: TemplateNode[];
+}
+/**
+ * Component template definition
+ */
+interface ComponentTemplate {
+    name: string;
+    props: PropSchema;
+    events?: EventDefinition[];
+    slots?: string[];
+    render: (props: ComponentProps, context?: any) => TemplateNode;
+}
+/**
+ * Template builder for creating templates programmatically
+ */
+declare class TemplateBuilder {
+    /**
+     * Create an element node
+     */
+    static element(tag: string, props?: Record<string, any>, children?: TemplateNode[]): TemplateNode;
+    /**
+     * Create a text node
+     */
+    static text(text: string): TemplateNode;
+    /**
+     * Create a component node
+     */
+    static component(component: string, props?: Record<string, any>, children?: TemplateNode[]): TemplateNode;
+    /**
+     * Create a fragment node
+     */
+    static fragment(children: TemplateNode[]): TemplateNode;
+    /**
+     * Create a conditional node
+     */
+    static if(condition: () => boolean, thenNode: TemplateNode | TemplateNode[], elseNode?: TemplateNode | TemplateNode[]): TemplateNode;
+    /**
+     * Create a loop node
+     */
+    static forEach<T>(items: () => T[], renderItem: (item: T, index: number) => TemplateNode): TemplateNode;
+    /**
+     * Create a slot node
+     */
+    static slot(name: string, fallback?: TemplateNode[]): TemplateNode;
+}
+/**
+ * Standard component templates
+ */
+declare class ComponentTemplates {
+    /**
+     * Product options template
+     */
+    static productOptions(): ComponentTemplate;
+    /**
+     * Product price template
+     */
+    static productPrice(): ComponentTemplate;
+    /**
+     * Product image template
+     */
+    static productImage(): ComponentTemplate;
+    /**
+     * Add to cart button template
+     */
+    static addToCartButton(): ComponentTemplate;
+}
+/**
+ * Template renderer interface
+ */
+interface TemplateRenderer {
+    render(node: TemplateNode, context?: any): any;
+}
+/**
+ * Abstract template renderer
+ */
+declare abstract class AbstractTemplateRenderer implements TemplateRenderer {
+    protected adapter: FrameworkAdapter;
+    constructor(adapter: FrameworkAdapter);
+    /**
+     * Render a template node
+     */
+    render(node: TemplateNode, context?: any): any;
+    /**
+     * Render child nodes
+     */
+    protected renderChildren(children?: TemplateNode[], context?: any): any[];
+    protected abstract renderElement(node: TemplateNode, context?: any): any;
+    protected abstract renderText(node: TemplateNode, context?: any): any;
+    protected abstract renderComponent(node: TemplateNode, context?: any): any;
+    protected abstract renderFragment(node: TemplateNode, context?: any): any;
+    protected abstract renderConditional(node: TemplateNode, context?: any): any;
+    protected abstract renderLoop(node: TemplateNode, context?: any): any;
+    protected abstract renderSlot(node: TemplateNode, context?: any): any;
+}
+
+/**
+ * Component registry for managing components across frameworks
+ */
+
+/**
+ * Component metadata
+ */
+interface ComponentMetadata {
+    name: string;
+    tagName?: string;
+    displayName?: string;
+    description?: string;
+    props: PropSchema;
+    events?: EventDefinition[];
+    slots?: string[];
+    version?: string;
+    framework?: 'react' | 'vue' | 'svelte' | 'lit' | 'vanilla';
+}
+/**
+ * Component definition combining metadata and implementation
+ */
+interface ComponentDefinition {
+    metadata: ComponentMetadata;
+    descriptor: ComponentDescriptor;
+    implementation?: any;
+}
+/**
+ * Global component registry
+ */
+declare class ComponentRegistry {
+    private components;
+    private frameworks;
+    /**
+     * Register a component
+     */
+    register(definition: ComponentDefinition): void;
+    /**
+     * Get a component definition
+     */
+    get(name: string): ComponentDefinition | undefined;
+    /**
+     * Get all components for a framework
+     */
+    getByFramework(framework: string): ComponentDefinition[];
+    /**
+     * Get all registered components
+     */
+    getAll(): ComponentDefinition[];
+    /**
+     * Check if a component is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Clear registry
+     */
+    clear(): void;
+}
+declare const componentRegistry: ComponentRegistry;
+/**
+ * Standard component definitions for all frameworks
+ */
+declare const StandardComponents: {
+    /**
+     * Product component
+     */
+    Product: {
+        metadata: {
+            name: string;
+            tagName: string;
+            displayName: string;
+            description: string;
+            props: {
+                productId: {
+                    type: "string";
+                };
+                mode: {
+                    type: "string";
+                    default: string;
+                    validator: (v: string) => boolean;
+                };
+                endpoint: {
+                    type: "string";
+                };
+                autoLoad: {
+                    type: "boolean";
+                    default: boolean;
+                };
+            };
+            events: {
+                name: string;
+                bubbles: boolean;
+            }[];
+            slots: string[];
+        };
+    };
+    /**
+     * Product Options component
+     */
+    ProductOptions: {
+        metadata: {
+            name: string;
+            tagName: string;
+            displayName: string;
+            description: string;
+            props: {
+                attributes: {
+                    type: "object";
+                };
+                selection: {
+                    type: "object";
+                };
+                combinations: {
+                    type: "array";
+                };
+                disabled: {
+                    type: "boolean";
+                    default: boolean;
+                };
+            };
+            events: {
+                name: string;
+                bubbles: boolean;
+            }[];
+        };
+    };
+    /**
+     * Product Price component
+     */
+    ProductPrice: {
+        metadata: {
+            name: string;
+            tagName: string;
+            displayName: string;
+            description: string;
+            props: {
+                price: {
+                    type: "number";
+                };
+                currency: {
+                    type: "string";
+                    default: string;
+                };
+                locale: {
+                    type: "string";
+                    default: string;
+                };
+                showCurrency: {
+                    type: "boolean";
+                    default: boolean;
+                };
+            };
+        };
+    };
+    /**
+     * Product Image component
+     */
+    ProductImage: {
+        metadata: {
+            name: string;
+            tagName: string;
+            displayName: string;
+            description: string;
+            props: {
+                productId: {
+                    type: "string";
+                };
+                mockupId: {
+                    type: "string";
+                };
+                variantId: {
+                    type: "string";
+                };
+                width: {
+                    type: "number";
+                    default: number;
+                };
+                aspectRatio: {
+                    type: "string";
+                };
+                design: {
+                    type: "object";
+                };
+            };
+            slots: string[];
+        };
+    };
+    /**
+     * Add to Cart component
+     */
+    AddToCart: {
+        metadata: {
+            name: string;
+            tagName: string;
+            displayName: string;
+            description: string;
+            props: {
+                text: {
+                    type: "string";
+                    default: string;
+                };
+                loadingText: {
+                    type: "string";
+                    default: string;
+                };
+                successText: {
+                    type: "string";
+                    default: string;
+                };
+                disabled: {
+                    type: "boolean";
+                    default: boolean;
+                };
+                quantity: {
+                    type: "number";
+                    default: number;
+                };
+            };
+            events: {
+                name: string;
+                bubbles: boolean;
+            }[];
+        };
+    };
+};
+/**
+ * Register all standard components
+ */
+declare function registerStandardComponents(): void;
+/**
+ * Component factory for creating framework-specific implementations
+ */
+declare class ComponentFactory {
+    /**
+     * Create a React component
+     */
+    static forReact(definition: ComponentDefinition, React: any): any;
+    /**
+     * Create a Vue component
+     */
+    static forVue(definition: ComponentDefinition): any;
+    /**
+     * Create a Svelte component
+     */
+    static forSvelte(definition: ComponentDefinition): any;
+    /**
+     * Create a Web Component
+     */
+    static forWebComponent(definition: ComponentDefinition, LitElement: any): any;
+}
+/**
+ * Auto-register components for a framework
+ */
+declare function autoRegister(framework: string, registrar: (definition: ComponentDefinition) => void): void;
+
+/**
+ * Lit/Web Components framework adapter implementation
+ */
+
+/**
+ * Lit adapter implementation for Web Components
+ */
+declare class LitAdapter implements FrameworkAdapter<ComponentProps> {
+    name: "lit";
+    private element;
+    private properties;
+    private subscriptions;
+    constructor(element?: any);
+    /**
+     * Create a stateful value using reactive properties
+     */
+    createState<T>(initialValue: T): ComponentState<T>;
+    /**
+     * Create a context provider/consumer
+     */
+    createContext<T>(name: string): ComponentContext<T>;
+    /**
+     * Register lifecycle hooks
+     */
+    useLifecycle(lifecycle: ComponentLifecycleHooks): void;
+    /**
+     * Register event handlers
+     */
+    useEvents(handlers: EventHandler[]): void;
+    /**
+     * Create a ref to a DOM element
+     */
+    createRef<T extends HTMLElement>(): {
+        current: T | null;
+    };
+    /**
+     * Render a component
+     */
+    render(component: ComponentDescriptor, props: ComponentProps): any;
+    /**
+     * Get Lit-specific utilities
+     */
+    getUtilities(): FrameworkUtilities;
+    /**
+     * Set the element instance
+     */
+    setElement(element: any): void;
+}
+/**
+ * Create a Lit component from a descriptor
+ */
+declare function createLitComponent(descriptor: ComponentDescriptor, LitElement: any, html: any): any;
+
+/**
+ * Vue 3 framework adapter implementation
+ */
+
+/**
+ * Vue 3 adapter implementation
+ */
+declare class VueAdapter implements FrameworkAdapter<ComponentProps> {
+    name: "vue";
+    private vue;
+    private instance;
+    constructor(vue: any, instance?: any);
+    /**
+     * Create a stateful value using ref/reactive
+     */
+    createState<T>(initialValue: T): ComponentState<T>;
+    /**
+     * Create a context provider/consumer
+     */
+    createContext<T>(name: string): ComponentContext<T>;
+    /**
+     * Register lifecycle hooks
+     */
+    useLifecycle(lifecycle: ComponentLifecycleHooks): void;
+    /**
+     * Register event handlers
+     */
+    useEvents(handlers: EventHandler[]): void;
+    /**
+     * Create a ref to a DOM element
+     */
+    createRef<T extends HTMLElement>(): {
+        current: T | null;
+    };
+    /**
+     * Render a component
+     */
+    render(component: ComponentDescriptor, props: ComponentProps): any;
+    /**
+     * Get Vue-specific utilities
+     */
+    getUtilities(): FrameworkUtilities;
+}
+/**
+ * Create a Vue component from a descriptor
+ */
+declare function createVueComponent(descriptor: ComponentDescriptor, vue: any): any;
+/**
+ * Composition API hook to use framework adapter
+ */
+declare function useFrameworkAdapter(vue: any): VueAdapter;
+
+/**
+ * Svelte framework adapter implementation
+ */
+
+/**
+ * Svelte adapter implementation
+ */
+declare class SvelteAdapter implements FrameworkAdapter<ComponentProps> {
+    name: "svelte";
+    private svelte;
+    private component;
+    constructor(svelte: any, component?: any);
+    /**
+     * Create a stateful value using Svelte stores
+     */
+    createState<T>(initialValue: T): ComponentState<T>;
+    /**
+     * Create a context provider/consumer
+     */
+    createContext<T>(name: string): ComponentContext<T>;
+    /**
+     * Register lifecycle hooks
+     */
+    useLifecycle(lifecycle: ComponentLifecycleHooks): void;
+    /**
+     * Register event handlers
+     */
+    useEvents(handlers: EventHandler[]): void;
+    /**
+     * Create a ref to a DOM element
+     */
+    createRef<T extends HTMLElement>(): {
+        current: T | null;
+    };
+    /**
+     * Render a component
+     */
+    render(component: ComponentDescriptor, props: ComponentProps): any;
+    /**
+     * Get Svelte-specific utilities
+     */
+    getUtilities(): FrameworkUtilities;
+}
+/**
+ * Create a Svelte component from a descriptor
+ * Note: Svelte components are compiled, so this is more of a template
+ */
+declare function createSvelteComponent(descriptor: ComponentDescriptor, svelte: any): any;
+
+interface ProductPlacement {
+    label: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation?: number;
+    scaleMode?: "fit" | "fill" | "stretch";
+}
+interface ProductVariant {
+    id: string;
+    size?: string;
+    color?: string;
+    material?: string;
+    mockupId: string;
+}
+interface ProductMockupData {
+    id: string;
+    name: string;
+    placements: ProductPlacement[];
+    variants: ProductVariant[];
+}
+
+interface CatalogListResponse {
+    items: CatalogProduct$2[];
+    total: number;
+}
+
+interface SdkConfig {
+    baseUrl: string;
+    fetcher?: typeof fetch;
+    mockup?: MockupServiceConfig;
+    mode?: "mock" | "meilisearch";
+    limit?: number;
+    meilisearch?: {
+        host?: string;
+        apiKey?: string;
+        index?: string;
+    };
+}
+interface MerchifyClient {
+    catalog: {
+        listProducts(config?: Partial<SdkConfig>): Promise<CatalogListResponse>;
+        getProduct(idOrSlug: string, config?: Partial<SdkConfig>): Promise<CatalogProduct$2>;
+    };
+    mockup: MockupService;
+}
+declare function listProducts(config?: Partial<SdkConfig>): Promise<CatalogListResponse>;
+declare function getProduct(idOrSlug: string, config?: Partial<SdkConfig>): Promise<CatalogProduct$2>;
+/**
+ * Create a unified Merchify client with catalog and mockup services
+ */
+declare function createClient(config: SdkConfig): MerchifyClient;
+
+export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type CartDetail, type CatalogListResponse, type CatalogProduct$2 as CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_COLOR, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type DesignElement, type DesignGenerationContext, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MerchifyClient, type MockupConfig, type MockupGenerationOptions, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, type RateLimitState, type RegularArtwork, type SdkConfig, type SeamlessPattern, type SignedUrlResponse, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, autoRegister, componentRegistry, config, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, isSelectionComplete, isValidAlignment, isValidTileCount, listProducts, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupConfig, resolveMockupId, resolveVariantId, retryOperation, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, withContext, withErrorHandling, withSyncErrorHandling };