@numueg/theme-sdk 0.1.2 → 0.2.0

package/dist/index.d.mts

@@ -1,10 +1,9 @@
-import { S as Store, P as Product, C as Collection, a as Cart, b as Customer, c as Page, d as ProductVariant } from './index-zSb0FIyh.mjs';
-export { A as Address, e as CartItem, O as Order, f as OrderItem, g as ProductImage, h as ProductOption } from './index-zSb0FIyh.mjs';
-import { T as ThemeSettingsV3, S as SectionInstance, B as BlockSchema, a as BlockProps$1, b as SectionSchema, c as SectionProps$1 } from './theme-NWJAU9jd.mjs';
-export { d as BlockInstance, E as ExternalThemeMetadata, P as PageTemplate, e as SectionGroup, f as SectionPreset, g as SettingDefinition } from './theme-NWJAU9jd.mjs';
+import { S as Store, e as Product, b as Collection, C as Cart, c as Customer, P as Page, g as ProductVariant } from './entities-iiuRSPpk.mjs';
+export { A as Address, a as CartItem, O as Order, d as OrderItem, f as ProductImage, h as ProductOption } from './entities-iiuRSPpk.mjs';
+import { T as ThemeSettingsV3, c as SectionInstance, M as MountResult, B as BlockInstance, b as BlockSchema, a as BlockProps$1, f as SectionSchema, e as SectionProps$1 } from './theme-D0QybTQS.mjs';
+export { E as ExternalThemeMetadata, h as MAX_BLOCK_DEPTH, P as PageTemplate, i as PresetBlock, S as SectionGroup, d as SectionPreset, g as SettingDefinition } from './theme-D0QybTQS.mjs';
 import * 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.mjs';
 
 /**
@@ -57,6 +56,32 @@ declare function useCustomer(): Customer | null;
 
 declare function useThemeSettings(): ThemeSettingsV3;
 
+/**
+ * useCurrentTemplate — read the active page template's id.
+ *
+ * Values are the same strings used as keys in
+ * `themeSettings.templates.<id>`:
+ *
+ *   "home" | "product" | "collection" | "cart" | "checkout"
+ *   "order-confirmation" | "profile" | "page" | "404" | "password"
+ *
+ * Themes use this to render the matching section list:
+ *
+ *   const template = useCurrentTemplate();
+ *   const settings = useThemeSettings();
+ *   const sections = settings.templates?.[template]?.sections ?? {};
+ *
+ * Default: "home" — when the host hasn't supplied a CurrentTemplate
+ * provider, themes still render their home template instead of
+ * crashing or showing a blank screen.
+ *
+ * The hook is read-only; the active template changes via the host
+ * navigating between Next.js routes (each route's `page.tsx` wraps
+ * its content with the correct currentTemplate at the
+ * `<NuMuProvider currentTemplate="…">` prop).
+ */
+declare function useCurrentTemplate(): string;
+
 interface LocalizationState {
     locale: string;
     direction: "ltr" | "rtl";
@@ -105,6 +130,35 @@ 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>;
+/**
+ * A merchant-managed navigation menu item, exactly as the storefront
+ * menus resolver returns it (`GET /storefront/store/{id}/menus`):
+ * bilingual `label`, a pre-resolved `url`, and nested `children`.
+ *
+ * This is the RAW shape the host injects via `NuMuProvider`'s
+ * `navigation` prop. `useNavigation(handle)` localizes it to the
+ * display-ready `NavigationItem` (a single `title` string for the
+ * active locale).
+ */
+interface MenuItemData {
+    id: string;
+    label: Record<string, string>;
+    url: string;
+    type?: string | null;
+    resource_id?: string | null;
+    children?: MenuItemData[];
+}
+/**
+ * Phase 2.4 — navigation menus keyed by handle (`main-menu`, `footer`,
+ * plus custom), injected by the host from the storefront resolver so a
+ * theme's `useNavigation(handle)` resolves without a client round-trip.
+ *
+ * Defaults to `{}` — an empty map signals "host provided no menus", at
+ * which point `useNavigation` falls back to its own fetch / a theme's
+ * `DEFAULT_NAV`. A present-but-handle-absent map means the menu simply
+ * doesn't exist (render nothing / fallback), no fetch attempted.
+ */
+declare const NavigationContext: react.Context<Record<string, MenuItemData[]>>;
 
 declare function useLocalization(): LocalizationState;
 declare function useDirection(): "ltr" | "rtl";
@@ -443,19 +497,17 @@ interface NavigationState {
 /**
  * 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.
+ * Resolution order (Phase 2.4):
+ *   1. Host-injected menus — the storefront resolves menus server-side
+ *      (`GET /storefront/store/{id}/menus`) and injects them via
+ *      `NuMuProvider`'s `navigation` prop → `NavigationContext`. When the
+ *      handle is present we localize + return it synchronously, no fetch.
+ *      A non-empty map that lacks the handle means "no such menu" → [].
+ *   2. `options.initialItems` — a theme that pre-fetched its own list.
+ *   3. Client fetch of `GET /api/storefront/navigation/{handle}` — the
+ *      legacy fallback for hosts that inject nothing. On 404 / network
+ *      error the hook resolves to [] (a missing menu is a soft failure;
+ *      the theme falls back to its own DEFAULT_NAV).
  */
 declare function useNavigation(handle: string, options?: {
     initialItems?: NavigationItem[];
@@ -511,11 +563,11 @@ declare function useSearch(query: string, options?: UseSearchOptions): SearchSta
  *
  * 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.
+ *      payload. The host storefront proxies to FastAPI's funnel-event
+ *      endpoint (/storefront/store/{id}/track) and fans out to
+ *      merchant-configured pixels (GA4 Measurement Protocol, Meta CAPI,
+ *      TikTok Events API). Failed pixels never block the UI — we
+ *      don't await the response.
  *   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
@@ -527,6 +579,17 @@ declare function useSearch(query: string, options?: UseSearchOptions): SearchSta
  *   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.
+ *
+ * Funnel-event mapping
+ * --------------------
+ * Standard event names that map to the backend's funnel steps are
+ * dispatched with the full funnel-event payload shape (path,
+ * session_fingerprint, attribution envelope from
+ * window.__numu_attribution). This is what powers the merchant
+ * funnel / journey / multi-touch attribution dashboards. Events with
+ * no funnel mapping still POST with the loose `{event, payload}`
+ * shape — the proxy forwards them so the pixel-fanout layer still
+ * fires.
  */
 interface AnalyticsPayload {
     /** Standard or custom event name. Lowercase + underscores recommended. */
@@ -539,6 +602,32 @@ interface AnalyticsApi {
      */
     track: (eventName: string, payload?: AnalyticsPayload) => void;
 }
+interface AttributionEnvelope {
+    v?: number;
+    first_touch?: unknown;
+    last_touch?: unknown;
+    session_id?: string | null;
+}
+interface NumuAttributionBridge {
+    get(): AttributionEnvelope | null;
+}
+interface NumuCustomerBridge {
+    /** Authenticated customer's UUID, or null when the visitor is a guest. */
+    getId(): string | null;
+}
+declare global {
+    interface Window {
+        __numu_attribution?: NumuAttributionBridge;
+        /**
+         * Optional bridge installed by the host storefront's customer
+         * provider. When set, the SDK includes ``customer_id`` on
+         * funnel-step events so the backend can record touches against
+         * the authenticated customer immediately instead of waiting for
+         * the next checkout to backfill.
+         */
+        __numu_customer?: NumuCustomerBridge;
+    }
+}
 declare function useAnalytics(): AnalyticsApi;
 
 /**
@@ -983,6 +1072,115 @@ interface UseShippingRatesState {
 }
 declare function useShippingRates({ address, location_id, enabled, }?: UseShippingRatesOptions): UseShippingRatesState;
 
+/**
+ * `mountTheme(el, ctx, renderApp)` — the canonical V3 bundle entry helper.
+ *
+ * ## Why this exists
+ *
+ * Every theme bundle exports `mount(el, ctx): MountResult`. Historically each
+ * theme hand-wrote that function, and the wiring it needs is non-trivial and
+ * easy to get wrong:
+ *
+ *   1. **Forward the real catalog.** The host ships the page's products /
+ *      collections in `ctx.page.data` (home + listing routes) and the product
+ *      in `ctx.page.data.product` (PDP). A theme that doesn't pass these into
+ *      `NuMuProvider` (+ wrap the PDP in `<ProductProvider>`) sees
+ *      `useProducts()` / `useProductOptional()` return empty on a REAL store —
+ *      so product sections render "No products yet" or fall back to demo data
+ *      on a stocked merchant. This was the single most common BYOT bug:
+ *      only bon-younes wired it; the other 13 themes dropped the catalog.
+ *
+ *   2. **Apply global style tokens.** Merchant-chosen colors/fonts live in
+ *      `themeSettings.global_settings`; they only paint if the bundle calls
+ *      `applyGlobalStyleTokens` on its mount root (and resolves font tokens
+ *      to real stacks + injects the webfont link). Themes that skipped this
+ *      ignored every color/font picker.
+ *
+ *   3. **Forward navigation.** `useNavigation(handle)` only resolves the
+ *      header/footer menus the host pre-resolved if the bundle passes
+ *      `ctx.navigation` into `NuMuProvider`.
+ *
+ *   4. **Live-preview + lifecycle.** The customizer streams draft settings via
+ *      the host's `applyDraft`; the bundle must hold them in state and re-paint
+ *      the style tokens on every draft. And it must return a `MountResult`
+ *      (`cleanup` + `applyDraft`) the host's `ByotThemeBoundary` understands.
+ *
+ * `mountTheme` does all of that once, so a theme's `main.tsx` collapses to:
+ *
+ * ```tsx
+ * import { mountTheme } from "@numueg/theme-sdk";
+ * export function mount(el, ctx) {
+ *   return mountTheme(el, ctx, ({ currentTemplate }) =>
+ *     <ThemeApp currentTemplate={currentTemplate} />,
+ *   );
+ * }
+ * ```
+ *
+ * The theme owns only its section list (`ThemeApp`). Everything in the list
+ * above is handled here — fix it once, every theme benefits.
+ *
+ * ## Both ctx shapes
+ *
+ * The host (numu-storefront `ByotThemeBoundary`) passes
+ * `{ themeSettings, storeData, page, locale, demo, navigation }`. Older / dev
+ * contexts used `{ store, currentTemplate }`. We normalise both so a bundle
+ * built against this helper works regardless of which host calls it.
+ */
+
+/** Minimal page descriptor the host forwards in the mount context. */
+interface ThemeMountPage {
+    type?: string;
+    handle?: string;
+    title?: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * The mount context a host (or dev harness) passes to a bundle's `mount`.
+ * Accepts both the current storefront shape (`storeData`/`page`) and the
+ * legacy/dev shape (`store`/`currentTemplate`); `mountTheme` normalises them.
+ */
+interface ThemeMountContext {
+    storeData?: Store;
+    page?: ThemeMountPage;
+    store?: Store;
+    currentTemplate?: string;
+    themeSettings: ThemeSettingsV3;
+    initialCart?: Cart;
+    customer?: Customer | null;
+    locale?: string;
+    translations?: Record<string, string>;
+    /** AUTHORITATIVE marketplace-preview flag from the host (true only for the
+     *  catalog "Try theme" preview). Themes with demo-image fallbacks gate on
+     *  it so a real installed store never shows demo imagery. */
+    demo?: boolean;
+    /** Store navigation menus keyed by handle, resolved server-side. */
+    navigation?: Record<string, MenuItemData[]>;
+    [extra: string]: unknown;
+}
+/** Arguments handed to a theme's render callback on every (re)render. */
+interface ThemeRenderArgs {
+    /** Active template key — "home" | "product" | "collection" | "cart" | … */
+    currentTemplate: string;
+    /** Marketplace-preview flag (see ThemeMountContext.demo). */
+    demo: boolean;
+    /** The raw host page descriptor (type/handle/data), or null. */
+    page: ThemeMountPage | null;
+    /** Normalised store record (never undefined). */
+    store: Store;
+    /** Live theme settings (reflects customizer drafts via applyDraft). */
+    themeSettings: ThemeSettingsV3;
+}
+/**
+ * Mount a V3 theme. Owns the React root, the provider stack (catalog + nav +
+ * style tokens), and the live-preview draft cycle. Returns the host-contract
+ * `MountResult` (`cleanup` + `applyDraft`).
+ *
+ * @param el        the host-supplied container element
+ * @param ctx       the mount context (either host or legacy/dev shape)
+ * @param renderApp returns the theme's section tree for the current args
+ */
+declare function mountTheme(el: HTMLElement, ctx: ThemeMountContext, renderApp: (args: ThemeRenderArgs) => ReactNode): MountResult;
+
 interface NuMuProviderProps {
     store: Store;
     themeSettings: ThemeSettingsV3;
@@ -990,21 +1188,52 @@ interface NuMuProviderProps {
     customer?: Customer | null;
     locale?: string;
     translations?: Record<string, string>;
+    /**
+     * Wave 5 — id of the active page template. Hosts pass this from the
+     * route (e.g. "product" inside app/(store)/[subdomain]/product/[id]).
+     * Themes read it via `useCurrentTemplate()` to render the matching
+     * section list. Defaults to "home" when omitted, so existing themes
+     * built before the prop existed keep rendering their home template.
+     */
+    currentTemplate?: string;
+    /**
+     * Pre-fetched product list for the current page. Themes that call
+     * `useProducts()` will read these from PageContext without needing
+     * `fetchIfMissing: true`. Hosts typically populate this from their
+     * route loader / SSR pass; omitting it leaves `useProducts()`
+     * returning an empty array unless the theme opts into client fetch.
+     */
+    initialProducts?: Product[];
+    /**
+     * Pre-fetched collection list — same pattern as initialProducts for
+     * `useCollections()`. Categories/collections shown on the home page
+     * read this slot.
+     */
+    initialCollections?: Collection[];
+    /**
+     * Phase 2.4 — store navigation menus keyed by handle (`main-menu`,
+     * `footer`, …), resolved server-side by the host and injected so a
+     * theme's `useNavigation(handle)` resolves synchronously without a
+     * client round-trip. Omit for hosts/themes that don't wire menus —
+     * `useNavigation` then falls back to its own fetch or the theme's
+     * `DEFAULT_NAV`.
+     */
+    navigation?: Record<string, MenuItemData[]>;
     children: ReactNode;
 }
-declare function NuMuProvider({ store, themeSettings, initialCart, customer, locale: initialLocale, translations: initialTranslations, children, }: NuMuProviderProps): react_jsx_runtime.JSX.Element;
+declare function NuMuProvider({ store, themeSettings, initialCart, customer, locale: initialLocale, translations: initialTranslations, currentTemplate, initialProducts, initialCollections, navigation, children, }: NuMuProviderProps): react.JSX.Element;
 
 interface ProductProviderProps {
     product: Product;
     children: ReactNode;
 }
-declare function ProductProvider({ product, children }: ProductProviderProps): react_jsx_runtime.JSX.Element;
+declare function ProductProvider({ product, children }: ProductProviderProps): react.JSX.Element;
 
 interface CollectionProviderProps {
     collection: Collection;
     children: ReactNode;
 }
-declare function CollectionProvider({ collection, children }: CollectionProviderProps): react_jsx_runtime.JSX.Element;
+declare function CollectionProvider({ collection, children }: CollectionProviderProps): react.JSX.Element;
 
 interface MoneyProps {
     /** Amount in major units (e.g. dollars, not cents). */
@@ -1064,7 +1293,7 @@ interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "
  * If `src` is empty/null, renders a placeholder div so the layout
  * doesn't shift while a merchant configures images in the customizer.
  */
-declare function Image({ src, alt, sizes, responsive, loading, className, style, ...rest }: ImageProps): react_jsx_runtime.JSX.Element;
+declare function Image({ src, alt, sizes, responsive, loading, className, style, ...rest }: ImageProps): react.JSX.Element;
 
 interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
     /**
@@ -1090,7 +1319,7 @@ interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"
  * unchanged so social-media links, CDN paths, etc. work without
  * special casing.
  */
-declare function Link({ to, children, ...rest }: LinkProps): react_jsx_runtime.JSX.Element;
+declare function Link({ to, children, ...rest }: LinkProps): react.JSX.Element;
 
 interface AddToCartButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onClick" | "disabled"> {
     product: Product;
@@ -1118,7 +1347,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_runtime.JSX.Element;
+declare function AddToCartButton({ product, variant, quantity, 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
@@ -1159,7 +1388,7 @@ interface SectionProps extends HTMLAttributes<HTMLElement> {
  * 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;
+declare function Section({ id, type, groupId, errorFallback, children, ...rest }: SectionProps): react.JSX.Element;
 interface BlockProps extends HTMLAttributes<HTMLDivElement> {
     /** Block instance id within its parent section. */
     id: string;
@@ -1176,7 +1405,7 @@ interface BlockProps extends HTMLAttributes<HTMLDivElement> {
  * 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;
+declare function Block({ id, type, errorFallback, children, ...rest }: BlockProps): react.JSX.Element;
 
 interface FormProps extends Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit" | "method" | "action" | "children" | "onError"> {
     /**
@@ -1233,7 +1462,7 @@ interface FormProps extends Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit"
  * 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;
+declare function Form({ action, method, onSuccess, onError, children, ...rest }: FormProps): react.JSX.Element;
 
 /**
  * Opinionated product tile.
@@ -1287,7 +1516,7 @@ interface ProductCardProps {
      */
     imageSizes?: string;
 }
-declare function ProductCard({ product, href, className, slots, imageSizes, }: ProductCardProps): react_jsx_runtime.JSX.Element;
+declare function ProductCard({ product, href, className, slots, imageSizes, }: ProductCardProps): react.JSX.Element;
 
 /**
  * Opinionated collection tile.
@@ -1317,7 +1546,7 @@ interface CollectionCardProps {
     slots?: CollectionCardSlots;
     imageSizes?: string;
 }
-declare function CollectionCard({ collection, href, className, slots, imageSizes, }: CollectionCardProps): react_jsx_runtime.JSX.Element;
+declare function CollectionCard({ collection, href, className, slots, imageSizes, }: CollectionCardProps): react.JSX.Element;
 
 /**
  * <RichText html=... /> — sanitized HTML renderer.
@@ -1371,7 +1600,7 @@ interface RichTextProps {
  * `bypassSanitize` (escape hatch below).
  */
 declare function sanitizeHtml(input: string): string;
-declare function RichText({ html, className, as }: RichTextProps): react_jsx_runtime.JSX.Element | null;
+declare function RichText({ html, className, as }: RichTextProps): react.JSX.Element | null;
 
 /**
  * <CurrencySwitcher /> — wired in Phase 6.
@@ -1397,7 +1626,7 @@ interface CurrencySwitcherProps {
         onChange: (next: string) => void;
     }) => React.ReactNode;
 }
-declare function CurrencySwitcher({ className, onSelect, render, }: CurrencySwitcherProps): react_jsx_runtime.JSX.Element | null;
+declare function CurrencySwitcher({ className, onSelect, render, }: CurrencySwitcherProps): react.JSX.Element | null;
 
 interface LocaleSwitcherProps {
     className?: string;
@@ -1410,7 +1639,62 @@ interface LocaleSwitcherProps {
         onChange: (next: string) => void;
     }) => React.ReactNode;
 }
-declare function LocaleSwitcher({ className, onSelect, render, }: LocaleSwitcherProps): react_jsx_runtime.JSX.Element | null;
+declare function LocaleSwitcher({ className, onSelect, render, }: LocaleSwitcherProps): react.JSX.Element | null;
+
+interface EditableTextProps extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+    /** The section instance id (key inside templates.<page>.sections). */
+    sectionId: string;
+    /** Optional block id when the field lives inside a section block. */
+    blockId?: string | null;
+    /** The setting key from the section's schema (e.g. "headline"). */
+    settingId: string;
+    /** The current text value (may be HTML for inline_richtext settings). */
+    value: string | undefined | null;
+    /**
+     * Element to render. Defaults to `<span>` so the component is
+     * inline-compatible. Pass "h1" / "h2" / "p" / "div" for block-level
+     * usage.
+     */
+    as?: ElementType;
+    /**
+     * Set to true to render the value as HTML (for inline_richtext
+     * settings whose stored form is `<b>Welcome</b>`). Defaults to false
+     * — plain-text fields are rendered as a text node.
+     */
+    html?: boolean;
+    /** Empty-state placeholder shown when value is "" / null. */
+    placeholder?: ReactNode;
+}
+declare const EditableText: react.ForwardRefExoticComponent<EditableTextProps & react.RefAttributes<HTMLElement>>;
+interface EditableImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src"> {
+    sectionId: string;
+    blockId?: string | null;
+    settingId: string;
+    /** Image src — may be empty/undefined if the merchant hasn't picked one yet. */
+    src: string | undefined | null;
+    /** Placeholder src shown when `src` is empty. Defaults to a 1x1 transparent gif. */
+    emptyPlaceholderSrc?: string;
+}
+declare const EditableImage: react.ForwardRefExoticComponent<EditableImageProps & react.RefAttributes<HTMLImageElement>>;
+
+declare const ICON_NAMES: string[];
+/** Public alias for the icon name → inner-SVG map. */
+declare const IconMap: Record<string, string>;
+interface IconProps {
+    /** Icon name from {@link ICON_NAMES}. Unknown names render a neutral glyph. */
+    name: string;
+    /** Pixel size (width === height). Defaults to 24. */
+    size?: number | string;
+    strokeWidth?: number;
+    className?: string;
+    /** Accessible label. When omitted the icon is treated as decorative. */
+    title?: string;
+}
+/**
+ * Render an icon by name from the shared {@link ICON_DEFS} set. Inherits color
+ * from `currentColor`, so set the parent's text color to recolor it.
+ */
+declare function Icon({ name, size, strokeWidth, className, title, }: IconProps): react.JSX.Element;
 
 /**
  * Module Federation singleton sharing for @numueg/theme-sdk.
@@ -1457,10 +1741,135 @@ interface ReactSingleton {
 }
 declare function registerSdkSingleton(sdk: SdkSingleton): void;
 declare function getSdkSingleton(): SdkSingleton | null;
+declare function clearSdkSingleton(): void;
 declare function registerReactSingleton(react: unknown, reactDom: unknown): void;
 declare function getReactSingleton(): ReactSingleton | null;
 declare function isSdkAvailable(): boolean;
 
+/**
+ * Dynamic sources — Shopify-parity feature that lets merchants bind a
+ * section setting to a value that's pulled from store data at render
+ * time instead of being a literal authored value.
+ *
+ * Stored shape:
+ *   { __numu_source: "<path>" }
+ *
+ * Paths use dot notation against the resolution context:
+ *   - `product.title` / `product.description` / `product.price` /
+ *     `product.image` / `product.first_image_url`
+ *   - `collection.title` / `collection.description` / `collection.image`
+ *   - `store.name` / `store.description`
+ *
+ * Why a reserved discriminant key (`__numu_source`)?
+ *
+ *   Setting values today are plain literals (`"Hero headline"`,
+ *   `12345`, `true`). Themes that read settings as strings/numbers
+ *   would break if we suddenly stored an object. The reserved key
+ *   tags object-shape values so the resolver only intercepts the ones
+ *   it knows about. Anything else (e.g. the `{ url, alt }` shape from
+ *   the image picker, or a future structured setting) passes through.
+ *
+ * Bindable-by-type matrix (enforced in the customizer's source picker):
+ *
+ *   text         | product.title, product.description (snippet),
+ *                | collection.title, collection.description (snippet),
+ *                | store.name, store.description
+ *   textarea     | same as text + full descriptions
+ *   richtext     | full descriptions only
+ *   url          | not bindable yet — product/collection URLs require
+ *                | the host's route resolver; deferred to a follow-up.
+ *   image_picker | product.image, collection.image, store.logo
+ *   number/range | product.price (raw cents) — risky because format
+ *                | varies. Deferred.
+ *   color/checkbox/select/radio/font | not bindable.
+ *
+ * Themes consume dynamic sources via `useResolvedSettings(instance)`
+ * which returns the section's settings map with every dynamic ref
+ * pre-resolved against the active product/collection/store context.
+ * Literal values pass through unchanged.
+ */
+
+/** Stored shape for a dynamic source reference. */
+interface DynamicSourceRef {
+    __numu_source: string;
+}
+/**
+ * Type guard. True when `value` is a dynamic source reference object.
+ * Order matters: we check the discriminant key BEFORE assuming the
+ * value is anything else, so an `{ __numu_source: "..." }` from the
+ * draft doesn't get treated as a literal record.
+ */
+declare function isDynamicSource(value: unknown): value is DynamicSourceRef;
+/**
+ * Build a fresh dynamic source ref. Pure helper used by the customizer
+ * when the merchant clicks a source in the picker.
+ */
+declare function dynamicSource(path: string): DynamicSourceRef;
+/** Resolution context for `resolveDynamicValue`. Each field is
+ *  independently optional so callers can pass only what's relevant
+ *  (e.g. cart template skips product/collection). */
+interface DynamicResolveContext {
+    product?: Product | null;
+    collection?: Collection | null;
+    store?: Pick<Store, "name" | "description" | "logo_url"> | null;
+}
+/**
+ * Look up the path inside the resolution context. Returns `null` when
+ * the source is unknown OR the context doesn't have the resource
+ * needed to resolve it (e.g. `product.title` when no product is in
+ * context). The customizer's source picker already hides incompatible
+ * sources, so this fallback only fires during preview navigation
+ * (merchant flips to a product template before the picker re-renders).
+ */
+declare function resolveSourcePath(path: string, ctx: DynamicResolveContext): unknown;
+/**
+ * Resolve a single setting value. Literal values pass through
+ * unchanged; dynamic references resolve against the context. Returns
+ * `null` (not the original ref) when resolution fails, so themes can
+ * branch on the null and either render a placeholder or hide the
+ * element entirely.
+ */
+declare function resolveDynamicValue<T = unknown>(value: unknown, ctx: DynamicResolveContext): T | null;
+/**
+ * Walk every key of a settings map and resolve every dynamic
+ * reference. Pure helper backing `useResolvedSettings`.
+ *
+ * The generic is unconstrained on purpose. Theme authors typically
+ * type their settings as `interface HeroSettings { headline?: string }`,
+ * and TypeScript interfaces don't implicitly satisfy
+ * `Record<string, unknown>` — there's no index signature on an
+ * interface. Leaving `T` open lets us pass through whatever shape the
+ * caller declared and still return the resolved-but-same shape.
+ */
+declare function resolveSettingsMap<T = Record<string, unknown>>(settings: T, ctx: DynamicResolveContext): T;
+
+/**
+ * Resolve every dynamic source in a section's settings against the
+ * active product / collection / store contexts.
+ *
+ * Section components that want to support merchant-bound fields call
+ * this in place of reading `instance.settings` directly:
+ *
+ *   const settings = useResolvedSettings(instance);
+ *
+ * Literal values pass through; `{ __numu_source: "product.title" }`
+ * becomes the current product's title when the section is rendered
+ * inside a `<ProductProvider>`. The returned object is memoized on
+ * the upstream contexts so themes can pass it straight into
+ * `useMemo` deps without retriggering renders.
+ *
+ * When the bound resource isn't in context (e.g. `product.*` on a
+ * non-product template), the resolved value is `null`. Themes can
+ * detect this and render a placeholder or hide the affected element.
+ *
+ * Note: the SectionContext provider already supplies the `instance`
+ * to children of `<Section>` — but we take it explicitly so section
+ * components can call this hook before they've descended into
+ * SectionContext (i.e. at the top of their render function, alongside
+ * destructuring `settings` from props).
+ */
+declare function useResolvedSettings<T = Record<string, unknown>>(instance: SectionInstance | BlockInstance | null | undefined): T;
+
 /**
  * Section + block authoring helpers.
  *
@@ -1584,6 +1993,52 @@ declare function collectBlocks<T extends Record<string, unknown>>(modules: T): R
  */
 declare function assetUrl(name: string): string;
 
+/**
+ * `applyGlobalStyleTokens(globalSettings, el)` — Phase 3.5.
+ *
+ * Bridges a store's **global theme settings** (colors, fonts, layout) to
+ * **CSS custom properties** on the bundle's mount root, so editing a color
+ * or font in Theme Settings actually re-paints the storefront. Before this,
+ * themes shipped static CSS tokens that nothing wrote to → the pickers were
+ * a silent no-op.
+ *
+ * ## Token contract (canonical names every theme can rely on)
+ *
+ * For each global setting `<id>` we set `--theme-<id>` verbatim (colors as
+ * their value, fonts resolved to a CSS font stack, other scalars as-is).
+ * Themes consume these with the current static value as a fallback:
+ *
+ *   --by-cream:     var(--theme-background_color, #f7f1e8);
+ *   --by-espresso:  var(--theme-primary_color,   #3a2418);
+ *   --by-font-serif: var(--theme-heading_font, "Cormorant Garamond", serif);
+ *
+ * In addition, well-known ids are aliased to **role** tokens so themes that
+ * prefer semantic names share one vocabulary:
+ *
+ *   colors → --theme-color-{background,text,primary,secondary,accent,border,button}
+ *   fonts  → --theme-font-{heading,body}
+ *
+ * `color_scheme` / `color_scheme_group` settings (object values keyed by role)
+ * emit `--scheme-<id>-<role>`.
+ *
+ * The helper is **idempotent** and safe to call on every `applyDraft` so the
+ * customizer's live preview re-paints as the merchant drags a color.
+ */
+type GlobalSettings = Record<string, unknown> | null | undefined;
+/**
+ * Resolve a font setting value to a CSS stack. Known tokens map through the
+ * registry (and load the webfont); anything else is treated as a literal
+ * family/stack the theme author supplied.
+ */
+declare function resolveFontStack(value: string): string;
+/**
+ * Map a store's global settings onto CSS custom properties on `el`. Call on
+ * mount and on every `applyDraft` (live preview). No-op when `el` or the
+ * settings are missing. Reserved `__`-prefixed keys (e.g. `__translations`)
+ * are skipped.
+ */
+declare function applyGlobalStyleTokens(globalSettings: GlobalSettings, el: HTMLElement | null | undefined): void;
+
 /**
  * Theme-bundled locale files: load + merge.
  *
@@ -1642,4 +2097,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, 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 };
+export { AddToCartButton, type AddressInput, type AnalyticsApi, type AnalyticsPayload, type AppManifestBlock, type AppPayload, type AppState, Block, BlockInstance, 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, type DynamicResolveContext, type DynamicSourceRef, EditableImage, type EditableImageProps, EditableText, type EditableTextProps, Form, type GiftCardBalance, ICON_NAMES, Icon, IconMap, type IconProps, Image, Link, type LocaleBundle, type LocaleMessages, LocaleSwitcher, type LocaleSwitcherProps, LocalizationContext, type MenuItemData, Money, MountResult, NavigationContext, 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, type ThemeMountContext, type ThemeMountPage, type ThemeRenderArgs, ThemeSettingsContext, ThemeSettingsV3, type UseGiftCardBalance, type UseReorder, type UseSearchOptions, type UseShippingRatesOptions, type UseShippingRatesState, type UseVariantSelection, type WishlistItem, type WishlistState, applyGlobalStyleTokens, assetUrl, availableValues, buildLocaleBundle, clearSdkSingleton, collectBlocks, collectSections, defaultVariant, defineBlock, defineSection, dynamicSource, findVariantByOptions, flattenMessages, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isDynamicSource, isSdkAvailable, mountTheme, pickTranslations, registerReactSingleton, registerSdkSingleton, resolveDynamicValue, resolveFontStack, resolveSettingsMap, 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, useProducts, useRelatedProducts, useReorder, useResolvedSettings, useSearch, useSection, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist };