@numueg/theme-sdk 0.2.3 → 0.3.1

package/dist/index.d.mts

@@ -1,9 +1,9 @@
-import { S as Store, e as Product, b as Collection, C as Cart, c as Customer, P as Page, g as ProductVariant } from './entities-C8B2U-V0.mjs';
-export { A as Address, a as CartItem, O as Order, d as OrderItem, f as ProductImage, h as ProductOption } from './entities-C8B2U-V0.mjs';
+import { i as Store, e as Product, b as Collection, C as Cart, c as Customer, P as Page, S as SizeChart, g as ProductVariant } from './entities-6MGANln7.mjs';
+export { A as Address, a as CartItem, O as Order, d as OrderItem, f as ProductImage, j as ProductOption, h as SizeChartMode } from './entities-6MGANln7.mjs';
 import { T as ThemeSettingsV3, c as SectionInstance, M as MountResult, B as BlockInstance, b as BlockSchema, a as BlockProps$1, f as SectionSchema, e as SectionProps$1 } from './theme-D0QybTQS.mjs';
 export { E as ExternalThemeMetadata, h as MAX_BLOCK_DEPTH, P as PageTemplate, i as PresetBlock, S as SectionGroup, d as SectionPreset, g as SettingDefinition } from './theme-D0QybTQS.mjs';
 import * as react from 'react';
-import { ReactNode, ElementType, CSSProperties, ImgHTMLAttributes, AnchorHTMLAttributes, ButtonHTMLAttributes, HTMLAttributes, FormHTMLAttributes, ComponentType } from 'react';
+import { ReactNode, ReactElement, ElementType, CSSProperties, ImgHTMLAttributes, AnchorHTMLAttributes, ButtonHTMLAttributes, HTMLAttributes, FormHTMLAttributes, ComponentType } from 'react';
 export { resolveThemeSettings } from './normalize.mjs';
 
 /**
@@ -744,6 +744,33 @@ declare function useRelatedProducts(productId: string | null | undefined, option
     limit?: number;
 }): RelatedProductsState;
 
+/**
+ * useProductSizeChart — resolve the size chart to show for a product.
+ *
+ * The merchant hub writes the per-product chart to
+ * `product.attributes.size_chart` and the store-wide default to
+ * `store.settings.size_chart`, with an explicit `mode`:
+ *
+ *   "off"     → never show, even if a store default exists
+ *   "custom"  → use the product's own chart
+ *   "default" → fall back to the store-wide chart
+ *   (legacy)  → no `mode`: a populated product chart wins, else the default
+ *
+ * This hook centralises that precedence so every theme resolves it identically
+ * (the backend `SizeChartSchema` validator and the hub editor share the same
+ * shape). Returns `null` when there is nothing to show — render the size-guide
+ * trigger only when this is non-null.
+ *
+ * @param productOverride - resolve against this product instead of the one in
+ *   context (e.g. when rendering a chart for a related/quick-view product).
+ */
+declare function useProductSizeChart(productOverride?: Product | null): SizeChart | null;
+/**
+ * Pure resolver (no React) — exported so non-hook code (SSR helpers, tests)
+ * can apply the same precedence.
+ */
+declare function resolveSizeChart(productAttributes: Record<string, unknown> | undefined, storeSettings: Record<string, unknown> | undefined): SizeChart | null;
+
 /**
  * Multi-currency presentment — Phase 6.
  *
@@ -1155,6 +1182,14 @@ interface ThemeMountContext {
     demo?: boolean;
     /** Store navigation menus keyed by handle, resolved server-side. */
     navigation?: Record<string, MenuItemData[]>;
+    /**
+     * Host signal that the container already holds server-rendered HTML for
+     * this exact ctx (produced via `createApp` from `defineThemeEntry`).
+     * `mountTheme` then adopts it with `hydrateRoot` instead of re-rendering
+     * from scratch. Ignored when the container is empty, so a host can pass
+     * it optimistically and still get a plain client mount on SSR failure.
+     */
+    hydrate?: boolean;
     [extra: string]: unknown;
 }
 /** Arguments handed to a theme's render callback on every (re)render. */
@@ -1170,17 +1205,81 @@ interface ThemeRenderArgs {
     /** Live theme settings (reflects customizer drafts via applyDraft). */
     themeSettings: ThemeSettingsV3;
 }
+interface DraftHandle {
+    applyDraft: (next: ThemeSettingsV3) => void;
+}
+/**
+ * Build the canonical theme element tree for a ctx. BOTH render paths go
+ * through here — `mountTheme` (client mount/hydrate) and `createApp`
+ * (host-side `renderToString`) — so the server markup and the hydration
+ * tree are the same React tree by construction. `mountEl` is a prop, not
+ * DOM output, so it differing between server (null) and client (the
+ * container) cannot cause a hydration mismatch.
+ */
+declare function buildThemeElement(ctx: ThemeMountContext, mountEl: HTMLElement | null, renderApp: (args: ThemeRenderArgs) => ReactNode, ref?: (h: DraftHandle | null) => void): ReactElement;
 /**
  * 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`).
  *
+ * When the host passes `ctx.hydrate === true` and the container already
+ * holds server-rendered HTML (produced by this theme's `createApp` with the
+ * identical ctx), the tree is adopted via `hydrateRoot` — no re-render, no
+ * flash. An empty container downgrades to a plain client mount so hosts can
+ * pass the flag optimistically.
+ *
  * @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;
 
+/**
+ * `defineThemeEntry(renderApp)` — one-call theme entry that yields BOTH
+ * halves of the V3 contract from a single component:
+ *
+ *   - `mount(el, ctx)`   — the client entry every host already calls
+ *                          (now hydration-aware via `ctx.hydrate`).
+ *   - `createApp(ctx)`   — the same React tree as a plain element, so the
+ *                          host can `renderToString(createApp(ctx))` on the
+ *                          server and ship real HTML before any JS runs.
+ *
+ * ```tsx
+ * // src/main.tsx
+ * import { defineThemeEntry } from "@numueg/theme-sdk";
+ *
+ * const entry = defineThemeEntry(({ currentTemplate }) => (
+ *   <ThemeApp currentTemplate={currentTemplate} />
+ * ));
+ *
+ * export const mount = entry.mount;
+ * export const createApp = entry.createApp;
+ * ```
+ *
+ * Why both MUST come from one definition: hydration only succeeds when the
+ * server markup and the client tree are identical. Routing both through
+ * `buildThemeElement` makes that true by construction — a theme cannot
+ * accidentally ship a `createApp` that disagrees with its `mount`.
+ *
+ * Themes that only export `mount` keep working exactly as before; they are
+ * simply never server-rendered (the host detects the missing `createApp`
+ * and falls back to today's client-only mount).
+ */
+
+/** The pair of entry points a V3 theme bundle exports. */
+interface ThemeEntry {
+    /** Client entry — host contract `mount(el, ctx): MountResult`. */
+    mount: (el: HTMLElement, ctx: ThemeMountContext) => MountResult;
+    /**
+     * Server entry — returns the exact element tree `mount` would render,
+     * for host-side `renderToString`. Must stay side-effect free: no DOM
+     * access happens until React effects run (which they don't on the
+     * server).
+     */
+    createApp: (ctx: ThemeMountContext) => ReactElement;
+}
+declare function defineThemeEntry(renderApp: (args: ThemeRenderArgs) => ReactNode): ThemeEntry;
+
 interface NuMuProviderProps {
     store: Store;
     themeSettings: ThemeSettingsV3;
@@ -2126,11 +2225,32 @@ type GlobalSettings = Record<string, unknown> | null | undefined;
  * family/stack the theme author supplied.
  */
 declare function resolveFontStack(value: string): string;
+/** Result of `computeGlobalStyleTokens` — everything a host needs to paint
+ *  global settings without a DOM. */
+interface ComputedStyleTokens {
+    /** CSS custom properties to set on the theme's mount root. */
+    cssVars: Record<string, string>;
+    /** Google-Fonts stylesheet hrefs for any registry fonts in use. */
+    fontHrefs: string[];
+}
+/**
+ * Pure half of `applyGlobalStyleTokens`: compute the exact CSS custom
+ * properties (and webfont hrefs) a settings object maps to, without touching
+ * any DOM. This is what lets a host SERVER-render a theme with the same vars
+ * the bundle applies on mount — both sides call this one function, so the
+ * values cannot drift (drift = unstyled flash or hydration noise).
+ *
+ * Includes the explicit `heading_font` / `body_font` resolution that
+ * `mountTheme` historically layered on top: any string value for those two
+ * ids resolves through the registry (or passes verbatim) so a picked font
+ * gets a real stack even when it isn't a known token.
+ */
+declare function computeGlobalStyleTokens(globalSettings: GlobalSettings): ComputedStyleTokens;
 /**
  * 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.
+ * are skipped. Thin DOM shell over `computeGlobalStyleTokens`.
  */
 declare function applyGlobalStyleTokens(globalSettings: GlobalSettings, el: HTMLElement | null | undefined): void;
 
@@ -2192,4 +2312,4 @@ declare function pickTranslations(bundle: LocaleBundle, locale: string): LocaleM
  */
 declare function buildLocaleBundle<T extends Record<string, unknown>>(modules: T): LocaleBundle;
 
-export { AddToCartButton, type AddressInput, type AnalyticsApi, type AnalyticsPayload, type AppManifestBlock, type AppPayload, type AppState, Block, BlockInstance, BlockProps$1 as BlockProps, BlockSchema, Cart, 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, type FocalSrcOptions, Form, type GiftCardBalance, ICON_NAMES, Icon, IconMap, type IconProps, Image, type ImageTransform, 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, applyImageTransform, asImageTransform, assetUrl, availableValues, buildLocaleBundle, clearSdkSingleton, collectBlocks, collectSections, defaultVariant, defineBlock, defineSection, dynamicSource, findVariantByOptions, flattenMessages, focalSrc, 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 };
+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 ComputedStyleTokens, 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, type FocalSrcOptions, Form, type GiftCardBalance, ICON_NAMES, Icon, IconMap, type IconProps, Image, type ImageTransform, 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, SizeChart, Store, type ThemeEntry, 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, applyImageTransform, asImageTransform, assetUrl, availableValues, buildLocaleBundle, buildThemeElement, clearSdkSingleton, collectBlocks, collectSections, computeGlobalStyleTokens, defaultVariant, defineBlock, defineSection, defineThemeEntry, dynamicSource, findVariantByOptions, flattenMessages, focalSrc, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isDynamicSource, isSdkAvailable, mountTheme, pickTranslations, registerReactSingleton, registerSdkSingleton, resolveDynamicValue, resolveFontStack, resolveSettingsMap, resolveSizeChart, resolveSourcePath, sanitizeHtml, useAnalytics, useApp, useCart, useCheckout, useCollection, useCollectionOptional, useCollections, useCurrency, useCurrentTemplate, useCustomer, useCustomerActions, useCustomerAddresses, useDirection, useFieldTranslation, useGiftCardBalance, useImage, useLocale, useLocalization, useMoney, useNavigation, useNumberFormat, useOrder, useOrders, usePage, useProduct, useProductOptional, useProductSizeChart, useProducts, useRelatedProducts, useReorder, useResolvedSettings, useSearch, useSection, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { S as Store, e as Product, b as Collection, C as Cart, c as Customer, P as Page, g as ProductVariant } from './entities-C8B2U-V0.js';
-export { A as Address, a as CartItem, O as Order, d as OrderItem, f as ProductImage, h as ProductOption } from './entities-C8B2U-V0.js';
+import { i as Store, e as Product, b as Collection, C as Cart, c as Customer, P as Page, S as SizeChart, g as ProductVariant } from './entities-6MGANln7.js';
+export { A as Address, a as CartItem, O as Order, d as OrderItem, f as ProductImage, j as ProductOption, h as SizeChartMode } from './entities-6MGANln7.js';
 import { T as ThemeSettingsV3, c as SectionInstance, M as MountResult, B as BlockInstance, b as BlockSchema, a as BlockProps$1, f as SectionSchema, e as SectionProps$1 } from './theme-D0QybTQS.js';
 export { E as ExternalThemeMetadata, h as MAX_BLOCK_DEPTH, P as PageTemplate, i as PresetBlock, S as SectionGroup, d as SectionPreset, g as SettingDefinition } from './theme-D0QybTQS.js';
 import * as react from 'react';
-import { ReactNode, ElementType, CSSProperties, ImgHTMLAttributes, AnchorHTMLAttributes, ButtonHTMLAttributes, HTMLAttributes, FormHTMLAttributes, ComponentType } from 'react';
+import { ReactNode, ReactElement, ElementType, CSSProperties, ImgHTMLAttributes, AnchorHTMLAttributes, ButtonHTMLAttributes, HTMLAttributes, FormHTMLAttributes, ComponentType } from 'react';
 export { resolveThemeSettings } from './normalize.js';
 
 /**
@@ -744,6 +744,33 @@ declare function useRelatedProducts(productId: string | null | undefined, option
     limit?: number;
 }): RelatedProductsState;
 
+/**
+ * useProductSizeChart — resolve the size chart to show for a product.
+ *
+ * The merchant hub writes the per-product chart to
+ * `product.attributes.size_chart` and the store-wide default to
+ * `store.settings.size_chart`, with an explicit `mode`:
+ *
+ *   "off"     → never show, even if a store default exists
+ *   "custom"  → use the product's own chart
+ *   "default" → fall back to the store-wide chart
+ *   (legacy)  → no `mode`: a populated product chart wins, else the default
+ *
+ * This hook centralises that precedence so every theme resolves it identically
+ * (the backend `SizeChartSchema` validator and the hub editor share the same
+ * shape). Returns `null` when there is nothing to show — render the size-guide
+ * trigger only when this is non-null.
+ *
+ * @param productOverride - resolve against this product instead of the one in
+ *   context (e.g. when rendering a chart for a related/quick-view product).
+ */
+declare function useProductSizeChart(productOverride?: Product | null): SizeChart | null;
+/**
+ * Pure resolver (no React) — exported so non-hook code (SSR helpers, tests)
+ * can apply the same precedence.
+ */
+declare function resolveSizeChart(productAttributes: Record<string, unknown> | undefined, storeSettings: Record<string, unknown> | undefined): SizeChart | null;
+
 /**
  * Multi-currency presentment — Phase 6.
  *
@@ -1155,6 +1182,14 @@ interface ThemeMountContext {
     demo?: boolean;
     /** Store navigation menus keyed by handle, resolved server-side. */
     navigation?: Record<string, MenuItemData[]>;
+    /**
+     * Host signal that the container already holds server-rendered HTML for
+     * this exact ctx (produced via `createApp` from `defineThemeEntry`).
+     * `mountTheme` then adopts it with `hydrateRoot` instead of re-rendering
+     * from scratch. Ignored when the container is empty, so a host can pass
+     * it optimistically and still get a plain client mount on SSR failure.
+     */
+    hydrate?: boolean;
     [extra: string]: unknown;
 }
 /** Arguments handed to a theme's render callback on every (re)render. */
@@ -1170,17 +1205,81 @@ interface ThemeRenderArgs {
     /** Live theme settings (reflects customizer drafts via applyDraft). */
     themeSettings: ThemeSettingsV3;
 }
+interface DraftHandle {
+    applyDraft: (next: ThemeSettingsV3) => void;
+}
+/**
+ * Build the canonical theme element tree for a ctx. BOTH render paths go
+ * through here — `mountTheme` (client mount/hydrate) and `createApp`
+ * (host-side `renderToString`) — so the server markup and the hydration
+ * tree are the same React tree by construction. `mountEl` is a prop, not
+ * DOM output, so it differing between server (null) and client (the
+ * container) cannot cause a hydration mismatch.
+ */
+declare function buildThemeElement(ctx: ThemeMountContext, mountEl: HTMLElement | null, renderApp: (args: ThemeRenderArgs) => ReactNode, ref?: (h: DraftHandle | null) => void): ReactElement;
 /**
  * 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`).
  *
+ * When the host passes `ctx.hydrate === true` and the container already
+ * holds server-rendered HTML (produced by this theme's `createApp` with the
+ * identical ctx), the tree is adopted via `hydrateRoot` — no re-render, no
+ * flash. An empty container downgrades to a plain client mount so hosts can
+ * pass the flag optimistically.
+ *
  * @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;
 
+/**
+ * `defineThemeEntry(renderApp)` — one-call theme entry that yields BOTH
+ * halves of the V3 contract from a single component:
+ *
+ *   - `mount(el, ctx)`   — the client entry every host already calls
+ *                          (now hydration-aware via `ctx.hydrate`).
+ *   - `createApp(ctx)`   — the same React tree as a plain element, so the
+ *                          host can `renderToString(createApp(ctx))` on the
+ *                          server and ship real HTML before any JS runs.
+ *
+ * ```tsx
+ * // src/main.tsx
+ * import { defineThemeEntry } from "@numueg/theme-sdk";
+ *
+ * const entry = defineThemeEntry(({ currentTemplate }) => (
+ *   <ThemeApp currentTemplate={currentTemplate} />
+ * ));
+ *
+ * export const mount = entry.mount;
+ * export const createApp = entry.createApp;
+ * ```
+ *
+ * Why both MUST come from one definition: hydration only succeeds when the
+ * server markup and the client tree are identical. Routing both through
+ * `buildThemeElement` makes that true by construction — a theme cannot
+ * accidentally ship a `createApp` that disagrees with its `mount`.
+ *
+ * Themes that only export `mount` keep working exactly as before; they are
+ * simply never server-rendered (the host detects the missing `createApp`
+ * and falls back to today's client-only mount).
+ */
+
+/** The pair of entry points a V3 theme bundle exports. */
+interface ThemeEntry {
+    /** Client entry — host contract `mount(el, ctx): MountResult`. */
+    mount: (el: HTMLElement, ctx: ThemeMountContext) => MountResult;
+    /**
+     * Server entry — returns the exact element tree `mount` would render,
+     * for host-side `renderToString`. Must stay side-effect free: no DOM
+     * access happens until React effects run (which they don't on the
+     * server).
+     */
+    createApp: (ctx: ThemeMountContext) => ReactElement;
+}
+declare function defineThemeEntry(renderApp: (args: ThemeRenderArgs) => ReactNode): ThemeEntry;
+
 interface NuMuProviderProps {
     store: Store;
     themeSettings: ThemeSettingsV3;
@@ -2126,11 +2225,32 @@ type GlobalSettings = Record<string, unknown> | null | undefined;
  * family/stack the theme author supplied.
  */
 declare function resolveFontStack(value: string): string;
+/** Result of `computeGlobalStyleTokens` — everything a host needs to paint
+ *  global settings without a DOM. */
+interface ComputedStyleTokens {
+    /** CSS custom properties to set on the theme's mount root. */
+    cssVars: Record<string, string>;
+    /** Google-Fonts stylesheet hrefs for any registry fonts in use. */
+    fontHrefs: string[];
+}
+/**
+ * Pure half of `applyGlobalStyleTokens`: compute the exact CSS custom
+ * properties (and webfont hrefs) a settings object maps to, without touching
+ * any DOM. This is what lets a host SERVER-render a theme with the same vars
+ * the bundle applies on mount — both sides call this one function, so the
+ * values cannot drift (drift = unstyled flash or hydration noise).
+ *
+ * Includes the explicit `heading_font` / `body_font` resolution that
+ * `mountTheme` historically layered on top: any string value for those two
+ * ids resolves through the registry (or passes verbatim) so a picked font
+ * gets a real stack even when it isn't a known token.
+ */
+declare function computeGlobalStyleTokens(globalSettings: GlobalSettings): ComputedStyleTokens;
 /**
  * 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.
+ * are skipped. Thin DOM shell over `computeGlobalStyleTokens`.
  */
 declare function applyGlobalStyleTokens(globalSettings: GlobalSettings, el: HTMLElement | null | undefined): void;
 
@@ -2192,4 +2312,4 @@ declare function pickTranslations(bundle: LocaleBundle, locale: string): LocaleM
  */
 declare function buildLocaleBundle<T extends Record<string, unknown>>(modules: T): LocaleBundle;
 
-export { AddToCartButton, type AddressInput, type AnalyticsApi, type AnalyticsPayload, type AppManifestBlock, type AppPayload, type AppState, Block, BlockInstance, BlockProps$1 as BlockProps, BlockSchema, Cart, 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, type FocalSrcOptions, Form, type GiftCardBalance, ICON_NAMES, Icon, IconMap, type IconProps, Image, type ImageTransform, 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, applyImageTransform, asImageTransform, assetUrl, availableValues, buildLocaleBundle, clearSdkSingleton, collectBlocks, collectSections, defaultVariant, defineBlock, defineSection, dynamicSource, findVariantByOptions, flattenMessages, focalSrc, 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 };
+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 ComputedStyleTokens, 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, type FocalSrcOptions, Form, type GiftCardBalance, ICON_NAMES, Icon, IconMap, type IconProps, Image, type ImageTransform, 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, SizeChart, Store, type ThemeEntry, 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, applyImageTransform, asImageTransform, assetUrl, availableValues, buildLocaleBundle, buildThemeElement, clearSdkSingleton, collectBlocks, collectSections, computeGlobalStyleTokens, defaultVariant, defineBlock, defineSection, defineThemeEntry, dynamicSource, findVariantByOptions, flattenMessages, focalSrc, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isDynamicSource, isSdkAvailable, mountTheme, pickTranslations, registerReactSingleton, registerSdkSingleton, resolveDynamicValue, resolveFontStack, resolveSettingsMap, resolveSizeChart, resolveSourcePath, sanitizeHtml, useAnalytics, useApp, useCart, useCheckout, useCollection, useCollectionOptional, useCollections, useCurrency, useCurrentTemplate, useCustomer, useCustomerActions, useCustomerAddresses, useDirection, useFieldTranslation, useGiftCardBalance, useImage, useLocale, useLocalization, useMoney, useNavigation, useNumberFormat, useOrder, useOrders, usePage, useProduct, useProductOptional, useProductSizeChart, useProducts, useRelatedProducts, useReorder, useResolvedSettings, useSearch, useSection, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { createContext, forwardRef, useState, useImperativeHandle, useEffect, useCallback, useMemo, useRef, useContext, StrictMode, createElement, Component } from 'react';
-import { createRoot } from 'react-dom/client';
+import { hydrateRoot, createRoot } from 'react-dom/client';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 
 // src/types/theme.ts
@@ -940,6 +940,29 @@ function useRelatedProducts(productId, options = {}) {
   }, [productId, limit]);
   return { items, loading, error };
 }
+function useProductSizeChart(productOverride) {
+  const ctxProduct = useProductOptional();
+  const product = productOverride ?? ctxProduct;
+  const shop = useShop();
+  const storeSettings = shop?.settings;
+  return useMemo(
+    () => resolveSizeChart(product?.attributes, storeSettings),
+    [product?.attributes, storeSettings]
+  );
+}
+function hasRows(c) {
+  return !!c && typeof c === "object" && Array.isArray(c.rows) && c.rows.length > 0;
+}
+function resolveSizeChart(productAttributes, storeSettings) {
+  const product = productAttributes?.size_chart;
+  const storeDefault = storeSettings?.size_chart;
+  if (product?.mode === "off") return null;
+  if (product?.mode === "custom") return hasRows(product) ? product : null;
+  if (product?.mode === "default") return hasRows(storeDefault) ? storeDefault : null;
+  if (hasRows(product)) return product;
+  if (hasRows(storeDefault)) return storeDefault;
+  return null;
+}
 var COOKIE_NAME = "numu_currency";
 var COOKIE_MAX_AGE = 60 * 60 * 24 * 30;
 function readCookie(name) {
@@ -1989,6 +2012,9 @@ function injectFontLink(href) {
   link.setAttribute("data-numu-font", "");
   document.head.appendChild(link);
 }
+function lookupFontStack(value) {
+  return FONT_REGISTRY[value]?.stack ?? value;
+}
 function resolveFontStack(value) {
   const entry = FONT_REGISTRY[value];
   if (entry) {
@@ -1997,39 +2023,69 @@ function resolveFontStack(value) {
   }
   return value;
 }
-function applyGlobalStyleTokens(globalSettings, el) {
-  if (!el || !globalSettings || typeof globalSettings !== "object") return;
-  const style = el.style;
+function computeGlobalStyleTokens(globalSettings) {
+  const cssVars = {};
+  const fontHrefs = [];
+  if (!globalSettings || typeof globalSettings !== "object") {
+    return { cssVars, fontHrefs };
+  }
+  const pushHref = (href) => {
+    if (href && !fontHrefs.includes(href)) fontHrefs.push(href);
+  };
   for (const [key, value] of Object.entries(globalSettings)) {
     if (!key || key.startsWith("__")) continue;
     if (value && typeof value === "object" && !Array.isArray(value)) {
       for (const [role, c] of Object.entries(value)) {
-        if (isColorValue(c)) style.setProperty(`--scheme-${key}-${role}`, c);
+        if (isColorValue(c)) cssVars[`--scheme-${key}-${role}`] = c;
       }
       continue;
     }
     if (isColorValue(value)) {
-      style.setProperty(`--theme-${key}`, value.trim());
+      cssVars[`--theme-${key}`] = value.trim();
       const role = COLOR_ROLE_ALIASES[key];
-      if (role) style.setProperty(`--theme-color-${role}`, value.trim());
+      if (role) cssVars[`--theme-color-${role}`] = value.trim();
       continue;
     }
     if (isFontToken(value)) {
-      const stack = resolveFontStack(value);
-      style.setProperty(`--theme-${key}`, stack);
+      const entry = FONT_REGISTRY[value];
+      cssVars[`--theme-${key}`] = entry.stack;
       const role = FONT_ROLE_ALIASES[key];
-      if (role) style.setProperty(`--theme-font-${role}`, stack);
+      if (role) cssVars[`--theme-font-${role}`] = entry.stack;
+      pushHref(entry.href);
       continue;
     }
     if (typeof value === "string" || typeof value === "number") {
       const v = String(value).trim();
-      if (v) style.setProperty(`--theme-${key}`, v);
+      if (v) cssVars[`--theme-${key}`] = v;
+    }
+  }
+  for (const id of ["heading_font", "body_font"]) {
+    const value = globalSettings[id];
+    if (typeof value === "string" && value.trim()) {
+      cssVars[`--theme-${id}`] = lookupFontStack(value);
+      pushHref(FONT_REGISTRY[value]?.href);
     }
   }
+  return { cssVars, fontHrefs };
+}
+function applyGlobalStyleTokens(globalSettings, el) {
+  if (!el || !globalSettings || typeof globalSettings !== "object") return;
+  const { cssVars, fontHrefs } = computeGlobalStyleTokens(globalSettings);
+  const style = el.style;
+  for (const [prop, value] of Object.entries(cssVars)) {
+    style.setProperty(prop, value);
+  }
+  for (const href of fontHrefs) injectFontLink(href);
 }
 function pickStore(ctx) {
   const s = ctx.storeData ?? ctx.store;
-  if (s) return s;
+  if (s) {
+    const raw = s;
+    if (!raw.currency && raw.default_currency) {
+      return { ...raw, currency: raw.default_currency };
+    }
+    return s;
+  }
   return {
     id: "unknown",
     name: "Store",
@@ -2064,19 +2120,9 @@ var ThemeMountBridge = forwardRef(function ThemeMountBridge2({ ctx, mountEl, ren
     []
   );
   useEffect(() => {
+    if (!mountEl) return;
     const gs = themeSettings.global_settings ?? {};
     applyGlobalStyleTokens(gs, mountEl);
-    const headingFont = gs.heading_font;
-    if (typeof headingFont === "string" && headingFont.trim()) {
-      mountEl.style.setProperty(
-        "--theme-heading_font",
-        resolveFontStack(headingFont)
-      );
-    }
-    const bodyFont = gs.body_font;
-    if (typeof bodyFont === "string" && bodyFont.trim()) {
-      mountEl.style.setProperty("--theme-body_font", resolveFontStack(bodyFont));
-    }
   }, [themeSettings, mountEl]);
   const store = pickStore(ctx);
   const template = pickTemplate(ctx);
@@ -2106,22 +2152,22 @@ var ThemeMountBridge = forwardRef(function ThemeMountBridge2({ ctx, mountEl, ren
     }
   );
 });
+function buildThemeElement(ctx, mountEl, renderApp, ref) {
+  return /* @__PURE__ */ jsx(StrictMode, { children: /* @__PURE__ */ jsx(ThemeMountBridge, { ctx, mountEl, renderApp, ref }) });
+}
 function mountTheme(el, ctx, renderApp) {
-  const root = createRoot(el);
   const handleRef = { current: null };
-  root.render(
-    /* @__PURE__ */ jsx(StrictMode, { children: /* @__PURE__ */ jsx(
-      ThemeMountBridge,
-      {
-        ctx,
-        mountEl: el,
-        renderApp,
-        ref: (h) => {
-          handleRef.current = h;
-        }
-      }
-    ) })
-  );
+  const element = buildThemeElement(ctx, el, renderApp, (h) => {
+    handleRef.current = h;
+  });
+  const shouldHydrate = ctx.hydrate === true && el.firstElementChild !== null;
+  let root;
+  if (shouldHydrate) {
+    root = hydrateRoot(el, element);
+  } else {
+    root = createRoot(el);
+    root.render(element);
+  }
   return {
     applyDraft: (next) => handleRef.current?.applyDraft(next),
     cleanup: () => {
@@ -2130,6 +2176,14 @@ function mountTheme(el, ctx, renderApp) {
     }
   };
 }
+
+// src/entry.tsx
+function defineThemeEntry(renderApp) {
+  return {
+    mount: (el, ctx) => mountTheme(el, ctx, renderApp),
+    createApp: (ctx) => buildThemeElement(ctx, null, renderApp)
+  };
+}
 function CollectionProvider({ collection, children }) {
   return /* @__PURE__ */ jsx(CollectionContext.Provider, { value: collection, children });
 }
@@ -2753,7 +2807,14 @@ function sanitizeHtmlServer(input) {
   return s;
 }
 function RichText({ html, className, as = "div" }) {
-  const safe = useMemo(() => sanitizeHtml(html || ""), [html]);
+  const [domReady, setDomReady] = useState(false);
+  useEffect(() => {
+    setDomReady(true);
+  }, []);
+  const safe = useMemo(
+    () => domReady ? sanitizeHtml(html || "") : sanitizeHtmlServer(html || ""),
+    [html, domReady]
+  );
   if (!safe) return null;
   const Tag = as;
   return /* @__PURE__ */ jsx(
@@ -3419,8 +3480,13 @@ function collectBlocks(modules) {
 
 // src/utils/assetUrl.ts
 function getRuntime() {
-  if (typeof window === "undefined") return {};
-  return window;
+  if (typeof window !== "undefined") {
+    return window;
+  }
+  if (typeof globalThis !== "undefined") {
+    return globalThis;
+  }
+  return {};
 }
 function assetUrl(name) {
   if (!name) return "";
@@ -3481,6 +3547,6 @@ function buildLocaleBundle(modules) {
   return bundle;
 }
 
-export { AddToCartButton, Block, CartContext, CollectionCard, CollectionContext, CollectionProvider, CurrencySwitcher, CustomerContext, EditableImage, EditableText, Form, ICON_NAMES, Icon, IconMap, Image, Link, LocaleSwitcher, LocalizationContext, MAX_BLOCK_DEPTH, Money, NavigationContext, NuMuProvider, PageContext, ProductCard, ProductContext, ProductProvider, RichText, Section, SectionContext, ShopContext, ThemeSettingsContext, applyGlobalStyleTokens, applyImageTransform, asImageTransform, assetUrl, availableValues, buildLocaleBundle, clearSdkSingleton, collectBlocks, collectSections, defaultVariant, defineBlock, defineSection, dynamicSource, findVariantByOptions, flattenMessages, focalSrc, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isDynamicSource, isSdkAvailable, mountTheme, pickTranslations, registerReactSingleton, registerSdkSingleton, resolveDynamicValue, resolveFontStack, resolveSettingsMap, resolveSourcePath, resolveThemeSettings, sanitizeHtml, useAnalytics, useApp, useCart, useCheckout, useCollection, useCollectionOptional, useCollections, useCurrency, useCurrentTemplate, useCustomer, useCustomerActions, useCustomerAddresses, useDirection, useFieldTranslation, useGiftCardBalance, useImage, useLocale, useLocalization, useMoney, useNavigation, useNumberFormat, useOrder, useOrders, usePage, useProduct, useProductOptional, useProducts, useRelatedProducts, useReorder, useResolvedSettings, useSearch, useSection, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist };
+export { AddToCartButton, Block, CartContext, CollectionCard, CollectionContext, CollectionProvider, CurrencySwitcher, CustomerContext, EditableImage, EditableText, Form, ICON_NAMES, Icon, IconMap, Image, Link, LocaleSwitcher, LocalizationContext, MAX_BLOCK_DEPTH, Money, NavigationContext, NuMuProvider, PageContext, ProductCard, ProductContext, ProductProvider, RichText, Section, SectionContext, ShopContext, ThemeSettingsContext, applyGlobalStyleTokens, applyImageTransform, asImageTransform, assetUrl, availableValues, buildLocaleBundle, buildThemeElement, clearSdkSingleton, collectBlocks, collectSections, computeGlobalStyleTokens, defaultVariant, defineBlock, defineSection, defineThemeEntry, dynamicSource, findVariantByOptions, flattenMessages, focalSrc, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isDynamicSource, isSdkAvailable, mountTheme, pickTranslations, registerReactSingleton, registerSdkSingleton, resolveDynamicValue, resolveFontStack, resolveSettingsMap, resolveSizeChart, resolveSourcePath, resolveThemeSettings, sanitizeHtml, useAnalytics, useApp, useCart, useCheckout, useCollection, useCollectionOptional, useCollections, useCurrency, useCurrentTemplate, useCustomer, useCustomerActions, useCustomerAddresses, useDirection, useFieldTranslation, useGiftCardBalance, useImage, useLocale, useLocalization, useMoney, useNavigation, useNumberFormat, useOrder, useOrders, usePage, useProduct, useProductOptional, useProductSizeChart, useProducts, useRelatedProducts, useReorder, useResolvedSettings, useSearch, useSection, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map