@numueg/theme-sdk 0.10.1 → 0.13.0

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import { i as Store, e as Product, b as Collection, c as Customer, P as Page, S as SizeChart, g as ProductVariant, C as Cart } from './entities-B8378GKp.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-B8378GKp.js';
+import { i as Store, e as Product, b as Collection, c as Customer, P as Page, M as Metafield, j as ArticleDetail, k as ArticleSummary, B as BlogSummary, C as Cart, S as SizeChart, g as ProductVariant } from './entities-DRKn04q0.js';
+export { A as Address, a as CartItem, O as Order, d as OrderItem, f as ProductImage, l as ProductOption, h as SizeChartMode } from './entities-DRKn04q0.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-CNTB4KnU.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-CNTB4KnU.js';
 export { KNOWN_SETTING_TYPES, KNOWN_TEMPLATES, REQUIRED_TEMPLATES, SDK_VERSION, THEME_CONTRACT_VERSION, ValidationIssue, ValidationResult, mergeResults, validateBuiltManifest, validateManifest, validateSectionSchema, validateSettingsAgainstSchema } from './validation.js';
-import { C as CartContextValue, L as LocalizationState, a as CurrencyState, T as ThemeMountContext, b as ThemeRenderArgs, M as MenuItemData } from './mount-DQZu8aBB.js';
-export { c as CartContext, d as CartMutationResult, e as CollectionContext, f as CurrencyConfig, g as CurrencyContext, h as CustomerContext, i as LocalizationContext, N as NavigationContext, P as PageContext, j as ProductContext, S as ShopContext, k as ThemeMountPage, l as ThemeSettingsContext, m as buildThemeElement, n as mountTheme } from './mount-DQZu8aBB.js';
+import { C as CartContextValue, L as LocalizationState, a as CurrencyState, T as ThemeMountContext, b as ThemeRenderArgs, M as MenuItemData } from './mount-CLQniVfc.js';
+export { c as CartContext, d as CartMutationResult, e as CollectionContext, f as CurrencyConfig, g as CurrencyContext, h as CustomerContext, i as LocalizationContext, N as NavigationContext, P as PageContext, j as ProductContext, S as ShopContext, k as ThemeMountPage, l as ThemeSettingsContext, m as buildThemeElement, n as mountTheme } from './mount-CLQniVfc.js';
 import * as react from 'react';
 import { ReactElement, ReactNode, ElementType, CSSProperties, ImgHTMLAttributes, AnchorHTMLAttributes, ButtonHTMLAttributes, HTMLAttributes, FormHTMLAttributes, ComponentType } from 'react';
 export { resolveThemeSettings } from './normalize.js';
@@ -43,6 +43,54 @@ declare function useProductOptional(): Product | null;
 declare function useCollection(): Collection;
 declare function useCollectionOptional(): Collection | null;
 
+interface ListingHeading {
+    /** The collection the shopper is inside, or `null` on the all-products listing. */
+    collection: Collection | null;
+    /** `true` when this listing is scoped to one collection. */
+    isCollection: boolean;
+    /** What to render as the page heading. */
+    title: string;
+    /** What to render under it. Empty string when there is nothing to say. */
+    description: string;
+}
+interface ListingHeadingOptions {
+    /** The merchant's own heading from this section's settings, if they set one. */
+    title?: string | null;
+    /** The merchant's own sub-heading from this section's settings. */
+    description?: string | null;
+    /**
+     * The theme's wording for the UNSCOPED listing — already localized by the
+     * theme, e.g. `localized(locale, "All products", "كل المنتجات")`.
+     */
+    defaultTitle?: string | null;
+}
+/**
+ * What a product-listing section should call itself.
+ *
+ * Every theme hardcoded "All products" as its listing heading, so a shopper who
+ * clicked into a category landed on a page titled **All products** showing a
+ * subset of the catalog. The products were correctly scoped — the page just
+ * never said which collection it was. That reads as a bug ("where did the rest
+ * go?") and it costs the collection name in the one place it matters most.
+ *
+ * Precedence, highest first:
+ *   1. the collection's own name — when the shopper is inside one, that IS the
+ *      page, and it always beats a static setting;
+ *   2. the merchant's section setting — their wording for the all-products page;
+ *   3. the theme's default.
+ *
+ * Categories carry no separate Arabic column, so `collection.name` is rendered
+ * as the merchant typed it; only the fallback is localized, by the caller.
+ *
+ * @example
+ * const { title, description, isCollection } = useListingHeading({
+ *   title: asString(s.title),
+ *   description: asString(s.subtitle),
+ *   defaultTitle: localized(locale, "All products", "كل المنتجات"),
+ * });
+ */
+declare function useListingHeading(options?: ListingHeadingOptions): ListingHeading;
+
 declare function useCart(): CartContextValue;
 
 declare function useCustomer(): Customer | null;
