@numueg/theme-sdk 0.5.2 → 0.6.0

package/dist/index.d.mts

@@ -1,10 +1,10 @@
 import { i as Store, e as Product, b as Collection, C as Cart, c as Customer, P as Page, S as SizeChart, g as ProductVariant } from './entities-6MGANln7.mjs';
 export { A as Address, a as CartItem, O as Order, d as OrderItem, f as ProductImage, j as ProductOption, h as SizeChartMode } from './entities-6MGANln7.mjs';
-import { T as ThemeSettingsV3, c as SectionInstance, M as MountResult, B as BlockInstance, b as BlockSchema, a as BlockProps$1, f as SectionSchema, e as SectionProps$1 } from './theme-D0QybTQS.mjs';
-export { E as ExternalThemeMetadata, h as MAX_BLOCK_DEPTH, P as PageTemplate, i as PresetBlock, S as SectionGroup, d as SectionPreset, g as SettingDefinition } from './theme-D0QybTQS.mjs';
+import { T as ThemeSettingsV3, c as SectionInstance, M as MountResult, B as BlockInstance, b as BlockSchema, a as BlockProps$1, f as SectionSchema, e as SectionProps$1 } from './theme-D8MOopvi.mjs';
+export { E as ExternalThemeMetadata, h as MAX_BLOCK_DEPTH, P as PageTemplate, i as PresetBlock, S as SectionGroup, d as SectionPreset, g as SettingDefinition } from './theme-D8MOopvi.mjs';
 export { KNOWN_SETTING_TYPES, KNOWN_TEMPLATES, REQUIRED_TEMPLATES, SDK_VERSION, THEME_CONTRACT_VERSION, ValidationIssue, ValidationResult, mergeResults, validateBuiltManifest, validateManifest, validateSectionSchema, validateSettingsAgainstSchema } from './validation.mjs';
-import { L as LocalizationState, T as ThemeMountContext, a as ThemeRenderArgs, M as MenuItemData } from './mount-DH9dz3dq.mjs';
-export { C as CartContext, b as CollectionContext, c as CustomerContext, d as LocalizationContext, N as NavigationContext, P as PageContext, e as ProductContext, S as ShopContext, f as ThemeMountPage, g as ThemeSettingsContext, h as buildThemeElement, m as mountTheme } from './mount-DH9dz3dq.mjs';
+import { L as LocalizationState, T as ThemeMountContext, a as ThemeRenderArgs, M as MenuItemData } from './mount-BGumg1JM.mjs';
+export { C as CartContext, b as CollectionContext, c as CustomerContext, d as LocalizationContext, N as NavigationContext, P as PageContext, e as ProductContext, S as ShopContext, f as ThemeMountPage, g as ThemeSettingsContext, h as buildThemeElement, m as mountTheme } from './mount-BGumg1JM.mjs';
 import * as react from 'react';
 import { ReactElement, ReactNode, ElementType, CSSProperties, ImgHTMLAttributes, AnchorHTMLAttributes, ButtonHTMLAttributes, HTMLAttributes, FormHTMLAttributes, ComponentType } from 'react';
 export { resolveThemeSettings } from './normalize.mjs';
@@ -1251,6 +1251,11 @@ interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "
      * "eager" for above-the-fold imagery.
      */
     loading?: "eager" | "lazy";
+    /**
+     * Above-the-fold? When true, forces loading="eager" + fetchPriority="high"
+     * (overrides `loading`). Use on the hero / LCP image. Default false.
+     */
+    priority?: boolean;
     /**
      * Shopify-style frame. When set (e.g. "3/4", "16/9", "1/1") the image is
      * wrapped in a fixed-aspect, overflow-hidden box and the `<img>` fills it.
@@ -1284,7 +1289,67 @@ interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "
  * If `src` is empty/null, renders a placeholder div so the layout
  * doesn't shift while a merchant configures images in the customizer.
  */
