@numueg/theme-sdk 0.2.3 → 0.3.2

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';
 
 /**
@@ -146,6 +146,12 @@ interface MenuItemData {
     url: string;
     type?: string | null;
     resource_id?: string | null;
+    /**
+     * §5 hide-page → hide-nav-link. `false` when the item targets a CMS page
+     * (`/pages/<handle>`) that is currently unpublished or deleted. The backend
+     * menus resolver annotates it; absent/`true` means visible (back-compat).
+     */
+    target_visible?: boolean;
     children?: MenuItemData[];
 }
 /**
@@ -485,6 +491,13 @@ interface NavigationItem {
     /** Optional foreign keys when the item references a typed resource. */
     resource_type?: "product" | "collection" | "page" | "blog" | "article" | "url" | null;
     resource_handle?: string | null;
+    /**
+     * §5 hide-page → hide-nav-link. `false` when the target CMS page is
+     * unpublished/deleted (backend-annotated). Defaults to `true` (visible)
+     * when the backend doesn't annotate, so themes can safely filter on
+     * `item.target_visible !== false`.
+     */
+    target_visible: boolean;
     children: NavigationItem[];
 }
 interface NavigationState {
@@ -744,6 +757,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 +1195,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 +1218,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 +2238,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 +2325,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';
 
 /**
@@ -146,6 +146,12 @@ interface MenuItemData {
     url: string;
     type?: string | null;
     resource_id?: string | null;
+    /**
+     * §5 hide-page → hide-nav-link. `false` when the item targets a CMS page
+     * (`/pages/<handle>`) that is currently unpublished or deleted. The backend
+     * menus resolver annotates it; absent/`true` means visible (back-compat).
+     */
+    target_visible?: boolean;
     children?: MenuItemData[];
 }
 /**
@@ -485,6 +491,13 @@ interface NavigationItem {
     /** Optional foreign keys when the item references a typed resource. */
     resource_type?: "product" | "collection" | "page" | "blog" | "article" | "url" | null;
     resource_handle?: string | null;
+    /**
+     * §5 hide-page → hide-nav-link. `false` when the target CMS page is
+     * unpublished/deleted (backend-annotated). Defaults to `true` (visible)
+     * when the backend doesn't annotate, so themes can safely filter on
+     * `item.target_visible !== false`.
+     */
+    target_visible: boolean;
     children: NavigationItem[];
 }
 interface NavigationState {
@@ -744,6 +757,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 +1195,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 +1218,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 +2238,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 +2325,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 };