@@ -121,6 +169,44 @@ declare function useNumberFormat(): (n: number, options?: Intl.NumberFormatOptio
 
 declare function usePage(): Page | null;
 
+/**
+ * Owners a theme can read metafields from. Matches the platform's
+ * metafield owner types (product / collection / page). Only PUBLIC
+ * metafields ever reach the storefront — the privacy filter runs
+ * server-side at the payload layer, so a private field is simply absent
+ * here, never present-but-hidden.
+ */
+type MetafieldOwner = "product" | "collection" | "page";
+/**
+ * All public metafields of the given owner currently in context.
+ * Empty array when the owner isn't in context (e.g. `"product"` on a
+ * collection page) or has no fields — never throws.
+ */
+declare function useMetafields(owner: MetafieldOwner): Metafield[];
+/**
+ * Read one merchant-defined field directly:
+ *
+ * ```tsx
+ * const material = useMetafield("product", "specs", "material");
+ * if (material) <dd>{String(material.value)}</dd>;
+ * ```
+ *
+ * Returns the full {@link Metafield} (value pre-coerced to its declared
+ * type by the platform) or `null` when missing — same convention as the
+ * dynamic-source resolver (`{owner}.metafield:{namespace}.{key}`), so a
+ * theme's own fallback renders for stores that haven't set the field.
+ */
+declare function useMetafield(owner: MetafieldOwner, namespace: string, key: string): Metafield | null;
+
+/** Published blogs of the store (blogs-index template). */
+declare function useBlogs(): BlogSummary[];
+/** The current blog (blog template), or the article's blog on an article page. */
+declare function useBlog(): BlogSummary | null;
+/** Published articles of the current blog (blog template), newest first. */
+declare function useArticles(): ArticleSummary[];
+/** The current article (article template). */
+declare function useArticle(): ArticleDetail | null;
+
 declare const SectionContext: react.Context<SectionInstance | null>;
 declare function useSection(): SectionInstance;
 declare function useSectionOptional(): SectionInstance | null;
@@ -840,6 +926,216 @@ interface UseCachedResourceOptions<T> {
  */
 declare function useCachedResource<T>(key: string | null | undefined, fetcher: CacheFetcher<T>, options?: UseCachedResourceOptions<T>): CachedResource<T>;
 
+/**
+ * Storefront promotion types — the shape the platform serves to every theme.
+ *
+ * Source of truth is the backend's offers-v2 engine. The host proxies it at
+ * `GET /api/storefront/promotions`, which returns the visitor's active
+ * promotions grouped by surface. Themes only ever *render* these; the engine
+ * decides what a cart costs, and the same engine runs at checkout. A theme
+ * that computes its own discount is telling the shopper a number the server
+ * will overrule.
+ *
+ * ⚠️ Every `*_cents` field here is in INTEGER CENTS, straight off the API —
+ * unlike `Cart`, which the SDK normalizes to major units. Convert with the
+ * helpers in `lib/promotions` rather than dividing ad hoc; a missed
+ * conversion is a silent 100x error.
+ */
+/** One step of a tiered "spend X, get Y%" rule. */
+interface DiscountTier {
+    threshold_cents: number;
+    percent: number;
+}
+/**
+ * The math behind a promotion. `kind` is an open string union on purpose:
+ * the platform adds kinds over time and older themes must degrade quietly
+ * rather than crash on one they've never heard of.
+ */
+interface DiscountRule {
+    kind: "percentage" | "fixed" | "free_shipping" | "bogo" | "tiered" | "multibuy" | (string & {});
+    value_cents?: number | null;
+    value_percent?: number | null;
+    min_subtotal_cents?: number | null;
+    max_discount_cents?: number | null;
+    buy_quantity?: number | null;
+    get_quantity?: number | null;
+    get_discount_percent?: number | null;
+    tiers?: DiscountTier[];
+    /** MULTIBUY: how many eligible items form one group (N). */
+    multibuy_quantity?: number | null;
+    /** MULTIBUY: the fixed total price for one complete group (P), in cents. */
+    multibuy_price_cents?: number | null;
+}
+/** A promotion resolved as active for the current visitor. */
+interface ActivePromotion {
+    promotion_id: string;
+    surface?: string;
+    priority?: number;
+    content?: Record<string, unknown>;
+    translated_content?: {
+        headline?: Record<string, string>;
+        body?: Record<string, string>;
+        [key: string]: unknown;
+    };
+    discount_rule?: DiscountRule | null;
+    coupon_code?: string | null;
+    /**
+     * Which catalog entries can take part in the rule. BOTH EMPTY (or absent,
+     * on an older backend) means the whole store qualifies.
+     *
+     * Needed so a scoped offer doesn't lie: without it a "3 for EGP 650 on
+     * scarves" offer counts every cart unit, and a shopper holding one
+     * ineligible item is told "add 2 more" and then doesn't get the discount.
+     */
+    eligible_product_ids?: string[];
+    eligible_category_ids?: string[];
+}
+/** The `/api/storefront/promotions` payload, grouped by surface. */
+interface ActivePromotionsPayload {
+    announcement_bars?: ActivePromotion[];
+    popups?: ActivePromotion[];
+    floating_widgets?: ActivePromotion[];
+    cookie_banner?: ActivePromotion | null;
+    /** Automatic (no code needed) discounts — where multibuy offers live. */
+    auto_discounts?: ActivePromotion[];
+    discount_codes_visible?: ActivePromotion[];
+}
+/**
+ * A validated multibuy offer, normalized for display.
+ *
+ * `groupPriceMajor` is in MAJOR units (EGP, not piastres) so it can go
+ * straight into `<Money>` / `formatMoney` — the conversion happened once,
+ * here, rather than in each theme.
+ */
+interface MultibuyOffer {
+    promotionId: string;
+    /** N — how many items make a group. */
+    quantity: number;
+    /** P in cents, as the engine stores it. */
+    groupPriceCents: number;
+    /** P in major units, ready to render. */
+    groupPriceMajor: number;
+    /** Merchant's bilingual headline, when they set one. */
+    headline?: Record<string, string>;
+    /** Products the offer is scoped to. Empty (with categories) = whole store. */
+    eligibleProductIds: string[];
+    /** Categories the offer is scoped to. Empty (with products) = whole store. */
+    eligibleCategoryIds: string[];
+    /** True when the offer applies to the entire catalogue. */
+    isStoreWide: boolean;
+    raw: ActivePromotion;
+}
+/** Where a shopper stands against one multibuy offer. */
+interface OfferProgress {
+    /** Eligible units currently in the cart. */
+    unitsInCart: number;
+    /** How many more units to complete the next group. 0 = just unlocked. */
+    unitsNeeded: number;
+    /** Complete groups the cart has already earned. */
+    groupsUnlocked: number;
+    /**
+     * What the engine says this offer actually saved, in MAJOR units. Read
+     * from `cart.applied_promotions` — never recomputed, so the number the
+     * shopper reads is the number they are charged.
+     */
+    savingMajor: number;
+}
+
+/**
+ * The store's active promotions for the current visitor.
+ *
+ * Reads the host proxy `GET /api/storefront/promotions` (never NUMU-api
+ * directly — the host owns credentials, caching and the store resolution).
+ * The backend groups by surface; the host already renders announcement bars,
+ * popups, the cookie banner and floating widgets in the shell, so what a
+ * theme normally wants is `auto_discounts` — the offers that price the cart
+ * with no code to type.
+ *
+ * SSR-safe: `useCachedResource` doesn't fetch during server render, so this
+ * resolves on hydrate. Sections must therefore tolerate a null first pass —
+ * render nothing (or a skeleton) rather than assuming data on first paint.
+ *
+ * Returns `null` on any miss (offline, 404, flag off). That is deliberate:
+ * a promotions outage should make an offer banner disappear, never break the
+ * page it sits on.
+ *
+ * @param page   page path used for page-targeted promotions (default "/")
+ * @param locale "ar" | "en" — selects the translated content
+ */
+declare function useActivePromotions(page?: string, locale?: string): ActivePromotionsPayload | null;
+
+/**
+ * Pure helpers for rendering platform promotions in a theme.
+ *
+ * These are headless by design — data and logic only, zero markup and zero
+ * styling — so every theme keeps its own look while sharing one correct
+ * implementation of the fiddly parts (unit counting, group math, the
+ * cents→major boundary).
+ *
+ * The hard rule these encode: **a theme never computes a discount.** The
+ * engine prices the cart and reports what it saved; helpers here only
+ * describe progress toward an offer and format what the engine already
+ * decided. Anything else eventually renders a number the server won't honour.
+ */
+
+/**
+ * Extract the usable multibuy offers ("any N for a fixed total P").
+ *
+ * Accepts either the whole `/api/storefront/promotions` payload or just an
+ * array of promotions, so callers don't have to reach into `auto_discounts`
+ * themselves. Anything that isn't a well-formed multibuy — a kind this SDK
+ * version doesn't know, a missing N or P — is skipped rather than thrown on:
+ * a theme built before a rule kind existed must keep rendering when a
+ * merchant starts using it.
+ */
+declare function multibuyOffers(promotions: ActivePromotionsPayload | ActivePromotion[] | null | undefined): MultibuyOffer[];
+/**
+ * Does this product take part in the offer?
+ *
+ * A store-wide offer includes everything. Otherwise the product must be named
+ * directly or sit in a named category. A scoped offer over a product whose
+ * `category_id` we don't know returns false — better to under-promise than to
+ * advertise a discount the server won't apply.
+ */
+declare function offerIncludesProduct(offer: MultibuyOffer | null | undefined, product: {
+    id?: string;
+    product_id?: string;
+    category_id?: string | null;
+}): boolean;
+/**
+ * How many cart UNITS actually qualify for the offer.
+ *
+ * Units, not lines — three of one product is a valid trio, the way the engine
+ * scores it. For a scoped offer this is what the nudge must count; counting
+ * the whole cart is how a shopper gets told "add 2 more" and then doesn't get
+ * the discount.
+ */
+declare function eligibleUnitsInCart(offer: MultibuyOffer | null | undefined, cart: Cart | null | undefined): number;
+/**
+ * Where the cart stands against one multibuy offer.
+ *
+ * Counts UNITS, not lines — three of the same product is a valid trio, the
+ * same way the engine scores it. `savingMajor` is read from the cart's
+ * engine-supplied `applied_promotions`, so an unlocked offer shows the real
+ * saving and a theme can never drift from the charged amount.
+ *
+ * Scoping is handled automatically: when the offer names products or
+ * categories, only qualifying units are counted (via `eligibleUnitsInCart`).
+ * Pass `eligibleUnits` explicitly to override that — e.g. when the theme has
+ * a better source of truth than the cart lines.
+ */
+declare function offerProgress(offer: MultibuyOffer | null | undefined, cart: Cart | null | undefined, eligibleUnits?: number): OfferProgress;
+/**
+ * Should a product page advertise this offer?
+ *
+ * Only when N of this product actually costs more than the group price —
+ * otherwise the "deal" is worse than just buying them, and §5 of the offer
+ * spec forbids advertising it (the engine likewise refuses to apply it).
+ *
+ * @param unitPriceMajor the product's price in MAJOR units, as a theme has it
+ */
+declare function offerBeatsRegularPrice(offer: MultibuyOffer | null | undefined, unitPriceMajor: number | null | undefined): boolean;
+
 /**
  * useProductSizeChart — resolve the size chart to show for a product.
  *
@@ -1340,9 +1636,16 @@ declare function asImageTransform(v: unknown): ImageTransform | undefined;
  * CSS reproducing the transform on an `<img>` that fills a fixed-aspect,
  * overflow-hidden frame. Default fit is `cover` (Shopify-style: the image
  * fills its frame, cropping to the focal point) — pass `"contain"` only for
- * placements that must show the whole image (e.g. a logo). Empty object when
- * there is no transform AND the caller wants the section's own className to
- * decide; pass an explicit `fit` to force a default even without a transform.
+ * placements that must show the whole image (e.g. a logo).
+ *
+ * **No transform → empty object.** An inline style beats a className, so
+ * returning `{ objectFit: fit }` here would silently override a placement's
+ * own `object-contain` / `object-none` class on every untransformed image —
+ * which is most merchant images. The section's className stays in charge; a
+ * caller that needs a guaranteed fit supplies it itself, e.g.
+ * `{ objectFit: fit, ...applyImageTransform(t, fit) }` (see `HeroMedia`).
+ * This matches `Image.tsx`'s untransformed branch and the behaviour every
+ * theme's local copy has shipped with.
  */
 declare function applyImageTransform(t: ImageTransform | undefined | null, fit?: "cover" | "contain"): CSSProperties;
 /**
@@ -2264,6 +2567,187 @@ declare function collectBlocks<T extends Record<string, unknown>>(modules: T): R
  */
 declare function assetUrl(name: string): string;
 
+/**
+ * Storefront route builders.
+ *
+ * The storefront's URL shape is platform knowledge, not theme knowledge: a
+ * theme that hardcodes `/products/${slug}` has quietly taken a dependency on
+ * the host's routing, and every copy of that template is a place the fleet can
+ * disagree with the host. Centralising the templates here means a route change
+ * is one edit rather than a fleet-wide grep.
+ *
+ * Hoisted out of the themes' `sections/_shared.ts`, where `productHref` was
+ * hand-copied into 4 themes and their 4 scaffold templates.
+ */
+/**
+ * Link to a product detail page.
+ *
+ * Falls back to the product index when there's no identifier, so a card built
+ * from incomplete data links somewhere useful instead of `/products/undefined`.
+ */
+declare function productHref(slugOrId: string | undefined | null): string;
+/**
+ * Link to a collection page.
+ *
+ * Prefers the slug and falls back to the id, because a category with no slug
+ * is common in practice and the bare template produces `/collections/undefined`
+ * — a 404 the merchant sees as a broken menu item. Accepts either a category
+ * object or a plain slug string so call sites don't have to unpack first.
+ */
+declare function collectionHref(category: string | {
+    slug?: string | null;
+    id?: string | null;
+} | null | undefined): string;
+
+/**
+ * Money formatting for NUMU storefronts.
+ *
+ * Three implementations of this existed and disagreed:
+ *
+ *   - the themes' own `fmt` (4 byte-identical copies): EGP fallback,
+ *     `maximumFractionDigits: 0`, locale `"ar"` mapped to `"ar-EG"`
+ *   - `@numueg/theme-kit`'s `formatMoney`: **USD** fallback, 2 fraction
+ *     digits, raw locale passed through
+ *   - `NuMuProvider`'s own `formatMoney`: a third variant again
+ *
+ * This adopts the themes' behaviour, because that is what production renders
+ * today: adopting the kit's would silently turn every promo nudge from
+ * `LE 500` into `£E 500.00` on live stores. NUMU is Egypt-first — EGP is the
+ * right fallback, whole piastres are noise at Egyptian price points, and
+ * `ar-EG` is what produces Egyptian Arabic numerals and currency placement.
+ *
+ * The unit is CENTS, matching the API end to end. `formatMoneyMajor` exists
+ * for the one place that already divided (the SDK exposes cart money in major
+ * units), so nobody has to remember which side of the boundary they're on.
+ */
+interface FormatMoneyOptions {
+    /** Currency code. Falls back to EGP — Egypt-first, not USD. */
+    currency?: string | null;
+    /** `"ar"` maps to `ar-EG`; anything else formats as `en-EG`. */
+    locale?: string | null;
+    /**
+     * Fraction digits. Defaults to 0: Egyptian retail prices are whole pounds,
+     * and `500.00 EGP` reads as noise next to `500 EGP`. Pass 2 where sub-unit
+     * precision genuinely matters (a unit price, an FX-converted amount).
+     */
+    fractionDigits?: number;
+}
+/**
+ * Format an integer amount of cents.
+ *
+ * @example formatMoney(50000)                    // "EGP 500"
+ * @example formatMoney(50000, { locale: "ar" })  // "٥٠٠ ج.م.‏"
+ */
+declare function formatMoney(cents: number, options?: FormatMoneyOptions): string;
+/**
+ * Format an amount already expressed in major units.
+ *
+ * The SDK hands cart money to themes in major units while the API speaks
+ * cents, so a shared helper that only accepted one of the two guaranteed a
+ * factor-of-100 bug at the seam.
+ */
+declare function formatMoneyMajor(amount: number, options?: FormatMoneyOptions): string;
+/** Cents to major units. Non-finite input yields 0, never NaN. */
+declare function centsToMajor(cents: number): number;
+/** Major units to integer cents, rounded — the inverse of `centsToMajor`. */
+declare function majorToCents(amount: number): number;
+
+/**
+ * Template + section-group resolution — the "no blank page" engine.
+ *
+ * This is engine policy, not theme code, and it was copy-pasted into every
+ * theme: `src/sections/_template-utils.ts` is BYTE-IDENTICAL across 11 of the
+ * 14 themes that carry it (md5 59608dd4f4a702136854d7aaf33ba5e3); the
+ * remaining copies differ only in comments and brace style. The file's own
+ * header instructed theme authors to copy it and said it could be deleted
+ * "once the published SDK ships its own sanitizeTemplate". This is that.
+ *
+ * Why centralising it is safe — and why it matters:
+ *   - It contains ZERO design. It decides WHICH sections render, never how
+ *     they look, so it cannot homogenise themes.
+ *   - Getting it subtly wrong renders an EMPTY STORE. Empire re-implemented a
+ *     weaker version inline with no unknown-type filtering, so a stale
+ *     customisation renders "Unknown section" placeholders there while every
+ *     other theme degrades gracefully. One implementation removes that class.
+ *
+ * The two rules it encodes, both learned from real blank-page incidents:
+ *   1. A template may arrive as an ARRAY or as a MAP + `order[]`. The
+ *      customizer writes one shape, theme presets use the other.
+ *   2. Host customisation wins over the theme's bundled preset — UNLESS it
+ *      resolves to nothing this theme can render, in which case fall back to
+ *      the preset rather than showing the shopper an empty page.
+ */
+
+/** A template or section group, in either of the two shapes hosts send. */
+interface MaybeOrderedTemplate {
+    name?: string;
+    sections?: Record<string, SectionInstance> | SectionInstance[];
+    order?: string[];
+}
+/** A section instance paired with the stable id the customizer selects by. */
+interface ResolvedSection {
+    id: string;
+    instance: SectionInstance;
+}
+/**
+ * Normalise a template/group into an ordered list.
+ *
+ * Array form gets synthetic `${type}-${index}` ids (presets have no ids of
+ * their own). Map form is walked in `order`, skipping ids the map doesn't
+ * contain — a dangling id in `order` is a customisation that referenced a
+ * deleted section and must not throw.
+ */
+declare function resolveSections(group: MaybeOrderedTemplate | undefined): ResolvedSection[];
+/**
+ * Choose between the host's customisation and the theme's bundled preset,
+ * then drop section types this theme cannot render.
+ *
+ * `isKnown` is the theme's own registry lookup — the one thing that genuinely
+ * belongs to the theme, so it stays a parameter.
+ *
+ * The order of the three checks is load-bearing:
+ *   - nothing from the host        → preset (a fresh install renders its demo)
+ *   - host sections, none known    → preset (a customisation built for a
+ *                                    DIFFERENT theme must not blank the page)
+ *   - otherwise                    → host sections, unknown types filtered out
+ */
+declare function selectTemplateSections(hostTemplate: MaybeOrderedTemplate | undefined, builtinTemplate: MaybeOrderedTemplate | undefined, isKnown: (sectionType: string) => boolean): ResolvedSection[];
+/**
+ * Find the theme's header/footer for a route it has no template for.
+ *
+ * Chrome reaches a theme from `section_groups` — except most themes never used
+ * that channel: they put the header and footer INLINE in each template's own
+ * section list. That works right up until the shopper hits a route the theme
+ * ships no template for. Then there are no sections, so there is no chrome,
+ * and the page renders with no navigation and no way back into the store.
+ *
+ * That is what `/blogs` looked like on every theme: correct, readable content
+ * with nothing around it — no logo, no menu, no cart, no footer. A shopper
+ * arriving from search had to press Back to escape.
+ *
+ * The template's OWN inline chrome still wins when it has some. This only
+ * supplies chrome to routes that would otherwise have none, by borrowing the
+ * chrome the theme already renders everywhere else — `home` first, since it is
+ * the one template every theme ships and the one merchants customise.
+ *
+ * Returns `[]` when the theme genuinely has no chrome of this kind anywhere,
+ * so a caller can still fall back to its own default.
+ */
+declare function selectChromeSections(options: {
+    /** `section_groups[kind]` from the host — the customizer's channel. */
+    hostGroup?: MaybeOrderedTemplate;
+    /** The theme's own preset `section_groups[kind]`. */
+    presetGroup?: MaybeOrderedTemplate;
+    /** Chrome found inline in the CURRENT template's section list. */
+    inline?: ResolvedSection[];
+    /** Every template the theme can draw on — host customisation and presets. */
+    templates?: Array<MaybeOrderedTemplate | undefined>;
+    /** True for the section types that count as this kind of chrome. */
+    isChrome: (sectionType: string) => boolean;
+    /** The theme's registry lookup. */
+    isKnown: (sectionType: string) => boolean;
+}): ResolvedSection[];
+
 /**
  * `applyGlobalStyleTokens(globalSettings, el)` — Phase 3.5.
  *
@@ -2459,4 +2943,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, type CacheFetcher, type CacheMutator, type CachedResource, type CachedResourceState, Cart, CartContextValue, type CheckoutAddress, type CheckoutApi, type CheckoutSessionState, type CheckoutStep, Collection, CollectionCard, type CollectionCardProps, type CollectionCardSlots, CollectionProvider, type ComputedStyleTokens, CurrencyState, CurrencySwitcher, type CurrencySwitcherProps, Customer, type CustomerAddress, type CustomerAddressesState, type DefineBlockInput, type DefineSectionInput, type DefinedBlock, type DefinedSection, type DynamicResolveContext, type DynamicSourceRef, EditableImage, type EditableImageProps, EditableText, type EditableTextProps, type FocalSrcOptions, Form, type GiftCardBalance, HeroMedia, type HeroMediaProps, ICON_NAMES, Icon, IconMap, type IconProps, Image, type ImageTransform, LOGO_SHAPE_OPTIONS, LOGO_SIZE_OPTIONS, Link, type LocaleBundle, type LocaleMessages, LocaleSwitcher, type LocaleSwitcherProps, Logo, type LogoProps, type LogoShape, type LogoSize, MenuItemData, Money, MountResult, type MutateOptions, NAVIGATE_EVENT, type NavigateEventDetail, type NavigationItem, type NavigationState, NuMuProvider, type OrderDetail, type OrderListEntry, type OrderListState, type OrderState, Page, type PlaceOrderResult, Product, ProductCard, type ProductCardProps, type ProductCardSlots, ProductProvider, ProductVariant, type RelatedProductsState, type ReorderResult, type ReorderSkipReason, type ReorderSkippedItem, RichText, type RichTextProps, type SearchResults, type SearchState, Section, SectionContext, type SectionGroupInstance, SectionInstance, SectionProps$1 as SectionProps, SectionSchema, type ShippingRateOption, type ShopWithHelpers, SizeChart, Store, type ThemeEntry, ThemeMountContext, ThemeRenderArgs, ThemeSettingsV3, type UseCachedResourceOptions, type UseGiftCardBalance, type UseReorder, type UseSearchOptions, type UseShippingRatesOptions, type UseShippingRatesState, type UseVariantSelection, type WishlistItem, type WishlistState, applyGlobalStyleTokens, applyImageTransform, asImageTransform, assetUrl, availableValues, buildLocaleBundle, clearSdkSingleton, collectBlocks, collectSections, computeGlobalStyleTokens, defaultVariant, defineBlock, defineSection, defineThemeEntry, dynamicSource, findVariantByOptions, flattenMessages, focalSrc, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isDynamicSource, isSdkAvailable, logoImgStyle, logoStyleTokens, pickTranslations, publishVariantSelection, readVariantSelection, registerReactSingleton, registerSdkSingleton, requestNavigate, resolveDynamicValue, resolveFontStack, resolveSettingsMap, resolveSizeChart, resolveSourcePath, sanitizeHtml, useAnalytics, useApp, useCachedResource, useCart, useCheckout, useCollection, useCollectionOptional, useCollections, useCurrency, useCurrentTemplate, useCustomer, useCustomerActions, useCustomerAddresses, useDirection, useFieldTranslation, useGiftCardBalance, useImage, useLocale, useLocalization, useMoney, useNavigation, useNumberFormat, useOrder, useOrders, usePage, useProduct, useProductOptional, useProductSizeChart, useProducts, useRelatedProducts, useReorder, useResolvedSettings, useSearch, useSection, useSectionGroup, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist };
+export { type ActivePromotion, type ActivePromotionsPayload, AddToCartButton, type AddressInput, type AnalyticsApi, type AnalyticsPayload, type AppManifestBlock, type AppPayload, type AppState, ArticleDetail, ArticleSummary, Block, BlockInstance, BlockProps$1 as BlockProps, BlockSchema, BlogSummary, type CacheFetcher, type CacheMutator, type CachedResource, type CachedResourceState, Cart, CartContextValue, type CheckoutAddress, type CheckoutApi, type CheckoutSessionState, type CheckoutStep, Collection, CollectionCard, type CollectionCardProps, type CollectionCardSlots, CollectionProvider, type ComputedStyleTokens, CurrencyState, CurrencySwitcher, type CurrencySwitcherProps, Customer, type CustomerAddress, type CustomerAddressesState, type DefineBlockInput, type DefineSectionInput, type DefinedBlock, type DefinedSection, type DiscountRule, type DiscountTier, type DynamicResolveContext, type DynamicSourceRef, EditableImage, type EditableImageProps, EditableText, type EditableTextProps, type FocalSrcOptions, Form, type FormatMoneyOptions, type GiftCardBalance, HeroMedia, type HeroMediaProps, ICON_NAMES, Icon, IconMap, type IconProps, Image, type ImageTransform, LOGO_SHAPE_OPTIONS, LOGO_SIZE_OPTIONS, Link, type ListingHeading, type ListingHeadingOptions, type LocaleBundle, type LocaleMessages, LocaleSwitcher, type LocaleSwitcherProps, Logo, type LogoProps, type LogoShape, type LogoSize, type MaybeOrderedTemplate, MenuItemData, type MetafieldOwner, Money, MountResult, type MultibuyOffer, type MutateOptions, NAVIGATE_EVENT, type NavigateEventDetail, type NavigationItem, type NavigationState, NuMuProvider, type OfferProgress, type OrderDetail, type OrderListEntry, type OrderListState, type OrderState, Page, type PlaceOrderResult, Product, ProductCard, type ProductCardProps, type ProductCardSlots, ProductProvider, ProductVariant, type RelatedProductsState, type ReorderResult, type ReorderSkipReason, type ReorderSkippedItem, type ResolvedSection, RichText, type RichTextProps, type SearchResults, type SearchState, Section, SectionContext, type SectionGroupInstance, SectionInstance, SectionProps$1 as SectionProps, SectionSchema, type ShippingRateOption, type ShopWithHelpers, SizeChart, Store, type ThemeEntry, ThemeMountContext, ThemeRenderArgs, ThemeSettingsV3, type UseCachedResourceOptions, type UseGiftCardBalance, type UseReorder, type UseSearchOptions, type UseShippingRatesOptions, type UseShippingRatesState, type UseVariantSelection, type WishlistItem, type WishlistState, applyGlobalStyleTokens, applyImageTransform, asImageTransform, assetUrl, availableValues, buildLocaleBundle, centsToMajor, clearSdkSingleton, collectBlocks, collectSections, collectionHref, computeGlobalStyleTokens, defaultVariant, defineBlock, defineSection, defineThemeEntry, dynamicSource, eligibleUnitsInCart, findVariantByOptions, flattenMessages, focalSrc, formatMoney, formatMoneyMajor, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isDynamicSource, isSdkAvailable, logoImgStyle, logoStyleTokens, majorToCents, multibuyOffers, offerBeatsRegularPrice, offerIncludesProduct, offerProgress, pickTranslations, productHref, publishVariantSelection, readVariantSelection, registerReactSingleton, registerSdkSingleton, requestNavigate, resolveDynamicValue, resolveFontStack, resolveSections, resolveSettingsMap, resolveSizeChart, resolveSourcePath, sanitizeHtml, selectChromeSections, selectTemplateSections, useActivePromotions, useAnalytics, useApp, useArticle, useArticles, useBlog, useBlogs, useCachedResource, useCart, useCheckout, useCollection, useCollectionOptional, useCollections, useCurrency, useCurrentTemplate, useCustomer, useCustomerActions, useCustomerAddresses, useDirection, useFieldTranslation, useGiftCardBalance, useImage, useListingHeading, useLocale, useLocalization, useMetafield, useMetafields, useMoney, useNavigation, useNumberFormat, useOrder, useOrders, usePage, useProduct, useProductOptional, useProductSizeChart, useProducts, useRelatedProducts, useReorder, useResolvedSettings, useSearch, useSection, useSectionGroup, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist };