@weaverse/hydrogen 5.17.0 → 5.18.0

package/dist/index.d.mts

@@ -1,1269 +0,0 @@
-import { SelectedOptionInput } from '@shopify/hydrogen/storefront-api-types';
-import { Weaverse, WeaverseItemStore, ElementData, WeaverseElement, WeaverseProjectDataType, WeaverseCoreParams, WeaverseResourcePickerData } from '@weaverse/react';
-export { PositionInputValue, WeaverseImage, WeaverseVideo, isBrowser, isIframe, useChildInstances, useItemInstance, useParentInstance, useWeaverse } from '@weaverse/react';
-import { PageType, InspectorGroup, SchemaType, PageSEOData, ComponentPresets, SchemaValidationResult } from '@weaverse/schema';
-export * from '@weaverse/schema';
-export { BasicInput, HeadingInput, InputType, InspectorGroup, PageType, SchemaValidationIssue, SchemaValidationResult } from '@weaverse/schema';
-import { createWithCache, CachingStrategy, I18nBase, HydrogenContext, HydrogenEnv } from '@shopify/hydrogen';
-export { CachingStrategy } from '@shopify/hydrogen';
-import { LoaderFunctionArgs, AppLoadContext } from '@shopify/remix-oxygen';
-import * as React$1 from 'react';
-import { ReactNode, ComponentType, JSX, ForwardRefExoticComponent } from 'react';
-import { NavigateFunction, UIMatch, MetaDescriptor } from 'react-router';
-import * as react_jsx_runtime from 'react/jsx-runtime';
-
-/**
- * Minimal mutable store for design-mode static text overrides.
- *
- * useSyncExternalStore-compatible. Passed into TranslationProvider which
- * subscribes internally and merges overrides into merchantOverrides.
- * The studio bridge calls updateOverrides() via weaverse.internal.translationStore
- * (also exposed as the deprecated weaverse.internal.themeTextStore alias).
- *
- * Shape: flat Record<string, string> — dot-notation keys map to values
- * (e.g. "cart.title" → "Shopping Cart").
- */
-declare class TranslationStore {
-    overrides: Record<string, string>;
-    private listeners;
-    setOverrides: (overrides: Record<string, string>) => void;
-    updateOverrides: (newOverrides: Record<string, string>) => void;
-    getSnapshot: () => Record<string, string>;
-    getServerSnapshot: () => Record<string, string>;
-    subscribe: (callback: () => void) => () => void;
-    private emit;
-}
-/**
- * @deprecated Use {@link TranslationStore} instead. Kept as a backward-compatible
- * alias and will remain exported for existing integrations.
- */
-declare const ThemeTextStore: typeof TranslationStore;
-/**
- * @deprecated Use {@link TranslationStore} instead. Kept as a backward-compatible
- * alias and will remain exported for existing integrations.
- */
-type ThemeTextStore = TranslationStore;
-
-type WeaverseThemeData = {
-    theme: HydrogenThemeSettings;
-    schema?: HydrogenThemeSchema;
-    publicEnv?: PublicEnv;
-};
-declare class ThemeSettingsStore {
-    settings: HydrogenThemeSettings;
-    schema?: HydrogenThemeSchema;
-    publicEnv?: PublicEnv;
-    private listeners;
-    private hasWarnedListenerCount;
-    private isDestroyed;
-    constructor(data: WeaverseThemeData);
-    updateThemeSettings: (newSettings: HydrogenThemeSettings) => void;
-    getSnapshot: () => HydrogenThemeSettings;
-    getServerSnapshot: () => HydrogenThemeSettings;
-    subscribe: (callback: () => void) => () => void;
-    private emit;
-    destroy: () => void;
-}
-
-/**
- * Traverse a nested object by dot-path.
- *
- * @example
- * getNestedKey({ cart: { title: 'Cart' } }, 'cart.title') // => 'Cart'
- * getNestedKey({}, 'cart.title', 'fallback')              // => 'fallback'
- */
-declare function getNestedKey(obj: Record<string, unknown>, path: string, fallback?: string): string | undefined;
-/**
- * Replace `{{variable}}` patterns in a string with provided values.
- *
- * @example
- * interpolate('Hello {{name}}!', { name: 'World' }) // => 'Hello World!'
- * interpolate('-{{percentage}}% Off', { percentage: 15 }) // => '-15% Off'
- */
-declare function interpolate(template: string, variables?: Record<string, string | number>): string;
-/**
- * Signature for a translation function.
- */
-type TranslateFunction = (key: string, variables?: Record<string, string | number>) => string;
-type TranslationValue = {
-    /**
-     * Translate a key with optional variable interpolation.
-     *
-     * Priority chain (highest wins):
-     * 1. External `t`        (passed into `withWeaverse` / `TranslationProvider`)
-     * 2. `merchantOverrides` (DB overrides for the current locale + design overrides)
-     * 3. `staticContent`     (theme default JSON)
-     * 4. The key itself      (fallback)
-     *
-     * @example
-     * t('cart.title')                           // => "Cart"
-     * t('badge.sale', { percentage: 15 })       // => "-15% Off"
-     */
-    t: TranslateFunction;
-    /** Exposed for useStudio to attach to weaverse.internal. Null in production. */
-    translationStore: TranslationStore | null;
-    /**
-     * @deprecated Use {@link TranslationValue.translationStore} instead. Kept as a
-     * backward-compatible alias pointing at the same store instance.
-     */
-    themeTextStore: TranslationStore | null;
-    /** Active-locale translated keys loaded from the storefront API. */
-    merchantOverrides: Record<string, unknown> | null;
-};
-type TranslationProviderProps = {
-    staticContent: Record<string, unknown>;
-    merchantOverrides?: Record<string, unknown>;
-    /**
-     * Optional external translation function.
-     * When provided it becomes the **highest-priority** source:
-     * if it returns a non-empty string that differs from the raw key,
-     * that value is used; otherwise the internal resolution chain continues.
-     */
-    t?: TranslateFunction;
-    /** Optional store for live design-mode text overrides from the builder. */
-    translationStore?: TranslationStore | null;
-    /**
-     * @deprecated Use {@link TranslationProviderProps.translationStore} instead.
-     * Still accepted for backward compatibility; ignored when `translationStore`
-     * is also provided.
-     */
-    themeTextStore?: TranslationStore | null;
-    children: ReactNode;
-};
-/**
- * Provider that wraps the app to expose the `t()` function.
- *
- * - `staticContent`      – the theme's default locale JSON (from themeSchema.i18n)
- * - `merchantOverrides`  – locale-specific overrides fetched from the API
- * - `translationStore`   – optional store for live design-mode text overrides
- *   (the deprecated `themeTextStore` prop is accepted as a fallback)
- */
-declare function TranslationProvider({ staticContent, merchantOverrides, t: externalT, translationStore, themeTextStore, children, }: TranslationProviderProps): react_jsx_runtime.JSX.Element;
-/**
- * Hook to access the translation `t()` function.
- *
- * Must be used inside a component wrapped by `withWeaverse` or `TranslationProvider`.
- *
- * @example
- * ```tsx
- * function CartTitle() {
- *   const { t } = useTranslation()
- *   return <h2>{t('cart.title')}</h2>
- * }
- * ```
- */
-declare function useTranslation(): TranslationValue;
-/**
- * @deprecated Use {@link TranslationProvider} instead.
- */
-declare const ThemeTextProvider: typeof TranslationProvider;
-/**
- * @deprecated Use {@link useTranslation} instead.
- */
-declare const useThemeText: typeof useTranslation;
-/**
- * @deprecated Use {@link TranslationValue} instead.
- */
-type ThemeTextValue = TranslationValue;
-/**
- * @deprecated Use {@link TranslationProviderProps} instead.
- */
-type ThemeTextProviderProps = TranslationProviderProps;
-
-type WeaverseDataValue = WeaverseLoaderData | Promise<WeaverseLoaderData> | null;
-
-declare class WeaverseHydrogenItem extends WeaverseItemStore {
-    weaverse: WeaverseHydrogen;
-    /**
-     * Cached merged snapshot (base + translations).
-     * Reset to `null` whenever `_store` or the item's translation entry changes.
-     */
-    private _cachedSnapshot;
-    private _snapshotStoreRef;
-    private _snapshotTranslationRef;
-    constructor(initialData: HydrogenComponentData, weaverse: WeaverseHydrogen);
-    get Element(): HydrogenElement;
-    /**
-     * Override getSnapShot to merge translation data when in translation mode.
-     * Memoizes the result: returns the same object reference as long as
-     * both `_store` and the translation entry haven't changed.
-     * This is critical for `useSyncExternalStore` stability.
-     */
-    getSnapShot: () => ElementData;
-}
-declare class WeaverseHydrogen extends Weaverse {
-    pageId: string;
-    internal: Partial<WeaverseInternal>;
-    requestInfo: WeaverseLoaderRequestInfo;
-    projectId: string;
-    weaverseHost: string;
-    weaverseApiBase: string;
-    weaverseApiKey: string;
-    weaverseVersion: string;
-    isDesignMode: boolean;
-    isPreviewMode: boolean;
-    isRevisionPreview: boolean;
-    sectionType: string;
-    ItemConstructor: typeof WeaverseHydrogenItem;
-    data: HydrogenPageData;
-    static itemInstances: Map<string, WeaverseHydrogenItem>;
-    static elementRegistry: Map<string, HydrogenElement>;
-    /**
-     * Translation map received from the builder in design mode.
-     * Keyed by item ID, each entry maps field names to translated values.
-     * `WeaverseHydrogenItem.getSnapShot()` merges these into the data
-     * returned to components, so translations render without monkey-patching.
-     */
-    translationMap: TranslationMap;
-    translationLocale: string;
-    translationLanguageId: string;
-    constructor(params: WeaverseHydrogenParams);
-    /**
-     * Extract translation sidecar data from `this.data` (the page data).
-     * The builder attaches `translationMap`, `translationLocale`, and
-     * `translationLanguageId` to the page data in design mode.
-     */
-    extractTranslationSidecar: () => void;
-    /**
-     * Set the translation sidecar data.
-     * Called by the studio bridge when translation data arrives or changes.
-     * Triggers a re-render of all items so translated snapshots are recalculated.
-     */
-    setTranslationSidecar: (translationMap: TranslationMap, locale: string, languageId: string) => void;
-    /**
-     * Update a single translation entry for a specific item field.
-     * Used by the studio bridge when the user edits a translatable field.
-     */
-    updateTranslation: (itemId: string, key: string, originalValue: string, translatedValue: string) => void;
-    /**
-     * Collect all translation changes across all weaverse instances.
-     * Used by the save flow to persist translation edits.
-     */
-    getTranslationChanges: () => TranslationChanges | undefined;
-    /**
-     * Override setProjectData to re-extract translation sidecar from new page data.
-     */
-    setProjectData: (data: HydrogenPageData) => void;
-}
-/**
- * Register a Weaverse component with the global element registry.
- * Must be called before rendering components in WeaverseHydrogenRoot.
- *
- * @param element - Component configuration with schema, Component, and optional loader
- *
- * @example
- * ```typescript
- * import Hero from './sections/Hero'
- * import { schema } from './sections/Hero'
- *
- * registerComponent({
- *   type: 'hero',
- *   Component: Hero,
- *   schema,
- *   loader: async ({ data, weaverse }) => {
- *     return { someData: 'value' }
- *   }
- * })
- * ```
- */
-declare function registerComponent(element: HydrogenElement): void;
-declare const WeaverseHydrogenRoot: React$1.MemoExoticComponent<({ components, data: dataProp, errorComponent: ErrorComponent, }: {
-    components: HydrogenComponent[];
-    /**
-     * Optional explicit `weaverseData` payload. When provided, bypasses the
-     * automatic route-scoped resolution. Accepts a resolved value, a
-     * `Promise` (handled via `<Await>`), or `null` to suppress rendering.
-     *
-     * Recommended for nested layout + child route compositions where two
-     * `<WeaverseHydrogenRoot>` instances need to render different Weaverse
-     * pages on the same URL. See issue #451.
-     */
-    data?: WeaverseDataValue;
-    errorComponent?: React.FC<{
-        error: Error | unknown;
-    }>;
-}) => react_jsx_runtime.JSX.Element | null>;
-/**
- * Options for the `withWeaverse` HOC.
- */
-type WithWeaverseOptions = {
-    /**
-     * Optional external translation function (e.g. from Shopify i18n).
-     * When provided it becomes the **highest-priority** source
-     * in the `t()` resolution chain exposed by `useTranslation()`.
-     */
-    t?: TranslateFunction;
-};
-/**
- * Higher-order component that wraps your app with Weaverse theme settings and
- * translation context, and mounts the Studio connect bridge.
- *
- * Export the result as your root route's **`Layout`** (not the default route
- * `Component`). In React Router the root `Layout` wraps both the matched route
- * and its `ErrorBoundary`, so the Studio bridge keeps rendering on 404s and
- * loader/render errors — exactly the pages where Studio must still answer its
- * handshake instead of reporting a false "Connection lost". A default-component
- * wrapper (`export default withWeaverse(App)`) is replaced by the error
- * boundary on those routes and would drop the bridge.
- *
- * @param Component - The root layout component to wrap
- * @param options   - Optional configuration (e.g. an external `t` function)
- * @returns Wrapped component with theme settings + translation providers
- *
- * @example
- * ```typescript
- * import { withWeaverse } from '@weaverse/hydrogen'
- *
- * // Basic usage — export as the root route Layout
- * export const Layout = withWeaverse(RootLayout)
- *
- * // With an external translation function
- * export const Layout = withWeaverse(RootLayout, { t: myI18nFunction })
- * ```
- */
-declare function withWeaverse(Component: ComponentType<any>, options?: WithWeaverseOptions): (props: JSX.IntrinsicAttributes) => react_jsx_runtime.JSX.Element;
-/**
- * React hook to access Weaverse theme settings from anywhere in your component tree.
- * Must be used within a component wrapped by `withWeaverse` or inside `WeaverseHydrogenRoot`.
- *
- * @returns Current theme settings object
- *
- * @example
- * ```typescript
- * function MyComponent() {
- *   const theme = useThemeSettings()
- *   const primaryColor = theme.colors?.primary
- *
- *   return <div style={{ color: primaryColor }}>Styled content</div>
- * }
- * ```
- */
-declare function useThemeSettings<T = HydrogenThemeSettings>(): T;
-
-type BuilderApiCacheTarget = 'custom-pages' | 'merchant-overrides' | 'project' | 'theme-settings';
-declare class WeaverseClient {
-    API: "v1";
-    basePageConfigs: Omit<WeaverseProjectConfigs, 'requestInfo'>;
-    basePageRequestBody: Omit<FetchProjectRequestBody, 'url'>;
-    configs: WeaverseProjectConfigs;
-    withCache: ReturnType<typeof createWithCache>;
-    request: WeaverseClientArgs['request'];
-    customerAccount: WeaverseClientArgs['customerAccount'];
-    storefront: WeaverseClientArgs['storefront'];
-    components: WeaverseClientArgs['components'];
-    themeSchema: WeaverseClientArgs['themeSchema'];
-    env: WeaverseClientArgs['env'];
-    cache: WeaverseClientArgs['cache'];
-    waitUntil: WeaverseClientArgs['waitUntil'];
-    private readonly parsedUrl;
-    private readonly componentsByType;
-    private readonly fetchTimeoutMs;
-    constructor(args: WeaverseClientArgs);
-    /**
-     * Initialize Hydrogen cache with proper configuration.
-     * Logs warning if waitUntil is missing.
-     */
-    private initializeCache;
-    /**
-     * Initialize configs with projectId resolution and fail-fast validation.
-     * Throws WeaverseError if projectId cannot be resolved.
-     */
-    private initializeConfigs;
-    /**
-     * Build component lookup map for O(1) access by type.
-     * Significantly improves performance for large component lists.
-     */
-    private buildComponentLookupMap;
-    /**
-     * Extract comprehensive error information from unknown error type.
-     * Preserves error context, codes, and stack traces for debugging.
-     *
-     * @param error - Unknown error to extract information from
-     * @returns Structured error information with message, code, stack, and context
-     *
-     * @example
-     * ```typescript
-     * try {
-     *   // ... operation
-     * } catch (error) {
-     *   const errorInfo = this.extractErrorInfo(error)
-     *   console.error('Operation failed:', errorInfo.message, errorInfo.context)
-     * }
-     * ```
-     */
-    private extractErrorInfo;
-    /**
-     * Extract error message only (for backward compatibility).
-     * Use extractErrorInfo() for more detailed error information.
-     *
-     * @deprecated Use extractErrorInfo() instead to preserve error context
-     */
-    private extractErrorMessage;
-    /**
-     * Validates projectId format (alphanumeric, hyphens, underscores only).
-     * Returns detailed validation result with error message.
-     *
-     * @param projectId - Project identifier to validate
-     * @returns Validation result with error message if invalid
-     */
-    private validateProjectId;
-    /**
-     * Resolves projectId with multi-project architecture support.
-     * Uses priority chain to determine the correct project ID.
-     *
-     * @param projectId - Project identifier (string, function, or undefined)
-     * @param request - HTTP request for context access
-     * @param env - Hydrogen environment with variables
-     * @param baseConfigs - Pre-fetched base configs to avoid duplicate calls
-     * @returns Resolved project ID string (empty string if none found)
-     */
-    private resolveProjectIdSync;
-    /**
-     * Priority 1: Resolve projectId from URL query parameters.
-     * Used for design mode and preview mode overrides.
-     */
-    private resolveFromQueryParams;
-    /**
-     * Priority 2: Resolve projectId from function parameter.
-     * Detects and rejects async functions with helpful error.
-     */
-    private resolveFromFunction;
-    /**
-     * Priority 3: Resolve projectId from explicit string parameter.
-     */
-    private resolveFromString;
-    /**
-     * Priority 4: Resolve projectId from environment variables.
-     */
-    private resolveFromEnvironment;
-    /**
-     * Helper method for direct fetching in design mode.
-     * Returns same format as withCache.fetch for consistency.
-     * Includes 10-second timeout to prevent hanging requests.
-     */
-    private readonly fetchOnce;
-    private readonly directFetch;
-    private getApiUrl;
-    private isExternalPublicApiUrl;
-    /**
-     * Fetch data with caching support for both design mode and production.
-     * Uses direct fetch in design mode, Hydrogen's withCache in production.
-     * Automatically includes projectId in cache key for multi-project isolation.
-     *
-     * @param url - The URL to fetch from
-     * @param options - Fetch options including optional cache strategy
-     * @returns Promise resolving to the fetched data
-     *
-     * @example
-     * ```typescript
-     * const data = await weaverse.fetchWithCache<MyData>(
-     *   'https://api.example.com/data',
-     *   { method: 'POST', body: JSON.stringify({ key: 'value' }) }
-     * )
-     * ```
-     */
-    fetchWithCache: <T = unknown>(url: string, options?: RequestInit & {
-        cacheTarget?: BuilderApiCacheTarget;
-        strategy?: CachingStrategy;
-    }) => Promise<T>;
-    /**
-     * Load theme settings from Weaverse API with fallback to schema defaults.
-     * Merges remote settings with local theme schema and handles design mode serialization.
-     *
-     * @param strategy - Optional cache strategy override
-     * @returns Promise resolving to theme settings response
-     *
-     * @example
-     * ```typescript
-     * const settings = await weaverse.loadThemeSettings()
-     * const primaryColor = settings.theme.colors?.primary
-     * ```
-     */
-    loadThemeSettings: (strategy?: CachingStrategy) => Promise<ThemeSettingsResponse>;
-    /**
-     * Fetch locale-specific merchant overrides from the translation API.
-     * Returns a nested JSON object with translated values.
-     * Falls back to empty object on error to avoid blocking theme rendering.
-     */
-    private fetchMerchantOverrides;
-    /**
-     * Generate fallback page with default structure when page data is unavailable.
-     * Used internally when API returns no page or when page needs default content.
-     *
-     * @param message - Custom message to display in the fallback page
-     * @returns HydrogenPageData with single main component containing the message
-     */
-    generateFallbackPage: (message: string) => HydrogenPageData;
-    /**
-     * Fetch all published custom pages for sitemap generation.
-     * Paginates automatically, never throws, returns accumulated results on partial failure.
-     */
-    fetchCustomPages(opts?: {
-        locale?: string;
-        limit?: number;
-    }): Promise<CustomPageEntry[]>;
-    /**
-     * Load page data from Weaverse API with optional route-level project override.
-     * Fetches page content, executes component loaders, and handles empty items fallback.
-     *
-     * @param params - Optional page loading parameters
-     * @param params.type - Page type (INDEX, PAGE, PRODUCT, COLLECTION, etc.)
-     * @param params.handle - Page handle for dynamic routes
-     * @param params.locale - Locale override
-     * @param params.projectId - Route-level project ID override (for multi-project)
-     * @param params.strategy - Custom cache strategy override
-     * @returns Promise resolving to page data or null on error
-     *
-     * @example
-     * ```typescript
-     * // Basic usage
-     * const data = await weaverse.loadPage()
-     *
-     * // With page type
-     * const data = await weaverse.loadPage({ type: 'INDEX' })
-     *
-     * // Route-level project override
-     * const data = await weaverse.loadPage({
-     *   type: 'PAGE',
-     *   handle: 'about',
-     *   projectId: 'campaign-project-123'
-     * })
-     * ```
-     */
-    loadPage: (params?: LoadPageParams) => Promise<WeaverseLoaderData | null>;
-    execComponentLoader: (item: HydrogenComponentData) => Promise<HydrogenComponentData>;
-}
-
-type ComponentLoaderArgs<T = any, _E = any> = {
-    data: T;
-    weaverse: WeaverseClient;
-};
-interface RouteLoaderArgs extends LoaderFunctionArgs {
-    context: AppLoadContext & {
-        weaverse: WeaverseClient;
-    };
-}
-type ComponentDataValue = string | number | boolean | undefined | null;
-interface HydrogenComponentData extends ElementData {
-    children?: {
-        id: string;
-    }[];
-    createdAt?: string;
-    data?: Record<string, ComponentDataValue | Record<string, unknown>>;
-    deletedAt?: string;
-    id: string;
-    type: string;
-    updatedAt?: string;
-}
-/**
- * Optimized: Use Zod-inferred SchemaType directly instead of extending
- * This ensures perfect type consistency with the schema validation
- */
-type HydrogenComponentSchema = SchemaType;
-interface HydrogenComponentProps<L = any> extends WeaverseElement {
-    children?: React$1.JSX.Element[];
-    className?: string;
-    loaderData?: L;
-}
-type WeaverseLoaderRequestInfo = {
-    search: string;
-    pathname: string;
-    queries: {
-        [key: string]: string | boolean;
-    };
-    i18n: WeaverseI18n;
-};
-type HydrogenThemeSettings = {
-    [key: string]: any;
-};
-type HydrogenProjectType = {
-    id: string;
-    weaverseShopId: string;
-    name: string;
-    [key: string]: any;
-};
-type WeaverseInternal = {
-    pageAssignment: HydrogenPageAssignment;
-    project: HydrogenProjectType;
-    navigate: NavigateFunction;
-    revalidate: () => void;
-    themeSettingsStore: ThemeSettingsStore;
-    translationStore?: TranslationStore | null;
-    /** @deprecated Use translationStore instead. */
-    themeTextStore?: TranslationStore | null;
-    merchantOverrides?: Record<string, unknown> | null;
-};
-/**
- * Optimized: Use direct type alias to maintain consistency
- */
-type HydrogenComponentPresets = ComponentPresets;
-type HydrogenElement = {
-    Component: ForwardRefExoticComponent<HydrogenComponentProps> | ((props: HydrogenComponentProps) => React$1.JSX.Element);
-    type: string;
-    schema?: HydrogenComponentSchema;
-    /** Optional data loader function for server-side data fetching */
-    loader?: (args: ComponentLoaderArgs) => Promise<unknown>;
-};
-interface WeaverseHydrogenParams extends Omit<WeaverseCoreParams, 'ItemConstructor'> {
-    data: HydrogenPageData;
-    dataContext?: Record<string, unknown> | null;
-    internal: Partial<WeaverseInternal>;
-    isDesignMode?: boolean;
-    isPreviewMode?: boolean;
-    isRevisionPreview?: boolean;
-    pageId: string;
-    projectId: string;
-    requestInfo: WeaverseLoaderRequestInfo;
-    sectionType?: string;
-    weaverseApiBase: string;
-    weaverseApiKey: string;
-    weaverseHost: string;
-    /**
-     * Public data API origin. Keep `weaverseHost` for Studio scripts/editor
-     * assets; point this at the Cloudflare proxy (`https://api.weaverse.io`)
-     * when edge caching is enabled.
-     */
-    weaversePublicApiBase?: string;
-    weaverseVersion?: string;
-}
-type HydrogenComponent<T extends HydrogenComponentProps = any> = {
-    default: ForwardRefExoticComponent<T> | ((props: T) => React$1.JSX.Element);
-    schema: HydrogenComponentSchema;
-    /** Optional data loader function for server-side data fetching */
-    loader?: (args: ComponentLoaderArgs) => Promise<unknown>;
-};
-type WeaverseStudioQueries = {
-    weaverseProjectId: string;
-    weaverseApiKey: string;
-    weaverseHost: string;
-    weaverseVersion: string;
-    isDesignMode: boolean;
-    isPreviewMode?: boolean;
-    sectionType?: string;
-};
-type PublicEnv = {
-    PUBLIC_STORE_DOMAIN: string;
-    PUBLIC_STOREFRONT_API_TOKEN: string;
-};
-type WeaverseProjectConfigs = {
-    projectId: string;
-    weaverseHost: string;
-    weaverseApiBase: string;
-    weaversePublicApiBase?: string;
-    weaverseApiKey: string;
-    weaverseVersion?: string;
-    isDesignMode?: boolean;
-    isPreviewMode?: boolean;
-    isRevisionPreview?: boolean;
-    sectionType?: string;
-    publicEnv?: PublicEnv;
-};
-type HydrogenPageAssignment = {
-    projectId: string;
-    type: PageType;
-    handle: string;
-    locale: string;
-    meta?: {
-        inherited: boolean;
-        sourceProjectId: string;
-        depth: number;
-    };
-};
-type WeaverseLoaderData = {
-    configs: Omit<WeaverseProjectConfigs, 'publicEnv'> & {
-        requestInfo: WeaverseLoaderRequestInfo;
-    };
-    page: HydrogenPageData;
-    project: HydrogenProjectType;
-    pageAssignment?: HydrogenPageAssignment;
-};
-interface HydrogenPageData extends WeaverseProjectDataType {
-    __cacheId?: string;
-    id: string;
-    items: HydrogenComponentData[];
-    name: string;
-    /**
-     * Page-level SEO metadata published by Weaverse Builder. `null` when
-     * the page has no `PageSeo` row; absent on revision snapshots that
-     * predate the SEO feature. Themes should treat both as "no Weaverse
-     * override".
-     */
-    seo?: PageSEOData | null;
-    [key: string]: any;
-}
-type WeaverseI18n = I18nBase & {
-    label?: string;
-    pathPrefix?: string;
-    [key: string]: any;
-};
-type HydrogenThemeSchema = {
-    info: {
-        name: string;
-        version: string;
-        author: string;
-        authorProfilePhoto: string;
-        documentationUrl: string;
-        supportUrl: string;
-    };
-    /** @deprecated Use settings instead */
-    inspector?: InspectorGroup[];
-    settings?: InspectorGroup[];
-    i18n?: {
-        urlStructure: 'url-path' | 'subdomain' | 'top-level-domain';
-        defaultLocale: WeaverseI18n;
-        shopLocales: WeaverseI18n[];
-        staticContent?: Record<string, unknown>;
-        /** Enable the translation UI in the builder. */
-        translation?: boolean;
-    };
-};
-type FetchProjectRequestBody = {
-    projectId: string;
-    url: string;
-    i18n?: WeaverseI18n;
-    params?: {
-        type?: PageType;
-        locale?: string;
-        handle?: string;
-    };
-    isDesignMode?: boolean;
-};
-type FetchProjectPayload = {
-    page?: HydrogenPageData;
-    project?: HydrogenProjectType;
-    pageAssignment?: HydrogenPageAssignment;
-    error?: string;
-    [key: string]: any;
-};
-/**
- * Project identifier value - can be static string or dynamic function.
- *
- * **Static String**: Direct project ID reference
- * ```ts
- * 'project-abc-123'
- * ```
- *
- * **Synchronous Function**: Returns project ID based on request context
- * ```ts
- * () => {
- *   const host = new URL(request.url).hostname
- *   return PROJECT_MAP[host] || 'default-project'
- * }
- * ```
- *
- * **Asynchronous Function**: Async project resolution (must be awaited before passing)
- * ```ts
- * async () => {
- *   return await database.getProjectId(userId)
- * }
- * ```
- */
-type ProjectIdValue = string | (() => string) | (() => Promise<string>);
-/**
- * Type guard for detecting function-based projectId.
- *
- * Used internally by WeaverseClient constructor to determine
- * if projectId needs evaluation or can be used directly.
- */
-declare function isProjectIdFunction(projectId: ProjectIdValue | undefined): projectId is (() => string) | (() => Promise<string>);
-/**
- * Extended WeaverseClient constructor arguments supporting multi-project architecture.
- *
- * @example Static project (existing pattern - backward compatible)
- * ```ts
- * const weaverse = new WeaverseClient({
- *   ...hydrogenContext,
- *   projectId: 'project-default-123'
- * })
- * ```
- *
- * @example Dynamic project selection (new capability)
- * ```ts
- * const weaverse = new WeaverseClient({
- *   ...hydrogenContext,
- *   projectId: () => {
- *     const origin = new URL(request.url).origin
- *     if (origin === 'https://mystore.se') return process.env.WEAVERSE_PROJECT_SWEDEN!
- *     if (origin === 'https://mystore.fr') return process.env.WEAVERSE_PROJECT_FRANCE!
- *     return process.env.WEAVERSE_PROJECT_ID!
- *   }
- * })
- * ```
- *
- * **Priority Chain** (highest to lowest):
- * 1. URL query parameter: `?weaverseProjectId=...` (design mode, preview mode)
- * 2. Function result (if function provided)
- * 3. Explicit string value (if string provided)
- * 4. Environment variable: `WEAVERSE_PROJECT_ID` (Hydrogen env or process.env)
- * 5. Empty string (triggers validation error in methods)
- *
- * **Function Requirements**:
- * - Must return non-empty string
- * - Can access request via closure for routing decisions
- * - Evaluated once per WeaverseClient instance (request-scoped)
- * - Async functions must be awaited before passing to constructor
- * - Should handle edge cases (missing headers, invalid domains, etc.)
- *
- * **Request Context Access**:
- * Functions access request via closure from constructor arguments.
- */
-type WeaverseClientArgs = HydrogenContext & {
-    /**
-     * React components registered with Weaverse CMS.
-     * Each component must have a schema defining its properties and settings.
-     */
-    components: HydrogenComponent[];
-    /**
-     * Theme schema defining global theme settings (colors, fonts, layouts).
-     * Used to generate default theme configuration and validate theme data.
-     */
-    themeSchema: HydrogenThemeSchema;
-    /**
-     * Incoming HTTP request object from React Router loader.
-     * Provides access to URL, headers, cookies for dynamic routing decisions.
-     */
-    request: Request;
-    /**
-     * Hydrogen cache instance for content caching.
-     *Supports multi-tenant caching with project-specific cache keys.
-     */
-    cache: Cache;
-    /**
-     * Project identifier for loading content from Weaverse CMS.
-     *
-     * **Value Types**:
-     * - Static string: 'project-123' (existing usage)
-     * - Synchronous function: () => determineProject(request)
-     * - Asynchronous function: async () => await getProject(request) (must be awaited)
-     *
-     * **Backward Compatibility**:
-     * - Optional parameter (defaults to environment variable)
-     * - Existing code without projectId continues to work unchanged
-     *
-     * **Cache Isolation**:
-     * ProjectId is included in cache keys to prevent cross-project content pollution.
-     * Each project's content is cached separately, ensuring multi-tenant isolation.
-     */
-    projectId?: ProjectIdValue;
-    /**
-     * Fetch timeout in milliseconds for API requests.
-     * Defaults to 10000ms (10 seconds) if not specified.
-     * Useful for adjusting based on network conditions or deployment environment.
-     *
-     * @default 10000
-     * @example
-     * ```typescript
-     * new WeaverseClient({
-     *   // ... other args
-     *   fetchTimeoutMs: 5000 // 5 second timeout
-     * })
-     * ```
-     */
-    fetchTimeoutMs?: number;
-};
-type WeaverseProduct = WeaverseResourcePickerData;
-type WeaverseCollection = WeaverseResourcePickerData;
-type WeaverseBlog = WeaverseResourcePickerData;
-type WeaverseArticle = WeaverseResourcePickerData;
-type WeaverseMetaObject = WeaverseResourcePickerData;
-/**
- * Response types for improved type safety
- */
-type WithCacheFetchResponse<T> = {
-    data: T;
-    response: Response;
-};
-type ThemeSettingsResponse = {
-    theme?: HydrogenThemeSettings;
-    schema?: HydrogenThemeSchema;
-    publicEnv?: PublicEnv;
-    /** Theme's default locale JSON from themeSchema.i18n.staticContent */
-    staticContent?: Record<string, unknown>;
-    /** Locale-specific merchant overrides from the API */
-    merchantOverrides?: Record<string, unknown>;
-    _error?: string;
-    _loadFailed?: boolean;
-};
-type DirectFetchResponse<T = unknown> = {
-    data?: T;
-    error?: string;
-};
-type CacheResponseValidator<T = unknown> = (response: WithCacheFetchResponse<T> | T) => boolean;
-declare class WeaverseError extends Error {
-    readonly code: string;
-    readonly statusCode?: number;
-    readonly context?: Record<string, unknown>;
-    constructor(message: string, code?: string, statusCode?: number, context?: Record<string, unknown>);
-}
-/**
- * Validation result type for project ID validation.
- * Returns validation status with optional error message.
- */
-type ProjectIdValidationResult = {
-    valid: boolean;
-    error?: string;
-};
-interface CustomPageEntry {
-    changeFrequency?: 'daily' | 'weekly' | 'monthly';
-    handle: string;
-    lastModified: string;
-    locale: string | null;
-    path: string;
-    priority?: number;
-}
-/**
- * Type guards for response validation
- */
-declare function isWithCacheFetchResponse<T>(response: unknown): response is WithCacheFetchResponse<T>;
-declare function isFetchProjectPayload(payload: unknown): payload is FetchProjectPayload;
-declare function hasError(response: unknown): response is {
-    error: string;
-};
-declare function isThemeSettingsResponse(data: unknown): data is ThemeSettingsResponse;
-/**
- * Enhanced type utilities for better development experience
- */
-type HydrogenSchemaValidationResult = SchemaValidationResult<HydrogenComponentSchema>;
-/**
- * Type guard to check if a schema is valid.
- * Leverages validation from @weaverse/schema package which provides
- * comprehensive Zod-based validation with the ElementSchema.
- *
- * @param schema - Unknown value to validate
- * @returns True if schema is a valid HydrogenComponentSchema
- *
- * @example
- * ```typescript
- * if (isValidHydrogenSchema(userInput)) {
- *   // userInput is now typed as HydrogenComponentSchema
- *   console.log(userInput.type)
- * }
- * ```
- */
-declare function isValidHydrogenSchema(schema: unknown): schema is HydrogenComponentSchema;
-/**
- * Type-safe helper to create component schemas with validation
- */
-type CreateHydrogenSchemaOptions = {
-    title: string;
-    type: string;
-    limit?: number;
-    settings?: InspectorGroup[];
-    childTypes?: string[];
-    enabledOn?: {
-        pages?: PageType[];
-        groups?: ('*' | 'header' | 'footer' | 'body')[];
-    };
-    enabled?: boolean | ((context: {
-        page: {
-            id: string;
-            type: PageType;
-            handle: string;
-            locale: string;
-        };
-        group: 'body' | 'header' | 'footer';
-    }) => boolean);
-    presets?: {
-        children?: ComponentPresets[];
-        [key: string]: any;
-    };
-};
-declare global {
-    interface Window {
-        __weaverse?: WeaverseHydrogen;
-        __weaverses?: Record<string, WeaverseHydrogen>;
-        __weaverseThemeSettingsStore?: ThemeSettingsStore;
-    }
-}
-interface WeaverseStudio {
-    init: (weaverse: WeaverseHydrogen) => void;
-    refreshStudio: (params: WeaverseHydrogenParams) => void;
-}
-declare function hasWeaverseStudio(window: Window): window is Window & {
-    weaverseStudio: WeaverseStudio;
-};
-declare module '@shopify/remix-oxygen' {
-    interface AppLoadContext {
-        weaverse: WeaverseClient;
-    }
-}
-declare module '@shopify/hydrogen' {
-    interface HydrogenEnv {
-        CUSTOM_COLLECTION_BANNER_METAFIELD: string;
-        JUDGEME_PRIVATE_API_TOKEN: string;
-        KLAVIYO_PRIVATE_API_TOKEN: string;
-        METAOBJECT_COLOR_NAME_KEY: string;
-        METAOBJECT_COLOR_VALUE_KEY: string;
-        METAOBJECT_COLORS_TYPE: string;
-        PUBLIC_GOOGLE_GTM_ID: string;
-        PUBLIC_SHOPIFY_INBOX_SHOP_ID: string;
-        PUBLIC_STORE_DOMAIN: string;
-        PUBLIC_STOREFRONT_API_TOKEN: string;
-        WEAVERSE_API_KEY: string;
-        WEAVERSE_HOST?: string;
-        WEAVERSE_PROJECT_ID: string;
-        WEAVERSE_PUBLIC_API_BASE?: string;
-    }
-}
-/**
- * Parameters for loadPage method supporting route-level project override.
- *
- * @example Basic usage (uses client-level project)
- * ```ts
- * const weaverseData = await weaverse.loadPage({
- *   type: 'PRODUCT',
- *   handle: params.productHandle
- * })
- * ```
- *
- * @example Route-level project override
- * ```ts
- * export async function loader({ params, context }: LoaderFunctionArgs) {
- *   const { weaverse } = context
- *
- *   // Use special campaign project for this route only
- *   const weaverseData = await weaverse.loadPage({
- *     type: 'PRODUCT',
- *     handle: params.productHandle,
- *     projectId: process.env.WEAVERSE_PROJECT_CAMPAIGN  // Override
- *   })
- *
- *   return { weaverseData }
- * }
- * ```
- */
-type LoadPageParams = {
-    /**
-     * Page type to load from Weaverse CMS.
-     *
-     * Determines which template to use for rendering the page.
-     * Falls back to 'INDEX' if not specified or if page type doesn't exist.
-     *
-     * @default 'INDEX'
-     */
-    type?: PageType;
-    /**
-     * Locale for internationalization.
-     *
-     * Format: IETF BCP 47 language tag (e.g., 'en-US', 'fr-FR', 'de-DE')
-     * Used to load locale-specific content and translations.
-     */
-    locale?: string;
-    /**
-     * Page handle for dynamic pages.
-     *
-     * Identifies specific resource within page type:
-     * - Product handle: 'red-sneakers'
-     * - Collection handle: 'summer-sale'
-     * - Page handle: 'about-us'
-     * - Article handle: 'how-to-style-sneakers'
-     */
-    handle?: string;
-    /**
-     * Cache strategy override for this specific page load.
-     *
-     * Overrides default cache strategy for special use cases:
-     * - Fresh content for checkout pages (no cache)
-     * - Long-lived cache for static pages (1 hour+)
-     * - Short-lived cache for frequently updated content (5 minutes)
-     */
-    strategy?: CachingStrategy;
-    /**
-     * Optional project override for this specific page load.
-     *
-     * **Precedence**: Route-level projectId takes precedence over client-level projectId.
-     *
-     * **Use Cases**:
-     * - Campaign landing pages with custom content
-     * - VIP customer experiences with dedicated projects
-     * - A/B testing specific pages without changing global config
-     * - Seasonal promotions with limited-time content
-     *
-     * **Validation**:
-     * - Must be non-empty string
-     * - Validated before API call
-     * - Falls back to client-level projectId if undefined
-     * - Does NOT support function (string only)
-     *
-     * **Cache Isolation**:
-     * Override projectId is included in cache key, ensuring separate caches
-     * for different projects even on the same route.
-     *
-     * @example Campaign page override
-     * ```ts
-     * const campaignData = await weaverse.loadPage({
-     *   type: 'PAGE',
-     *   handle: 'summer-sale',
-     *   projectId: process.env.WEAVERSE_PROJECT_CAMPAIGN
-     * })
-     * ```
-     */
-    projectId?: string;
-};
-/** A single translated field for one item */
-interface TranslationMapEntry {
-    originalValue: string;
-    translatedValue: string;
-}
-/** Per-item translation fields, keyed by field name */
-type TranslationItemEntry = {
-    [key: string]: TranslationMapEntry;
-};
-/**
- * Translation map sent from the builder alongside page data in design mode.
- * Keyed by item ID, each value maps field names to translation entries.
- */
-type TranslationMap = {
-    [itemId: string]: TranslationItemEntry;
-};
-/** A single translation entry for save payloads */
-interface TranslationEntry {
-    deleted?: boolean;
-    itemId: string;
-    key: string;
-    originalValue: string;
-    translatedValue: string;
-}
-/** Result of collecting translation changes for the save flow */
-type TranslationChanges = {
-    languageId: string;
-    entries: TranslationEntry[];
-};
-
-declare let defaultComponents: HydrogenComponent[];
-
-interface RouteKeyedDataContext {
-    root?: Record<string, unknown>;
-    [routeKey: `routes/${string}`]: Record<string, unknown>;
-}
-type WeaverseDataContext = RouteKeyedDataContext & Record<string, unknown>;
-/**
- * Hook to get flat route-keyed data context from matches
- * Returns: {root: {...}, "routes/xxx": {...}}
- * No more useLoaderData dependency - everything comes from matches
- */
-declare function useWeaverseDataContext(): WeaverseDataContext;
-/**
- * Helper function to create flat route-keyed data context from useMatches() result
- * Returns: {root: {...}, "routes/xxx": {...}}
- */
-declare function createWeaverseDataContext(matches: UIMatch<unknown, unknown>[]): WeaverseDataContext;
-
-/**
- * Convert a Weaverse page-level SEO payload into React Router
- * `MetaDescriptor[]`. Pure, synchronous, tree-shakeable — does not fetch.
- *
- * Behavior:
- * - `title` → top-level `{ title }` descriptor.
- * - `description` / `keywords` → `<meta name="...">`.
- * - `canonicalUrl` → `<link rel="canonical">`.
- * - `openGraph.*` → `<meta property="og:*">`. `og:type` defaults to
- *   `'website'` when any other OG field is present.
- * - `twitter.*` → `<meta name="twitter:*">`. `twitter:card` defaults to
- *   `'summary'` when any other Twitter field is present.
- * - `robots` is always emitted (defaults to `'index,follow'`) so themes
- *   stacking multiple SEO sources have a deterministic last word on
- *   indexing for Weaverse-managed pages.
- * - Empty strings / missing fields are filtered before return so empty
- *   descriptors don't override earlier sources (e.g. Hydrogen
- *   `getSeoMeta`).
- */
-declare function formatMetaDescriptors(seo: PageSEOData | null | undefined): MetaDescriptor[];
-/**
- * Convenience accessor: pull `page.seo` out of a `WeaverseLoaderData`
- * (or `HydrogenPageData`) and emit `MetaDescriptor[]`. Null-safe.
- *
- * @example
- * ```ts
- * export const meta: MetaFunction<typeof loader> = ({ data }) => {
- *   return getWeaverseSeoMeta(data?.weaverseData)
- * }
- * ```
- */
-declare function getWeaverseSeoMeta(data: WeaverseLoaderData | HydrogenPageData | {
-    page?: HydrogenPageData | null;
-} | null | undefined): MetaDescriptor[];
-
-/**
- * Extract and parse query parameters from a request URL.
- * Supports optional allowlist for security-sensitive applications.
- *
- * @param request - The incoming request
- * @param options - Optional configuration
- * @param options.allowedKeys - If provided, only these keys will be extracted
- * @returns Parsed query parameters with type coercion for booleans
- *
- * @example
- * ```typescript
- * // Extract all params
- * const queries = getRequestQueries(request)
- *
- * // Extract only allowed params (security-sensitive)
- * const queries = getRequestQueries(request, {
- *   allowedKeys: ['weaverseProjectId', 'weaverseHost']
- * })
- * ```
- */
-declare function getRequestQueries<T = Record<string, string | boolean>>(request: Request, options?: {
-    allowedKeys?: string[];
-}): T;
-declare function getWeaverseConfigs(request: Request, env: HydrogenEnv): WeaverseProjectConfigs;
-/**
- * Generate default data from component or theme schema.
- * Results are memoized using WeakMap for performance.
- *
- * @param schema - Component or theme schema
- * @returns Default data object extracted from schema inputs
- */
-declare function generateDataFromSchema(schema: HydrogenComponentSchema | HydrogenThemeSchema): Record<string, any>;
-declare function getPreviewData(type: string, components: HydrogenComponent[], weaverseHost: string): WeaverseLoaderData;
-
-/**
- * Filter out Weaverse-specific query parameters from product options.
- * Removes `isDesignMode` and any parameters starting with `weaverse` prefix.
- *
- * @param request - The incoming HTTP request
- * @returns Filtered product options for Shopify Hydrogen
- *
- * @example
- * ```typescript
- * export async function loader({ request }: LoaderFunctionArgs) {
- *   const selectedOptions = getSelectedProductOptions(request)
- *   // Use selectedOptions for product queries without Weaverse params
- * }
- * ```
- */
-declare function getSelectedProductOptions(request: Request): SelectedOptionInput[];
-declare const IMAGES_PLACEHOLDERS: {
-    logo_white: string;
-    logo_black: string;
-    image: string;
-    banner_1: string;
-    banner_2: string;
-    collection_1: string;
-    collection_2: string;
-    collection_3: string;
-    collection_4: string;
-    collection_5: string;
-    collection_6: string;
-    product_1: string;
-    product_2: string;
-    product_3: string;
-    product_4: string;
-    product_5: string;
-    product_6: string;
-    product_7: string;
-    product_8: string;
-    product_9: string;
-    product_10: string;
-    product_11: string;
-    product_12: string;
-    product_13: string;
-    product_14: string;
-    product_15: string;
-    product_16: string;
-    product_17: string;
-    product_18: string;
-};
-
-export { type CacheResponseValidator, type ComponentDataValue, type ComponentLoaderArgs, type CreateHydrogenSchemaOptions, type CustomPageEntry, type DirectFetchResponse, type FetchProjectPayload, type FetchProjectRequestBody, type HydrogenComponent, type HydrogenComponentData, type HydrogenComponentPresets, type HydrogenComponentProps, type HydrogenComponentSchema, type HydrogenElement, type HydrogenPageAssignment, type HydrogenPageData, type HydrogenProjectType, type HydrogenSchemaValidationResult, type HydrogenThemeSchema, type HydrogenThemeSettings, IMAGES_PLACEHOLDERS, type LoadPageParams, type ProjectIdValidationResult, type ProjectIdValue, type PublicEnv, type RouteLoaderArgs, type ThemeSettingsResponse, ThemeTextProvider, type ThemeTextProviderProps, ThemeTextStore, type ThemeTextValue, type TranslateFunction, type TranslationChanges, type TranslationEntry, type TranslationItemEntry, type TranslationMap, type TranslationMapEntry, TranslationProvider, type TranslationProviderProps, TranslationStore, type TranslationValue, type WeaverseArticle, type WeaverseBlog, WeaverseClient, type WeaverseClientArgs, type WeaverseCollection, type WeaverseDataContext, WeaverseError, WeaverseHydrogen, WeaverseHydrogenItem, type WeaverseHydrogenParams, WeaverseHydrogenRoot, type WeaverseI18n, type WeaverseInternal, type WeaverseLoaderData, type WeaverseLoaderRequestInfo, type WeaverseMetaObject, type WeaverseProduct, type WeaverseProjectConfigs, type WeaverseStudioQueries, type WithCacheFetchResponse, type WithWeaverseOptions, createWeaverseDataContext, defaultComponents, formatMetaDescriptors, generateDataFromSchema, getNestedKey, getPreviewData, getRequestQueries, getSelectedProductOptions, getWeaverseConfigs, getWeaverseSeoMeta, hasError, hasWeaverseStudio, interpolate, isFetchProjectPayload, isProjectIdFunction, isThemeSettingsResponse, isValidHydrogenSchema, isWithCacheFetchResponse, registerComponent, useThemeSettings, useThemeText, useTranslation, useWeaverseDataContext, withWeaverse };