-declare function Image({ src, alt, sizes, responsive, loading, aspectRatio, objectFit, objectPosition, transform, className, style, ...rest }: ImageProps): react.JSX.Element;
+declare function Image({ src, alt, sizes, responsive, loading, priority, aspectRatio, objectFit, objectPosition, transform, className, style, ...rest }: ImageProps): react.JSX.Element;
+
+interface HeroMediaProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "srcSet" | "alt" | "style"> {
+    /** Desktop (primary) image URL. */
+    src: string | null | undefined;
+    alt: string;
+    /** Desktop focal/zoom/rotation (`asImageTransform(setting)`). */
+    transform?: ImageTransform | null;
+    /** Optional mobile art-direction image. When set → swaps below `breakpoint`. */
+    mobileSrc?: string | null;
+    /** Mobile focal/zoom/rotation. Falls back to the desktop transform's focal. */
+    mobileTransform?: ImageTransform | null;
+    /** Server-crop box aspect for desktop, e.g. "16/9". Match the theme container. */
+    desktopAspect?: string;
+    /** Server-crop box aspect for mobile, e.g. "4/5". */
+    mobileAspect?: string;
+    /** object-fit. Default "cover". Pass "contain" for letterboxed art. */
+    fit?: "cover" | "contain";
+    /** Above-the-fold? Default true → loading=eager + fetchPriority=high. */
+    priority?: boolean;
+    /** sizes attribute. Hero is full-width → default "100vw". */
+    sizes?: string;
+    /** Below this width (px) the mobile image is used. Default 768. */
+    breakpoint?: number;
+    /**
+     * Pre-fetch the alternate (off-breakpoint) image so a Desktop↔Mobile swap is an
+     * instant cache hit instead of a flash-and-fetch. Default true. Set false to save
+     * the one extra background request when smooth resizing isn't worth the bandwidth.
+     */
+    preloadAlternate?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * <HeroMedia> — above-the-fold hero image for V3 themes.
+ *
+ *  - Real responsive srcSet routed through /api/image-transform (resize + AVIF/WebP,
+ *    + focal smart-crop when Cloudflare Image Resizing is enabled).
+ *  - LCP perf defaults: loading=eager + fetchPriority=high (disable via priority={false}).
+ *  - Non-destructive focal/zoom/rotation framing via applyImageTransform.
+ *  - Optional MOBILE art-direction image: a different bitmap below `breakpoint`.
+ *
+ * ## Why matchMedia, not <picture><source media>
+ * Art direction is resolved in JS (a `matchMedia` listener) rather than a native
+ * `<picture><source media>`. A native `<picture>` does NOT reliably re-pick its source
+ * when an EMBEDDED preview resizes its iframe — exactly what the theme editor's
+ * Desktop/Mobile toggle does — so the hero would stay stuck on the desktop bitmap at
+ * mobile sizes. CSS media queries DO re-evaluate on that resize (Tailwind flips the
+ * container to portrait), and `matchMedia` shares that engine, so the swap is
+ * deterministic. The state initialises from `matchMedia` so the first client paint is
+ * already correct (V3 themes mount client-side) — no desktop→mobile flash on phones.
+ *
+ * ## Smooth swap
+ * The off-breakpoint image is pre-warmed (low priority, after paint) so toggling the
+ * breakpoint — the editor switch, or a window resize — paints from cache instantly
+ * instead of fetching on demand. See `preloadAlternate`.
+ *
+ * When `mobileSrc` is omitted this is a single responsive <img> filling its parent —
+ * the theme keeps its own wrapper/sizing, identical to a raw <img> plus srcSet + perf.
+ */
+declare function HeroMedia({ src, alt, transform, mobileSrc, mobileTransform, desktopAspect, mobileAspect, fit, priority, sizes, breakpoint, preloadAlternate, className, style, ...rest }: HeroMediaProps): react.JSX.Element;
 
 interface LogoProps {
     /** Explicit logo URL; falls back to global_settings.logo_url then shop.logo_url. */
@@ -2202,4 +2267,4 @@ declare function pickTranslations(bundle: LocaleBundle, locale: string): LocaleM
  */
 declare function buildLocaleBundle<T extends Record<string, unknown>>(modules: T): LocaleBundle;
 
-export { AddToCartButton, type AddressInput, type AnalyticsApi, type AnalyticsPayload, type AppManifestBlock, type AppPayload, type AppState, Block, BlockInstance, BlockProps$1 as BlockProps, BlockSchema, Cart, type CheckoutAddress, type CheckoutApi, type CheckoutSessionState, type CheckoutStep, Collection, CollectionCard, type CollectionCardProps, type CollectionCardSlots, CollectionProvider, type ComputedStyleTokens, type CurrencyConfig, type CurrencyState, CurrencySwitcher, type CurrencySwitcherProps, Customer, type CustomerAddress, type CustomerAddressesState, type DefineBlockInput, type DefineSectionInput, type DefinedBlock, type DefinedSection, type DynamicResolveContext, type DynamicSourceRef, EditableImage, type EditableImageProps, EditableText, type EditableTextProps, type FocalSrcOptions, Form, type GiftCardBalance, ICON_NAMES, Icon, IconMap, type IconProps, Image, type ImageTransform, LOGO_SHAPE_OPTIONS, LOGO_SIZE_OPTIONS, Link, type LocaleBundle, type LocaleMessages, LocaleSwitcher, type LocaleSwitcherProps, Logo, type LogoProps, type LogoShape, type LogoSize, MenuItemData, Money, MountResult, type NavigationItem, type NavigationState, NuMuProvider, type OrderDetail, type OrderListEntry, type OrderListState, type OrderState, Page, type PlaceOrderResult, Product, ProductCard, type ProductCardProps, type ProductCardSlots, ProductProvider, ProductVariant, type RelatedProductsState, type ReorderResult, type ReorderSkipReason, type ReorderSkippedItem, RichText, type RichTextProps, type SearchResults, type SearchState, Section, SectionContext, SectionInstance, SectionProps$1 as SectionProps, SectionSchema, type ShippingRateOption, type ShopWithHelpers, SizeChart, Store, type ThemeEntry, ThemeMountContext, ThemeRenderArgs, ThemeSettingsV3, type UseGiftCardBalance, type UseReorder, type UseSearchOptions, type UseShippingRatesOptions, type UseShippingRatesState, type UseVariantSelection, type WishlistItem, type WishlistState, applyGlobalStyleTokens, applyImageTransform, asImageTransform, assetUrl, availableValues, buildLocaleBundle, clearSdkSingleton, collectBlocks, collectSections, computeGlobalStyleTokens, defaultVariant, defineBlock, defineSection, defineThemeEntry, dynamicSource, findVariantByOptions, flattenMessages, focalSrc, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isDynamicSource, isSdkAvailable, logoImgStyle, logoStyleTokens, pickTranslations, registerReactSingleton, registerSdkSingleton, resolveDynamicValue, resolveFontStack, resolveSettingsMap, resolveSizeChart, resolveSourcePath, sanitizeHtml, useAnalytics, useApp, useCart, useCheckout, useCollection, useCollectionOptional, useCollections, useCurrency, useCurrentTemplate, useCustomer, useCustomerActions, useCustomerAddresses, useDirection, useFieldTranslation, useGiftCardBalance, useImage, useLocale, useLocalization, useMoney, useNavigation, useNumberFormat, useOrder, useOrders, usePage, useProduct, useProductOptional, useProductSizeChart, useProducts, useRelatedProducts, useReorder, useResolvedSettings, useSearch, useSection, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist };
+export { AddToCartButton, type AddressInput, type AnalyticsApi, type AnalyticsPayload, type AppManifestBlock, type AppPayload, type AppState, Block, BlockInstance, BlockProps$1 as BlockProps, BlockSchema, Cart, type CheckoutAddress, type CheckoutApi, type CheckoutSessionState, type CheckoutStep, Collection, CollectionCard, type CollectionCardProps, type CollectionCardSlots, CollectionProvider, type ComputedStyleTokens, type CurrencyConfig, type CurrencyState, CurrencySwitcher, type CurrencySwitcherProps, Customer, type CustomerAddress, type CustomerAddressesState, type DefineBlockInput, type DefineSectionInput, type DefinedBlock, type DefinedSection, type DynamicResolveContext, type DynamicSourceRef, EditableImage, type EditableImageProps, EditableText, type EditableTextProps, type FocalSrcOptions, Form, type GiftCardBalance, HeroMedia, type HeroMediaProps, ICON_NAMES, Icon, IconMap, type IconProps, Image, type ImageTransform, LOGO_SHAPE_OPTIONS, LOGO_SIZE_OPTIONS, Link, type LocaleBundle, type LocaleMessages, LocaleSwitcher, type LocaleSwitcherProps, Logo, type LogoProps, type LogoShape, type LogoSize, MenuItemData, Money, MountResult, type NavigationItem, type NavigationState, NuMuProvider, type OrderDetail, type OrderListEntry, type OrderListState, type OrderState, Page, type PlaceOrderResult, Product, ProductCard, type ProductCardProps, type ProductCardSlots, ProductProvider, ProductVariant, type RelatedProductsState, type ReorderResult, type ReorderSkipReason, type ReorderSkippedItem, RichText, type RichTextProps, type SearchResults, type SearchState, Section, SectionContext, SectionInstance, SectionProps$1 as SectionProps, SectionSchema, type ShippingRateOption, type ShopWithHelpers, SizeChart, Store, type ThemeEntry, ThemeMountContext, ThemeRenderArgs, ThemeSettingsV3, type UseGiftCardBalance, type UseReorder, type UseSearchOptions, type UseShippingRatesOptions, type UseShippingRatesState, type UseVariantSelection, type WishlistItem, type WishlistState, applyGlobalStyleTokens, applyImageTransform, asImageTransform, assetUrl, availableValues, buildLocaleBundle, clearSdkSingleton, collectBlocks, collectSections, computeGlobalStyleTokens, defaultVariant, defineBlock, defineSection, defineThemeEntry, dynamicSource, findVariantByOptions, flattenMessages, focalSrc, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isDynamicSource, isSdkAvailable, logoImgStyle, logoStyleTokens, pickTranslations, registerReactSingleton, registerSdkSingleton, resolveDynamicValue, resolveFontStack, resolveSettingsMap, resolveSizeChart, resolveSourcePath, sanitizeHtml, useAnalytics, useApp, useCart, useCheckout, useCollection, useCollectionOptional, useCollections, useCurrency, useCurrentTemplate, useCustomer, useCustomerActions, useCustomerAddresses, useDirection, useFieldTranslation, useGiftCardBalance, useImage, useLocale, useLocalization, useMoney, useNavigation, useNumberFormat, useOrder, useOrders, usePage, useProduct, useProductOptional, useProductSizeChart, useProducts, useRelatedProducts, useReorder, useResolvedSettings, useSearch, useSection, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist };

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import { i as Store, e as Product, b as Collection, C as Cart, c as Customer, P as Page, S as SizeChart, g as ProductVariant } from './entities-6MGANln7.js';
 export { A as Address, a as CartItem, O as Order, d as OrderItem, f as ProductImage, j as ProductOption, h as SizeChartMode } from './entities-6MGANln7.js';
-import { T as ThemeSettingsV3, c as SectionInstance, M as MountResult, B as BlockInstance, b as BlockSchema, a as BlockProps$1, f as SectionSchema, e as SectionProps$1 } from './theme-D0QybTQS.js';
-export { E as ExternalThemeMetadata, h as MAX_BLOCK_DEPTH, P as PageTemplate, i as PresetBlock, S as SectionGroup, d as SectionPreset, g as SettingDefinition } from './theme-D0QybTQS.js';
+import { T as ThemeSettingsV3, c as SectionInstance, M as MountResult, B as BlockInstance, b as BlockSchema, a as BlockProps$1, f as SectionSchema, e as SectionProps$1 } from './theme-D8MOopvi.js';
+export { E as ExternalThemeMetadata, h as MAX_BLOCK_DEPTH, P as PageTemplate, i as PresetBlock, S as SectionGroup, d as SectionPreset, g as SettingDefinition } from './theme-D8MOopvi.js';
 export { KNOWN_SETTING_TYPES, KNOWN_TEMPLATES, REQUIRED_TEMPLATES, SDK_VERSION, THEME_CONTRACT_VERSION, ValidationIssue, ValidationResult, mergeResults, validateBuiltManifest, validateManifest, validateSectionSchema, validateSettingsAgainstSchema } from './validation.js';
-import { L as LocalizationState, T as ThemeMountContext, a as ThemeRenderArgs, M as MenuItemData } from './mount-BN2mz_wx.js';
-export { C as CartContext, b as CollectionContext, c as CustomerContext, d as LocalizationContext, N as NavigationContext, P as PageContext, e as ProductContext, S as ShopContext, f as ThemeMountPage, g as ThemeSettingsContext, h as buildThemeElement, m as mountTheme } from './mount-BN2mz_wx.js';
+import { L as LocalizationState, T as ThemeMountContext, a as ThemeRenderArgs, M as MenuItemData } from './mount-Bt-4ken5.js';
+export { C as CartContext, b as CollectionContext, c as CustomerContext, d as LocalizationContext, N as NavigationContext, P as PageContext, e as ProductContext, S as ShopContext, f as ThemeMountPage, g as ThemeSettingsContext, h as buildThemeElement, m as mountTheme } from './mount-Bt-4ken5.js';
 import * as react from 'react';
 import { ReactElement, ReactNode, ElementType, CSSProperties, ImgHTMLAttributes, AnchorHTMLAttributes, ButtonHTMLAttributes, HTMLAttributes, FormHTMLAttributes, ComponentType } from 'react';
 export { resolveThemeSettings } from './normalize.js';
@@ -1251,6 +1251,11 @@ interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "
      * "eager" for above-the-fold imagery.
      */
     loading?: "eager" | "lazy";
+    /**
+     * Above-the-fold? When true, forces loading="eager" + fetchPriority="high"
+     * (overrides `loading`). Use on the hero / LCP image. Default false.
+     */
+    priority?: boolean;
     /**
      * Shopify-style frame. When set (e.g. "3/4", "16/9", "1/1") the image is
      * wrapped in a fixed-aspect, overflow-hidden box and the `<img>` fills it.
@@ -1284,7 +1289,67 @@ interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "
  * If `src` is empty/null, renders a placeholder div so the layout
  * doesn't shift while a merchant configures images in the customizer.
  */
-declare function Image({ src, alt, sizes, responsive, loading, aspectRatio, objectFit, objectPosition, transform, className, style, ...rest }: ImageProps): react.JSX.Element;
+declare function Image({ src, alt, sizes, responsive, loading, priority, aspectRatio, objectFit, objectPosition, transform, className, style, ...rest }: ImageProps): react.JSX.Element;
+
+interface HeroMediaProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "srcSet" | "alt" | "style"> {
+    /** Desktop (primary) image URL. */
+    src: string | null | undefined;
+    alt: string;
+    /** Desktop focal/zoom/rotation (`asImageTransform(setting)`). */
+    transform?: ImageTransform | null;
+    /** Optional mobile art-direction image. When set → swaps below `breakpoint`. */
+    mobileSrc?: string | null;
+    /** Mobile focal/zoom/rotation. Falls back to the desktop transform's focal. */
+    mobileTransform?: ImageTransform | null;
+    /** Server-crop box aspect for desktop, e.g. "16/9". Match the theme container. */
+    desktopAspect?: string;
+    /** Server-crop box aspect for mobile, e.g. "4/5". */
+    mobileAspect?: string;
+    /** object-fit. Default "cover". Pass "contain" for letterboxed art. */
+    fit?: "cover" | "contain";
+    /** Above-the-fold? Default true → loading=eager + fetchPriority=high. */
+    priority?: boolean;
+    /** sizes attribute. Hero is full-width → default "100vw". */
+    sizes?: string;
+    /** Below this width (px) the mobile image is used. Default 768. */
+    breakpoint?: number;
+    /**
+     * Pre-fetch the alternate (off-breakpoint) image so a Desktop↔Mobile swap is an
+     * instant cache hit instead of a flash-and-fetch. Default true. Set false to save
+     * the one extra background request when smooth resizing isn't worth the bandwidth.
+     */
+    preloadAlternate?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * <HeroMedia> — above-the-fold hero image for V3 themes.
+ *
+ *  - Real responsive srcSet routed through /api/image-transform (resize + AVIF/WebP,
+ *    + focal smart-crop when Cloudflare Image Resizing is enabled).
+ *  - LCP perf defaults: loading=eager + fetchPriority=high (disable via priority={false}).
+ *  - Non-destructive focal/zoom/rotation framing via applyImageTransform.
+ *  - Optional MOBILE art-direction image: a different bitmap below `breakpoint`.
+ *
+ * ## Why matchMedia, not <picture><source media>
+ * Art direction is resolved in JS (a `matchMedia` listener) rather than a native
+ * `<picture><source media>`. A native `<picture>` does NOT reliably re-pick its source
+ * when an EMBEDDED preview resizes its iframe — exactly what the theme editor's
+ * Desktop/Mobile toggle does — so the hero would stay stuck on the desktop bitmap at
+ * mobile sizes. CSS media queries DO re-evaluate on that resize (Tailwind flips the
+ * container to portrait), and `matchMedia` shares that engine, so the swap is
+ * deterministic. The state initialises from `matchMedia` so the first client paint is
+ * already correct (V3 themes mount client-side) — no desktop→mobile flash on phones.
+ *
+ * ## Smooth swap
+ * The off-breakpoint image is pre-warmed (low priority, after paint) so toggling the
+ * breakpoint — the editor switch, or a window resize — paints from cache instantly
+ * instead of fetching on demand. See `preloadAlternate`.
+ *
+ * When `mobileSrc` is omitted this is a single responsive <img> filling its parent —
+ * the theme keeps its own wrapper/sizing, identical to a raw <img> plus srcSet + perf.
+ */
+declare function HeroMedia({ src, alt, transform, mobileSrc, mobileTransform, desktopAspect, mobileAspect, fit, priority, sizes, breakpoint, preloadAlternate, className, style, ...rest }: HeroMediaProps): react.JSX.Element;
 
 interface LogoProps {
     /** Explicit logo URL; falls back to global_settings.logo_url then shop.logo_url. */
@@ -2202,4 +2267,4 @@ declare function pickTranslations(bundle: LocaleBundle, locale: string): LocaleM
  */
 declare function buildLocaleBundle<T extends Record<string, unknown>>(modules: T): LocaleBundle;
 
-export { AddToCartButton, type AddressInput, type AnalyticsApi, type AnalyticsPayload, type AppManifestBlock, type AppPayload, type AppState, Block, BlockInstance, BlockProps$1 as BlockProps, BlockSchema, Cart, type CheckoutAddress, type CheckoutApi, type CheckoutSessionState, type CheckoutStep, Collection, CollectionCard, type CollectionCardProps, type CollectionCardSlots, CollectionProvider, type ComputedStyleTokens, type CurrencyConfig, type CurrencyState, CurrencySwitcher, type CurrencySwitcherProps, Customer, type CustomerAddress, type CustomerAddressesState, type DefineBlockInput, type DefineSectionInput, type DefinedBlock, type DefinedSection, type DynamicResolveContext, type DynamicSourceRef, EditableImage, type EditableImageProps, EditableText, type EditableTextProps, type FocalSrcOptions, Form, type GiftCardBalance, ICON_NAMES, Icon, IconMap, type IconProps, Image, type ImageTransform, LOGO_SHAPE_OPTIONS, LOGO_SIZE_OPTIONS, Link, type LocaleBundle, type LocaleMessages, LocaleSwitcher, type LocaleSwitcherProps, Logo, type LogoProps, type LogoShape, type LogoSize, MenuItemData, Money, MountResult, type NavigationItem, type NavigationState, NuMuProvider, type OrderDetail, type OrderListEntry, type OrderListState, type OrderState, Page, type PlaceOrderResult, Product, ProductCard, type ProductCardProps, type ProductCardSlots, ProductProvider, ProductVariant, type RelatedProductsState, type ReorderResult, type ReorderSkipReason, type ReorderSkippedItem, RichText, type RichTextProps, type SearchResults, type SearchState, Section, SectionContext, SectionInstance, SectionProps$1 as SectionProps, SectionSchema, type ShippingRateOption, type ShopWithHelpers, SizeChart, Store, type ThemeEntry, ThemeMountContext, ThemeRenderArgs, ThemeSettingsV3, type UseGiftCardBalance, type UseReorder, type UseSearchOptions, type UseShippingRatesOptions, type UseShippingRatesState, type UseVariantSelection, type WishlistItem, type WishlistState, applyGlobalStyleTokens, applyImageTransform, asImageTransform, assetUrl, availableValues, buildLocaleBundle, clearSdkSingleton, collectBlocks, collectSections, computeGlobalStyleTokens, defaultVariant, defineBlock, defineSection, defineThemeEntry, dynamicSource, findVariantByOptions, flattenMessages, focalSrc, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isDynamicSource, isSdkAvailable, logoImgStyle, logoStyleTokens, pickTranslations, registerReactSingleton, registerSdkSingleton, resolveDynamicValue, resolveFontStack, resolveSettingsMap, resolveSizeChart, resolveSourcePath, sanitizeHtml, useAnalytics, useApp, useCart, useCheckout, useCollection, useCollectionOptional, useCollections, useCurrency, useCurrentTemplate, useCustomer, useCustomerActions, useCustomerAddresses, useDirection, useFieldTranslation, useGiftCardBalance, useImage, useLocale, useLocalization, useMoney, useNavigation, useNumberFormat, useOrder, useOrders, usePage, useProduct, useProductOptional, useProductSizeChart, useProducts, useRelatedProducts, useReorder, useResolvedSettings, useSearch, useSection, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist };
+export { AddToCartButton, type AddressInput, type AnalyticsApi, type AnalyticsPayload, type AppManifestBlock, type AppPayload, type AppState, Block, BlockInstance, BlockProps$1 as BlockProps, BlockSchema, Cart, type CheckoutAddress, type CheckoutApi, type CheckoutSessionState, type CheckoutStep, Collection, CollectionCard, type CollectionCardProps, type CollectionCardSlots, CollectionProvider, type ComputedStyleTokens, type CurrencyConfig, type CurrencyState, CurrencySwitcher, type CurrencySwitcherProps, Customer, type CustomerAddress, type CustomerAddressesState, type DefineBlockInput, type DefineSectionInput, type DefinedBlock, type DefinedSection, type DynamicResolveContext, type DynamicSourceRef, EditableImage, type EditableImageProps, EditableText, type EditableTextProps, type FocalSrcOptions, Form, type GiftCardBalance, HeroMedia, type HeroMediaProps, ICON_NAMES, Icon, IconMap, type IconProps, Image, type ImageTransform, LOGO_SHAPE_OPTIONS, LOGO_SIZE_OPTIONS, Link, type LocaleBundle, type LocaleMessages, LocaleSwitcher, type LocaleSwitcherProps, Logo, type LogoProps, type LogoShape, type LogoSize, MenuItemData, Money, MountResult, type NavigationItem, type NavigationState, NuMuProvider, type OrderDetail, type OrderListEntry, type OrderListState, type OrderState, Page, type PlaceOrderResult, Product, ProductCard, type ProductCardProps, type ProductCardSlots, ProductProvider, ProductVariant, type RelatedProductsState, type ReorderResult, type ReorderSkipReason, type ReorderSkippedItem, RichText, type RichTextProps, type SearchResults, type SearchState, Section, SectionContext, SectionInstance, SectionProps$1 as SectionProps, SectionSchema, type ShippingRateOption, type ShopWithHelpers, SizeChart, Store, type ThemeEntry, ThemeMountContext, ThemeRenderArgs, ThemeSettingsV3, type UseGiftCardBalance, type UseReorder, type UseSearchOptions, type UseShippingRatesOptions, type UseShippingRatesState, type UseVariantSelection, type WishlistItem, type WishlistState, applyGlobalStyleTokens, applyImageTransform, asImageTransform, assetUrl, availableValues, buildLocaleBundle, clearSdkSingleton, collectBlocks, collectSections, computeGlobalStyleTokens, defaultVariant, defineBlock, defineSection, defineThemeEntry, dynamicSource, findVariantByOptions, flattenMessages, focalSrc, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isDynamicSource, isSdkAvailable, logoImgStyle, logoStyleTokens, pickTranslations, registerReactSingleton, registerSdkSingleton, resolveDynamicValue, resolveFontStack, resolveSettingsMap, resolveSizeChart, resolveSourcePath, sanitizeHtml, useAnalytics, useApp, useCart, useCheckout, useCollection, useCollectionOptional, useCollections, useCurrency, useCurrentTemplate, useCustomer, useCustomerActions, useCustomerAddresses, useDirection, useFieldTranslation, useGiftCardBalance, useImage, useLocale, useLocalization, useMoney, useNavigation, useNumberFormat, useOrder, useOrders, usePage, useProduct, useProductOptional, useProductSizeChart, useProducts, useRelatedProducts, useReorder, useResolvedSettings, useSearch, useSection, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist };

package/dist/index.mjs

@@ -7,7 +7,7 @@ var MAX_BLOCK_DEPTH = 5;
 
 // src/validation/index.ts
 var THEME_CONTRACT_VERSION = 1;
-var SDK_VERSION = "0.5.2" ;
+var SDK_VERSION = "0.6.0" ;
 var REQUIRED_TEMPLATES = [
   "home",
   "product",
@@ -2740,6 +2740,7 @@ function Image({
   sizes = "(min-width: 1024px) 25vw, (min-width: 640px) 50vw, 100vw",
   responsive = true,
   loading = "lazy",
+  priority = false,
   aspectRatio,
   objectFit,
   objectPosition,
@@ -2776,6 +2777,7 @@ function Image({
     );
   }
   const srcSet = responsive ? buildSrcSet(src) : void 0;
+  const effLoading = priority ? "eager" : loading;
   const effFit = objectFit ?? (framed ? "cover" : void 0);
   const fitStyle = transform ? applyImageTransform(transform, effFit === "contain" ? "contain" : "cover") : {
     ...effFit ? { objectFit: effFit } : {},
@@ -2788,7 +2790,8 @@ function Image({
       alt,
       srcSet: srcSet || void 0,
       sizes: srcSet ? sizes : void 0,
-      loading,
+      loading: effLoading,
+      fetchPriority: priority ? "high" : void 0,
       decoding: "async",
       className: framed ? void 0 : className,
       style: framed ? { width: "100%", height: "100%", display: "block", ...fitStyle } : { ...fitStyle, ...style },
@@ -2812,6 +2815,111 @@ function Image({
     }
   );
 }
+var HERO_WIDTHS = [640, 768, 1024, 1280, 1920];
+var DEFAULT_BREAKPOINT = 768;
+var DESKTOP_BASE_WIDTH = 1920;
+var MOBILE_BASE_WIDTH = 1280;
+function heroSrcSet(url, opts) {
+  return HERO_WIDTHS.map((w) => `${focalSrc(url, { width: w, ...opts })} ${w}w`).join(", ");
+}
+function HeroMedia({
+  src,
+  alt,
+  transform,
+  mobileSrc,
+  mobileTransform,
+  desktopAspect,
+  mobileAspect,
+  fit = "cover",
+  priority = true,
+  sizes = "100vw",
+  breakpoint = DEFAULT_BREAKPOINT,
+  preloadAlternate = true,
+  className,
+  style,
+  ...rest
+}) {
+  const hasMobile = !!mobileSrc;
+  const mobileQuery = `(max-width: ${breakpoint - 1}px)`;
+  const [isMobile, setIsMobile] = useState(
+    () => hasMobile && typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia(mobileQuery).matches
+  );
+  const [rawFallback, setRawFallback] = useState(false);
+  const { onError: themeOnError, ...imgRest } = rest;
+  const handleError = (e) => {
+    if (!rawFallback) setRawFallback(true);
+    else themeOnError?.(e);
+  };
+  useEffect(() => {
+    if (!hasMobile || typeof window === "undefined" || typeof window.matchMedia !== "function") {
+      return;
+    }
+    const mq = window.matchMedia(mobileQuery);
+    const sync = () => setIsMobile(mq.matches);
+    sync();
+    mq.addEventListener?.("change", sync);
+    return () => mq.removeEventListener?.("change", sync);
+  }, [hasMobile, mobileQuery]);
+  const desktopFocal = transform?.focal;
+  const mobileFocal = mobileTransform?.focal ?? desktopFocal;
+  const desktopCrop = desktopAspect ? { focal: desktopFocal, aspect: desktopAspect, fit } : {};
+  const mobileCrop = {
+    focal: mobileFocal,
+    aspect: mobileAspect,
+    fit
+  };
+  useEffect(() => {
+    if (!preloadAlternate || !hasMobile || !src || !mobileSrc) return;
+    if (typeof window === "undefined" || typeof window.Image !== "function") return;
+    const altUrl = isMobile ? rawFallback ? src : focalSrc(src, { width: DESKTOP_BASE_WIDTH, ...desktopCrop }) : rawFallback ? mobileSrc : focalSrc(mobileSrc, { width: MOBILE_BASE_WIDTH, ...mobileCrop });
+    if (!altUrl) return;
+    const im = new window.Image();
+    im.onerror = () => {
+    };
+    try {
+      im.fetchPriority = "low";
+    } catch {
+    }
+    im.decoding = "async";
+    im.src = altUrl;
+    if (typeof im.decode === "function") im.decode().catch(() => {
+    });
+  }, [preloadAlternate, hasMobile, src, mobileSrc, isMobile, rawFallback]);
+  if (!src) {
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        className,
+        role: "img",
+        "aria-label": alt,
+        style: { width: "100%", height: "100%", backgroundColor: "rgba(0,0,0,0.05)", ...style }
+      }
+    );
+  }
+  const useMobile = hasMobile && isMobile;
+  const activeUrl = useMobile ? mobileSrc : src;
+  const activeCrop = useMobile ? mobileCrop : desktopCrop;
+  const activeBase = useMobile ? MOBILE_BASE_WIDTH : DESKTOP_BASE_WIDTH;
+  const activeSrc = rawFallback ? activeUrl : focalSrc(activeUrl, { width: activeBase, ...activeCrop });
+  const activeSrcSet = rawFallback ? void 0 : heroSrcSet(activeUrl, activeCrop);
+  const fitStyle = applyImageTransform(useMobile ? mobileTransform ?? transform : transform, fit);
+  return /* @__PURE__ */ jsx(
+    "img",
+    {
+      src: activeSrc,
+      srcSet: activeSrcSet,
+      sizes: activeSrcSet ? sizes : void 0,
+      alt,
+      loading: priority ? "eager" : "lazy",
+      fetchPriority: priority ? "high" : void 0,
+      decoding: "async",
+      onError: handleError,
+      className,
+      style: { width: "100%", height: "100%", display: "block", ...fitStyle, ...style },
+      ...imgRest
+    }
+  );
+}
 var str = (v) => typeof v === "string" ? v : "";
 var NONE_HEIGHT = { small: 28, medium: 36, large: 48 };
 function Logo({
@@ -4059,6 +4167,6 @@ function buildLocaleBundle(modules) {
   return bundle;
 }
 
-export { AddToCartButton, Block, CartContext, CollectionCard, CollectionContext, CollectionProvider, CurrencySwitcher, CustomerContext, EditableImage, EditableText, Form, ICON_NAMES, Icon, IconMap, Image, KNOWN_SETTING_TYPES, KNOWN_TEMPLATES, LOGO_SHAPE_OPTIONS, LOGO_SIZE_OPTIONS, Link, LocaleSwitcher, LocalizationContext, Logo, MAX_BLOCK_DEPTH, Money, NavigationContext, NuMuProvider, PageContext, ProductCard, ProductContext, ProductProvider, REQUIRED_TEMPLATES, RichText, SDK_VERSION, Section, SectionContext, ShopContext, THEME_CONTRACT_VERSION, ThemeSettingsContext, applyGlobalStyleTokens, applyImageTransform, asImageTransform, assetUrl, availableValues, buildLocaleBundle, buildThemeElement, clearSdkSingleton, collectBlocks, collectSections, computeGlobalStyleTokens, defaultVariant, defineBlock, defineSection, defineThemeEntry, dynamicSource, findVariantByOptions, flattenMessages, focalSrc, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isDynamicSource, isSdkAvailable, logoImgStyle, logoStyleTokens, mergeResults, mountTheme, pickTranslations, registerReactSingleton, registerSdkSingleton, resolveDynamicValue, resolveFontStack, resolveSettingsMap, resolveSizeChart, resolveSourcePath, resolveThemeSettings, sanitizeHtml, useAnalytics, useApp, useCart, useCheckout, useCollection, useCollectionOptional, useCollections, useCurrency, useCurrentTemplate, useCustomer, useCustomerActions, useCustomerAddresses, useDirection, useFieldTranslation, useGiftCardBalance, useImage, useLocale, useLocalization, useMoney, useNavigation, useNumberFormat, useOrder, useOrders, usePage, useProduct, useProductOptional, useProductSizeChart, useProducts, useRelatedProducts, useReorder, useResolvedSettings, useSearch, useSection, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist, validateBuiltManifest, validateManifest, validateSectionSchema, validateSettingsAgainstSchema };
+export { AddToCartButton, Block, CartContext, CollectionCard, CollectionContext, CollectionProvider, CurrencySwitcher, CustomerContext, EditableImage, EditableText, Form, HeroMedia, ICON_NAMES, Icon, IconMap, Image, KNOWN_SETTING_TYPES, KNOWN_TEMPLATES, LOGO_SHAPE_OPTIONS, LOGO_SIZE_OPTIONS, Link, LocaleSwitcher, LocalizationContext, Logo, MAX_BLOCK_DEPTH, Money, NavigationContext, NuMuProvider, PageContext, ProductCard, ProductContext, ProductProvider, REQUIRED_TEMPLATES, RichText, SDK_VERSION, Section, SectionContext, ShopContext, THEME_CONTRACT_VERSION, ThemeSettingsContext, applyGlobalStyleTokens, applyImageTransform, asImageTransform, assetUrl, availableValues, buildLocaleBundle, buildThemeElement, clearSdkSingleton, collectBlocks, collectSections, computeGlobalStyleTokens, defaultVariant, defineBlock, defineSection, defineThemeEntry, dynamicSource, findVariantByOptions, flattenMessages, focalSrc, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isDynamicSource, isSdkAvailable, logoImgStyle, logoStyleTokens, mergeResults, mountTheme, pickTranslations, registerReactSingleton, registerSdkSingleton, resolveDynamicValue, resolveFontStack, resolveSettingsMap, resolveSizeChart, resolveSourcePath, resolveThemeSettings, sanitizeHtml, useAnalytics, useApp, useCart, useCheckout, useCollection, useCollectionOptional, useCollections, useCurrency, useCurrentTemplate, useCustomer, useCustomerActions, useCustomerAddresses, useDirection, useFieldTranslation, useGiftCardBalance, useImage, useLocale, useLocalization, useMoney, useNavigation, useNumberFormat, useOrder, useOrders, usePage, useProduct, useProductOptional, useProductSizeChart, useProducts, useRelatedProducts, useReorder, useResolvedSettings, useSearch, useSection, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist, validateBuiltManifest, validateManifest, validateSectionSchema, validateSettingsAgainstSchema };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map