@numueg/theme-sdk 0.6.1 → 0.10.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-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';
+import { i as Store, e as Product, b as Collection, c as Customer, P as Page, S as SizeChart, g as ProductVariant, C as Cart } from './entities-B8378GKp.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-B8378GKp.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-CNTB4KnU.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-CNTB4KnU.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-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 { C as CartContextValue, L as LocalizationState, a as CurrencyState, T as ThemeMountContext, b as ThemeRenderArgs, M as MenuItemData } from './mount-eAhGgGtZ.mjs';
+export { c as CartContext, d as CartMutationResult, e as CollectionContext, f as CurrencyConfig, g as CurrencyContext, h as CustomerContext, i as LocalizationContext, N as NavigationContext, P as PageContext, j as ProductContext, S as ShopContext, k as ThemeMountPage, l as ThemeSettingsContext, m as buildThemeElement, n as mountTheme } from './mount-eAhGgGtZ.mjs';
 import * as react from 'react';
 import { ReactElement, ReactNode, ElementType, CSSProperties, ImgHTMLAttributes, AnchorHTMLAttributes, ButtonHTMLAttributes, HTMLAttributes, FormHTMLAttributes, ComponentType } from 'react';
 export { resolveThemeSettings } from './normalize.mjs';
@@ -43,17 +43,7 @@ declare function useProductOptional(): Product | null;
 declare function useCollection(): Collection;
 declare function useCollectionOptional(): Collection | null;
 
-declare function useCart(): {
-    cart: Cart;
-    addItem: (productId: string, variantId?: string, quantity?: number) => Promise<void>;
-    removeItem: (itemId: string) => Promise<void>;
-    updateQuantity: (itemId: string, quantity: number) => Promise<void>;
-    applyDiscount: (code: string) => Promise<void>;
-    removeDiscount: () => Promise<void>;
-    updateNote: (note: string) => Promise<void>;
-    clearCart: () => Promise<void>;
-    loading: boolean;
-};
+declare function useCart(): CartContextValue;
 
 declare function useCustomer(): Customer | null;
 
@@ -136,14 +126,67 @@ declare function useSection(): SectionInstance;
 declare function useSectionOptional(): SectionInstance | null;
 
 /**
- * useMoney — convenience hook that returns a stable formatter bound to
- * the active store's currency.
+ * A section instance from a section group, carrying its own `id` (the key it
+ * had inside the group's `sections` map). The raw `SectionInstance` drops the
+ * id — but a theme needs it to key its React list, wire `<Section id={…}>`
+ * click-to-select, and look the type up in its own registry — so
+ * `useSectionGroup` re-attaches it here.
+ */
+interface SectionGroupInstance extends SectionInstance {
+    /** The instance's key within the group's `sections` map. */
+    id: string;
+}
+/**
+ * useSectionGroup — read the ordered section instances for a named section
+ * group ("header", "footer", or any custom global group) out of
+ * `themeSettings.section_groups[group]`.
+ *
+ * This is the SDK side of "global sections shared across pages": the host
+ * ships one `section_groups` map on every page, and a theme renders a given
+ * group in its layout (header/footer) or wherever it wants a page-independent
+ * section list. The returned array is in the group's `order`, and each entry
+ * carries its `id` so the theme can key + select + dispatch on it:
+ *
+ * ```tsx
+ * const headerSections = useSectionGroup("header");
+ * return headerSections.map(({ id, type, settings }) => {
+ *   const Comp = registry[type]?.render;      // theme owns the registry
+ *   return Comp ? (
+ *     <Section key={id} id={id} type={type} groupId="header">
+ *       <Comp settings={settings} />
+ *     </Section>
+ *   ) : null;
+ * });
+ * ```
+ *
+ * Pure data hook — it does NOT map types to components. The SDK has no section
+ * registry (a theme builds its own via `collectSections`), so there is no
+ * generic `<GlobalSections>` renderer to ship: the theme walks the returned
+ * instances through its own registry, exactly as it already does for template
+ * sections. Returns `[]` (a stable reference) when there is no provider, no
+ * `section_groups`, the named group is absent, or its `order` is empty.
+ *
+ * Disabled instances are INCLUDED (a `disabled` flag is preserved on each
+ * entry); filter with `.filter((s) => !s.disabled)` if the theme hides them.
+ * Ids listed in `order` but missing from `sections` are skipped defensively.
+ */
+declare function useSectionGroup(group: string): SectionGroupInstance[];
+
+/**
+ * useMoney — convenience hook that returns a formatter bound to the active
+ * store's currency.
  *
  * Useful when a section needs to format multiple amounts in a render:
  *
  *   const money = useMoney();
  *   return <td>{money(item.price * item.quantity)}</td>
  *
+ * Multi-currency: like <Money>, when the store has `auto_convert` on and no
+ * `currencyOverride` is passed, amounts are converted to and formatted in the
+ * visitor's SELECTED presentment currency (shared via `useCurrency()`), so a
+ * `<CurrencySwitcher>` change reflows these too. Pass a `currencyOverride` to
+ * pin a specific currency and skip conversion.
+ *
  * For one-off price displays prefer the <Money> component which handles
  * compare-at and inline rendering.
  */
@@ -579,10 +622,19 @@ declare function useAnalytics(): AnalyticsApi;
  * `{ available: false }` rather than as a network error — themes
  * branch on availability without try/catch.
  *
- * The hook revalidates whenever the slug changes, but does NOT refetch
- * on focus / interval — app data is usually slow-changing (config +
- * manifest). Themes that need live data should layer their own
- * refresh on top of the returned `refresh()` callback.
+ * Phase 3 (client-data layer): the fetch now runs through the shared
+ * `useCachedResource` store keyed by `numu:app:<store_id>:<slug>`. Two upgrades
+ * over the old per-instance `useState` + fetch:
+ *   - DEDUP + SYNC: N consumers of the same app slug share ONE request and one
+ *     result, instead of each firing its own `/apps/{slug}` fetch.
+ *   - CANCELLATION / ORDERING: the fetcher receives an AbortSignal and the
+ *     cache seq-guards results, so a slow response for a superseded slug (or a
+ *     superseded `refresh()`) can no longer apply stale state over a newer one
+ *     — the audited "out-of-order responses apply stale state" bug.
+ *
+ * `loading` reflects the FIRST load only; a `refresh()` revalidates in the
+ * background (`isValidating`) while keeping the last-good data visible, rather
+ * than blanking to a skeleton on every manual refresh.
  */
 interface AppManifestBlock {
     type: string;
@@ -628,8 +680,17 @@ declare function useApp<T = unknown>(slug: string): AppState<T>;
  * v1 implementation: localStorage only. The /api/customer/me/wishlist
  * endpoint isn't wired yet; an authed visitor still gets the local
  * fallback so themes work end-to-end. When the endpoint lands, the
- * mutation methods will short-circuit to the server fetch and the
- * effect below will drop the localStorage path for authed users.
+ * fetcher below swaps its localStorage read for the server fetch and the
+ * mutation methods gain a `{ revalidate: true }` write-through.
+ *
+ * Phase 3 (client-data layer): the items list now lives in the shared
+ * `useCachedResource` store keyed by `numu_wishlist_<store_id>`, NOT in
+ * per-instance `useState`. Previously two `<Heart>`s for the same product
+ * each held their own copy, so adding via one never re-rendered the other —
+ * the two hearts DESYNCED. Now every `useWishlist(storeId)` consumer reads
+ * and writes ONE shared entry, so an add/remove anywhere reflows every heart.
+ * Writes are optimistic (the shared store updates instantly) and roll back if
+ * persistence throws.
  */
 interface WishlistItem {
     product_id: string;
@@ -661,11 +722,17 @@ declare function useWishlist(storeId: string): WishlistState;
  * together"; v1 ships the simpler same-category-minus-self heuristic.
  *
  * Backend contract: GET /api/storefront/products/{id}/related?limit=N
- *   → { items: Product[] } | Product[]
+ *   → { items: Product[] } | { data: Product[] } | Product[]
  *
  * Returns an empty list (no error) when the endpoint is missing or the
  * product has no siblings — themes should branch on `items.length` and
  * either render the section or skip it entirely.
+ *
+ * Phase 3 (client-data layer): routed through the shared `useCachedResource`
+ * store keyed by `numu:related:<productId>:<limit>`. Two "related products"
+ * sections on the same PDP now share ONE request + one result instead of each
+ * refetching, and the AbortSignal + cache seq-guard drop a superseded response
+ * (e.g. after a rapid product switch) so it can't overwrite the newer list.
  */
 interface RelatedProductsState {
     items: Product[];
@@ -676,6 +743,103 @@ declare function useRelatedProducts(productId: string | null | undefined, option
     limit?: number;
 }): RelatedProductsState;
 
+/**
+ * Shared client-data layer (Phase 3) — a tiny SWR-style cache with ZERO
+ * runtime dependencies.
+ *
+ * Why this exists (from the audit): several hooks fetched + held per-instance
+ * state, so N components rendering the same resource fired N identical requests
+ * AND drifted out of sync (e.g. two wishlist hearts for one product; `useApp`
+ * applying an out-of-order response over a newer one). `useCachedResource`
+ * centralizes fetching behind one module-level store keyed by a string:
+ *
+ *   (a) DEDUP — the first consumer of a key starts the fetch and stashes the
+ *       in-flight promise on the entry; every other consumer that revalidates
+ *       the same key while it's pending joins that promise instead of firing a
+ *       second request. N consumers → ONE network call.
+ *   (b) CACHE — results live on the entry keyed by string, so a later mount
+ *       reads the cached value immediately (and skips refetch within
+ *       `dedupeIntervalMs`).
+ *   (c) SUBSCRIBE / NOTIFY — every hook instance subscribes to its key via
+ *       `useSyncExternalStore`. Any update (fetch resolve, `mutate`) rebuilds
+ *       the entry's immutable snapshot and notifies ALL subscribers, so every
+ *       instance re-renders with the same value — cross-instance state sync.
+ *   (d) REVALIDATE + CANCELLATION — each fetch reserves a monotonic sequence
+ *       number and an `AbortController`. Starting a new (forced) fetch aborts
+ *       the previous one; when any fetch settles, its result is applied ONLY if
+ *       its sequence is still the latest (`mySeq === entry.seq`). So a slow,
+ *       superseded response can never overwrite a newer result regardless of
+ *       the order the network resolves them in.
+ *
+ * SSR-safe: the fetch is triggered from `useEffect` (never runs under
+ * `renderToString`), and `useSyncExternalStore`'s server snapshot returns the
+ * `initialData` fallback without ever touching the module cache — so nothing is
+ * written to the shared map on the server and there is no cross-request bleed.
+ *
+ * This is intentionally NOT a full SWR clone (no focus/reconnect revalidation,
+ * no suspense, no infinite pagination). It's the smallest primitive that fixes
+ * the audited dedup + sync + ordering bugs and that themes can reuse.
+ */
+/** The reactive slice a consumer reads. */
+interface CachedResourceState<T> {
+    /** Latest cached value, or `initialData` before the first fetch settles. */
+    data: T | undefined;
+    /** Error from the most recent settled fetch (cleared on success / mutate). */
+    error: Error | undefined;
+    /** True until the first fetch (or `mutate`) settles a value for this key. */
+    isLoading: boolean;
+    /** True whenever a fetch is currently in flight (initial OR background). */
+    isValidating: boolean;
+}
+/** Fetcher receives an AbortSignal so a superseding fetch can cancel it. */
+type CacheFetcher<T> = (signal: AbortSignal) => Promise<T>;
+/** `mutate` accepts a value or an updater `(current) => next`. */
+type CacheMutator<T> = T | undefined | ((current: T | undefined) => T | undefined);
+interface MutateOptions {
+    /** After applying the local value, kick a fresh (forced) revalidation. */
+    revalidate?: boolean;
+}
+interface CachedResource<T> extends CachedResourceState<T> {
+    /**
+     * Optimistically write the cached value for this key (all subscribers
+     * re-render). Pass `{ revalidate: true }` to also refetch afterwards.
+     */
+    mutate: (next: CacheMutator<T>, opts?: MutateOptions) => void;
+    /** Force a fresh fetch, superseding + aborting any in-flight request. */
+    revalidate: () => Promise<void>;
+}
+interface UseCachedResourceOptions<T> {
+    /**
+     * Value shown on the server and on the first client paint before the fetch
+     * resolves. Used as the SSR snapshot (SSR-safe: no fetch on the server).
+     */
+    initialData?: T;
+    /** When `false`, the hook holds no subscription and never fetches. */
+    enabled?: boolean;
+    /** Auto-fetch on mount / key change (default `true`). */
+    revalidateOnMount?: boolean;
+    /**
+     * Skip the mount fetch if a value settled within this window (ms). Prevents
+     * a staggered second mount from refetching a still-fresh key. Default 2000.
+     */
+    dedupeIntervalMs?: number;
+    /** Called on a non-abort fetch error, with the key. */
+    onError?: (error: Error, key: string) => void;
+}
+/**
+ * Subscribe to a cached resource keyed by `key`, deduping the fetch across all
+ * instances and keeping them in sync. See the module docblock for the full
+ * contract.
+ *
+ * @param key       Cache key. `null`/`undefined`/`""` (or `enabled: false`)
+ *                  disables the hook — no subscription, no fetch, `initialData`
+ *                  is returned.
+ * @param fetcher   `(signal) => Promise<T>`. Recreated-per-render is fine; the
+ *                  latest is captured in a ref so it doesn't retrigger fetches.
+ * @param options   See {@link UseCachedResourceOptions}.
+ */
+declare function useCachedResource<T>(key: string | null | undefined, fetcher: CacheFetcher<T>, options?: UseCachedResourceOptions<T>): CachedResource<T>;
+
 /**
  * useProductSizeChart — resolve the size chart to show for a product.
  *
@@ -703,53 +867,6 @@ declare function useProductSizeChart(productOverride?: Product | null): SizeChar
  */
 declare function resolveSizeChart(productAttributes: Record<string, unknown> | undefined, storeSettings: Record<string, unknown> | undefined): SizeChart | null;
 
-/**
- * Multi-currency presentment — Phase 6.
- *
- * The store's *capture* currency (what Paymob/Stripe/etc. charges)
- * never changes mid-session. This hook is purely about **display**:
- * letting visitors browse prices in a currency they recognize.
- *
- * Usage:
- *
- *     const { base, selected, presentment, convert, setSelected } = useCurrency();
- *     <p>{convert(product.price.amount_cents)} {selected}</p>
- *     {presentment.length > 1 && (
- *       <select value={selected} onChange={(e) => setSelected(e.target.value)}>
- *         {presentment.map(c => <option key={c}>{c}</option>)}
- *       </select>
- *     )}
- *
- * Behavior:
- *   - `selected` defaults to the persisted `numu_currency` cookie if
- *     valid, else `default_presentment`, else `base`.
- *   - `setSelected` writes the cookie (path=/, 30d) so navigation
- *     preserves the choice across pages.
- *   - `convert(cents)` returns the converted cents in `selected`,
- *     using the rates from the API. When no rate exists, returns
- *     the input unchanged (theme renders in base — better than a
- *     wrong number).
- *
- * Use `<CurrencySwitcher>` from the SDK for an opinionated UI, or
- * read this hook directly for full control.
- */
-interface CurrencyConfig {
-    base: string;
-    default_presentment: string;
-    presentment: string[];
-    rates: Record<string, string>;
-    auto_convert: boolean;
-}
-interface CurrencyState {
-    base: string;
-    selected: string;
-    presentment: string[];
-    rates: Record<string, number>;
-    autoConvert: boolean;
-    loading: boolean;
-    setSelected: (currency: string) => void;
-    convert: (cents: number, target?: string) => number;
-}
 declare function useCurrency(): CurrencyState;
 
 /**
@@ -811,10 +928,30 @@ interface UseVariantSelection {
  * Shopify's behavior. Themes that prefer "Choose your size" empty
  * state can pass `autoSelect: false`.
  */
-declare function useVariantSelection(product: Pick<Product, "options" | "variants">, opts?: {
+declare function useVariantSelection(product: Pick<Product, "options" | "variants"> & {
+    id?: string;
+}, opts?: {
     autoSelect?: boolean;
 }): UseVariantSelection;
 
+/**
+ * Live variant-picker selection registry.
+ *
+ * `useVariantSelection` publishes its current axis→value map here keyed by
+ * product id; `AddToCartButton` reads it back at click time. This is what
+ * lets the selection reach the cart even when no real variant row matches —
+ * legacy products keep their axes in attributes JSON with a single
+ * placeholder variant whose option_values is {}, so `findVariantByOptions`
+ * returns null and there'd otherwise be nothing to send.
+ *
+ * Module-scoped (not React context) on purpose: the hook instance lives in
+ * the theme's PDP section while the button may be a sibling — they share no
+ * provider of ours. Bounded: one entry per product id, last write wins.
+ */
+declare function publishVariantSelection(productId: string | undefined | null, selection: Record<string, string>): void;
+/** Latest non-empty selection for a product, or null. */
+declare function readVariantSelection(productId: string | undefined | null): Record<string, string> | null;
+
 /**
  * Gift card balance check — Phase 8.3.
  *
@@ -1092,6 +1229,15 @@ interface NuMuProviderProps {
      * built before the prop existed keep rendering their home template.
      */
     currentTemplate?: string;
+    /**
+     * I3 — resolved alternate template key for the current page (e.g.
+     * `"product.wholesale"`) when the storefront routed it to a template
+     * suffix. Published on the synthesized `PageContext` value so themes read
+     * it via `usePage()?.template`. Distinct from `currentTemplate`, which is
+     * the base route type (`"product"`). Omit for pages on their default
+     * template; additive, so themes/hosts predating it are unaffected.
+     */
+    pageTemplate?: string;
     /**
      * Pre-fetched product list for the current page. Themes that call
      * `useProducts()` will read these from PageContext without needing
@@ -1117,7 +1263,7 @@ interface NuMuProviderProps {
     navigation?: Record<string, MenuItemData[]>;
     children: ReactNode;
 }
-declare function NuMuProvider({ store, themeSettings, initialCart, customer, locale: initialLocale, translations: initialTranslations, currentTemplate, initialProducts, initialCollections, navigation, children, }: NuMuProviderProps): react.JSX.Element;
+declare function NuMuProvider({ store, themeSettings, initialCart, customer, locale: initialLocale, translations: initialTranslations, currentTemplate, pageTemplate, initialProducts, initialCollections, navigation, children, }: NuMuProviderProps): react.JSX.Element;
 
 interface ProductProviderProps {
     product: Product;
@@ -1154,6 +1300,13 @@ interface MoneyProps {
  * Intl.NumberFormat. Renders inline with `dir="auto"` so the digits
  * flow naturally in RTL (Arabic) without flipping the currency symbol.
  *
+ * Multi-currency: when the store has `auto_convert` on and the caller did NOT
+ * pin an explicit `currency`, the amount is presented in the visitor's
+ * SELECTED currency (converted via the shared rates from `useCurrency()`). A
+ * `<CurrencySwitcher>` change therefore re-renders every `<Money>` on the page
+ * without a reload. An explicit `currency` prop means "this amount is already
+ * in that currency" — it is respected and never converted.
+ *
  * Usage:
  *   <Money amount={product.price} compareAt={product.compare_at_price} />
  */
@@ -1383,27 +1536,66 @@ interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"
     to: string;
     children: ReactNode;
 }
+/**
+ * Event dispatched on `window` when a Link is clicked and eligible for
+ * client-side (soft) navigation. `detail.href` is the target path.
+ *
+ * Contract: the event is CANCELABLE. A host that can perform soft
+ * navigation (e.g. the Next.js storefront routing through its client
+ * router) listens for it and calls `event.preventDefault()` to claim
+ * the navigation. If no listener claims it, the Link falls back to
+ * default anchor behavior — a normal full-page navigation — so themes
+ * running under hosts without the bridge (older storefronts, the CLI
+ * dev server, static previews) keep working unchanged.
+ */
+declare const NAVIGATE_EVENT = "numu:navigate";
+interface NavigateEventDetail {
+    href: string;
+}
+/**
+ * Ask the host to soft-navigate to `href`. Returns true when a host
+ * listener claimed the navigation (the caller should suppress its own
+ * default behavior), false when no handler is present (the caller
+ * should fall back to a full navigation). Exposed for themes that
+ * navigate programmatically (e.g. after a search submit).
+ */
+declare function requestNavigate(href: string): boolean;
 /**
  * Route-aware <Link>. Themes write paths as `/products/<slug>` (matches
  * the production subdomain root). The storefront proxy rewrites those
  * under `/<subdomain>/...` in dev path-segment routing; in production
  * the subdomain hostname does the same job at the edge.
  *
- * For plain anchor behavior — server-rendered HTML, full page nav — we
- * just emit a regular `<a>`. Themes that want client-side transitions
- * can wrap this in their own router-aware component; in practice
- * storefront pages are SSR'd so a full nav is fine and predictable.
- *
- * External URLs (have a protocol or start with `//`) pass through
- * unchanged so social-media links, CDN paths, etc. work without
- * special casing.
- */
-declare function Link({ to, children, ...rest }: LinkProps): react.JSX.Element;
+ * Navigation is a two-tier contract:
+ *   1. Soft (preferred): on an eligible plain left-click we dispatch a
+ *      cancelable NAVIGATE_EVENT. A router-aware host claims it with
+ *      preventDefault() and performs a client-side transition — React,
+ *      the SDK runtime, and the evaluated theme bundle all stay warm,
+ *      so page-to-page moves skip the full document reload + remount.
+ *   2. Hard (fallback): no listener claims the event → default anchor
+ *      behavior, a normal full-page navigation. Identical to the
+ *      pre-0.10 behavior, so themes never break on hosts without the
+ *      bridge.
+ *
+ * Soft navigation is only attempted for storefront-internal paths and
+ * unmodified left-clicks: external URLs (protocol or `//`), hash-only
+ * anchors, modified clicks (ctrl/cmd/shift/alt — "open in new tab"),
+ * non-left buttons, `target` other than `_self`, and `download` links
+ * all keep default browser behavior.
+ */
+declare function Link({ to, children, onClick, ...rest }: LinkProps): react.JSX.Element;
 
 interface AddToCartButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onClick" | "disabled"> {
     product: Product;
     variant?: ProductVariant;
     quantity?: number;
+    /**
+     * Picker axes to persist on the cart line ({Color: "Black"}). Optional —
+     * when omitted, the button reads the live useVariantSelection state for
+     * this product from the SDK registry, so existing themes get the variant
+     * label end-to-end (cart → checkout → order → email) with no changes.
+     */
+    selectedOptions?: Record<string, string>;
     /** Custom labels — fallbacks are English defaults. */
     label?: ReactNode;
     loadingLabel?: ReactNode;
@@ -1426,7 +1618,7 @@ interface AddToCartButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonEleme
  * Doesn't trap navigation — for "buy now" flows that should redirect
  * to checkout, themes wrap this in their own `<a>` after onAdded.
  */
-declare function AddToCartButton({ product, variant, quantity, label, loadingLabel, soldOutLabel, errorLabel, onAdded, ...rest }: AddToCartButtonProps): react.JSX.Element;
+declare function AddToCartButton({ product, variant, quantity, selectedOptions, label, loadingLabel, soldOutLabel, errorLabel, onAdded, ...rest }: AddToCartButtonProps): react.JSX.Element;
 
 interface SectionProps extends HTMLAttributes<HTMLElement> {
     /** Section instance id (the order key in templates). Required for the
@@ -1670,13 +1862,13 @@ interface RichTextProps {
  * Sanitize an HTML string against the allowlist above. Runs server-
  * AND client-side because rich-text fields are server-rendered for SEO.
  *
- * Implementation note: We use DOMParser when available (browser) for
- * structural correctness; on server we fall through a regex-based
- * pass that handles the common formatting tags + escapes everything
- * else. The server pass is intentionally conservative — themes that
- * need server-rendered rich content with edge-case structure should
- * sanitize on the API tier and pass the sanitized HTML through
- * `bypassSanitize` (escape hatch below).
+ * Implementation note: in the browser we use DOMParser (structural allowlist
+ * — see `sanitizeHtmlClient`/`walk`). On the server (no DOM) we fall through
+ * to `sanitizeHtmlServer`, a hardened regex denylist that strips dangerous
+ * element blocks to a fixpoint, removes inline event handlers (incl.
+ * slash-separated ones), and drops non-allowlisted `href`/`src` URLs. Themes
+ * needing server-rendered rich content with edge-case structure should
+ * sanitize on the API tier and pass already-safe HTML through.
  */
 declare function sanitizeHtml(input: string): string;
 declare function RichText({ html, className, as }: RichTextProps): react.JSX.Element | null;
@@ -2267,4 +2459,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, 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 };
+export { AddToCartButton, type AddressInput, type AnalyticsApi, type AnalyticsPayload, type AppManifestBlock, type AppPayload, type AppState, Block, BlockInstance, BlockProps$1 as BlockProps, BlockSchema, type CacheFetcher, type CacheMutator, type CachedResource, type CachedResourceState, Cart, CartContextValue, type CheckoutAddress, type CheckoutApi, type CheckoutSessionState, type CheckoutStep, Collection, CollectionCard, type CollectionCardProps, type CollectionCardSlots, CollectionProvider, type ComputedStyleTokens, 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 MutateOptions, NAVIGATE_EVENT, type NavigateEventDetail, 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, type SectionGroupInstance, SectionInstance, SectionProps$1 as SectionProps, SectionSchema, type ShippingRateOption, type ShopWithHelpers, SizeChart, Store, type ThemeEntry, ThemeMountContext, ThemeRenderArgs, ThemeSettingsV3, type UseCachedResourceOptions, 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, publishVariantSelection, readVariantSelection, registerReactSingleton, registerSdkSingleton, requestNavigate, resolveDynamicValue, resolveFontStack, resolveSettingsMap, resolveSizeChart, resolveSourcePath, sanitizeHtml, useAnalytics, useApp, useCachedResource, 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, useSectionGroup, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist };