@numueg/theme-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1645 @@
+import { S as Store, P as Product, C as Collection, a as Cart, b as Customer, c as Page, d as ProductVariant } from './index-CGx6FNqb.js';
+export { A as Address, e as CartItem, O as Order, f as OrderItem, g as ProductImage, h as ProductOption } from './index-CGx6FNqb.js';
+import { T as ThemeSettingsV3, S as SectionInstance, B as BlockSchema, a as BlockProps$1, b as SectionSchema, c as SectionProps$1 } from './theme-NWJAU9jd.js';
+export { d as BlockInstance, E as ExternalThemeMetadata, P as PageTemplate, e as SectionGroup, f as SectionPreset, g as SettingDefinition } from './theme-NWJAU9jd.js';
+import * as react from 'react';
+import { ReactNode, ElementType, ImgHTMLAttributes, AnchorHTMLAttributes, ButtonHTMLAttributes, HTMLAttributes, FormHTMLAttributes, ComponentType } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+export { resolveThemeSettings } from './normalize.js';
+
+/**
+ * Augmented Store shape returned from useShop().
+ *
+ * Adds a couple of conveniences theme devs reach for constantly:
+ *   - `domain` — the active hostname (subdomain or custom). Resolved
+ *     from `store.domain ?? store.subdomain ?? store.slug`.
+ *   - `formatUrl(path)` — emits a fully-qualified URL using `domain`.
+ *     Theme code that needs to render absolute URLs (canonical tags,
+ *     Open Graph, JSON-LD) goes through this so dev/prod / subdomain
+ *     vs. custom-domain stays correct without each theme reinventing
+ *     the resolver.
+ */
+interface ShopWithHelpers extends Store {
+    /** Fully-qualified hostname this store currently serves on. */
+    domain: string;
+    /**
+     * Format a path (relative or absolute) as a fully-qualified URL on
+     * this store's domain. No-ops when given an already-absolute URL.
+     *
+     * Phase 6 — when the active locale is non-default and the store
+     * has opted into locale URL prefixes, the path is prefixed with
+     * `/{locale}/` (e.g. `/ar/products/foo`). Already-prefixed paths
+     * are left alone so calling `formatUrl(formatUrl(...))` is safe.
+     */
+    formatUrl(path: string): string;
+}
+declare function useShop(): ShopWithHelpers;
+
+declare function useProduct(): Product;
+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 useCustomer(): Customer | null;
+
+declare function useThemeSettings(): ThemeSettingsV3;
+
+interface LocalizationState {
+    locale: string;
+    direction: "ltr" | "rtl";
+    translations: Record<string, string>;
+    formatMoney: (amount: number, currency?: string) => string;
+    formatDate: (date: string | Date) => string;
+    /**
+     * Phase 3.7 — locale-aware number formatter. Routes to either
+     * Western (1234) or Arab-Indic (١٢٣٤) digits depending on
+     * `store.settings.numerals`. Themes calling formatMoney get the
+     * same digit choice automatically; this is for raw counts ("12 items").
+     */
+    formatNumber: (n: number, options?: Intl.NumberFormatOptions) => string;
+    /**
+     * Phase 3.6 — switch the active locale.
+     *
+     * Sets the `numu_locale` cookie and triggers a full page reload so
+     * the server-rendered layout picks up the new locale (the storefront
+     * resolves locale at SSR time from cookie/query). Returns once the
+     * cookie is written; the page navigation cancels any pending React
+     * work so callers don't need to await.
+     */
+    setLocale: (next: string) => void;
+    /**
+     * Phase 3.6 — list of locales the store advertises. Empty when the
+     * store hasn't configured a multi-locale catalog. Themes use this
+     * to decide whether to render the LocaleSwitcher at all.
+     */
+    availableLocales: string[];
+}
+declare const ShopContext: react.Context<Store | null>;
+declare const ProductContext: react.Context<Product | null>;
+declare const CollectionContext: react.Context<Collection | null>;
+declare const CartContext: react.Context<{
+    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;
+} | null>;
+declare const CustomerContext: react.Context<Customer | null>;
+declare const ThemeSettingsContext: react.Context<ThemeSettingsV3 | null>;
+declare const LocalizationContext: react.Context<LocalizationState | null>;
+declare const PageContext: react.Context<Page | null>;
+
+declare function useLocalization(): LocalizationState;
+declare function useDirection(): "ltr" | "rtl";
+declare function useLocale(): string;
+declare function useTranslation(): {
+    t: (key: string, fallback?: string) => string;
+    locale: string;
+};
+/**
+ * Phase 3.6 — pull a translated field off a domain object.
+ *
+ * Convention: per-product translations live on `entity.attributes`
+ * keyed as `<field>_<locale>` — e.g. `name_ar`, `description_ar`.
+ * Backend writes these via the merchant hub when a merchant turns on
+ * "Translations" for a product. Themes call:
+ *
+ *     const productName = useFieldTranslation(product, "name");
+ *
+ * and get the Arabic name when the active locale is "ar", falling
+ * back to the English `product.name` otherwise. Works for any object
+ * that pairs a base field on the entity with an `attributes` JSONB
+ * blob holding the translated variants.
+ *
+ * Why not put translations on the entity itself? Adding `name_ar`,
+ * `description_ar`, `name_he`, etc. as first-class columns means a
+ * schema migration every time a merchant enables a new locale. JSONB
+ * lets the merchant flip locales on/off in settings without touching
+ * the table.
+ */
+declare function useFieldTranslation<T extends {
+    attributes?: Record<string, unknown>;
+}>(entity: T | null | undefined, field: string): string | undefined;
+/**
+ * Phase 3.7 — formatted-number hook.
+ *
+ * Themes that need to render counts ("12 items", "3 reviews") should
+ * route through this hook so Arab-Indic digits (٠١٢٣٤) vs Western
+ * (01234) stay consistent with money + date elsewhere on the page.
+ *
+ *     const fmtNum = useNumberFormat();
+ *     fmtNum(12)              → "12"   (or "١٢" for Arabic stores)
+ *     fmtNum(12.5, { minimumFractionDigits: 2 }) → "12.50" / "١٢٫٥٠"
+ */
+declare function useNumberFormat(): (n: number, options?: Intl.NumberFormatOptions) => string;
+
+declare function usePage(): Page | null;
+
+declare const SectionContext: react.Context<SectionInstance | null>;
+declare function useSection(): SectionInstance;
+declare function useSectionOptional(): SectionInstance | null;
+
+/**
+ * useMoney — convenience hook that returns a stable 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>
+ *
+ * For one-off price displays prefer the <Money> component which handles
+ * compare-at and inline rendering.
+ */
+declare function useMoney(currencyOverride?: string): (amount: number) => string;
+
+interface UseImageOptions {
+    /** Sizes attribute (CSS sizes form). */
+    sizes?: string;
+    /** Widths to generate in srcSet. Falsy → use defaults. */
+    widths?: number[];
+    /** Pass-through alt text — useImage doesn't render anything; the
+     * caller does. */
+    alt?: string;
+}
+interface ImageDescriptor {
+    src: string | null;
+    srcSet: string | null;
+    sizes: string;
+    alt: string;
+}
+/**
+ * useImage — returns srcSet/sizes for a CDN-served image so themes
+ * don't have to hand-roll responsive image markup. Pairs with the
+ * <Image> component, but is also useful when the theme wants to render
+ * something other than a plain `<img>` (e.g., `<picture>` with art
+ * direction or a CSS `background-image` via inline style).
+ *
+ * Returns `null` srcSet if the source URL already encodes a width
+ * directive (theme author opted out of auto-sizing).
+ */
+declare function useImage(src: string | null | undefined, opts?: UseImageOptions): ImageDescriptor;
+
+interface UseProductsOptions {
+    /** Limit the slice returned. Defaults to whatever the host gave us. */
+    limit?: number;
+    /**
+     * When true, fetch from `/api/products` if the host didn't provide a
+     * list via PageContext. Useful for sections rendered on routes that
+     * don't pre-fetch products (e.g. a custom CMS page that wants a
+     * "featured" rail). Default: false — themes typically prefer SSR data.
+     */
+    fetchIfMissing?: boolean;
+}
+interface UseProductsResult {
+    products: Product[];
+    loading: boolean;
+    error: Error | null;
+}
+/**
+ * useProducts — read the storefront-pre-fetched product list from the
+ * page context, optionally falling back to a client-side fetch.
+ *
+ * The SSR path passes `page.data.products: Product[]` from
+ * `numu-storefront/src/app/[domain]/page.tsx`; sections on the home
+ * route get them for free. For other routes that don't pre-fetch, set
+ * `fetchIfMissing: true` and we'll hit `/api/products`.
+ */
+declare function useProducts(opts?: UseProductsOptions): UseProductsResult;
+
+interface UseCollectionsOptions {
+    limit?: number;
+    fetchIfMissing?: boolean;
+}
+interface UseCollectionsResult {
+    collections: Collection[];
+    loading: boolean;
+    error: Error | null;
+}
+/**
+ * useCollections — analog to useProducts. Reads page.data.collections
+ * pre-fetched by the storefront SSR; falls back to /api/collections
+ * when fetchIfMissing is true.
+ */
+declare function useCollections(opts?: UseCollectionsOptions): UseCollectionsResult;
+
+/**
+ * The action surface a theme can call to drive customer auth +
+ * profile mutations. Each action returns the parsed response body
+ * (or throws on network failure); the *result* of the operation is
+ * conveyed by the response shape, not the throw boundary.
+ *
+ * The provider implements these by calling /api/customer/* proxy
+ * routes on the storefront, which in turn forward to FastAPI's
+ * /storefront/store/{store_id}/auth/* and /storefront/me/* endpoints.
+ *
+ * Why a separate context (vs bundling onto CustomerContext): the
+ * value `Customer | null` was already in CustomerContext for
+ * back-compat with themes that read `useCustomer()`. Adding a
+ * sibling context for actions keeps the existing read hook stable
+ * while letting themes opt into actions via `useCustomerActions()`.
+ */
+interface CustomerActions {
+    /** Email + password → returns { success, data?, error? }. On
+     * success the SDK refreshes the customer context automatically. */
+    login: (input: {
+        email: string;
+        password: string;
+    }) => Promise<unknown>;
+    /** Create a new customer + log them in. Some stores require
+     * email verification before login is fully usable; this flow
+     * still issues the auth cookie so the customer can verify from
+     * the welcome email and land logged-in. */
+    register: (input: {
+        email: string;
+        password: string;
+        first_name?: string;
+        last_name?: string;
+        phone?: string;
+        accepts_marketing?: boolean;
+    }) => Promise<unknown>;
+    /** Clear the customer_access_token cookie + refresh the context
+     * to null. Idempotent: safe to call when not logged in. */
+    logout: () => Promise<unknown>;
+    /** Issue a password-reset email. Anti-enumeration: response
+     * never reveals whether the email exists. */
+    requestRecover: (input: {
+        email: string;
+    }) => Promise<unknown>;
+    /** Submit the new password with the token from the recovery email. */
+    confirmReset: (input: {
+        token: string;
+        password: string;
+    }) => Promise<unknown>;
+    /** Verify the email with the token from the welcome email. */
+    verifyEmail: (input: {
+        token: string;
+    }) => Promise<unknown>;
+    /** Resend the verification email. Server-side rate-limited to
+     * prevent email-bombing. */
+    resendVerification: (input: {
+        email: string;
+    }) => Promise<unknown>;
+    /** Update the customer's profile (name / phone / marketing). */
+    updateProfile: (input: {
+        first_name?: string;
+        last_name?: string;
+        phone?: string;
+        accepts_marketing?: boolean;
+    }) => Promise<unknown>;
+    /** Change the customer's password from inside the dashboard.
+     * Backend requires the current password as confirmation. */
+    changePassword: (input: {
+        current_password: string;
+        new_password: string;
+    }) => Promise<unknown>;
+    /** Re-fetch the customer profile from the backend and replace
+     * the context value. Themes call this after performing any
+     * out-of-band mutation that changed the customer's record. */
+    refresh: () => Promise<void>;
+}
+
+/**
+ * Returns the customer-mutation actions provided by NuMuProvider.
+ *
+ * Pair with `useCustomer()` for read access:
+ *
+ *   const customer = useCustomer();
+ *   const { login, logout, register } = useCustomerActions();
+ *
+ * The actions hit the storefront's `/api/customer/*` proxies, which
+ * own the cookie/CSRF/idempotency story. Themes don't talk to the
+ * backend directly — they get a stable client-side surface here.
+ */
+declare function useCustomerActions(): CustomerActions;
+
+/**
+ * Customer order history.
+ *
+ * `useOrders()` returns the logged-in customer's orders, paginated.
+ * The hook is gated on `useCustomer()` — when null (anonymous
+ * visitor), it returns an empty list without hitting the network.
+ *
+ * `useOrder(id)` fetches a single order. Backend rejects with 404
+ * when the id doesn't belong to the customer regardless of whether
+ * it exists for someone else (avoids enumeration).
+ */
+interface OrderListEntry {
+    id: string;
+    order_number: string;
+    status: string;
+    payment_status: string;
+    fulfillment_status: string;
+    total: number;
+    currency: string;
+    created_at: string | null;
+    item_count?: number;
+}
+interface OrderListState {
+    orders: OrderListEntry[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => void;
+}
+interface OrderDetail extends OrderListEntry {
+    line_items: unknown[];
+    shipping_address?: Record<string, unknown> | null;
+    billing_address?: Record<string, unknown> | null;
+    subtotal: number;
+    shipping_cost: number;
+    tax_amount: number;
+    discount_amount: number;
+}
+interface OrderState {
+    order: OrderDetail | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => void;
+}
+declare function useOrders(): OrderListState;
+declare function useOrder(id: string | null | undefined): OrderState;
+
+/**
+ * Customer address book. Used by:
+ *   - The /account/addresses dashboard (list + CRUD).
+ *   - Checkout autofill (default address selected by default).
+ *
+ * Mutations return the updated row (or void on delete) and bump the
+ * internal tick so the list reflects state changes immediately.
+ * Anonymous visitors get an empty list with no network calls.
+ */
+interface CustomerAddress {
+    id: string;
+    first_name?: string | null;
+    last_name?: string | null;
+    address_line1?: string | null;
+    address_line2?: string | null;
+    city?: string | null;
+    state?: string | null;
+    postal_code?: string | null;
+    country?: string | null;
+    phone?: string | null;
+    label?: string | null;
+    is_default?: boolean;
+    latitude?: number | null;
+    longitude?: number | null;
+}
+type AddressInput = Omit<CustomerAddress, "id" | "is_default"> & {
+    is_default?: boolean;
+};
+interface CustomerAddressesState {
+    addresses: CustomerAddress[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => void;
+    addAddress: (input: AddressInput) => Promise<CustomerAddress | null>;
+    updateAddress: (id: string, input: Partial<AddressInput>) => Promise<CustomerAddress | null>;
+    deleteAddress: (id: string) => Promise<boolean>;
+    setDefaultAddress: (id: string) => Promise<boolean>;
+}
+declare function useCustomerAddresses(): CustomerAddressesState;
+
+/**
+ * Menu item, modeled on Shopify's `linklists` entries.
+ *
+ * Themes typically render header/footer nav as a tree — we expose
+ * `children` so a single fetch hydrates an arbitrary depth. Backends
+ * that don't support nesting return a flat list (children=[]).
+ */
+interface NavigationItem {
+    id: string;
+    title: string;
+    /** The URL the menu item points to — relative path or absolute URL. */
+    url: string;
+    /** Optional foreign keys when the item references a typed resource. */
+    resource_type?: "product" | "collection" | "page" | "blog" | "article" | "url" | null;
+    resource_handle?: string | null;
+    children: NavigationItem[];
+}
+interface NavigationState {
+    /** Items in display order. Empty array when the menu is missing or still loading. */
+    items: NavigationItem[];
+    loading: boolean;
+    /** Non-null when the fetch failed — the menu still resolves to []. */
+    error: Error | null;
+}
+/**
+ * Fetch a merchant-managed nav menu by handle.
+ *
+ * Backend contract: GET /api/storefront/navigation/{handle} →
+ *   { items: NavigationItem[] }
+ * On 404 / network error / non-OK response the hook returns an empty
+ * list — the calling theme decides whether to render nothing or show
+ * a fallback. We deliberately don't throw because a missing menu is
+ * a soft failure (theme should still render).
+ *
+ * Why no SSR pre-fetch:
+ *   The storefront's [domain]/layout doesn't currently inject menus
+ *   into `page.data.navigation`. Once it does, themes can pass an
+ *   `initialItems` prop (added below) and skip the round-trip; until
+ *   then we fetch on mount with a process-local cache so the same
+ *   handle doesn't fetch twice per session.
+ */
+declare function useNavigation(handle: string, options?: {
+    initialItems?: NavigationItem[];
+}): NavigationState;
+
+/**
+ * Mixed-result search shape. The backend tsvector implementation lands in
+ * Phase 4; until then this hook talks to /api/storefront/search and
+ * gracefully degrades (empty results) when the endpoint isn't available.
+ *
+ * Two modes:
+ *   - "predictive" (default): debounced, capped at 5 per type, returns
+ *     fast for autocomplete dropdowns.
+ *   - "full": full result set with paging, used by /search pages.
+ */
+interface SearchResults {
+    products: Product[];
+    collections: Collection[];
+    pages: Page[];
+    /** Articles will populate once the blog backend lands; field shape is
+     *  reserved here so themes can write code that doesn't break on
+     *  upgrade. */
+    articles: Array<{
+        id: string;
+        title: string;
+        handle: string;
+        excerpt?: string;
+    }>;
+    total: number;
+}
+interface UseSearchOptions {
+    /** "predictive" debounces and caps; "full" returns paged results. */
+    mode?: "predictive" | "full";
+    /** Restrict to specific result types. Default: all. */
+    types?: Array<"products" | "collections" | "pages" | "articles">;
+    /** Per-type cap. Predictive mode defaults to 5; full mode defaults to 24. */
+    limit?: number;
+    /** Debounce window in ms for predictive mode. Default 200. */
+    debounceMs?: number;
+    /** Skip the debounce (e.g. when the user submits the form). */
+    immediate?: boolean;
+}
+interface SearchState {
+    query: string;
+    results: SearchResults;
+    loading: boolean;
+    error: Error | null;
+}
+declare function useSearch(query: string, options?: UseSearchOptions): SearchState;
+
+/**
+ * Theme-facing analytics dispatcher.
+ *
+ * Two delivery channels, fired in parallel:
+ *   1. Server-side track: POST /api/storefront/track with the event
+ *      payload. The backend fans out to merchant-configured pixels
+ *      (GA4 Measurement Protocol, Meta CAPI, TikTok Events API). The
+ *      server-side fanout lands in Phase 4 — until then the endpoint
+ *      either no-ops or returns 404, which is fine; we don't await
+ *      the response because failed pixels must never block the UI.
+ *   2. Window CustomEvent (`numu:analytics:event`): so theme devs can
+ *      wire their own GTM container, third-party SDK, or in-house
+ *      pixel without going through the server. Detail shape mirrors
+ *      what gets POSTed.
+ *
+ * Standard event names (recommended for compatibility with GA4 / Meta):
+ *   page_view, view_item, view_collection, search, add_to_cart,
+ *   remove_from_cart, view_cart, begin_checkout, add_payment_info,
+ *   add_shipping_info, purchase, refund, sign_up, login,
+ *   add_to_wishlist, share. Custom names are also fine — the dispatcher
+ *   does not validate, so themes can ship store-specific events.
+ */
+interface AnalyticsPayload {
+    /** Standard or custom event name. Lowercase + underscores recommended. */
+    [key: string]: unknown;
+}
+interface AnalyticsApi {
+    /**
+     * Fire an event. Non-blocking — both the fetch and the CustomEvent
+     * dispatch happen in the next microtask; theme code shouldn't await.
+     */
+    track: (eventName: string, payload?: AnalyticsPayload) => void;
+}
+declare function useAnalytics(): AnalyticsApi;
+
+/**
+ * Read app-provided data + manifest for a slug installed on the
+ * current store.
+ *
+ * Phase 6 wired this to the real backend at
+ * `/api/storefront/store/{store_id}/apps/{slug}`. Theme usage:
+ *
+ *     const recommend = useApp<RecommendationData>("recommendation-engine");
+ *     if (!recommend.available) return <Fallback />;
+ *     if (recommend.loading) return <Skeleton />;
+ *     return <RecommendList items={recommend.data?.products ?? []} />;
+ *
+ * `available` flips to true only when an enabled installation exists
+ * for the store. Apps the merchant hasn't installed surface as
+ * `{ 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.
+ */
+interface AppManifestBlock {
+    type: string;
+    name: string;
+    block_schema: Record<string, unknown>;
+}
+interface AppPayload<T = unknown> {
+    slug: string;
+    name: string;
+    description: string | null;
+    icon_url: string | null;
+    version: string;
+    manifest: Record<string, unknown>;
+    settings: Record<string, unknown>;
+    blocks: AppManifestBlock[];
+    /** App-provided data (shape defined by the app developer). Today
+     * the response always returns null for `data` — apps emit data via
+     * their `endpoints.data` URL, which the theme fetches separately.
+     * Surfaced here so the field is stable when v2 lands the proxy. */
+    data: T | null;
+}
+interface AppState<T = unknown> {
+    data: AppPayload<T> | null;
+    loading: boolean;
+    available: boolean;
+    error: Error | null;
+    /** Re-fetch the install. Returns a promise that resolves when the
+     * request settles (regardless of success). */
+    refresh: () => Promise<void>;
+}
+declare function useApp<T = unknown>(slug: string): AppState<T>;
+
+/**
+ * Wishlist hook with localStorage fallback.
+ *
+ * Architecture (Phase 4 lands the server side):
+ *   - Authenticated customer: persists to /api/customer/me/wishlist
+ *     (server-backed, syncs across devices).
+ *   - Anonymous visitor: persists to localStorage under
+ *     `numu_wishlist_<store_id>`. On login, the wishlist merges into
+ *     the server-side list (mirrors the cart's session→customer flow).
+ *
+ * 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.
+ */
+interface WishlistItem {
+    product_id: string;
+    /** Optional variant scoping — themes that show variant pickers can
+     *  wishlist a specific size/color combo separately. */
+    variant_id?: string | null;
+    /** Server timestamp once persistence lands; ms-since-epoch in v1. */
+    added_at: number;
+}
+interface WishlistState {
+    items: WishlistItem[];
+    loading: boolean;
+    has: (productId: string, variantId?: string | null) => boolean;
+    addToWishlist: (productId: string, variantId?: string | null) => void;
+    removeFromWishlist: (productId: string, variantId?: string | null) => void;
+    clear: () => void;
+}
+/**
+ * @param storeId The store the wishlist is scoped to. Pass `useShop().id`.
+ *                Without it, the hook can't keep one merchant's wishlist
+ *                from leaking into another's localStorage on a shared
+ *                domain (e.g. apex preview).
+ */
+declare function useWishlist(storeId: string): WishlistState;
+
+/**
+ * Fetch products related to the given product (same category, excluding
+ * self). Phase 3 lands collaborative-filtering / "frequently bought
+ * together"; v1 ships the simpler same-category-minus-self heuristic.
+ *
+ * Backend contract: GET /api/storefront/products/{id}/related?limit=N
+ *   → { items: 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.
+ */
+interface RelatedProductsState {
+    items: Product[];
+    loading: boolean;
+    error: Error | null;
+}
+declare function useRelatedProducts(productId: string | null | undefined, options?: {
+    limit?: number;
+}): RelatedProductsState;
+
+/**
+ * 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;
+
+/**
+ * Variant resolution helpers — Phase 8.1.
+ *
+ * Themes render a variant picker (Size + Color radios), then ask the
+ * SDK "given my current selection, which variant is it?" The matching
+ * variant's id is what add-to-cart sends.
+ */
+
+/**
+ * Pick the variant that exactly matches the given option_values map.
+ * Returns null when no variant matches — themes render that as
+ * "Combination unavailable" or a disabled buy button.
+ */
+declare function findVariantByOptions(product: Pick<Product, "variants">, selection: Record<string, string>): ProductVariant | null;
+/**
+ * Find the "default" variant — the one the PDP should auto-select on
+ * first render. Prefers the first in-stock variant; falls back to the
+ * first variant if all are out of stock (so the picker still shows
+ * something coherent).
+ */
+declare function defaultVariant(product: Pick<Product, "variants">): ProductVariant | null;
+/**
+ * Given a partial selection (e.g. just Size=M, no Color yet), return
+ * the set of values still available on each unselected axis. Themes
+ * use this to disable swatches whose paired variants are all out of
+ * stock for the current selection.
+ */
+declare function availableValues(product: Pick<Product, "options" | "variants">, selection: Record<string, string>): Record<string, Set<string>>;
+
+interface UseVariantSelection {
+    /** Currently-selected axis → value map. */
+    selection: Record<string, string>;
+    /** The variant matching the current selection, if any. */
+    variant: ProductVariant | null;
+    /** Pick a value on one axis. Other axes stay locked. */
+    select: (axis: string, value: string) => void;
+    /** Reset the selection (e.g. on "Choose another" button). */
+    reset: () => void;
+    /**
+     * For each unselected axis, the set of values that lead to at
+     * least one in-stock variant given the current locked axes.
+     * Themes use this to grey out swatches.
+     */
+    availability: Record<string, Set<string>>;
+    /**
+     * True when every option axis on the product has a chosen value
+     * and `variant` is resolved. Buy buttons should disable until
+     * this flips to true on products with options.
+     */
+    isComplete: boolean;
+}
+/**
+ * Hook that owns variant-axis selection state for a PDP.
+ *
+ * Initial state auto-selects the default variant's axis values so
+ * the PDP loads with a coherent price + image + buy state, matching
+ * Shopify's behavior. Themes that prefer "Choose your size" empty
+ * state can pass `autoSelect: false`.
+ */
+declare function useVariantSelection(product: Pick<Product, "options" | "variants">, opts?: {
+    autoSelect?: boolean;
+}): UseVariantSelection;
+
+/**
+ * Gift card balance check — Phase 8.3.
+ *
+ * Themes call this from the checkout payment step to validate a
+ * customer-typed code before sending it as part of the checkout
+ * payload. The backend returns 404 for any non-redeemable card
+ * (expired, depleted, voided, or wrong store) — the response shape
+ * stays uniform so the hook can't be used to probe for valid codes.
+ *
+ * Backend contract (via storefront proxy):
+ *   GET /api/gift-cards/{code}
+ *     → 200 { data: { last_four, current_balance_cents, currency,
+ *                     expires_at? } }
+ *     → 404 { error: { code, message } }
+ */
+interface GiftCardBalance {
+    last_four: string;
+    current_balance_cents: number;
+    currency: string;
+    expires_at: string | null;
+}
+interface UseGiftCardBalance {
+    /** Last lookup result, or null when nothing checked yet / failed. */
+    balance: GiftCardBalance | null;
+    /** True while a lookup is in flight. */
+    loading: boolean;
+    /** Latest error from the lookup, if any. Cleared on next check. */
+    error: Error | null;
+    /** Trigger a balance check. Returns the result or null on failure. */
+    check: (code: string) => Promise<GiftCardBalance | null>;
+    /** Clear the last result + error (e.g. when the user clears the input). */
+    reset: () => void;
+}
+declare function useGiftCardBalance(): UseGiftCardBalance;
+
+/**
+ * Reorder / "buy again" — Phase 8.5.
+ *
+ * Clones every line item from an existing order into the current cart.
+ * The backend skips lines whose product is deleted/archived, whose
+ * variant is gone, or that are out of stock — returning per-line
+ * reasons so themes can show a "couldn't add X items" banner.
+ *
+ * Backend contract:
+ *   POST /storefront/me/orders/{order_id}/reorder
+ *     → 200 { data: { added_count, skipped[], cart_total_items } }
+ *     → 404 if order doesn't belong to the current customer
+ */
+type ReorderSkipReason = "product_deleted" | "product_archived" | "out_of_stock" | "variant_unavailable";
+interface ReorderSkippedItem {
+    product_id: string;
+    variant_id: string | null;
+    quantity: number;
+    reason: ReorderSkipReason | string;
+}
+interface ReorderResult {
+    added_count: number;
+    skipped: ReorderSkippedItem[];
+    cart_total_items: number;
+}
+interface UseReorder {
+    /** Last reorder result. */
+    result: ReorderResult | null;
+    /** True while a reorder is in flight. */
+    loading: boolean;
+    /** Latest error, cleared on next reorder call. */
+    error: Error | null;
+    /** Trigger the reorder. Returns the result or null on failure. */
+    reorder: (orderId: string) => Promise<ReorderResult | null>;
+    /** Clear the last result + error (e.g. after dismissing the banner). */
+    reset: () => void;
+}
+declare function useReorder(): UseReorder;
+
+/**
+ * Programmatic checkout driver — Phase 7.6.
+ *
+ * The storefront's multi-step checkout pages (Phase 1.2) own the
+ * default flow: contact → shipping → payment → review → processing →
+ * thank-you. This hook gives themes a programmatic alternative so a
+ * BYOT theme can render the checkout exactly how it wants — single-
+ * page, accordion, full-bleed hero, whatever — without being forced
+ * through the platform's step pages.
+ *
+ * State lives in `numu_checkout_state` sessionStorage (same blob the
+ * platform's step pages use) so themes that drive checkout
+ * programmatically can hand off to the platform mid-flow (e.g. theme
+ * collects contact + shipping, then redirects to /checkout/payment
+ * for the gateway capture). The platform-side state machine guards
+ * deep-links via `hasContactStep / hasShippingStep / hasPaymentStep`
+ * regardless of how the state got populated.
+ *
+ * Usage:
+ *
+ *     const checkout = useCheckout();
+ *     checkout.contact.set({ email, phone, shipping_address });
+ *     await checkout.shipping.refresh();
+ *     checkout.shipping.select(rate.id);
+ *     checkout.payment.select("paymob");
+ *     const result = await checkout.placeOrder();
+ *     if (result.payment_url) window.location.assign(result.payment_url);
+ */
+type CheckoutStep = "contact" | "shipping" | "payment" | "review" | "processing";
+interface CheckoutAddress {
+    first_name?: string;
+    last_name?: string;
+    line1?: string;
+    line2?: string | null;
+    city?: string;
+    state?: string | null;
+    postal_code?: string | null;
+    country?: string;
+    phone?: string | null;
+}
+interface ShippingRateOption {
+    id: string;
+    name: string;
+    amount_cents: number;
+    currency: string;
+    estimated_days_min?: number | null;
+    estimated_days_max?: number | null;
+    carrier?: string | null;
+}
+interface CheckoutSessionState {
+    email: string;
+    phone: string;
+    shipping_address: CheckoutAddress;
+    selected_shipping_rate_id: string | null;
+    shipping_method: string | null;
+    payment_method: string | null;
+    cod_requested: boolean;
+    deposit_gateway: string | null;
+    saved_payment_method_id: string | null;
+    customer_notes: string;
+    coupon_code: string;
+}
+interface PlaceOrderResult {
+    order_id: string;
+    order_number: string;
+    total: number;
+    currency: string;
+    payment_status: string;
+    payment_url?: string | null;
+    payment_data?: Record<string, unknown> | null;
+}
+interface CheckoutApi {
+    state: CheckoutSessionState;
+    step: CheckoutStep;
+    contact: {
+        set: (input: {
+            email?: string;
+            phone?: string;
+            shipping_address?: CheckoutAddress;
+        }) => void;
+        isComplete: () => boolean;
+    };
+    shipping: {
+        rates: ShippingRateOption[] | null;
+        loading: boolean;
+        refresh: () => Promise<ShippingRateOption[]>;
+        select: (rateId: string) => void;
+        isComplete: () => boolean;
+    };
+    payment: {
+        select: (method: string, opts?: {
+            saved_payment_method_id?: string;
+            deposit_gateway?: string;
+        }) => void;
+        isComplete: () => boolean;
+    };
+    setNotes: (notes: string) => void;
+    setCoupon: (code: string) => void;
+    placeOrder: () => Promise<PlaceOrderResult>;
+    reset: () => void;
+}
+declare function useCheckout(): CheckoutApi;
+
+/**
+ * Fetch shipping rate options for an address — Phase 7.4.
+ *
+ * Themes that want to display rates on the cart page (Shopify
+ * pattern: "Shipping calculated at checkout — preview from cart")
+ * use this. It posts to /api/shipping/options the same way the
+ * platform's shipping step does, but as a self-contained hook so
+ * themes don't need to drive the full useCheckout() machinery for a
+ * simple display.
+ *
+ * Returns null when no address is provided (the typical pre-input
+ * state) — themes branch on `rates !== null` to decide whether to
+ * show the rates panel or a "Enter address" prompt.
+ *
+ * Optionally accepts a `location_id` for multi-location stores
+ * (Phase 8.2) — the resolver uses the named fulfilling location's
+ * origin address when calculating rates. Ignored if multi-location
+ * is off.
+ *
+ * Usage:
+ *
+ *     const { rates, loading, refresh } = useShippingRates({
+ *       address: { country: "EG", city: "Cairo" },
+ *     });
+ */
+interface UseShippingRatesOptions {
+    address?: CheckoutAddress | null;
+    location_id?: string | null;
+    /** Auto-fetch on mount + when the address changes. Default true. */
+    enabled?: boolean;
+}
+interface UseShippingRatesState {
+    rates: ShippingRateOption[] | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+declare function useShippingRates({ address, location_id, enabled, }?: UseShippingRatesOptions): UseShippingRatesState;
+
+interface NuMuProviderProps {
+    store: Store;
+    themeSettings: ThemeSettingsV3;
+    initialCart?: Cart;
+    customer?: Customer | null;
+    locale?: string;
+    translations?: Record<string, string>;
+    children: ReactNode;
+}
+declare function NuMuProvider({ store, themeSettings, initialCart, customer, locale: initialLocale, translations: initialTranslations, children, }: NuMuProviderProps): react_jsx_runtime.JSX.Element;
+
+interface ProductProviderProps {
+    product: Product;
+    children: ReactNode;
+}
+declare function ProductProvider({ product, children }: ProductProviderProps): react_jsx_runtime.JSX.Element;
+
+interface CollectionProviderProps {
+    collection: Collection;
+    children: ReactNode;
+}
+declare function CollectionProvider({ collection, children }: CollectionProviderProps): react_jsx_runtime.JSX.Element;
+
+interface MoneyProps {
+    /** Amount in major units (e.g. dollars, not cents). */
+    amount: number;
+    /** ISO-4217 currency code. Defaults to the active store's currency. */
+    currency?: string;
+    /**
+     * When the same product has both a sale price and a compare-at price,
+     * pass the higher (compare-at) value here and we'll render it with a
+     * strike-through next to the active price. Skipped when undefined or
+     * <= the main amount.
+     */
+    compareAt?: number;
+    className?: string;
+    /** Custom HTML element tag — defaults to `span`. */
+    as?: ElementType;
+}
+/**
+ * <Money amount={49.99} /> — formatted price, locale-aware.
+ *
+ * Wraps useLocalization().formatMoney so theme code stops re-implementing
+ * Intl.NumberFormat. Renders inline with `dir="auto"` so the digits
+ * flow naturally in RTL (Arabic) without flipping the currency symbol.
+ *
+ * Usage:
+ *   <Money amount={product.price} compareAt={product.compare_at_price} />
+ */
+declare function Money({ amount, currency, compareAt, className, as, }: MoneyProps): react.ReactElement<any, string | react.JSXElementConstructor<any>>;
+
+interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "srcSet"> {
+    src: string | undefined | null;
+    alt: string;
+    /**
+     * Comma-separated breakpoints for the `sizes` attribute. Default
+     * matches a typical responsive grid:
+     *   "(min-width: 1024px) 25vw, (min-width: 640px) 50vw, 100vw"
+     */
+    sizes?: string;
+    /**
+     * When true (default), generate a `srcSet` with several widths.
+     * Disable for above-the-fold hero images where you want a single
+     * source under direct theme control.
+     */
+    responsive?: boolean;
+    /**
+     * Loading strategy. Default "lazy" matches Shopify themes; pass
+     * "eager" for above-the-fold imagery.
+     */
+    loading?: "eager" | "lazy";
+}
+/**
+ * <Image> — drop-in replacement for `<img>` with srcSet + lazy loading
+ * defaults. Themes should use this everywhere they'd otherwise write a
+ * raw `<img>` so merchant-uploaded images get responsive variants and
+ * lazy loading without per-section work.
+ *
+ * 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, className, style, ...rest }: ImageProps): react_jsx_runtime.JSX.Element;
+
+interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+    /**
+     * Path relative to the storefront root, e.g. "/products/foo",
+     * "/collections/all", "/cart", "/pages/about". External URLs (with
+     * a protocol) are passed through unchanged.
+     */
+    to: string;
+    children: ReactNode;
+}
+/**
+ * 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_runtime.JSX.Element;
+
+interface AddToCartButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onClick" | "disabled"> {
+    product: Product;
+    variant?: ProductVariant;
+    quantity?: number;
+    /** Custom labels — fallbacks are English defaults. */
+    label?: ReactNode;
+    loadingLabel?: ReactNode;
+    soldOutLabel?: ReactNode;
+    errorLabel?: ReactNode;
+    /** Called after successful addition. Useful for analytics events. */
+    onAdded?: (product: Product, variant?: ProductVariant) => void;
+}
+/**
+ * Themed Add-to-Cart button with built-in loading/disabled/error states.
+ *
+ * Wraps useCart().addItem and tracks its own UX state machine:
+ *   idle → adding → idle (or → error briefly, then idle)
+ *
+ * Renders a regular `<button>` so themes style it with whatever class
+ * names they want — we only own the disabled/aria-busy logic and label
+ * swaps. If the variant (or product) is out of stock, button is
+ * disabled and shows soldOutLabel.
+ *
+ * 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_runtime.JSX.Element;
+
+interface SectionProps extends HTMLAttributes<HTMLElement> {
+    /** Section instance id (the order key in templates). Required for the
+     * customizer's click-to-select to work. */
+    id: string;
+    /** Section type as registered in the theme registry / schemas. */
+    type: string;
+    /** Section group id (header / footer / announcement-bar) when this
+     * section is mounted inside a group rather than a page template. */
+    groupId?: string;
+    /** Override the fallback shown when this section throws. Defaults to
+     * a small inline error card (visible to the merchant in the customizer,
+     * invisible to live shoppers — see CSS comment below). */
+    errorFallback?: ReactNode;
+    children: ReactNode;
+}
+/**
+ * <Section> — wrapper that emits the `data-section-id` / `data-section-type`
+ * attributes the storefront's PreviewBridge needs to relay clicks back
+ * to the V3 customizer for "select section X" navigation.
+ *
+ * Use this around the top-level element of every section component:
+ *
+ *   export default function Hero({ settings, ...sectionMeta }) {
+ *     return (
+ *       <Section id={sectionMeta.id} type="hero">
+ *         <h1>{settings.headline}</h1>
+ *       </Section>
+ *     );
+ *   }
+ *
+ * Without `data-section-id` on a real DOM ancestor, clicking anywhere
+ * in the section in the customizer iframe falls through to the page
+ * background and the merchant has to use the section list panel to
+ * select sections — slow and confusing.
+ *
+ * Errors thrown by `children` are caught by an internal ErrorBoundary
+ * so one bad section doesn't unmount its siblings. Customize the
+ * fallback via `errorFallback`.
+ */
+declare function Section({ id, type, groupId, errorFallback, children, ...rest }: SectionProps): react_jsx_runtime.JSX.Element;
+interface BlockProps extends HTMLAttributes<HTMLDivElement> {
+    /** Block instance id within its parent section. */
+    id: string;
+    type: string;
+    /** Override the fallback shown when this block throws. */
+    errorFallback?: ReactNode;
+    children: ReactNode;
+}
+/**
+ * <Block> — analog to <Section> for nested block selection. Same DOM
+ * attribute contract; PreviewBridge reads `data-block-id` and reports
+ * the block as selected when its child clicks bubble up.
+ *
+ * Wraps `children` in the same per-instance ErrorBoundary as <Section>
+ * so a bad block within a section isolates its failure.
+ */
+declare function Block({ id, type, errorFallback, children, ...rest }: BlockProps): react_jsx_runtime.JSX.Element;
+
+interface FormProps extends Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit" | "method" | "action" | "children" | "onError"> {
+    /**
+     * Endpoint to POST/etc. the form values to. Should be one of the
+     * storefront's `/api/*` proxy routes — they handle CSRF + cookie
+     * forwarding + idempotency on the way to FastAPI.
+     */
+    action: string;
+    /**
+     * HTTP method. POST is the typical theme use-case (newsletter,
+     * contact, customer login, address create). GET is supported for
+     * search-style forms.
+     */
+    method?: "POST" | "GET" | "PUT" | "DELETE";
+    /**
+     * Called with the JSON-decoded response body on success. Use to
+     * trigger a toast, redirect, etc. Theme owns the UX.
+     */
+    onSuccess?: (response: unknown) => void;
+    /**
+     * Called with the Error on failure. Falls through to the default
+     * error label otherwise.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Render-prop access to the in-flight state if the theme wants to
+     * show its own loading / disabled / error UI. Default `children`
+     * behavior just lets the form's inputs and submit button render —
+     * we don't impose styling.
+     */
+    children?: ReactNode | ((state: {
+        submitting: boolean;
+        error: Error | null;
+    }) => ReactNode);
+}
+/**
+ * <Form action="/api/cart/add" method="POST" onSuccess={...}>
+ *
+ * Theme-friendly wrapper around `<form>` that handles:
+ *   - CSRF: reads `numu_csrf` cookie, sends as `x-numu-csrf` header on
+ *     every mutating request. Same wire format as <NuMuProvider>'s
+ *     cart machinery — interoperates seamlessly.
+ *   - Idempotency: mints a UUID per submit, sends as
+ *     `x-numu-idempotency-key`. Backend dedupes if it supports the
+ *     header (cart endpoints today; more later).
+ *   - Submit lifecycle: tracks `submitting` + `error` state and
+ *     either passes them to a render-prop child or wires them to a
+ *     submit-button's `disabled` automatically.
+ *   - Throws away page navigation: `onSubmit` calls preventDefault and
+ *     fetches via JSON. Themes that want classic POST-and-navigate
+ *     can drop down to a plain `<form>`.
+ *
+ * Refuses to submit to absolute URLs (must point at the storefront
+ * itself or an `/api/*` proxy) so a misconfigured theme can't leak
+ * customer data to a third party origin.
+ */
+declare function Form({ action, method, onSuccess, onError, children, ...rest }: FormProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Opinionated product tile.
+ *
+ * Themes drop this anywhere a product list is needed — collection
+ * pages, search results, recommendations, recently-viewed grids.
+ * Renders image + title + price (with compare-at strike-through when
+ * present) + an optional "Sold out" badge + AddToCartButton.
+ *
+ * The component is **unstyled by default** — it ships only structural
+ * markup with stable class names. Themes provide the CSS. Class names
+ * use a `numu-product-card__*` BEM convention so themes can target
+ * pieces without grep-and-replace if NUMU later renames anything.
+ *
+ * Class hooks:
+ *   .numu-product-card           — root <article>
+ *   .numu-product-card__link     — wrapping <a>
+ *   .numu-product-card__media    — image container
+ *   .numu-product-card__image    — the <img> itself
+ *   .numu-product-card__badge    — "Sold out" overlay
+ *   .numu-product-card__title    — title <h3>
+ *   .numu-product-card__price    — price wrapper
+ *   .numu-product-card__cta      — CTA wrapper (AddToCartButton)
+ *
+ * Themes can override any piece by passing `slots`:
+ *   <ProductCard product={p} slots={{ price: <CustomPrice /> }} />
+ *
+ * For deeper customization, themes should compose the primitives
+ * (Image / Money / Link / AddToCartButton) directly instead.
+ */
+interface ProductCardSlots {
+    /** Replaces the badge area (default: "Sold out" when out of stock, else nothing). */
+    badge?: ReactNode;
+    /** Replaces the title `<h3>` block. */
+    title?: ReactNode;
+    /** Replaces the price `<Money>` block. */
+    price?: ReactNode;
+    /** Replaces the AddToCartButton. Pass `null` to hide it. */
+    cta?: ReactNode | null;
+}
+interface ProductCardProps {
+    product: Product;
+    /** Override the link target. Default: `/products/{slug}`. */
+    href?: string;
+    className?: string;
+    slots?: ProductCardSlots;
+    /**
+     * Image sizing hint for the responsive srcSet. Default: a 4-up grid
+     * sizing (~25vw at desktop, ~50vw at tablet, ~100vw at mobile).
+     * Override when rendering in a different layout density.
+     */
+    imageSizes?: string;
+}
+declare function ProductCard({ product, href, className, slots, imageSizes, }: ProductCardProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Opinionated collection tile.
+ *
+ * Renders a single collection's hero image + name + product count.
+ * Used by collection-list sections, footer "Featured collections"
+ * blocks, and search-result mixed views.
+ *
+ * Unstyled by default; themes ship the CSS. Class hooks:
+ *   .numu-collection-card           — root <article>
+ *   .numu-collection-card__link     — wrapping <a>
+ *   .numu-collection-card__media    — image container
+ *   .numu-collection-card__image    — the <img>
+ *   .numu-collection-card__title    — title <h3>
+ *   .numu-collection-card__count    — product count line
+ */
+interface CollectionCardSlots {
+    title?: ReactNode;
+    /** Replaces the "N products" line. Pass null to hide it. */
+    count?: ReactNode | null;
+}
+interface CollectionCardProps {
+    collection: Collection;
+    /** Override the link target. Default: `/collections/{slug}`. */
+    href?: string;
+    className?: string;
+    slots?: CollectionCardSlots;
+    imageSizes?: string;
+}
+declare function CollectionCard({ collection, href, className, slots, imageSizes, }: CollectionCardProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * <RichText html=... /> — sanitized HTML renderer.
+ *
+ * Wraps `dangerouslySetInnerHTML` so theme code stops calling it
+ * directly with merchant-supplied content. Themes that need to render
+ * rich-text fields (product descriptions, page bodies, blog articles,
+ * policy bodies) go through this so an XSS in a single field can't
+ * cross-contaminate the whole storefront.
+ *
+ * **Why a built-in allowlist sanitizer instead of DOMPurify?**
+ * The audit plan called for DOMPurify, but adding it as a hard dep
+ * inflates every theme bundle by ~12KB gzipped — and the merchant-
+ * editable surface is small enough (a fixed set of formatting tags +
+ * links + images) that a curated allowlist is both smaller AND easier
+ * to reason about. If a theme needs richer sanitization (embeds,
+ * iframes, MathML), it can import DOMPurify directly and pre-sanitize
+ * before passing the result here.
+ *
+ * Allowed tags:
+ *   p, br, hr, h1-h6, blockquote, pre, code,
+ *   strong, b, em, i, u, s, sub, sup, mark,
+ *   ul, ol, li, dl, dt, dd,
+ *   a (href, target, rel only),
+ *   img (src, alt, width, height, loading only — http(s) URLs only),
+ *   table, thead, tbody, tr, th, td,
+ *   span, div (with class attribute only).
+ *
+ * Stripped:
+ *   <script>, <style>, <iframe>, <object>, <embed>, <link>, <meta>,
+ *   form/input, on*= handlers, javascript:/data: URLs, srcset on
+ *   <img> (we let the storefront's image-transform handle that
+ *   uniformly).
+ */
+interface RichTextProps {
+    html: string | null | undefined;
+    className?: string;
+    /** Element to render — defaults to `<div>`. Use `<article>` for body content. */
+    as?: "div" | "article" | "section" | "aside";
+}
+/**
+ * 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).
+ */
+declare function sanitizeHtml(input: string): string;
+declare function RichText({ html, className, as }: RichTextProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * <CurrencySwitcher /> — wired in Phase 6.
+ *
+ * Reads presentment currencies + the persisted selection from
+ * `useCurrency()`, which talks to
+ * `/api/storefront/store/{id}/currencies`. Changing the dropdown
+ * writes the `numu_currency` cookie via the hook, which then
+ * propagates to `<Money>`'s display.
+ *
+ * Renders nothing when the store offers only one currency — themes
+ * can drop the component into a layout without conditional render.
+ *
+ * Pass `render` to take over the markup completely (e.g. a custom
+ * dropdown component or a flag-icon grid).
+ */
+interface CurrencySwitcherProps {
+    className?: string;
+    onSelect?: (currency: string) => void;
+    render?: (state: {
+        currencies: string[];
+        current: string;
+        onChange: (next: string) => void;
+    }) => React.ReactNode;
+}
+declare function CurrencySwitcher({ className, onSelect, render, }: CurrencySwitcherProps): react_jsx_runtime.JSX.Element | null;
+
+interface LocaleSwitcherProps {
+    className?: string;
+    onSelect?: (locale: string) => void;
+    /** Custom renderer. Receives the resolved locale list + current selection. */
+    render?: (state: {
+        locales: string[];
+        current: string;
+        labelFor: (code: string) => string;
+        onChange: (next: string) => void;
+    }) => React.ReactNode;
+}
+declare function LocaleSwitcher({ className, onSelect, render, }: LocaleSwitcherProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Module Federation singleton sharing for @numueg/theme-sdk.
+ *
+ * Why this exists:
+ *   BYOT bundles (loaded at runtime as cross-origin ESM modules) need to
+ *   share React + the SDK with the host storefront. Otherwise React's
+ *   internal "two copies" check trips and hooks crash. The host registers
+ *   its singletons here; the BYOT bundle reads them via the SDK shim.
+ *
+ * Threat model:
+ *   We do NOT want third-party scripts (analytics, chat widgets, BYOT
+ *   community themes) to read PII off the SDK. The earlier version stored
+ *   the SDK on `window.__NUMU_SDK__` — anything in the page could read it
+ *   and call `useCustomer()` etc.
+ *
+ * Mitigation:
+ *   The singleton is keyed by a Symbol that's only handed to consumers
+ *   we've verified (the storefront's BYOT entry function passes it to the
+ *   bundle's `setup()`). Symbols can't be enumerated through `window` or
+ *   `Object.getOwnPropertyNames`, so a leaked global reference doesn't
+ *   yield SDK access.
+ *
+ *   For maximum safety we also expose `clearSdkSingleton()` so the host
+ *   can revoke after a BYOT theme is unmounted.
+ */
+interface SdkSingleton {
+    useShop: unknown;
+    useProduct: unknown;
+    useCollection: unknown;
+    useCart: unknown;
+    useCustomer: unknown;
+    useThemeSettings: unknown;
+    useLocalization: unknown;
+    usePage: unknown;
+    useSection: unknown;
+    NuMuProvider: unknown;
+    ProductProvider: unknown;
+    CollectionProvider: unknown;
+}
+interface ReactSingleton {
+    React: unknown;
+    ReactDOM: unknown;
+}
+declare function registerSdkSingleton(sdk: SdkSingleton): void;
+declare function getSdkSingleton(): SdkSingleton | null;
+declare function registerReactSingleton(react: unknown, reactDom: unknown): void;
+declare function getReactSingleton(): ReactSingleton | null;
+declare function isSdkAvailable(): boolean;
+
+/**
+ * Section + block authoring helpers.
+ *
+ * `defineSection` and `defineBlock` bind a JSON schema to its render
+ * component so theme authors don't keep two files in sync by hand.
+ * The plugin ships the schema half (writes `schemas/sections/<type>.json`
+ * for the customizer), the runtime imports the component half — both
+ * sourced from the same factory call.
+ *
+ * Why factories instead of two separate files:
+ *   Pre-Phase-2 layout was:
+ *     theme/main.tsx        → registers components
+ *     theme/schemas/sections/Hero.json → declares schema
+ *   Drift was the bug. Renaming a setting required edits in two places;
+ *   adding a new section meant remembering to update three lists.
+ *   Factories collapse that into a single export the plugin and runtime
+ *   both read.
+ *
+ * Usage:
+ *   // sections/Hero.tsx
+ *   import { defineSection } from "@numueg/theme-sdk";
+ *   export default defineSection({
+ *     schema: {
+ *       type: "hero",
+ *       name: "Hero",
+ *       settings: [{ type: "text", id: "heading", label: "Heading" }],
+ *       presets: [{ name: "Hero — Centered", settings: { heading: "Welcome" } }],
+ *     },
+ *     render: ({ settings }) => <h1>{settings.heading}</h1>,
+ *   });
+ *
+ * The plugin's section-discovery scan picks up files under
+ * `src/sections/**\/*.{tsx,ts}` whose default export is a section
+ * definition. No registration list needed.
+ */
+
+declare const SECTION_MARKER: unique symbol;
+declare const BLOCK_MARKER: unique symbol;
+/**
+ * A defined section: paired schema + render component.
+ *
+ * The marker symbol lets the plugin's discovery scan identify section
+ * definitions without depending on a structural shape that themes might
+ * accidentally collide with.
+ */
+interface DefinedSection {
+    schema: SectionSchema;
+    render: ComponentType<SectionProps$1>;
+    readonly [SECTION_MARKER]: true;
+}
+interface DefinedBlock {
+    schema: BlockSchema;
+    render: ComponentType<BlockProps$1>;
+    readonly [BLOCK_MARKER]: true;
+}
+interface DefineSectionInput {
+    schema: SectionSchema;
+    render: ComponentType<SectionProps$1>;
+}
+interface DefineBlockInput {
+    schema: BlockSchema;
+    render: ComponentType<BlockProps$1>;
+}
+/**
+ * Bind a section schema to its renderer.
+ *
+ * Validates at runtime that `schema.type` is a stable identifier
+ * (lowercase + dashes/underscores) — drift here breaks the plugin's
+ * codegen step (which writes `__generated__/sections.d.ts` keyed off
+ * `schema.type`).
+ */
+declare function defineSection(input: DefineSectionInput): DefinedSection;
+declare function defineBlock(input: DefineBlockInput): DefinedBlock;
+declare function isDefinedSection(v: unknown): v is DefinedSection;
+declare function isDefinedBlock(v: unknown): v is DefinedBlock;
+/**
+ * Build a section registry from a Vite glob import.
+ *
+ * Themes call this at the top of their `main.tsx`:
+ *
+ *   const sectionModules = import.meta.glob<{ default: DefinedSection }>(
+ *     "./sections/*.tsx", { eager: true });
+ *   const sections = collectSections(sectionModules);
+ *
+ * The returned object is keyed by `schema.type` for direct lookup at
+ * render time. Modules whose default export isn't a DefinedSection are
+ * skipped with a console warning (drops a half-migrated section without
+ * breaking the rest of the bundle).
+ */
+declare function collectSections<T extends Record<string, unknown>>(modules: T): Record<string, DefinedSection>;
+declare function collectBlocks<T extends Record<string, unknown>>(modules: T): Record<string, DefinedBlock>;
+
+/**
+ * `assetUrl(name)` — resolve a theme-bundled asset's runtime URL.
+ *
+ * Themes ship static assets (images, fonts, JSON) under `assets/`.
+ * The plugin copies each asset to `dist/assets/` with a content-hashed
+ * filename and writes a manifest (`asset-manifest.json`) mapping each
+ * source path to the hashed name.
+ *
+ * At runtime this function reads the manifest off the runtime window
+ * object (`window.__NUMU_ASSET_MANIFEST`) — populated by the storefront's
+ * `<RuntimeImportMap>` component when the theme bundle is loaded —
+ * and returns the absolute URL to the hashed file.
+ *
+ * Why a runtime helper instead of bake-time string interpolation:
+ *   The same theme bundle is reused across hosted stores. The asset
+ *   base URL differs per environment (CDN vs local dev) and per store
+ *   (subdomain vs custom domain). Resolving at runtime keeps a single
+ *   bundle deployable across all of them.
+ *
+ * Usage:
+ *   <Image src={assetUrl("hero.jpg")} alt="..." />
+ *   <link rel="preload" as="font" href={assetUrl("fonts/Inter.woff2")} />
+ *
+ * Behavior when the manifest is missing or the asset isn't listed:
+ *   Returns the original `name` (prefixed with the conventional
+ *   `/assets/` path) as a fallback. This keeps dev workable when the
+ *   plugin's asset-pipeline step hasn't run yet, and surfaces obviously-
+ *   wrong asset names as 404s rather than silent failures.
+ */
+declare function assetUrl(name: string): string;
+
+/**
+ * Theme-bundled locale files: load + merge.
+ *
+ * The plugin discovers `locales/<code>.json` (and the fallback
+ * `locales/en.default.json`) and bakes them into the bundle as a map
+ * keyed by locale code. The runtime calls `pickTranslations(map, locale)`
+ * to resolve the right one, with English fallback for missing keys.
+ *
+ * Conventions:
+ *   - locales/en.default.json is the canonical English source. It's
+ *     the fallback for any other locale's missing keys.
+ *   - locales/ar.json (and friends) override or extend the default.
+ *   - Nested keys are flattened with dot notation: `{"hero": {"cta": "Buy"}}`
+ *     becomes `"hero.cta"` for `t("hero.cta")` to look up.
+ *
+ * Why flatten:
+ *   `useTranslation()` returns `t(key)` which expects a string lookup —
+ *   structured access would force every theme to write
+ *   `translations.hero?.cta ?? "Buy"`. Flattening keeps the call site
+ *   short and matches Shopify's `t` semantics.
+ */
+interface LocaleMessages {
+    [key: string]: string;
+}
+interface LocaleBundle {
+    /** Locale code → flat key/value messages. */
+    [locale: string]: LocaleMessages;
+}
+/**
+ * Recursively flatten a nested locale object into dot-keyed strings.
+ *
+ * Non-string leaves are skipped with a console warning — translations
+ * are user-facing strings; numbers and booleans don't belong in a
+ * locale file (they should be in schema settings).
+ */
+declare function flattenMessages(source: Record<string, unknown>, prefix?: string): LocaleMessages;
+/**
+ * Resolve the messages map for the requested locale, falling back to
+ * "en" then "en.default" then an empty map. Missing keys in the
+ * requested locale are filled from "en" (so an Arabic translation
+ * file with 90% coverage doesn't show empty strings for the missing
+ * 10%; English shows through).
+ */
+declare function pickTranslations(bundle: LocaleBundle, locale: string): LocaleMessages;
+/**
+ * Build a LocaleBundle from raw imports. Themes call this in their
+ * `main.tsx` after a Vite glob import:
+ *
+ *   const localeModules = import.meta.glob<Record<string, unknown>>(
+ *     "./locales/*.json", { eager: true, import: "default" });
+ *   const translations = buildLocaleBundle(localeModules);
+ *
+ * `localeModules` keys are paths like `./locales/ar.json`; we strip
+ * the directory + extension to get the locale code, and flatten each
+ * value.
+ */
+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, BlockProps$1 as BlockProps, BlockSchema, Cart, CartContext, type CheckoutAddress, type CheckoutApi, type CheckoutSessionState, type CheckoutStep, Collection, CollectionCard, type CollectionCardProps, type CollectionCardSlots, CollectionContext, CollectionProvider, type CurrencyConfig, type CurrencyState, CurrencySwitcher, type CurrencySwitcherProps, Customer, type CustomerAddress, type CustomerAddressesState, CustomerContext, type DefineBlockInput, type DefineSectionInput, type DefinedBlock, type DefinedSection, Form, type GiftCardBalance, Image, Link, type LocaleBundle, type LocaleMessages, LocaleSwitcher, type LocaleSwitcherProps, LocalizationContext, Money, type NavigationItem, type NavigationState, NuMuProvider, type OrderDetail, type OrderListEntry, type OrderListState, type OrderState, Page, PageContext, type PlaceOrderResult, Product, ProductCard, type ProductCardProps, type ProductCardSlots, ProductContext, 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, ShopContext, type ShopWithHelpers, Store, ThemeSettingsContext, ThemeSettingsV3, type UseGiftCardBalance, type UseReorder, type UseSearchOptions, type UseShippingRatesOptions, type UseShippingRatesState, type UseVariantSelection, type WishlistItem, type WishlistState, assetUrl, availableValues, buildLocaleBundle, collectBlocks, collectSections, defaultVariant, defineBlock, defineSection, findVariantByOptions, flattenMessages, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isSdkAvailable, pickTranslations, registerReactSingleton, registerSdkSingleton, sanitizeHtml, useAnalytics, useApp, useCart, useCheckout, useCollection, useCollectionOptional, useCollections, useCurrency, useCustomer, useCustomerActions, useCustomerAddresses, useDirection, useFieldTranslation, useGiftCardBalance, useImage, useLocale, useLocalization, useMoney, useNavigation, useNumberFormat, useOrder, useOrders, usePage, useProduct, useProductOptional, useProducts, useRelatedProducts, useReorder, useSearch, useSection, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist };