@shoppexio/storefront-react 0.0.0 → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,3087 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Which account surface a URL names.
+ *
+ * The account lives under `/dashboard`, and the panel is a PATH SEGMENT:
+ * `/dashboard/orders`, `/dashboard/orders/<uniqid>`, `/dashboard/settings`.
+ * `/dashboard` itself is the overview. This is the platform's route shape and it
+ * is identical on both storefront lanes (ADR-0064), so a theme that invents its
+ * own account paths breaks links it does not own.
+ *
+ * The older query spelling — `?tab=<tab>` and `?order=<id>` — is still ACCEPTED,
+ * because it sits in order emails already sent and in the platform's post-login
+ * redirect. It is read as input and never written: a URL carrying it is
+ * canonicalized to the path form, by replacement rather than a push, so the back
+ * button does not bounce the buyer between the two spellings. The path always
+ * wins when a URL carries both.
+ *
+ * `/customer-portal` is the oldest spelling of the same route and folds in with
+ * its tail and query intact.
+ *
+ * A locale prefix (`/de/dashboard/orders`) is part of the served URL on a
+ * localized storefront. The router's basename normally strips it before any of
+ * this sees it, so the parser accepts a pathname with or without one and
+ * canonicalization keeps whatever prefix it was given.
+ *
+ * Everything here is pure string work, so `tests/account-route.test.ts` can pin
+ * the parts email links depend on.
+ */
+declare const ACCOUNT_PATH = "/dashboard";
+/** The older spelling of the same route. Folded, never served separately. */
+declare const ACCOUNT_PATH_ALIAS = "/customer-portal";
+/**
+ * Every tab the Shoppex account surface defines, in navigation order.
+ *
+ * Listed in full so a link to a real platform tab can be told apart from a typo
+ * and answered differently.
+ */
+declare const ACCOUNT_TABS: readonly ["overview", "orders", "downloads", "subscriptions", "rewards", "referrals", "favorites", "support", "settings", "reseller"];
+type AccountTab = (typeof ACCOUNT_TABS)[number];
+/**
+ * The catalog key a tab's label lives under.
+ *
+ * A key rather than a string: this file is imported by the router, the
+ * navigation and the "not part of this store" notice, and each of them needs
+ * the label in the locale the edge served — see `account/i18n.ts`.
+ */
+declare function accountTabLabelKey(tab: AccountTab): string;
+/**
+ * The tabs the account renders.
+ *
+ * All ten platform tabs. Adding a panel means adding its tab here AND
+ * rendering it, in the same change: a tab listed without a panel would navigate
+ * to the "not built" notice, which is worse than not offering it.
+ *
+ * Reseller payloads are locally narrowed because shared contracts do not cover
+ * them, but the worker now allowlists their SDK routes.
+ */
+declare const IMPLEMENTED_ACCOUNT_TABS: readonly ["overview", "orders", "downloads", "subscriptions", "rewards", "referrals", "favorites", "support", "settings", "reseller"];
+type ImplementedAccountTab = (typeof IMPLEMENTED_ACCOUNT_TABS)[number];
+declare const DEFAULT_ACCOUNT_TAB: ImplementedAccountTab;
+/**
+ * What the account page should show.
+ *
+ * `not-built` and `unknown-tab` are separate on purpose. The first is a real
+ * platform tab this storefront chose not to render, the second is a value that
+ * names no tab at all. Collapsing them into "show the overview instead" would
+ * hide a broken link behind a page that looks like it worked.
+ */
+type AccountView = {
+    kind: 'panel';
+    tab: ImplementedAccountTab;
+} | {
+    kind: 'order';
+    orderId: string;
+} | {
+    kind: 'not-built';
+    tab: AccountTab;
+} | {
+    kind: 'unknown-tab';
+};
+declare function isAccountTab(value: string): value is AccountTab;
+declare function isImplementedAccountTab(value: string): value is ImplementedAccountTab;
+interface AccountRouteParts {
+    /** What preceded `/dashboard`: '' or a locale prefix such as '/de'. */
+    prefix: string;
+    /** Whether the URL used the retired `/customer-portal` spelling. */
+    alias: boolean;
+    /** The segments after `/dashboard`, decoded. */
+    tail: string[];
+}
+/**
+ * Split an account URL into its prefix and the segments below `/dashboard`.
+ *
+ * Null when the path is not the account route at all. The account segment is
+ * only recognised first or directly after a locale segment — searching for it
+ * anywhere would make `/product/dashboard-pro` an account URL.
+ */
+declare function parseAccountPath(pathname: string): AccountRouteParts | null;
+/**
+ * What to render for a URL.
+ *
+ * The path is read first and the query only when the path names no panel, so a
+ * canonical URL is never reinterpreted by a stale parameter riding along on it.
+ */
+declare function resolveAccountView(pathname: string, search: URLSearchParams): AccountView;
+/** `/dashboard/<tab>`. The overview is the bare path, not `/dashboard/overview`. */
+declare function accountTabHref(tab: AccountTab): string;
+/** `/dashboard/orders/<id>`, the one order-detail spelling. */
+declare function accountOrderHref(orderId: string): string;
+/**
+ * The canonical path for a URL that is not written the canonical way, or null
+ * when it already is.
+ *
+ * Three URLs need rewriting: the `/customer-portal` alias, a `?tab=`/`?order=`
+ * query, and the redundant `/dashboard/overview`. The caller replaces rather
+ * than pushes — a push would put the retired spelling in the history and send
+ * the back button straight back into it.
+ *
+ * A URL naming nothing real (`?tab=orderz`, `/dashboard/nope`) has no canonical
+ * form and keeps the address it came with: rewriting it to the overview would
+ * turn a broken link into one that looks like it worked.
+ *
+ * The prefix the URL came with is preserved, so a buyer on `/de/dashboard` is
+ * not quietly moved out of their locale.
+ */
+declare function canonicalAccountPath(pathname: string, search: URLSearchParams): string | null;
+/**
+ * The storefront routes the account links to outside itself: the catalog
+ * behind every "browse the store" action, and a product page per favorite.
+ * React Router does not check a `to`, so a host that does not route one of
+ * these answers the account's own buttons with its not-found page. A host
+ * checks its router against this list (ForkMe: `tests/account-routes.test.ts`).
+ */
+declare const ACCOUNT_STOREFRONT_ROUTES: readonly ["/all-products", "/product/:slug"];
+/**
+ * The artifact capabilities the account relies on. A storefront that mounts
+ * the account lists each of them in its `public/shoppex.capabilities.json`;
+ * the storefront worker reads that file from the artifact and only then hands
+ * the account what the capability promises. `account-reseller-invite-cookie`
+ * is pinned to `RESELLER_INVITE_ARTIFACT_CAPABILITY` in
+ * `workers/storefront/src/reseller-invite-link.ts`: without it the worker
+ * leaves a reseller invitation in the URL for that build.
+ */
+declare const ACCOUNT_ARTIFACT_CAPABILITIES: readonly ["account-reseller-invite-cookie"];
+
+declare const ACCOUNT_ROUTE_MESSAGE_KEYS: readonly ["account.checkingSession", "common.notLoaded", "common.genericError", "common.retry"];
+type AccountRouteMessageKey = (typeof ACCOUNT_ROUTE_MESSAGE_KEYS)[number];
+declare function accountRouteMessage(key: AccountRouteMessageKey, lang?: string | null): string;
+
+/**
+ * Type surface of the Shoppex Storefront SDK global (window.shoppex), loaded
+ * as a UMD script from cdn.shoppex.io in index.html.
+ *
+ * This declares the whole customer surface the SDK exports in addition to the
+ * storefront subset this theme consumes today: merchants fork this template,
+ * and a runtime method must not be hidden by its local types. The full API is
+ * documented at https://docs.shoppex.io/storefront-sdk. Keep field names in
+ * sync with the SDK's public response contracts (snake_case).
+ */
+/** One addon selection on a cart line. Part of the line's identity. */
+interface SdkCartAddon {
+    id: string;
+    option_id?: string;
+    quantity?: number;
+}
+interface SdkCartItem {
+    line_id: string;
+    product_id: string;
+    variant_id: string;
+    quantity: number;
+    price_variant_id?: string | null;
+    addons?: SdkCartAddon[];
+    custom_fields?: Record<string, string>;
+    price_data?: {
+        unit_price: number;
+    };
+    pay_what_you_want_price?: number;
+    title?: string;
+    variant_title?: string;
+    image_url?: string;
+    addon_labels?: string[];
+    max_quantity?: number;
+    min_quantity?: number;
+}
+interface SdkCartAppliedDiscount {
+    source: 'PRODUCT_DISCOUNT' | 'VOLUME_DISCOUNT' | 'AUTOMATIC_PRODUCT_DEAL' | 'BUNDLE_DEAL' | 'STORE_PROMOTION' | 'COUPON' | 'AFFILIATE';
+    label: string;
+    amount: string;
+}
+/**
+ * One cart line as the SERVER resolved it — the authoritative bounds and
+ * sellability for the option that line names.
+ *
+ * PAYMENT PATH, and a contract with rules that cannot be guessed from the
+ * shape. `min_quantity` is OMITTED when it is 1; `max_quantity` is OMITTED when
+ * nothing bounds the line (`-1` is never emitted, so a missing key means
+ * UNBOUNDED and must never be read as 0). When several cart lines name one
+ * product+option they draw from one shelf and the checkout sums them, so
+ * `max_quantity` is that line's SHARE of the option's ceiling. `sellable: false`
+ * means this cart cannot be ordered as it stands — the option is unorderable,
+ * or the cart's lines of it together exceed its ceiling — and it answers for the
+ * OPTION, so every line of one option carries the same value.
+ *
+ * The consumer duty is in `cart-quote-bounds.ts`: REPLACE the stored
+ * bounds rather than merging them, and refuse the hand-off while any line is
+ * unsellable.
+ */
+interface SdkCartQuoteLine {
+    product_id: string;
+    /** The resolved option id, or null for a product with no variants. */
+    variant_id: string | null;
+    /** The quantity this row was quoted AT, after per-line summing. */
+    quantity: number;
+    /** Absent when 1. */
+    min_quantity?: number;
+    /** Absent when unbounded. Never `-1`. */
+    max_quantity?: number;
+    sellable: boolean;
+}
+interface SdkEligibleCartDeal {
+    deal_uniqid: string;
+    product_id: string;
+    label: string;
+    missing_quantity: number;
+    required_quantity: number;
+}
+/**
+ * How the backend classified an accepted cart code. The buyer types ONE field;
+ * the server decides whether that string is a coupon or an affiliate referral
+ * (`CartQuoteService`), and the two are paid out completely differently — a
+ * referral submitted as a coupon credits nobody.
+ */
+type SdkCartCodeSource = 'COUPON' | 'AFFILIATE';
+interface SdkCartQuote {
+    subtotal: string;
+    discount: string;
+    total: string;
+    currency: string;
+    coupon_applied: boolean;
+    /**
+     * Which kind of code the quote accepted; null when it accepted none. The
+     * theme must not classify a code itself — only the server knows which of the
+     * merchant's coupons and which affiliates exist.
+     */
+    coupon_source: SdkCartCodeSource | null;
+    applied_discounts: SdkCartAppliedDiscount[];
+    /**
+     * Per-line effective bounds and sellability — see {@link SdkCartQuoteLine}.
+     * Absent on a backend older than the contract; a consumer must then keep the
+     * add-time snapshot rather than invent bounds of its own.
+     */
+    lines?: SdkCartQuoteLine[];
+    /**
+     * TRUE when this cart's total already exceeds the shop's configured checkout
+     * maximum. OMITTED when the cart is within it.
+     *
+     * PAYMENT PATH, and advisory by design: the quote still prices and returns
+     * the cart so the storefront can warn the buyer while they are still looking
+     * at it, instead of letting them spend a click on a
+     * `cart_maximum_checkout_exceeded` rejection that explains nothing.
+     * `/from-cart` refuses authoritatively either way — this flag never
+     * AUTHORISES a checkout, it only ever stops one.
+     */
+    cart_max_exceeded?: true;
+    /**
+     * TRUE when at least one line is a PHYSICAL product. `total` then EXCLUDES
+     * shipping: the hosted checkout prices it from the buyer's address. Absent on
+     * a backend without physical products, so read it as `=== true`.
+     */
+    requires_shipping?: boolean;
+    /**
+     * The configured maximum, in this quote's currency. Present only alongside
+     * `cart_max_exceeded`, so it is read only when that flag is set.
+     */
+    cart_maximum_checkout?: string;
+    eligible_deals: SdkEligibleCartDeal[];
+    eligible_bundle_deals: Array<{
+        bundle_uniqid: string;
+        label: string;
+        /**
+         * The members the cart is still short of. `price` and `default_variant_id`
+         * are what let the teaser's Add button cart them with a real price
+         * snapshot — the storefront payload carries no catalog entry for a product
+         * the buyer has not opened, so this is the only price available here.
+         */
+        missing_products: Array<{
+            product_uniqid: string;
+            title: string;
+            quantity: number;
+            price: string;
+            default_variant_id: string;
+        }>;
+    }>;
+}
+interface SdkCartAddOptions {
+    price_variant_id?: string | null;
+    /** Identity fields — omitting one on a rebuild changes which line it is. */
+    addons?: SdkCartAddon[];
+    custom_fields?: Record<string, string>;
+    price_data?: {
+        unit_price: number;
+    };
+    pay_what_you_want_price?: number;
+    /** Display snapshot fields shown in the cart without a product lookup. */
+    title?: string;
+    variant_title?: string;
+    image_url?: string;
+    addon_labels?: string[];
+    max_quantity?: number;
+    min_quantity?: number;
+    replace_display_snapshot?: boolean;
+}
+interface SdkPage {
+    id: string;
+    slug: string;
+    name: string;
+    /**
+     * The merchant's body as MARKDOWN, not HTML — the dashboard's Pages editor
+     * stores it that way and every lane renders it through a markdown pass
+     * (`renderCmsPageMarkdownHtml` on the Easy lane). Null when the page has no
+     * body yet.
+     */
+    content: string | null;
+    /** 'faq' switches the page to the accordion; anything else renders the body. */
+    template_type?: string;
+    is_system?: boolean;
+    /** Template-specific payload. `faq_items` lives here for `template_type: 'faq'`. */
+    settings?: Record<string, unknown> | null;
+}
+interface SdkMenuItem {
+    id: string;
+    title: string;
+    /** Absent on a PAGE item — `page_slug` carries the destination instead. */
+    url?: string | null;
+    /**
+     * Set when the item points at one of the merchant's CMS pages. It wins over
+     * `url`, and resolves to `/page/<slug>` in the same tab.
+     */
+    page_slug?: string | null;
+    link_type?: string | null;
+    target?: string | null;
+    sort_order?: number;
+}
+interface SdkMenu {
+    id: string;
+    title: string;
+    /** 'header' | 'footer' | custom slot name. */
+    slot?: string | null;
+    item_count?: number | null;
+    items?: SdkMenuItem[];
+}
+interface SdkCheckoutResult {
+    success: boolean;
+    message?: string;
+    /**
+     * The backend's machine-readable refusal reason, present only on failures
+     * that name one. It is the server's FULL i18n key —
+     * `errors.checkout.affiliate_code_not_applicable`,
+     * `errors.checkout.coupon_no_longer_valid`,
+     * `errors.checkout.price_increased_since_quote`, … — because `from-cart`
+     * sends exactly that as `error_code` and the SDK copies it verbatim. The
+     * short reason names in the server's own code never cross the wire.
+     *
+     * The quote-proof family — `errors.checkout.quote_token_invalid`,
+     * `…_expired`, `…_stale`, and `errors.checkout.price_increased_since_quote`
+     * — means the proof this hand-off submitted could not be honoured (not ours,
+     * past its window, priced for a cart that has since moved, or the ceiling
+     * refusing an invoice that would price ABOVE the approved total). They are
+     * all cleared the same way: re-quote and let the buyer approve the current
+     * total before retrying.
+     *
+     * `message` is already localized prose meant for the buyer; it is NOT a
+     * branchable value — matching on its text breaks the moment the copy or the
+     * locale changes. Branch on this instead, and only on this.
+     */
+    code?: string;
+    redirectUrl?: string;
+    invoiceId?: string;
+}
+interface SdkRecentSaleEntry {
+    product_title: string;
+    seconds_ago: number;
+}
+interface SdkInitOptions {
+    shopId?: string;
+    apiBaseUrl?: string;
+    checkoutBaseUrl?: string;
+    currency?: string;
+    locale?: string;
+}
+/** The envelope every customer-account call answers with. */
+interface SdkResponse<T> {
+    success: boolean;
+    data?: T;
+    /** Buyer-safe sentence from the server. Display copy, never a branch value. */
+    message?: string;
+    /**
+     * The TRANSPORT status, absent when the request never reached a server.
+     *
+     * This is the field that separates "the buyer is signed out" (401) from "the
+     * API is broken" (5xx) or "the request never left the browser" (undefined).
+     * Branch on it before deciding a buyer has no session: signing someone out
+     * because an endpoint returned 500 throws away a session that is still valid.
+     */
+    status?: number;
+    /** Machine-readable refusal identifier, when the server emitted one. */
+    code?: string;
+    errorParams?: Record<string, unknown>;
+}
+/** One order row inside the dashboard payload. snake_case, unlike the list. */
+interface SdkCustomerDashboardOrder {
+    uniqid: string;
+    status: string;
+    /**
+     * USD-normalized total. `currency` is the BUYER display currency, so this
+     * number and that currency are not a pair — see `total_display`.
+     */
+    total: string;
+    /** The total in `currency`. Null when the invoice has no display amount. */
+    total_display: string | null;
+    currency: string;
+    created_at: string;
+    line_items: Array<{
+        product_title: string | null;
+        quantity: number;
+    }>;
+}
+/**
+ * One row of the buyer's purchased licenses.
+ *
+ * `expires_at` is EPOCH SECONDS, not milliseconds — the producer emits
+ * `EXTRACT(EPOCH FROM ...)::bigint` — and `null` means the license has no end
+ * date at all, which is a different thing from an expiry the client failed to
+ * read. `invoice_id` carries the ORDER's `uniqid`, so it addresses the same
+ * order-detail route as an invoice row.
+ *
+ * `renewable` is decided server-side: only the backend can see whether the
+ * product still exists, still sells and still licenses. A storefront must never
+ * derive it.
+ */
+interface SdkCustomerLicense {
+    uniqid: string;
+    invoice_id: string;
+    status: string;
+    hardware_id: string | null;
+    expires_at: number | null;
+    renewable: boolean;
+}
+/**
+ * One thing the shop has delivered: a license key, a file, or a code/link.
+ *
+ * A `license` deliverable's `id` is `license:<license uniqid>` and that is the
+ * only join between this list and {@link SdkCustomerLicense} — the license row
+ * carries the expiry, the hardware lock and the renewal flag, the deliverable
+ * carries the key itself.
+ *
+ * `href` on a `file` is a same-origin `/api/customer/invoice/:uniqid/download`
+ * path. The session cookie authorizes it, so it is followed as a plain link;
+ * nothing here attaches a token.
+ */
+interface SdkCustomerDeliverable {
+    id: string;
+    invoice_uniqid: string;
+    product_title: string;
+    kind: 'file' | 'serial' | 'license';
+    label: string;
+    value: string;
+    href: string | null;
+    created_at: string;
+}
+/**
+ * One subscription, with the actions the SERVER says are possible on it.
+ *
+ * `actions` is not advice: pause and resume are Stripe-only and status-bound,
+ * and a storefront that renders a control the flag denies is offering a button
+ * the backend will refuse. There is deliberately no payment-method action here
+ * — that endpoint hands out a signed redirect into the provider's portal and is
+ * not open to storefront code (ADR-0064).
+ */
+interface SdkCustomerSubscription {
+    uniqid: string;
+    status: string;
+    gateway: string;
+    current_period_end: string;
+    trial_end: string | null;
+    cancel_at_period_end: boolean;
+    canceled_at: string | null;
+    created_at: string;
+    plan: {
+        name: string;
+        price: string;
+        currency: string;
+        /** 'day' | 'week' | 'month' | 'year' as the gateway spells it. */
+        interval: string;
+        interval_count: number;
+    } | null;
+    payment_method: {
+        type: string;
+        card_brand: string | null;
+        card_last4: string | null;
+        card_exp_month: number | null;
+        card_exp_year: number | null;
+    } | null;
+    actions: {
+        can_pause: boolean;
+        can_resume: boolean;
+        can_cancel: boolean;
+        can_manage_payment_method: boolean;
+    };
+}
+/** One earned reward. `created_at` and `expires_at` are epoch SECONDS. */
+interface SdkCustomerRewardActivity {
+    id: string;
+    type: string;
+    status: string;
+    amount: string | null;
+    currency: string | null;
+    coupon_code: string | null;
+    reason: string;
+    created_at: number;
+    expires_at: number | null;
+}
+interface SdkCustomerRewards {
+    summary: {
+        available: string;
+        pending: string;
+        lifetime_earned: string;
+        currency: string;
+    };
+    activity: SdkCustomerRewardActivity[];
+}
+interface SdkCustomerAffiliateLink {
+    id: string;
+    label: string | null;
+    code: string;
+    url: string | null;
+    status: 'pending' | 'active' | 'inactive' | 'rejected';
+    is_primary: boolean;
+    total_clicks: number;
+    total_sales: number;
+    total_revenue: string;
+    effective_commission_percent: number;
+    effective_customer_discount_percent: number;
+}
+/**
+ * The buyer's standing in the shop's referral programme.
+ *
+ * Read-only on this lane. Converting a balance and requesting a payout move
+ * money toward the buyer and are not open to storefront code (ADR-0064, "money
+ * paths do not belong on the account API"), so this template renders what the
+ * buyer has earned and says where the payout lives.
+ */
+interface SdkCustomerAffiliateSummary {
+    /** `not_enrolled` is the availability gate for the whole referrals panel. */
+    state: string;
+    affiliate_codes_accepted_at_checkout: boolean;
+    balance_currency: string;
+    balances: {
+        pending: string;
+        available: string;
+        requested: string;
+        converted: string;
+        paid: string;
+    };
+    links: SdkCustomerAffiliateLink[];
+    commissions: Array<{
+        id: string;
+        invoice_id: string;
+        commission_amount: string;
+        status: string;
+        created_at: string | null;
+    }>;
+    claims: Array<{
+        id: string;
+        type: string;
+        status: string;
+        amount: string;
+        currency: string;
+        created_at: string | null;
+    }>;
+}
+/** One support ticket as the dashboard lists it. The thread is a second call. */
+interface SdkCustomerTicketSummary {
+    uniqid: string;
+    title: string;
+    status: string;
+    updated_at: string;
+    created_at: string | null;
+}
+type SdkCustomerLoyaltyTransactionType = 'EARN_ORDER' | 'EARN_REVIEW' | 'REDEEM' | 'ADJUST';
+interface SdkCustomerLoyalty {
+    enabled: boolean;
+    account: {
+        points_balance: number;
+        lifetime_points: number;
+    } | null;
+    settings: {
+        earn_rate_per_usd: number;
+        redeem_value_per_point: number;
+        min_redeem_points: number;
+    } | null;
+    transactions: Array<{
+        type: SdkCustomerLoyaltyTransactionType;
+        points: number;
+        balance_after: number;
+        description: string | null;
+        created_at: string;
+    }>;
+}
+interface SdkCustomerLoyaltyRedeem {
+    redeemed_points: number;
+    wallet_amount: string;
+    currency: string;
+    points_balance: number;
+    replayed: boolean;
+}
+type SdkCustomerWarrantyStatus = 'ACTIVE' | 'EXPIRED' | 'VOIDED';
+type SdkCustomerWarrantyClaimStatus = 'REQUESTED' | 'APPROVED' | 'DENIED';
+interface SdkCustomerWarranty {
+    uniqid: string;
+    invoice_uniqid: string;
+    product_title: string;
+    period_days: number;
+    starts_at: string;
+    expires_at: string;
+    status: SdkCustomerWarrantyStatus;
+    claim_status: SdkCustomerWarrantyClaimStatus | null;
+    created_at: string;
+}
+interface SdkCustomerWarrantyList {
+    warranties: SdkCustomerWarranty[];
+}
+interface SdkCustomerWarrantyClaim {
+    warranty: Omit<SdkCustomerWarranty, 'claim_status'> & {
+        claim_status: 'REQUESTED';
+    };
+}
+interface SdkCustomerDashboard {
+    shop: {
+        name: string;
+        currency: string;
+    };
+    customer: {
+        email: string;
+        name: string;
+    };
+    stats: {
+        invoices_count: number;
+        licenses_count: number;
+        deliverables_count: number;
+        tickets_count: number;
+    };
+    /**
+     * Null when the shop runs no wallet. That null IS the availability gate: a
+     * storefront must hide the wallet section rather than render a zero balance.
+     */
+    wallet: {
+        available: string;
+        total: string;
+        hold: string;
+        currency: string;
+        enabled: boolean;
+    } | null;
+    invoices: SdkCustomerDashboardOrder[];
+    rewards: SdkCustomerRewards;
+    affiliate: SdkCustomerAffiliateSummary;
+    subscriptions: SdkCustomerSubscription[];
+    licenses: SdkCustomerLicense[];
+    deliverables: SdkCustomerDeliverable[];
+    tickets: SdkCustomerTicketSummary[];
+}
+/** One order row in the paginated list. camelCase, unlike the dashboard. */
+interface SdkCustomerOrderSummary {
+    uniqid: string;
+    status: string;
+    /** USD-normalized, like the dashboard's `total`. Render `totalDisplay` first. */
+    total: string;
+    totalDisplay: string | null;
+    currency: string;
+    createdAt: string;
+    lineItems: Array<{
+        productTitle: string | null;
+        quantity: number;
+    }>;
+}
+/**
+ * Page-based, not cursor-based. The producer reads `page` and `limit` and
+ * answers with `has_more`; a cursor parameter is ignored upstream and returns
+ * page one forever.
+ */
+interface SdkCustomerOrderPage {
+    invoices: SdkCustomerOrderSummary[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        has_more: boolean;
+    };
+}
+/** Per-line fulfillment state, decided server-side and independent of payment. */
+type SdkCustomerDeliveryStatus = 'PENDING' | 'AWAITING_FULFILLMENT' | 'DELIVERED' | 'FAILED';
+/** What the shop delivered for one line. Null while nothing was delivered. */
+interface SdkCustomerDeliverySummary {
+    codes: string[];
+    links: Array<{
+        label: string;
+        value: string;
+        href?: string | null;
+    }>;
+    notes: string[];
+    serials: Array<{
+        value: string;
+        is_replacement: boolean;
+        is_replaced: boolean;
+    }>;
+}
+interface SdkCustomerOrderDetail {
+    uniqid: string;
+    status: string;
+    statusDetails: string | null;
+    total: string;
+    totalDisplay: string | null;
+    subtotal: string;
+    discount: string;
+    discountDisplay: string | null;
+    tax: string;
+    taxPercentage: string;
+    currency: string;
+    createdAt: string;
+    lineItems: Array<{
+        id: string;
+        productTitle: string;
+        variantTitle: string | null;
+        unitPrice: string;
+        quantity: number;
+        total: string;
+        deliveryText: string | null;
+        deliveryStatus: SdkCustomerDeliveryStatus;
+        deliverySummary: SdkCustomerDeliverySummary | null;
+    }>;
+    currentPayment: {
+        /** Internal rail — NATIVE_CRYPTO, NOWPAYMENTS, STRIPE… Not buyer-facing. */
+        gateway: string;
+        displayName: string | null;
+        /** Concrete coin, e.g. USDT_TRC20. Set for crypto rails. */
+        cryptoGateway: string | null;
+        blockchain: string | null;
+        /** Alternative method the buyer chose, e.g. 'Card', 'iDEAL'. */
+        apmMethod: string | null;
+    } | null;
+}
+interface ShoppexSdk {
+    init(storeSlug: string, options?: SdkInitOptions): unknown;
+    isInitialized(): boolean;
+    getConfig(): {
+        storeSlug: string;
+    };
+    getCart(): SdkCartItem[];
+    getCartItemCount(): number;
+    addToCart(productId: string, variantId: string, quantity?: number, options?: SdkCartAddOptions): void;
+    /**
+     * Patches a cart line. The second argument is an update object — passing a
+     * bare number silently does nothing, because the SDK reads named keys off it.
+     *
+     * `custom_fields` is part of the line's IDENTITY, so writing it makes the SDK
+     * recompute `line_id` and merge the line into any existing line that now has
+     * the same identity. A caller holding a list of line ids has to tolerate one
+     * of them no longer existing after a write — and, because the merge SUMS the
+     * two lines' quantities, has to treat it as a repricing: quantities are bound
+     * into the signed quote proof, `custom_fields` is not. See
+     * `checkoutFieldWriteRepriced` in `checkout-fields.ts`.
+     *
+     * `min_quantity` and `max_quantity` are TRI-STATE: an absent key leaves the
+     * stored bound alone, a number sets it, and `null` DELETES it. The null
+     * spelling is what a healed line needs — an `undefined` reads as "not
+     * mentioned", so a ceiling the merchant removed would survive every heal that
+     * tried to remove it. The SDK re-clamps the line's quantity after the write.
+     */
+    updateCartItem(lineId: string, updates: {
+        quantity?: number;
+        custom_fields?: Record<string, string>;
+        min_quantity?: number | null;
+        max_quantity?: number | null;
+    }): void;
+    removeFromCart(lineId: string): void;
+    clearCart(): void;
+    /**
+     * `currency` is not optional in practice: omitted, the SDK reads `?currency=`
+     * off window.location, which a client-side navigation has already dropped.
+     */
+    quoteCart(coupon?: string, currency?: string): Promise<{
+        success: boolean;
+        data?: SdkCartQuote;
+        message?: string;
+    }>;
+    getCartCoupon(): string | null;
+    /** The stored code's classification, or null when nothing is stored. */
+    getCartCouponSource(): SdkCartCodeSource | null;
+    /**
+     * Stores a code AND what kind of code it is. The source defaults to `'COUPON'`
+     * in the SDK, so an affiliate referral saved without it is later submitted as
+     * a coupon and the affiliate is never credited — pass the source the QUOTE
+     * reported, never a guess.
+     */
+    setCartCoupon(coupon: string, source?: SdkCartCodeSource): void;
+    clearCartCoupon(): void;
+    /**
+     * Reads `?ref=<code>` from the current URL, validates it and stores it for 30
+     * days (last-click). `checkout()` then sends the stored code on its own, so
+     * calling this once at boot is all a storefront has to do for referrals to
+     * pay out.
+     */
+    captureAffiliateFromUrl(param?: string): Promise<string | null>;
+    getAffiliateCode(): string | null;
+    /**
+     * Forgets the stored ambient referral. The storage key belongs to the SDK —
+     * this is the only supported way to drop the attribution, and the exit a
+     * storefront needs when the backend refuses the code the buyer is carrying.
+     */
+    clearAffiliateCode(): void;
+    /** Merchant-authored custom pages (About, Delivery info, …). */
+    getPages(): Promise<{
+        success: boolean;
+        data?: SdkPage[];
+        message?: string;
+    }>;
+    getPage(slug: string): Promise<{
+        success: boolean;
+        data?: SdkPage;
+        message?: string;
+    }>;
+    /** Merchant-configured navigation menus, keyed by slot (header/footer/…). */
+    getMenus(): Promise<{
+        success: boolean;
+        data?: SdkMenu[];
+        message?: string;
+    }>;
+    checkout(options?: {
+        email?: string;
+        /**
+         * Submitted as `coupon`. An OMITTED value is not "no coupon": the SDK then
+         * falls back to whatever is in cart storage (`resolveCheckoutCodes`), so
+         * suppressing a stored code takes an explicit empty string.
+         */
+        coupon?: string;
+        /**
+         * Submitted as `affiliate_code` — the field the payout is attributed on.
+         * A referral sent under `coupon` instead credits nobody.
+         *
+         * A tri-state, exactly like `coupon` (`normalizeAffiliateCode`):
+         * - OMITTED — the SDK reads the ambient `?ref=` code out of its own storage
+         *   at submit time, a SECOND read of storage the caller already looked at.
+         * - `''` — explicitly NONE: no referral is submitted and the storage read
+         *   is suppressed. This is how a caller pins "quoted without a referral".
+         * - non-empty — pinned: submitted verbatim.
+         *
+         * So the quote and the invoice only agree if the code is NAMED here, in
+         * every lane including the empty one.
+         */
+        affiliateCode?: string;
+        autoRedirect?: boolean;
+        /** Same as quoteCart: pass it, or the cart and the page disagree. */
+        currency?: string;
+    }): Promise<SdkCheckoutResult>;
+    getStorefrontRecentSales(): Promise<{
+        success: boolean;
+        data?: {
+            items: SdkRecentSaleEntry[];
+            window_hours: number;
+        };
+    }>;
+    /**
+     * Visitors active on this storefront in the last 10 minutes. A real count of
+     * real sessions — the header pill hides itself at 0 rather than inventing a
+     * livelier shop than the merchant has.
+     */
+    getStorefrontOnlineUsers(): Promise<{
+        success: boolean;
+        data?: {
+            count: number;
+            window_seconds: number;
+        };
+    }>;
+    /**
+     * Shop-level feedback/reviews (Shoppex has shop feedback, not per-product
+     * reviews). Returns [] when the shop has none — the caller must hide the
+     * reviews UI rather than render an empty block or fake entries.
+     */
+    getShopReviews(): Promise<{
+        success: boolean;
+        data?: SdkShopReview[];
+    }>;
+    /** Starts an in-page sign-in. Sends the email and nothing else. */
+    requestOtp(email: string): Promise<SdkResponse<unknown>>;
+    /**
+     * Finishes sign-in. The second argument is submitted as `otp`; the producer
+     * rejects a body that names it `code` with a 400.
+     *
+     * On success the WORKER sets the session cookie from the response it saw.
+     * Nothing here returns a token, and no storefront code may store one.
+     */
+    verifyOtp(email: string, otp: string): Promise<SdkResponse<unknown>>;
+    /** Ends the session. The worker clears the cookie on the way back. */
+    logout(): Promise<SdkResponse<unknown>>;
+    /**
+     * The signed-in customer, or a failure when there is no session.
+     *
+     * Only a **401** means "not signed in". Any other failure — 403, 5xx, a
+     * contract mismatch, a network error with no `status` at all — means the
+     * answer is unknown, and a storefront that renders the sign-in form there
+     * tells a buyer with a live session that they are signed out. Show an error
+     * and let them retry instead.
+     *
+     * Never treat a failure as a signed-in customer either: that renders an
+     * account shell around data nobody fetched.
+     */
+    me(): Promise<SdkResponse<unknown>>;
+    /**
+     * The overview payload — and the collection route for five other panels.
+     *
+     * Shop, customer, counters, the wallet gate, recent orders, and the lists
+     * that have no route of their own: licenses, deliverables, subscriptions,
+     * tickets, rewards and the affiliate summary.
+     */
+    dashboard(): Promise<SdkResponse<SdkCustomerDashboard>>;
+    /** Order history, page-based. */
+    /**
+     * `status` and `search` filter SERVER-side. The list is paged, so a filter
+     * applied to the page in hand would filter only the rows it happens to hold.
+     */
+    orders(options?: {
+        page?: number;
+        limit?: number;
+        status?: string;
+        search?: string;
+    }): Promise<SdkResponse<SdkCustomerOrderPage>>;
+    /** One order, by the `uniqid` the list rows carry. */
+    order(id: string): Promise<SdkResponse<SdkCustomerOrderDetail>>;
+    /** Loyalty settings, balance and the latest points activity. */
+    loyalty(): Promise<SdkResponse<SdkCustomerLoyalty>>;
+    /** Exchanges points for store credit. Keep one idempotency key per retryable submission. */
+    redeemLoyaltyPoints(input: {
+        points: number;
+        idempotencyKey: string;
+    }): Promise<SdkResponse<SdkCustomerLoyaltyRedeem>>;
+    /**
+     * The warranties this buyer holds. Given an order's `uniqid`, only that
+     * order's — the route filters on `invoices.uniqid`, which is the same id.
+     */
+    warranties(invoiceUniqid?: string): Promise<SdkResponse<SdkCustomerWarrantyList>>;
+    claimWarranty(uniqid: string, message?: string): Promise<SdkResponse<SdkCustomerWarrantyClaim>>;
+    /** Clears a license's hardware lock so the next activation claims it. */
+    resetLicenseHwid(uniqid: string): Promise<SdkResponse<unknown>>;
+    /** Renewal invoices for one subscription. */
+    subscriptionBillingHistory(uniqid: string): Promise<SdkResponse<unknown>>;
+    /**
+     * Ends a subscription. `cancel_at_period_end` decides whether the buyer keeps
+     * the time they already paid for — PayPal cannot, every other gateway can.
+     */
+    cancelSubscription(uniqid: string, options?: {
+        cancel_at_period_end?: boolean;
+        reason?: string | null;
+    }): Promise<SdkResponse<unknown>>;
+    pauseSubscription(uniqid: string): Promise<SdkResponse<unknown>>;
+    resumeSubscription(uniqid: string): Promise<SdkResponse<unknown>>;
+    /** The buyer's saved products. */
+    favorites(): Promise<SdkResponse<unknown>>;
+    /** Idempotent upstream, and a PUT — `customer-favorites.ts` has no POST route. */
+    addFavorite(productUniqid: string): Promise<SdkResponse<unknown>>;
+    removeFavorite(productUniqid: string): Promise<SdkResponse<unknown>>;
+    /**
+     * The affiliate summary as its own read. The Referrals panel takes it from
+     * `dashboard()` instead, but a merchant extending this template should not
+     * have to discover that the runtime has a method the types deny.
+     */
+    affiliate(): Promise<SdkResponse<unknown>>;
+    /** Opens a ticket. `title` is optional; the producer names it "Support Request". */
+    createTicket(payload: {
+        title?: string;
+        message: string;
+        invoice_id?: string;
+    }): Promise<SdkResponse<unknown>>;
+    /** One ticket with its whole message thread. */
+    ticket(uniqid: string): Promise<SdkResponse<unknown>>;
+    replyToTicket(uniqid: string, message: string): Promise<SdkResponse<unknown>>;
+    /**
+     * Renames the buyer. The email is NOT editable here: changing it is gated
+     * behind a fresh code in the backend and has no allowlisted path.
+     */
+    updateProfile(patch: {
+        name: string;
+    }): Promise<SdkResponse<unknown>>;
+    updateAvatar(file: File): Promise<SdkResponse<unknown>>;
+    removeAvatar(): Promise<SdkResponse<unknown>>;
+    /** Marketing consent: the shop's lists plus the global unsubscribe. */
+    emailPreferences(): Promise<SdkResponse<unknown>>;
+    updateEmailPreferences(patch: {
+        global_unsubscribed?: boolean;
+        list_subscriptions?: Array<{
+            list_id: string;
+            subscribed: boolean;
+        }>;
+    }): Promise<SdkResponse<unknown>>;
+    /** Signed-in devices. Never returns a token value, only a description. */
+    sessions(): Promise<SdkResponse<unknown>>;
+    revokeSession(id: string): Promise<SdkResponse<unknown>>;
+    /** Ends every session except the one making the call. */
+    revokeAllSessions(): Promise<SdkResponse<unknown>>;
+    /** Program configuration and this buyer's reseller relationship, if any. */
+    reseller(): Promise<SdkResponse<unknown>>;
+    /** APPLICATION mode: submits the producer's optional/required note. */
+    applyForReseller(note?: string): Promise<SdkResponse<unknown>>;
+    /** OPEN mode: enrolls the signed-in buyer immediately. */
+    enrollAsReseller(): Promise<SdkResponse<unknown>>;
+    /** MANUAL mode: redeems the merchant-issued invitation token. */
+    acceptResellerInvite(token: string): Promise<SdkResponse<unknown>>;
+    /** Wholesale catalog at this buyer's tier prices. */
+    resellerCatalog(options?: {
+        search?: string;
+        page?: number;
+        per_page?: number;
+    }): Promise<SdkResponse<unknown>>;
+    /** Server-prices a basket, including volume discounts, without writing. */
+    quoteResellerOrder(items: Array<{
+        product_id: string;
+        variant_id?: string;
+        quantity: number;
+    }>): Promise<SdkResponse<unknown>>;
+    /** Page-based wholesale order history. */
+    resellerOrders(options?: {
+        page?: number;
+        per_page?: number;
+    }): Promise<SdkResponse<unknown>>;
+    /** One wholesale order, including delivery state and serials. */
+    resellerOrder(uniqid: string): Promise<SdkResponse<unknown>>;
+    /** Wholesale prepaid balance, separate from the retail wallet panel. */
+    resellerWallet(): Promise<SdkResponse<unknown>>;
+    /** Lists the buyer's reseller API keys without plaintext secrets. */
+    resellerApiKeys(): Promise<SdkResponse<unknown>>;
+}
+interface SdkShopReview {
+    id: string;
+    /** 1-5, normalized by the SDK from the shop-feedback score (5/3/1). */
+    rating: number;
+    /** Buyer names are anonymized by the API to "Customer Hidden". */
+    author?: string;
+    customer_name?: string;
+    comment?: string;
+    message?: string | null;
+    product_title?: string | null;
+    /** True when the review is tied to a real completed purchase. */
+    verified?: boolean;
+    is_automated?: boolean;
+    created_at: string;
+}
+type AddonBarPreset = 'brand_blue' | 'emerald' | 'sunset' | 'rose' | 'charcoal' | 'custom';
+type StorefrontAddon = {
+    id: string;
+    type: 'announcement_bar';
+    slot: string;
+    component: 'announcement_bar';
+    sort_order: number;
+    props: {
+        addon_id: string;
+        text: string;
+        link_label?: string | null;
+        link_url?: string | null;
+        dismissible: boolean;
+        display_mode: 'static' | 'marquee';
+        theme_preset: AddonBarPreset;
+        animation_speed_seconds: number;
+        background_color: string;
+        text_color: string;
+    };
+} | {
+    id: string;
+    type: 'countdown_bar';
+    slot: string;
+    component: 'countdown_bar';
+    sort_order: number;
+    props: {
+        addon_id: string;
+        text: string;
+        end_at: string;
+        link_label?: string | null;
+        link_url?: string | null;
+        dismissible: boolean;
+        theme_preset: AddonBarPreset;
+        expired_behavior: 'hide' | 'message';
+        expired_message?: string | null;
+        density: 'compact' | 'comfortable';
+        cta_style: 'subtle' | 'outline' | 'solid';
+        timer_style: 'minimal' | 'boxed';
+        background_color: string;
+        text_color: string;
+    };
+} | {
+    id: string;
+    type: 'promo_info_card';
+    slot: string;
+    component: 'promo_info_card';
+    sort_order: number;
+    props: {
+        addon_id: string;
+        eyebrow?: string | null;
+        title: string;
+        body: string;
+        link_label?: string | null;
+        link_url?: string | null;
+        theme_preset: 'indigo' | 'emerald' | 'amber' | 'rose' | 'slate' | 'custom';
+        layout_style: 'compact' | 'feature' | 'alert';
+        density: 'compact' | 'comfortable';
+        cta_style: 'subtle' | 'outline' | 'solid';
+        icon: 'sparkles' | 'megaphone' | 'gift' | 'truck' | 'shield' | 'support' | 'none';
+        icon_visibility: 'show' | 'hide';
+        background_color: string;
+        text_color: string;
+        accent_color: string;
+    };
+} | {
+    id: string;
+    type: 'recent_purchase_popup';
+    slot: string;
+    component: 'recent_purchase_popup';
+    sort_order: number;
+    props: {
+        addon_id: string;
+        title: string;
+        cooldown_seconds: number;
+        items: Array<{
+            customer_label: string;
+            product_title: string;
+            created_at: string;
+        }>;
+    };
+} | {
+    id: string;
+    type: 'coupon_popup_modal';
+    slot: string;
+    component: 'coupon_popup_modal';
+    sort_order: number;
+    props: {
+        addon_id: string;
+        eyebrow?: string | null;
+        title: string;
+        body: string;
+        coupon_code: string;
+        primary_button_label: string;
+        secondary_button_label: string;
+        disclaimer?: string | null;
+        theme_preset: 'midnight' | 'ocean' | 'ember' | 'forest' | 'custom';
+        trigger: 'delay' | 'exit_intent';
+        delay_seconds: number;
+        show_once_per_session: boolean;
+        reminder_hours: number;
+        background_color: string;
+        text_color: string;
+        accent_color: string;
+        hero_image_url?: string | null;
+        discount_display?: string | null;
+        expires_at?: string | null;
+    };
+};
+declare global {
+    interface Window {
+        shoppex?: ShoppexSdk;
+        /** SDK bootstrap globals injected by the Shoppex storefront/preview worker. */
+        shopSlug?: string;
+        shopId?: string;
+        apiBaseUrl?: string;
+        checkoutBaseUrl?: string;
+        defaultCurrency?: string;
+    }
+}
+
+/**
+ * Merchant-authored product badges ("New!", "Limited", "Best value").
+ *
+ * Purely decorative merchandising the merchant attaches in the dashboard. They
+ * never affect price, stock or fulfilment, and they never speak for the
+ * storefront: a badge cannot say a product is available, on sale, or in stock —
+ * those remain the theme's own signals, derived from real fields.
+ *
+ * Ported rather than imported, for the same reason `video-embed.ts` is: this
+ * theme builds standalone from `templates/code-storefronts/`, in an offline
+ * sandbox, with no workspace dependency on `@shoppex/builder-contracts`. The
+ * canonical contract is `packages/builder-contracts/src/product-badges.ts` —
+ * keep the wire field names, the caps and the contrast rule in step with it.
+ *
+ * Everything below reads UNTRUSTED JSON: the payload arrives over the network
+ * in `window.__SHOPPEX_INITIAL__`. Entries that do not parse are dropped rather
+ * than repaired — a badge with no usable label has no meaning, and inventing
+ * one would be a fabricated value on a merchandising surface.
+ */
+/**
+ * The icon catalog the dashboard offers. A name outside this list is NOT an
+ * error — the catalog is append-only upstream, so a storefront artifact built
+ * before an icon was added must degrade to a text-only badge rather than throw
+ * on a name it has never heard of.
+ */
+declare const PRODUCT_BADGE_ICON_NAMES: readonly ["sparkles", "flame", "star", "zap", "tag", "percent", "trending-up", "megaphone", "party-popper", "crown", "gem", "trophy", "award", "medal", "badge-check", "thumbs-up", "heart", "shield", "shield-check", "lock", "handshake", "rocket", "truck", "clock", "timer", "infinity", "refresh-ccw", "download", "package", "send", "headphones", "message-circle", "life-buoy", "users", "gamepad-2", "monitor", "smartphone", "key", "file-text", "book-open", "music", "video", "image", "palette", "code", "wrench", "wallet", "credit-card", "globe", "gift", "bot"];
+type ProductBadgeIconName = (typeof PRODUCT_BADGE_ICON_NAMES)[number];
+/** One badge, in this theme's camelCase model. */
+interface ProductBadge {
+    label: string;
+    /** null for a text-only badge, and for any icon name this build cannot draw. */
+    icon: ProductBadgeIconName | null;
+    /** `#rrggbb` lowercase, or null when the theme owns the colour. */
+    backgroundColor: string | null;
+    /**
+     * The readable foreground for `backgroundColor`, decided by WCAG contrast.
+     * null exactly when `backgroundColor` is null — the theme then owns both.
+     */
+    foregroundColor: string | null;
+    showOnProductCard: boolean;
+    showOnProductPage: boolean;
+}
+/**
+ * The readable foreground for a badge background.
+ *
+ * The merchant picks the fill from a colour well with no contrast check of its
+ * own, so the label colour cannot also be theirs: a mid-yellow badge with white
+ * text is unreadable and a navy badge with black text is worse. Both candidates
+ * are scored by WCAG contrast ratio against the chosen fill and the higher one
+ * wins, which is the same decision the other lane makes for the same badge.
+ *
+ * Returns null when there is no explicit background — the theme then owns both
+ * colours, and substituting one here would override its palette.
+ */
+declare function resolveBadgeForeground(backgroundColor: string | null): string | null;
+/**
+ * The `badges` array off the product wire. Missing, malformed or empty all
+ * produce `[]` — a product without badges is the overwhelmingly common case and
+ * is not an error.
+ */
+declare function parseProductBadges(value: unknown): ProductBadge[];
+/** Badges the catalog card shows, in the merchant's order. */
+declare function badgesForCard(badges: readonly ProductBadge[]): ProductBadge[];
+/** Badges the product page shows, in the merchant's order. */
+declare function badgesForProductPage(badges: readonly ProductBadge[]): ProductBadge[];
+
+/**
+ * The `window.__SHOPPEX_INITIAL__` contract: catalog, store switches and addon
+ * slots, injected by the Shoppex storefront (or preview) worker immediately
+ * before `</head>` per
+ * `packages/builder-contracts/src/storefront-initial-data-html.ts`.
+ *
+ * This is PLATFORM data, not merchant content — the theme never authors it and
+ * must never invent it. Merchant-authored content lives in
+ * `src/config/site-config.ts` and is read from the same object under
+ * `store.builder_settings.theme.content`.
+ */
+
+interface StorefrontPriceVariant {
+    id: string;
+    label: string;
+    /** What this option states about its term; `inherit` defers to the product. */
+    license: LicenseStatement;
+    /** Display unit price with the product percent discount already applied. */
+    price: number;
+    /**
+     * Undiscounted display-currency unit price — the input for line-level
+     * pricing, where the percent is applied to the whole line like the quote
+     * does, and the floor the server holds pay-what-you-want amounts to.
+     */
+    baseUnitPrice: number;
+    stock: number | null;
+    quantityMin: number | null;
+    quantityMax: number | null;
+    imageUrl: string | null;
+    isFeatured: boolean;
+}
+interface VolumeDiscountRule {
+    quantity: number;
+    type: 'PERCENTAGE' | 'FIXED';
+    value: number;
+}
+type ProductBundleItem = {
+    /** Cart id (uniqid) — what addToCart expects. */
+    id: string;
+    title: string;
+    variantId: string;
+    unitPrice: number;
+    imageUrl: string | null;
+    variantTitle: string | null;
+};
+/**
+ * A "buy these together" offer the merchant configured. The discount is applied
+ * by the backend when the cart is quoted — the theme only advertises it, it
+ * never computes the charged price itself.
+ */
+type ProductBundle = {
+    id: string;
+    title: string;
+    discountType: 'PERCENTAGE' | 'FIXED';
+    discountAmount: number;
+    items: ProductBundleItem[];
+};
+type ProductContentTab = {
+    title: string;
+    html: string;
+};
+/**
+ * A paid extra the buyer may add to the line. The price is a per-unit surcharge
+ * on top of the resolved variant price, and `required` options are locked on —
+ * the buy box shows them checked and refuses to clear them, because the backend
+ * charges them either way.
+ */
+type ProductAddon = {
+    id: string;
+    title: string;
+    price: number;
+    required: boolean;
+};
+type ProductFaq = {
+    question: string;
+    answer: string;
+};
+/**
+ * One ACTIVE "buy N, get M" deal on this product.
+ *
+ * The server filters the list to the currently live window before it emits it,
+ * so the storefront advertises what `CartQuoteService` would actually apply —
+ * it never computes the discount itself. The discounted units sit WITHIN the
+ * required quantity (they are not extra items on top), and
+ * `maxApplicationsPerCart` caps how often the reward repeats in one cart; both
+ * are `applyAutomaticProductDeals` semantics and the wording depends on them.
+ *
+ * `endsAt` is what makes a row time-limited. Once it passes the backend stops
+ * applying the deal, so the WHOLE row has to disappear — not just its
+ * countdown — which is why the panel drops expired rows rather than freezing
+ * them at 00:00:00.
+ */
+type ProductAutomaticDeal = {
+    id: string;
+    /** Merchant title. Empty when they named the rule nothing. */
+    title: string;
+    requiredQuantity: number;
+    discountedQuantity: number;
+    /** FREE gives the units away; PERCENTAGE takes `discountValue` percent off. */
+    discountType: 'FREE' | 'PERCENTAGE';
+    /** Percent off the discounted units. 0 for a FREE deal. */
+    discountValue: number;
+    /** How often the reward repeats per cart; null when uncapped. */
+    maxApplicationsPerCart: number | null;
+    /** ISO timestamp the deal stops applying, or null when it does not expire. */
+    endsAt: string | null;
+};
+/**
+ * One detail the merchant requires from the buyer for this product — a Steam
+ * id, a server name, a licence holder.
+ *
+ * PAYMENT PATH. These are not decoration: the backend validates them when the
+ * invoice is built (`custom_fields_validation_failed`), so a product with a
+ * REQUIRED field cannot be sold at all until its value reaches the cart line.
+ * The values ride on the cart line's `custom_fields`, which is also part of the
+ * SDK's line identity — see `checkout-fields.ts`.
+ *
+ * The shape mirrors the SDK's own `StorefrontCustomField`
+ * (`packages/sdk/src/utils/storefront-custom-fields.ts`), because that is what
+ * the Easy lane validates against and the two lanes must agree about which
+ * value a merchant's definition accepts.
+ */
+type ProductCustomField = {
+    name: string;
+    /** 'text' | 'textarea' | 'checkbox' | … — anything else renders as text. */
+    type: string;
+    required: boolean;
+    defaultValue: string;
+    placeholder: string;
+    /** Merchant-authored validation pattern. Absent when they set none. */
+    regex: string | null;
+};
+/** A category a product belongs to. The id is what the filter chips match on. */
+type ProductCategoryRef = {
+    id: string;
+    title: string;
+};
+/**
+ * Product kinds the catalog renders differently. `SUBSCRIPTION` earns a badge,
+ * `INFO_CARD` is not buyable at all, `SERIALS` reads its stock straight off
+ * the product row instead of aggregating variants, and `PHYSICAL` ships to an
+ * address the hosted checkout collects, so it is never "instant".
+ */
+type ProductType = 'PRODUCT' | 'SUBSCRIPTION' | 'INFO_CARD' | 'SERIALS' | 'PHYSICAL';
+/**
+ * What a product promises about delivery.
+ *
+ * - `shipped`: a PHYSICAL product. Its digital `delivery_time` is null, which
+ *   would otherwise read as instant, so the type decides first.
+ * - `timed`: the merchant set a delivery time.
+ * - `instant`: digital with no delivery time.
+ *
+ * Parity with the hosted checkout's `apps/checkout/lib/delivery-promise.ts`.
+ */
+type DeliveryPromise = {
+    kind: 'shipped';
+} | {
+    kind: 'timed';
+    count: number;
+    unit: DeliveryTimeUnit;
+} | {
+    kind: 'instant';
+};
+declare function resolveDeliveryPromise(product: Pick<StorefrontProduct, 'productType' | 'deliveryTimeCount' | 'deliveryTimeUnit'>): DeliveryPromise;
+/**
+ * How often a subscription product is charged, and how long it is free first.
+ *
+ * PARITY CONTRACT. The Easy lane derives the same three facts from the same
+ * flat wire fields in
+ * `packages/storefront-render-core/src/subscription-billing.ts`, and the
+ * wordings below are that module's wordings. A change on either side without
+ * the other makes the two lanes describe one product differently, which is the
+ * one thing this template may not do.
+ */
+type SubscriptionIntervalUnit = 'DAY' | 'WEEK' | 'MONTH' | 'YEAR';
+interface ProductSubscription {
+    /**
+     * The billing interval, or null when the merchant configured none. The
+     * product contract allows a SUBSCRIPTION product without an interval, so the
+     * buy box then prints no cadence rather than inventing one.
+     */
+    intervalUnit: SubscriptionIntervalUnit | null;
+    /** Intervals per charge, at least 1. */
+    intervalCount: number;
+    /** Free-trial length in days; 0 when the merchant set none. */
+    trialDays: number;
+}
+/** The cadence as it reads next to a price: "per month", "every 3 months". */
+declare function formatSubscriptionCadence(subscription: ProductSubscription): string;
+/** "7-day free trial" — the plan charges nothing for those days. */
+declare function formatSubscriptionTrial(subscription: ProductSubscription): string;
+interface StorefrontProduct {
+    /** uniqid — the identifier the cart/SDK use for this product. */
+    id: string;
+    /** Drives the catalog badge, the buy controls and the stock aggregation. */
+    productType: ProductType;
+    /**
+     * The product's real database id. Distinct from `id` (uniqid); shop feedback
+     * references products by this id, so review matching must use it.
+     */
+    productId: string;
+    name: string;
+    price: number;
+    currency: string;
+    description: string | null;
+    slug: string | null;
+    imageUrl: string | null;
+    /**
+     * The product's own image attachments, in the merchant's order — the product
+     * page gallery. Empty when the product has none; the gallery then falls back
+     * to `imageUrl`, the same resolution the Easy lane's gallery producer applies.
+     * The wire carries no per-image alt text, so the alt is the product title.
+     */
+    imageUrls: string[];
+    stock: number | null;
+    /**
+     * Merchant-set "Low Stock Warning" threshold (`quantity_warning` on the
+     * wire), null when disabled. NOT `stock_delimiter` — that field is the text
+     * delimiter splitting the serial-key blob, never a number.
+     */
+    lowStockThreshold: number | null;
+    /** Per-product stock-counter override; null inherits the shop-wide setting. */
+    hideStockCounter: boolean | null;
+    /**
+     * Quantity-tier discounts, sorted ascending by quantity. The backend applies
+     * them at charge time, so the displayed line total must apply them too or
+     * the buyer sees a higher number than they pay.
+     */
+    volumeDiscounts: VolumeDiscountRule[];
+    /**
+     * Buyers may choose their own unit price at or above the resolved
+     * product/variant price. Without an amount input the checkout silently
+     * charges the minimum, so the buy box must render one when this is set.
+     */
+    payWhatYouWant: boolean;
+    /** Normalized product percent discount (0 when none, and always 0 for PWYW). */
+    discountPercent: number;
+    /**
+     * Undiscounted starting unit price (min variant, or the base for
+     * variant-less products) — the line-pricing input for the no-variant case.
+     */
+    baseUnitPrice: number;
+    /**
+     * The product ROW's own undiscounted price, before variants are considered.
+     * Distinct from `baseUnitPrice`, which already falls back to the cheapest
+     * variant: a variant-led product carries 0 here, and that zero is what marks
+     * its catalog price as a range ("$7.00 - $50.00") rather than a single
+     * amount. Collapsing the two would price every variant product from its
+     * minimum and silently drop the range.
+     */
+    basePrice: number;
+    priceVariants: StorefrontPriceVariant[];
+    quantityMin: number;
+    quantityMax: number | null;
+    /** Units sold, for social proof. 0 when the shop has no sales for it. */
+    soldCount: number;
+    /** Merchant flagged this product as a bestseller. */
+    bestseller: boolean;
+    /**
+     * Merchant-authored decorative badges, in their order, at most four. Empty
+     * on almost every product. Purely merchandising — see `product-badges.ts`:
+     * they never speak for availability, price or fulfilment, so they are read
+     * alongside the theme's own signals rather than instead of them.
+     */
+    badges: ProductBadge[];
+    /** Merchant-assigned listing order; lower sorts first. */
+    sortPriority: number;
+    /** ISO timestamp the product was created, or null when the payload omits it. */
+    createdAt: string | null;
+    /** Categories this product belongs to. Empty when uncategorised. */
+    categories: ProductCategoryRef[];
+    /** Bundle offers this product takes part in. Empty when it is in none. */
+    bundles: ProductBundle[];
+    /**
+     * Active quantity deals on this product, in the merchant's order. Empty when
+     * the product has none or every rule is malformed — see `ProductAutomaticDeal`.
+     */
+    automaticDeals: ProductAutomaticDeal[];
+    /**
+     * The merchant's product video as an embeddable, allowlisted `src`. null when
+     * they set none OR when the host is not one the storefront frames — see
+     * `video-embed.ts`.
+     */
+    videoEmbedSrc: string | null;
+    /** Paid extras offered alongside this product. Empty when it has none. */
+    addons: ProductAddon[];
+    /**
+     * Details the merchant collects from the buyer for this product. Empty when
+     * they configured none. A REQUIRED entry makes the product unsellable until
+     * its value is on the cart line — see `ProductCustomField`.
+     */
+    customFields: ProductCustomField[];
+    /**
+     * The merchant PAUSED this product ("Coming soon"). It is not a supply state
+     * and has nothing to do with stock or `orderable`: the backend refuses to
+     * sell it at any inventory level, so the storefront must not offer it. Same
+     * precedence the document lane applies (`isProductOutOfStock` checks it
+     * before it looks at stock at all).
+     */
+    onHold: boolean;
+    /**
+     * Original price when a discount applies (price is the discounted one).
+     * null when there is no discount — never a fabricated "was" price.
+     */
+    compareAtPrice: number | null;
+    /**
+     * Average star rating (1-5) derived from REAL feedback only. null when the
+     * product has zero feedback — the UI then renders no stars rather than a
+     * fake score.
+     */
+    rating: number | null;
+    /** Number of feedback entries the rating is based on (0 when none). */
+    ratingCount: number;
+    /**
+     * The feedback tally as the payload states it: how many buyers were
+     * positive, neutral or negative. null exactly when `rating` is null.
+     */
+    ratingTally: {
+        positive: number;
+        neutral: number;
+        negative: number;
+    } | null;
+    /** Bulleted selling points shown in the buy box. */
+    highlights: string[];
+    /**
+     * Merchant-defined key/value pairs, set per product in the dashboard under
+     * Integrations -> Metadata. Always present ({} when the merchant set none)
+     * and every value is a string, so `product.metadata.status` is safe to read
+     * without a guard.
+     *
+     * This is your extension point: values you need that Shoppex has no field for
+     * — a release status, an accent colour, a grouping tag. The merchant edits
+     * them in the dashboard, so changing one does NOT require rebuilding this
+     * storefront. Nothing here is rendered for you; read the keys your shop uses
+     * and render them yourself.
+     *
+     * Public: everything in here is readable by anyone who opens the store.
+     */
+    metadata: Record<string, string>;
+    /** Extra merchant-authored content tabs ({title, html}). */
+    descriptionTabs: ProductContentTab[];
+    /** Per-product FAQ entries for the details accordion. */
+    faqs: ProductFaq[];
+    /** What this product states about its licence term. Resolve with resolveLicenseTerm. */
+    license: LicenseStatement;
+    /** Whether licensing is on at all; a stale term must not be advertised when it is off. */
+    licensingEnabled: boolean;
+    /** Estimated delivery time as a bare count (null when unset/instant). */
+    deliveryTimeCount: number | null;
+    /** Unit `deliveryTimeCount` is counted in: 'minutes' | 'hours' | 'days'. */
+    deliveryTimeUnit: DeliveryTimeUnit;
+    /**
+     * Recurring billing, present only on a product the merchant sells as a
+     * subscription. null on every other product.
+     */
+    subscription: ProductSubscription | null;
+}
+interface StorefrontSettings {
+    cartEnabled: boolean;
+    hideOutOfStock: boolean;
+    hideStockCounter: boolean;
+    /**
+     * Buyer-facing switches the MERCHANT owns, not the theme.
+     *
+     * A storefront that moves to the Advanced lane must not quietly re-enable
+     * what its owner turned off, or offer a contact form the backend will refuse.
+     * The document lane has honoured all three from the start.
+     */
+    searchEnabled: boolean;
+    contactFormEnabled: boolean;
+    requireInvoiceForContact: boolean;
+    /**
+     * The merchant centres bundle cards. A shop-level presentation switch, not a
+     * theme setting: the Easy lane reads `ctx.shop.center_group_titles` and
+     * re-lays the GROUP card out — product cards are untouched.
+     */
+    centerGroupTitles: boolean;
+    /**
+     * The merchant does not want the product's own picture used as its gallery.
+     * The Easy lane's gallery producer empties the image list outright when this
+     * is on, so the product page shows its placeholder frame instead.
+     */
+    descriptionSkipDefaultImage: boolean;
+    /**
+     * Whether pictures INSIDE a product description are shown. Off strips every
+     * `<img>` from the description and from each content tab, the same rewrite
+     * `stripDescriptionImages` performs on the document lane. It does not touch
+     * the gallery, which is `descriptionSkipDefaultImage`'s job.
+     */
+    descriptionImage: boolean;
+    /**
+     * The merchant let buyers re-sort the catalog. Off hides the control on every
+     * listing surface and pins the order to `defaultSort` — the same AND the Easy
+     * lane applies (`enrichPageAllProductsBlockSettings`: the block setting and
+     * `shop.sort_enabled` both have to be on).
+     */
+    sortEnabled: boolean;
+    /**
+     * The order the merchant wants their catalog listed in, normalized to the
+     * four keys every lane sorts by. It is the INITIAL sort of a listing and the
+     * only sort when `sortEnabled` is false.
+     */
+    defaultSort: StorefrontSortKey;
+    /**
+     * Every currency this shop sells in, the shop's own default first, uppercased
+     * and de-duplicated. One entry (or none) means the shop has nothing to switch
+     * between and the header renders no control.
+     */
+    availableCurrencies: string[];
+    /** The currency the merchant configured — the one served without a choice. */
+    defaultCurrency: string;
+    /**
+     * The currency THIS page was priced in. It is the buyer's choice, their
+     * country's match, or the shop default, resolved at the edge before the
+     * catalog was fetched — so it is the only currency the amounts on screen are
+     * actually in.
+     */
+    activeCurrency: string;
+    /**
+     * Payment gateway codes the shop has connected. The cart turns them into the
+     * brand marks under its checkout button — merchant fact, so an empty list
+     * renders no row rather than a reassuring default.
+     */
+    availableGateways: string[];
+}
+/**
+ * The shop itself: the identity and the aggregate metrics the storefront
+ * chrome renders. Merchant-owned facts, never theme content — a theme that
+ * authored its own store name or sales count would be publishing a claim the
+ * merchant never made.
+ */
+interface StorefrontShop {
+    /** The shop's public display name. */
+    name: string;
+    /** Branding/domain logo, falling back to the profile picture for logo surfaces. */
+    logoUrl: string | null;
+    /** Shop profile picture, falling back to the logo only when no avatar exists. */
+    avatarUrl: string | null;
+    /** Merchant-configured social profiles, in the platform's presentation order. */
+    socialLinks: SocialLink[];
+    /**
+     * The merchant's published terms of service, as authored HTML — null when
+     * the shop has no terms or turned them off. `/terms` renders it through
+     * `sanitizeMerchantHtml`, never raw.
+     */
+    termsHtml: string | null;
+    /** True when the merchant published terms and the `/terms` route has content. */
+    hasPublishedTerms: boolean;
+    /**
+     * The shop's reward program, or null when it is off / has no perks. Merchant
+     * fact: the headline and the perk labels are the merchant's wording, and a
+     * theme that supplied its own would advertise a program nobody configured.
+     */
+    rewardProgram: RewardProgramSummary | null;
+    /**
+     * The shop's wholesale reseller program, or null when the shop runs none.
+     * Merchant fact: only a shop that actually accepts resellers may advertise
+     * one, so the footer's "Become a reseller" link is gated on this and not on
+     * theme content.
+     */
+    resellerProgram: ResellerProgramSummary | null;
+    stats: StorefrontShopStats;
+}
+/**
+ * The reseller program off the wire, gated the way the Easy lane's footer link
+ * gates it (`blocks/reseller-program-link.ts`): a summary is usable only when
+ * it names an enrolment mode the portal can serve. Both modes render the SAME
+ * link — the portal decides between one-click enrolment and the application
+ * form.
+ */
+type ResellerProgramSummary = {
+    enrollmentMode: 'OPEN' | 'APPLICATION';
+};
+/**
+ * The reward-program teaser's data, gated exactly as the Easy lane gates it
+ * (`blocks/reward-program-teaser.ts` + `mapRewardProgramSummary`): the program
+ * must be enabled, it must carry a headline, and it must have at least one
+ * usable perk. Anything short of that is not a program to advertise, so the
+ * whole summary is null and every teaser renders nothing.
+ */
+type RewardProgramSummary = {
+    headline: string;
+    items: RewardProgramItem[];
+};
+/**
+ * One perk. `triggerType` and `actionType` are required by the platform's own
+ * mapper — a row missing either is a half-configured rule, not a perk — even
+ * though only the label is rendered.
+ */
+type RewardProgramItem = {
+    triggerType: string;
+    actionType: string;
+    label: string;
+};
+type SocialNetwork = 'discord' | 'telegram' | 'youtube' | 'twitter' | 'instagram' | 'tiktok' | 'facebook' | 'reddit' | 'email';
+type SocialLink = {
+    network: SocialNetwork;
+    href: string;
+};
+/**
+ * Aggregate shop metrics for the store-stats strip.
+ *
+ * Counts are raw numbers, not display strings: formatting belongs to the
+ * component. `averageRating` and `reviewCount` are independent on purpose —
+ * a shop can carry a rating from transferred feedback without a countable
+ * review, and rounding that to "no reviews" would drop a real number.
+ */
+interface StorefrontShopStats {
+    productsSold: number;
+    customers: number;
+    reviewCount: number;
+    /** 1-5, or null when the shop has no rating at all. */
+    averageRating: number | null;
+    /** Products the storefront lists — the theme counts them, the API does not. */
+    productCount: number;
+}
+/**
+ * A merchant-curated bundle of products. The wire payload references its
+ * members by uniqid; the members themselves are ordinary catalog products, so
+ * they arrive in `products` and are resolved from there.
+ */
+interface StorefrontGroup {
+    id: string;
+    title: string;
+    description: string | null;
+    imageUrl: string | null;
+    /** Category the merchant filed the bundle under, if any. */
+    categoryId: string | null;
+    /** Member product uniqids, in the merchant's order. */
+    productIds: string[];
+    /** Member count as the API counts it — may exceed the resolvable members. */
+    productsCount: number;
+    sortPriority: number;
+}
+interface StorefrontCategory {
+    id: string;
+    slug: string;
+    title: string;
+    /** The merchant's category picture. Null leaves the filter chip text-only. */
+    imageUrl: string | null;
+    productsCount: number;
+    groupsCount: number;
+}
+/**
+ * One entry of the storefront's listing order.
+ *
+ * `items` is a pure display-order reference list: it decides WHICH products and
+ * groups the storefront lists and in what order, and the referenced records are
+ * delivered exactly once in `products` / `groups`. A storefront that listed
+ * `products` directly would show unlisted rows (bundle members, hidden
+ * products) the merchant never put on the shelf.
+ */
+interface StorefrontListingItem {
+    type: 'product' | 'group';
+    id: string;
+    sortPriority: number;
+}
+interface ShoppexInitialData {
+    store?: Record<string, unknown> & {
+        builder_settings?: {
+            theme?: {
+                content?: unknown;
+            };
+        };
+    };
+    products?: unknown[];
+    groups?: unknown[];
+    items?: unknown[];
+    categories?: unknown[];
+    addons?: {
+        items?: StorefrontAddon[];
+    };
+}
+declare global {
+    interface Window {
+        __SHOPPEX_INITIAL__?: ShoppexInitialData;
+    }
+}
+/**
+ * Whether the page carries an injected payload AT ALL.
+ *
+ * Not a validity check — an empty object passes. It separates "nothing injected
+ * this document" from "something was injected and is wrong", which are two
+ * different faults with two different fixes. See `boot` in `App.tsx`.
+ */
+declare function hasInjectedStorefrontData(): boolean;
+/** Merchant-authored content, or undefined when the store has none yet. */
+declare function getAuthoredContent(): unknown;
+declare function getProducts(): StorefrontProduct[];
+declare function getProductGroups(): StorefrontGroup[];
+declare function getStorefrontCategories(): StorefrontCategory[];
+declare function getStorefrontListing(): StorefrontListingItem[];
+declare function getStorefrontShop(productCount: number): StorefrontShop;
+/** The four orders every Shoppex lane sorts a catalog listing by. */
+declare const STOREFRONT_SORT_KEYS: readonly ["featured", "newest", "price-asc", "price-desc"];
+type StorefrontSortKey = (typeof STOREFRONT_SORT_KEYS)[number];
+/**
+ * `store.default_sort` off the wire, normalized to one of the four keys.
+ *
+ * Field-for-field port of `normalizeStorefrontSortKey`
+ * (`packages/storefront-render-core/src/normalize-storefront-sort-key.ts`),
+ * because the column does NOT hold those keys: the response contract emits the
+ * dashboard's enum (`DEFAULT`, `NEWEST`, `PRICE`, `PRICE_DESC`, `BESTSELLER`,
+ * `NAME`, …). Reading it literally would leave every shop on 'featured' and the
+ * merchant's chosen order would never reach either lane. An order this theme
+ * cannot express — name, stock, type — degrades to the merchant's own shelf
+ * order rather than to a different one.
+ */
+declare function parseStorefrontSortKey(value: unknown): StorefrontSortKey;
+declare function getStorefrontSettings(): StorefrontSettings;
+declare function getStorefrontAddons(): StorefrontAddon[];
+/**
+ * The stock a buyer can actually reach, in ONE number: null is unlimited.
+ *
+ * Variants are the trap. A variant product's own `stock` column is not the
+ * inventory anyone buys — the variants hold it — so a product with two
+ * unbounded variants and a `stock` of 0 is not sold out. Serial products are
+ * the exception: their stock IS the key pool on the product row.
+ */
+declare function resolveDisplayStock(product: StorefrontProduct): number | null;
+declare function isProductSoldOut(product: StorefrontProduct): boolean;
+/**
+ * The stock behind ONE selected option — null is unlimited.
+ *
+ * A variant without its own counter inherits the product's, and the whole
+ * product falls back to the product row when EVERY variant reports zero while
+ * the product itself has units — that combination is a catalog that never
+ * populated per-variant stock, not a sold-out product.
+ */
+declare function resolveVariantStock(product: StorefrontProduct, variant: StorefrontPriceVariant): number | null;
+/**
+ * The one sold-out predicate every add path passes.
+ *
+ * PAYMENT PATH. A product-level read is not enough: an option of an otherwise
+ * stocked product can be sold out on its own, and the backend refuses that line
+ * at invoice creation (`errors.checkout.insufficient_stock`). Adding it anyway
+ * only moves the dead end to checkout.
+ */
+declare function isSelectionSoldOut(product: StorefrontProduct, variant: StorefrontPriceVariant | null): boolean;
+/**
+ * The stock counter resolves per product: a product's own hide_stock_counter
+ * wins, null inherits the shop-wide setting — same rule the document lane's
+ * readHideStockCounterForProduct applies.
+ */
+declare function resolveHideStockCounter(product: StorefrontProduct, settings: StorefrontSettings): boolean;
+/**
+ * How many units the buyer may put on ONE line, for the selected option.
+ *
+ * A variant overrides the product's own bounds, and the stock caps whatever the
+ * merchant configured: offering a stepper that runs past the inventory produces
+ * a cart the quote then rejects. `max: null` is unlimited, never zero.
+ */
+declare function resolveQuantityBounds(product: StorefrontProduct, variant: StorefrontPriceVariant | null): {
+    min: number;
+    max: number | null;
+};
+type LicenseTerm = {
+    kind: 'lifetime';
+} | {
+    kind: 'period';
+    days: number;
+};
+/**
+ * What ONE row — a product or one of its options — states about its own term.
+ *
+ * `inherit` is an option saying the product answers for it; only an option may say it, because the
+ * product is the root of the term. `unresolved` is a row stating a term nobody can read: an unknown
+ * mode, a PERIOD carrying no days, a legacy `'90d'` that was never validated.
+ *
+ * These three are separate states on purpose. They used to share one nullable column — `NULL` meant
+ * "inherit" on an option and "nothing" on a product — and on 2026-08-18 the unnamed state was
+ * rendered as "Lifetime": 5,333 licences were sold as perpetual and issued with a 30-day expiry.
+ * Neither `inherit` nor `unresolved` may become a term here.
+ */
+type LicenseStatement = LicenseTerm | {
+    kind: 'inherit';
+} | {
+    kind: 'unresolved';
+};
+/**
+ * The term the buyer is being sold for the option they have selected, or `null` when nothing about
+ * it is resolvable — licensing off, a mode nobody can read, a PERIOD with no days, an option
+ * inheriting from a product that states nothing itself.
+ *
+ * `null` means the page renders NO licence row. It never means "Lifetime".
+ */
+declare function resolveLicenseTerm(product: StorefrontProduct, variant: StorefrontPriceVariant | null): LicenseTerm | null;
+/** "Lifetime" / "30 days" — the same wording the Easy lane prints for the same product. */
+declare function formatLicenseTerm(term: LicenseTerm): string;
+/** Half-up rounding to cents. Every displayed money amount rounds through here. */
+declare function roundCurrency(value: number): number;
+/**
+ * Line total the way the quote computes it: undiscounted subtotal, percent
+ * discount applied at LINE level (not per rounded unit — $9.99 at 15% × 10 is
+ * $84.92, not 10 × $8.49), then the volume tier. Intermediate values stay
+ * unrounded like the quote's Decimal chain; only the final amount rounds —
+ * rounding between the two percent stages shifts the cent ($76.43 vs the
+ * quoted $76.42 for 15% + 10% on a $99.90 line). Every displayed quantity
+ * price must come from here or it disagrees with checkout.
+ */
+declare function calculateDisplayLineTotal(baseUnitPrice: number, quantity: number, discountPercent: number, rules: VolumeDiscountRule[]): number;
+/**
+ * Delivery units, mirroring the `products.delivery_time_unit` CHECK constraint.
+ * The column is NOT NULL DEFAULT 'days', so an absent value only comes from a
+ * payload minted before the unit existed — and days is what it meant.
+ */
+declare const DELIVERY_TIME_UNITS: readonly ["minutes", "hours", "days"];
+type DeliveryTimeUnit = (typeof DELIVERY_TIME_UNITS)[number];
+/** "1 hour" / "3 days" — the count with its unit, singular when the count is one. */
+declare function formatDeliveryTime(count: number, unit: DeliveryTimeUnit): string;
+
+/**
+ * The per-product details a buyer has to supply before an invoice can exist.
+ *
+ * PAYMENT PATH, and the reason this module exists at all: a merchant who marks
+ * one product custom field REQUIRED cannot sell that product until its value is
+ * on the cart line. `apps/backend/src/services/storefront/invoices/from-cart.ts`
+ * validates every line's `custom_fields` and rejects the whole request with
+ * `custom_fields_validation_failed` — no invoice is created, so the buyer gets a
+ * dead checkout button and the merchant gets no order.
+ *
+ * WHERE THE VALUES GO. Not into the checkout call: the SDK's `checkout()` has no
+ * custom-field option. `mapCartItemsForApi` (`packages/sdk/src/modules/checkout.ts`)
+ * reads `custom_fields` off each CART LINE, so the values are written onto the
+ * lines with `updateCartItem(lineId, { custom_fields })` BEFORE the hand-off.
+ * That is exactly what the Easy lane does — see
+ * `packages/storefront-commerce/src/checkout-custom-fields.ts`, whose
+ * `writeCustomFieldsToCart` runs on the same contract.
+ *
+ * WHERE THE DEFINITIONS COME FROM. The Easy lane fetches each cart product
+ * (`getProduct(uniqid)`) because it has no catalog in the page. This lane does:
+ * `window.__SHOPPEX_INITIAL__` carries every product, listed or not, so the
+ * definitions are read straight out of it. There is no request to fail — but
+ * there is still a line whose product is not in the payload, and that case
+ * FAILS CLOSED for the same reason the Easy lane's failed fetch does: an
+ * unresolvable product may carry required fields, and treating "unknown" as
+ * "none" is how a checkout submits without them.
+ *
+ * VALUES ARE PER PRODUCT, not per cart line. Two lines of the same product (a
+ * different option, a different extra) describe the same thing being bought
+ * twice, and the merchant asked their question once — so both lines receive the
+ * same answers, which is also what keeps them from splitting into two identities
+ * the buyer never chose. It differs from the Easy lane, which dedupes by field
+ * NAME across the whole cart: two products that both ask "Steam ID" are two
+ * questions here, and one there.
+ */
+
+/** One product's questions, and the product they belong to. */
+interface CheckoutFieldGroup {
+    productId: string;
+    /** The product's own title — the section heading the buyer reads. */
+    productName: string;
+    fields: ProductCustomField[];
+}
+/**
+ * What the cart needs before it can be checked out.
+ *
+ * `resolved: false` is the fail-closed state: at least one line names a product
+ * the payload does not carry, so nothing can be said about what it requires.
+ */
+type CheckoutFields = {
+    resolved: true;
+    groups: CheckoutFieldGroup[];
+    hasRequired: boolean;
+} | {
+    resolved: false;
+    unresolvedProductIds: string[];
+};
+/** Answers, keyed product id → field name → value. */
+type CheckoutFieldValues = Record<string, Record<string, string>>;
+/**
+ * The questions the current cart raises, grouped by product and in cart order.
+ *
+ * Products with no custom fields produce no group — they are resolved, they
+ * simply ask nothing.
+ */
+declare function resolveCheckoutFields(lines: readonly SdkCartItem[]): CheckoutFields;
+/**
+ * Whether the checkout CTA has to route through the details form instead of
+ * handing off straight away.
+ *
+ * True for the fail-closed state as well: a cart whose products cannot be
+ * resolved must not be handed to `checkout()` on the assumption that it asks
+ * nothing. The form is where that is said out loud.
+ *
+ * Optional-only fields do NOT gate the hand-off — nothing about the invoice
+ * depends on them, and stopping a buyer for a question they may leave blank
+ * would be this theme inventing a step. They are still collected whenever the
+ * form does open, so a cart that has to stop for one product's required field
+ * gathers every other answer in the same pass.
+ */
+declare function checkoutNeedsDetails(fields: CheckoutFields): boolean;
+/**
+ * The form's starting values: whatever the cart lines already carry, else the
+ * merchant's own default for the field.
+ *
+ * Pre-filling from the line is what makes the form survive a buyer going back to
+ * the cart and returning — the answers are stored on the line, not in React.
+ */
+declare function buildInitialCheckoutFieldValues(groups: readonly CheckoutFieldGroup[], lines: readonly SdkCartItem[]): CheckoutFieldValues;
+/**
+ * Whether a checkbox answer counts as ticked.
+ *
+ * The stored value is a string, and the four spellings below are the ones the
+ * SDK's `isStorefrontCheckboxCustomFieldValueChecked` accepts — a checkbox the
+ * two lanes read differently is a required tick one lane honours and the other
+ * silently drops.
+ */
+declare function isCheckboxValueChecked(value: string | undefined): boolean;
+/**
+ * The buyer-facing problem with one answer, or null when it is acceptable.
+ *
+ * A port of the SDK's `validateStorefrontCustomFieldValue`, down to the wording:
+ * the Easy lane refuses the same values with the same sentences, and the backend
+ * refuses them again when the invoice is built. A malformed merchant regex
+ * validates NOTHING rather than blocking every buyer on a pattern that cannot
+ * compile — the merchant's mistake must not become the buyer's dead end, and the
+ * backend still holds the line.
+ */
+declare function validateCheckoutFieldValue(field: ProductCustomField, value: string): string | null;
+/**
+ * Every problem the form has to show, keyed `<productId>.<fieldName>` so two
+ * products asking the same question keep their own message.
+ */
+declare function validateCheckoutFields(groups: readonly CheckoutFieldGroup[], values: CheckoutFieldValues): Record<string, string>;
+declare function checkoutFieldKey(productId: string, fieldName: string): string;
+/**
+ * One product's answers in the shape a cart line stores.
+ *
+ * A port of the SDK's `buildStorefrontCustomFieldPayload`: an unticked checkbox
+ * and an empty answer are OMITTED rather than stored blank, which is what keeps
+ * an optional field the buyer skipped from becoming an empty string the backend
+ * has to interpret. A ticked checkbox is always the literal `'true'`.
+ */
+declare function buildCustomFieldPayload(fields: readonly ProductCustomField[], values: Record<string, string> | undefined): Record<string, string>;
+/**
+ * The required answers that are NOT on the cart, read back out of the SDK.
+ *
+ * PAYMENT PATH. The write-back is `updateCartItem`, which the SDK can drop the
+ * same way it drops an add — its storage wrapper catches a quota or blocked
+ * write and only logs it. A hand-off that trusted the write would create no
+ * invoice at all (the backend rejects the cart) after telling the buyer their
+ * details were taken. So the cart is read back and every required field is
+ * checked against the value that actually landed, with the same validator the
+ * form used.
+ *
+ * Returns the buyer-facing messages, empty when the cart is ready to submit.
+ */
+declare function missingRequiredCheckoutValues(groups: readonly CheckoutFieldGroup[], lines: readonly SdkCartItem[]): string[];
+/**
+ * Whether a details write changed what the cart PRICES.
+ *
+ * PAYMENT PATH, and the one consequence of the identity merge that is not
+ * harmless. Two lines of the same product and option can exist while their
+ * `custom_fields` differ — the only way this theme's `add` produces one is a
+ * buyer who answered once, came back from a checkout that did not complete, and
+ * added the product again from the PDP or through Buy Now, because `add` sends
+ * no answers at all. Giving both the SAME answers collapses them into one line
+ * whose quantity is the SUM, and the quote proof the SDK is holding is bound to
+ * a hash of the cart's products, options and QUANTITIES (`custom_fields` and
+ * `delivery_instructions` are deliberately NOT hashed — see
+ * `apps/backend/src/services/storefront/cart/cartQuoteToken.ts`). So the answers
+ * alone never stale a proof, and a merge always does.
+ *
+ * Handing off anyway is refused by `/from-cart` as `quote_token_stale`. The
+ * hand-off already recovers from that refusal by re-quoting, so nothing is
+ * mispriced — but the buyer spends a click and a server round trip on a message
+ * about a cart change they did not make. Answering it here instead re-quotes
+ * straight away and names what actually happened.
+ *
+ * Compared on the priced shape rather than on `line_id`s, because every id in
+ * the cart changes when the answers are written — that is the identity rehash
+ * doing its job, not a repricing. A merge is the only thing this write can do
+ * to that shape, and it always removes a line, so the two multisets can never
+ * coincide.
+ */
+declare function checkoutFieldWriteRepriced(before: readonly SdkCartItem[], after: readonly SdkCartItem[]): boolean;
+
+type CartContextValue = {
+    lines: SdkCartItem[];
+    count: number;
+    quote: SdkCartQuote | null;
+    /** The server could not price the cart. Written by the refresh, only. */
+    quoteError: string | null;
+    /**
+     * A cart WRITE failed — an add the SDK refused or dropped, a bundle that had
+     * to be rolled back. Held apart from `quoteError` on purpose: a refresh must
+     * never be able to clear it. See `mutate`.
+     */
+    mutationError: string | null;
+    /**
+     * The last code the buyer applied was refused by the quote.
+     *
+     * Written only by `applyCoupon` and cleared only by the buyer's next cart
+     * action (see `mutate`). It cannot be derived from the quote any more,
+     * because a refused code is REMOVED from storage the moment it is refused —
+     * the very next quote therefore carries no code and would erase the message
+     * that explains why.
+     */
+    couponRejected: boolean;
+    /**
+     * True when the code the CURRENT quote was priced with is the ambient
+     * affiliate referral rather than one the buyer applied.
+     *
+     * The promo field decides between its entry row and its "applied" chip from
+     * `quote.coupon_applied`, which was a complete answer while the only code
+     * that could ever reach a quote was one the buyer typed. It is not one any
+     * more: an accepted ambient referral sets that same flag, and the chip would
+     * then congratulate the buyer on a code they never entered, print it blank
+     * (the field is empty, because nothing was applied), and offer a Remove
+     * button wired to cart-coupon storage the referral does not live in — so it
+     * would reappear on the next quote. Kept next to the quote it describes and
+     * written by the same statements, so the two can never disagree.
+     */
+    quotedAmbientAffiliate: boolean;
+    /**
+     * The shop's checkout maximum, stated once, while the CURRENT quote says this
+     * cart is over it. Null while it is within the limit or while no quote has
+     * settled.
+     *
+     * PAYMENT PATH. The summary prints it beside the total — an over-limit cart
+     * is a cart the checkout refuses, and the buyer cannot act on a limit nobody
+     * names — and `checkout` refuses the hand-off on the same fact, exactly as it
+     * refuses an unsellable line. See `resolveCartMaximumWarning`.
+     */
+    cartMaxWarning: string | null;
+    /**
+     * The settled quote contains a PHYSICAL line, so its total excludes shipping,
+     * which the hosted checkout prices from the buyer's address. False while no
+     * quote has settled. The summary says so under the total.
+     */
+    requiresShipping: boolean;
+    checkoutError: string | null;
+    /**
+     * True when the LAST hand-off was refused because the referral on this cart
+     * is the buyer's own (`affiliate_code_not_applicable`).
+     *
+     * It needs its own flag rather than being read out of `checkoutError`,
+     * because it is the one refusal the buyer cannot resolve by re-reading the
+     * message: the code is ambient — nobody typed it, no field shows it, and no
+     * control removes it — so without an explicit exit the cart refuses every
+     * retry forever. The surface renders `clearBlockedReferral` next to the
+     * message; the flag is what tells it to.
+     */
+    selfReferralBlocked: boolean;
+    /**
+     * The exit. Drops the referral attribution the SDK is carrying, re-quotes
+     * without it, and lets the buyer check out again. See the implementation.
+     */
+    clearBlockedReferral: () => Promise<void>;
+    busy: boolean;
+    couponInput: string;
+    setCouponInput: (value: string) => void;
+    drawerOpen: boolean;
+    setDrawerOpen: (open: boolean) => void;
+    add: (product: StorefrontProduct, variant: StorefrontPriceVariant | null, quantity: number, options?: {
+        /**
+         * Buyer-chosen unit price for a pay-what-you-want product. Part of the
+         * cart line identity — the server validates it against the minimum.
+         */
+        payWhatYouWantPrice?: number;
+        /** Extras the buyer ticked in the buy box. Also part of line identity. */
+        addons?: ProductAddon[];
+    }) => Promise<void>;
+    /**
+     * Adds EVERY member of a bundle offer, as one operation.
+     *
+     * Bundle members arrive as a compact summary rather than a full product, so
+     * they cannot go through `add` — their quantity bounds are resolved from the
+     * member's own catalog product instead, and a member that cannot be resolved
+     * is rejected rather than added. The set is all-or-nothing: see the
+     * implementation for why a half-added bundle is worse than none of it.
+     */
+    addBundle: (items: readonly ProductBundleItem[]) => Promise<void>;
+    update: (lineId: string, quantity: number) => Promise<void>;
+    remove: (lineId: string) => Promise<void>;
+    clear: () => Promise<void>;
+    applyCoupon: () => Promise<void>;
+    removeCoupon: () => Promise<void>;
+    /**
+     * The per-product details this cart's products require, resolved from the
+     * injected catalog. `/checkout` renders the form from it.
+     */
+    checkoutFields: CheckoutFields;
+    /**
+     * True when the hand-off must go through `/checkout` to collect those details
+     * first. Read it on CLICK rather than from a render closure after a cart
+     * write — `readCheckoutNeedsDetails` exists for exactly that.
+     */
+    checkoutNeedsDetails: boolean;
+    /**
+     * Hands over to Hosted Checkout. `customFieldValues` writes the buyer's
+     * answers onto the cart lines first and is what `/checkout` submits; every
+     * other surface hands off with no values, and may only do so when
+     * `checkoutNeedsDetails` is false.
+     */
+    checkout: (customFieldValues?: CheckoutFieldValues) => Promise<void>;
+};
+/**
+ * Whether the checkout CTA has to stop for details, read from the SDK's cart
+ * RIGHT NOW rather than from React state.
+ *
+ * PAYMENT PATH. Buy Now adds a line and then hands off in the same click. The
+ * `checkoutNeedsDetails` on the context describes the cart as it was when the
+ * component last rendered, which is the cart BEFORE that add — a product whose
+ * required fields the add has just brought into the cart would be handed
+ * straight to a checkout that cannot be created.
+ */
+declare function readCheckoutNeedsDetails(): boolean;
+declare function CartProvider({ children }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useCart(): CartContextValue;
+/**
+ * Starts a cart mutation from a control that has nothing to chain onto it.
+ *
+ * Every mutation now REJECTS when the write fails, which is what lets Buy Now
+ * stop before checkout. A stepper, a remove button or a bundle offer has no next
+ * step to stop: its failure is already rendered from `mutationError` on the
+ * drawer and `/cart`, the surfaces those controls live on. This states that at
+ * the call site rather than leaving the rejection unhandled — the error is
+ * displayed, not swallowed.
+ */
+declare function startCartMutation(mutation: Promise<void>): void;
+
+/**
+ * Reading THE CART BOUNDS CONTRACT off a settled quote.
+ *
+ * PAYMENT PATH. Its own module, free of React and of the SDK singleton, so the
+ * rules can be read and exercised on their own: the cart provider hands them the
+ * quote's `lines` and the cart it holds, and they answer what has to change.
+ *
+ * The producer is the backend's `CartQuoteService` (`CartQuoteLine`), and its
+ * field rules — which this module exists to honour exactly — are:
+ *
+ *   `variant_id`   the RESOLVED option id, or `null` for a product with no
+ *                  variants, which the cart stores under the `'default'` marker.
+ *                  The match has to bridge the two spellings.
+ *   `min_quantity` OMITTED when it is 1.
+ *   `max_quantity` OMITTED when nothing bounds the line. `-1` is NEVER emitted;
+ *                  omission IS the unbounded sentinel, and a missing key must
+ *                  never be read as 0 — that says "sold out". SHARED when
+ *                  several cart lines name one product+option: they draw from
+ *                  one shelf and the checkout sums them, so the value is that
+ *                  line's SHARE of the option's ceiling.
+ *   `sellable`     false = this line cannot be ordered as the cart stands:
+ *                  either no quantity of the option can be ordered at all, or
+ *                  the cart's lines of this option together ask for more units
+ *                  than the option's ceiling, which the checkout refuses on the
+ *                  SUM. The line is still priced and still counted — it is one
+ *                  the buyer must reduce or remove. It answers for the OPTION
+ *                  and for the whole cart's demand on it, so every line of one
+ *                  option carries the same value.
+ *
+ * CONSUMER DUTY, from the same contract, and the reason this module exists in
+ * the Advanced lane at all: cart lines hold an ADD-TIME SNAPSHOT of their
+ * bounds, so a line goes stale the moment stock moves or the merchant edits the
+ * limits — and the stepper is driven off those stored values. Heal them by
+ * REPLACING, never merging: an absent `max_quantity` means the ceiling was
+ * REMOVED, and a merge would keep a stale one forever. And refuse the checkout
+ * hand-off while any line is unsellable, because that cart is exactly the one
+ * `/from-cart` rejects.
+ */
+
+type CartQuoteLineBounds = {
+    productId: string;
+    /** `'default'` for the contract's `null`, so it compares against a cart line. */
+    variantId: string;
+    /** The quantity this row was quoted AT, after per-line summing. */
+    quantity: number;
+    /** `null` = unstated, which is the SDK's own default of 1. */
+    minQuantity: number | null;
+    /** `null` = unbounded. Never a negative sentinel. */
+    maxQuantity: number | null;
+    sellable: boolean;
+};
+/** One healing write: the line to patch, and the bounds to REPLACE it with. */
+type CartBoundsHeal = {
+    lineId: string;
+    /**
+     * `null` DELETES the stored bound — the contract's "no bound" — in the SDK's
+     * own tri-state (absent = leave alone, null = clear, number = set). It is not
+     * `undefined`, because `undefined` is exactly what the SDK reads as "this
+     * update did not mention the field", so a removed ceiling would stick to the
+     * line forever.
+     */
+    minQuantity: number | null;
+    maxQuantity: number | null;
+};
+/** Parse `lines` off a settled quote. An absent or malformed list yields none. */
+declare function parseCartQuoteLines(raw: SdkCartQuoteLine[] | undefined): CartQuoteLineBounds[];
+/**
+ * The writes needed to bring stored line bounds back in line with the quote.
+ *
+ * Only lines whose stored bounds actually DIFFER are returned, which is what
+ * keeps this from looping: writing the same values back would emit another
+ * cart-changed, re-quote, and arrive here again. Cart lines the quote did not
+ * mention are left untouched — the quote answers for the cart it was given, and
+ * a line added after it was sent has no answer in it yet.
+ */
+declare function resolveCartBoundsHeals(lines: readonly SdkCartItem[], quoted: readonly CartQuoteLineBounds[]): CartBoundsHeal[];
+/** The stored `line_id`s the quote says cannot be ordered right now. */
+declare function resolveUnsellableLineIds(lines: readonly SdkCartItem[], quoted: readonly CartQuoteLineBounds[]): string[];
+
+/**
+ * View models for the cart drawer and the `/cart` page.
+ *
+ * The cart lives in the SDK as a flat list of lines plus a server quote. This
+ * module turns those two into the rows a buyer reads, and it is the only place
+ * that decides what a cart line SAYS.
+ *
+ * PRICING RULE, and it is the whole reason this file exists: a line total is
+ * the stored price snapshot times the quantity, and nothing else. The totals
+ * block is the SERVER's quote, verbatim — subtotal, discounts and total all
+ * from the SAME quote, on both the drawer and `/cart`.
+ *
+ * The two are never mixed. The quote's subtotal is pre-discount while the line
+ * snapshots already carry the product and volume discounts, so printing the
+ * client's sum above the quote's discount rows produces a summary whose
+ * arithmetic does not work (Subtotal 9, Discount −1, Total 9) — which is
+ * exactly what the drawer used to show. `CartView.subtotal` is therefore the
+ * client's own number for ONE purpose: standing in for the whole block while no
+ * quote exists, where every row is the client's and the block still adds up.
+ *
+ * When a line has no snapshot its total is zero and the whole cart is flagged
+ * as an estimate rather than presenting a confident wrong number.
+ *
+ * Cents are settled by the SHARED `roundCurrency`, the same half-up-on-the-
+ * decimal-text rule the buy box and the line-pricing maths use. This file used
+ * to carry a naive `Math.round(v * 100) / 100` of its own, which is a different
+ * function: binary noise puts 10.03 × 50% at 5.014999…, which that version
+ * floors to 5.01 while the quote's ROUND_HALF_UP gives 5.02. One rounding rule,
+ * or two surfaces disagree by a cent about the same cart.
+ */
+
+interface CartViewLine {
+    lineId: string;
+    title: string;
+    /** The option, and any extras the buyer ticked, as one caption. Blank hides it. */
+    subtitle: string;
+    imageUrl: string | null;
+    quantity: number;
+    lineTotal: number;
+    /** False at the line's floor — the stepper removes the line instead. */
+    canDecrease: boolean;
+    /** False at the stock or per-order ceiling recorded when the line was added. */
+    canIncrease: boolean;
+    /** The quantity the stepper drops to; below it the line is removed. */
+    minimumQuantity: number;
+}
+interface CartView {
+    lines: CartViewLine[];
+    /** Sum of the line totals — the client's own number, not the quote's. */
+    subtotal: number;
+    /**
+     * True when a line carries no price snapshot, so `subtotal` understates the
+     * cart. The summary says "estimated" instead of pretending otherwise.
+     */
+    subtotalIsEstimate: boolean;
+    isEmpty: boolean;
+}
+declare function buildCartView(lines: SdkCartItem[]): CartView;
+interface CartTotals {
+    /**
+     * The subtotal to print. From the quote when one exists (pre-discount, the
+     * same basis its discount rows are stated against), otherwise the client's
+     * own sum.
+     */
+    subtotal: number;
+    /** Itemised discounts, exactly as the quote named them. */
+    discounts: Array<{
+        label: string;
+        amount: string;
+    }>;
+    /**
+     * Aggregate discount, shown only when the quote reports a reduction it did
+     * not itemise. Never rendered alongside `discounts`.
+     */
+    aggregateDiscount: number | null;
+    total: number;
+    currency: string;
+    /**
+     * True while the printed numbers are not a server quote — a quote in flight,
+     * a quote that failed, or a line without a price snapshot.
+     */
+    isEstimate: boolean;
+}
+declare function buildCartTotals(view: CartView, quote: SdkCartQuote | null, fallbackCurrency: string): CartTotals;
+
+/**
+ * Catalog view models: the step between the injected wire payload and the
+ * cards.
+ *
+ * Everything a card shows — the price label, the badge, the stock chip, the
+ * buy control it gets — is decided here once, so the card components stay
+ * markup. Nothing in this module invents a value: a product without a rating
+ * has no rating chip, a product without a description has no description line.
+ */
+
+/**
+ * Money as the storefront shows it: `$49`, `$49.50`, `€9.99`, `¥1,200`.
+ *
+ * A whole amount drops its zero cents (`$49`, not `$49.00`); any other amount
+ * keeps the currency's own number of decimals, so `$49.50` never turns into
+ * `$49.5` and a three-decimal currency keeps all three. "Whole" is judged on
+ * the amount rounded to those decimals, so float noise like `48.99999999`
+ * still reads as `$49`.
+ */
+declare function formatMoney(amount: number, currency: string): string;
+/** Compact counts for the store-stats strip: 12450 → `12k`, 8200 → `8.2k`. */
+declare function formatCompactCount(value: number): string;
+type StockTone = 'in_stock' | 'low_stock' | 'sold_out';
+type StockChip = {
+    tone: StockTone;
+    label: string;
+};
+/**
+ * The units at or below which stock reads as LOW when the merchant configured
+ * no threshold of their own. Ten is what every Easy-lane stock surface hardcodes
+ * (`resolveCatalogStockPresentation`, `resolveStockTone`), so a merchant who
+ * never set "Low Stock Warning" sees the same wording on both lanes.
+ */
+declare const DEFAULT_LOW_STOCK_THRESHOLD = 10;
+interface ProductCardModel {
+    kind: 'product';
+    key: string;
+    product: StorefrontProduct;
+    href: string;
+    priceLabel: string;
+    badgeLabel: string | null;
+    /**
+     * The merchant's own badges for this surface, already filtered by
+     * `show_on_product_card`. Separate from `badgeLabel`, which is the theme's
+     * product-TYPE chip: one is authored, the other is derived, and they occupy
+     * different corners of the media so neither can hide the other.
+     */
+    badges: ProductBadge[];
+    /** Up to three merchant bullets; the description line renders only when empty. */
+    highlights: string[];
+    description: string | null;
+    rating: number | null;
+    /**
+     * Absent for info cards, sold-out products and paused ones — each has its own
+     * chip or its own action row instead.
+     */
+    stockChip: StockChip | null;
+    soldOut: boolean;
+    /**
+     * The merchant PAUSED this product. Not a stock state: it outranks stock
+     * entirely, because the backend refuses to sell it however many units exist.
+     */
+    onHold: boolean;
+    categoryIds: string[];
+    sortPriority: number;
+    createdAt: string | null;
+    price: number;
+}
+interface GroupCardModel {
+    kind: 'group';
+    key: string;
+    group: StorefrontGroup;
+    priceLabel: string;
+    /** Resolvable members, in the merchant's order. */
+    members: StorefrontProduct[];
+    memberCountLabel: string;
+    categoryIds: string[];
+    sortPriority: number;
+    price: number;
+}
+type CatalogCardModel = ProductCardModel | GroupCardModel;
+interface StorefrontCatalog {
+    cards: CatalogCardModel[];
+    categories: StorefrontCategory[];
+    /**
+     * Every product the payload carries, including the ones the shelf does not
+     * list. A bundle member has a real product page even though it has no card,
+     * so product-page lookups read this and not `cards`.
+     */
+    products: StorefrontProduct[];
+    /** Products the storefront lists — the store-stats "products" cell counts these. */
+    listedProductCount: number;
+}
+/**
+ * The product a `/product/:slug` route points at.
+ *
+ * The id is accepted alongside the slug because a product without a slug is
+ * linked by uniqid, and a bookmarked uniqid must keep working after the
+ * merchant adds one.
+ */
+declare function findStorefrontProduct(catalog: StorefrontCatalog, slugOrId: string): StorefrontProduct | null;
+/**
+ * The storefront's catalog, in the merchant's shelf order.
+ *
+ * `items` decides what is on the shelf. Reading `products` instead would put
+ * every bundle member on the home page as a standalone card — they are real
+ * catalog products, they are simply not listed on their own.
+ */
+declare function buildStorefrontCatalog(settings: StorefrontSettings): StorefrontCatalog;
+declare const CATALOG_SORTS: readonly ["featured", "newest", "price-asc", "price-desc"];
+type CatalogSort = StorefrontSortKey;
+declare const CATALOG_SORT_LABELS: Record<CatalogSort, string>;
+/**
+ * Sorting never mutates the shelf order: `featured` IS that order, and the
+ * others sort a copy of it so switching back is exact.
+ */
+declare function sortCatalogCards(cards: CatalogCardModel[], sort: CatalogSort): CatalogCardModel[];
+/**
+ * The category a `?category=` value names, as the CARD models key on it.
+ *
+ * A shared or bookmarked listing URL may carry the merchant's slug, the
+ * category title, or the uniqid — the Easy lane accepts all of them
+ * (`resolveAllProductsCategorySelection`) and answers with the uniqid the cards
+ * are filtered by. Mirrored here so one storefront's filtered link keeps working
+ * after a lane switch. An unknown value selects nothing rather than emptying the
+ * grid against a category that does not exist.
+ */
+declare function resolveCategorySelection(value: string | null, categories: readonly StorefrontCategory[]): string | null;
+declare function filterCatalogCards(cards: CatalogCardModel[], categoryId: string | null): CatalogCardModel[];
+/** Products per page in the full listing. Bundles do not count against it. */
+declare const CATALOG_PAGE_SIZE = 24;
+interface CatalogPage {
+    cards: CatalogCardModel[];
+    /** The page actually shown — an out-of-range request lands on the last one. */
+    page: number;
+    totalPages: number;
+}
+/**
+ * One page of the full listing.
+ *
+ * Bundles all sit on page one and never count against the page size: a shop
+ * with three bundles and twenty-four products is one page, not two, because a
+ * bundle is an entry point into the catalog rather than an item in it. The
+ * input must already be filtered and sorted — paging re-orders nothing.
+ */
+declare function paginateCatalogCards(cards: CatalogCardModel[], page: number): CatalogPage;
+
+declare const QUOTE_UNAVAILABLE_CHECKOUT_ERROR = "Cart pricing is unavailable, so this order cannot be priced yet. Try again in a moment.";
+/** Retires only the checkout refusal that a newly settled quote resolved. */
+declare function clearRecoveredQuoteCheckoutError(error: string | null): string | null;
+
+/**
+ * The contact form's submit path and the community channels beside it.
+ *
+ * The Storefront SDK has no contact method, so this posts the storefront
+ * ticket endpoint directly — the same request, body and validation the
+ * document lane's `sx-contact-form` runs through `submitStorefrontContactTicket`
+ * (`packages/sdk/src/utils/storefront-contact.ts`). Keeping the payload shape
+ * identical is what makes a message sent from a code storefront indistinguishable
+ * from one sent from the Builder.
+ */
+
+interface ContactFormValues {
+    name: string;
+    email: string;
+    subject: string;
+    message: string;
+    invoiceId: string;
+}
+interface ContactSubmissionContext {
+    contactEnabled: boolean;
+    requireInvoice: boolean;
+}
+/**
+ * Client-side validation, mirroring `validateStorefrontContactSubmission`.
+ *
+ * It is a courtesy, not a gate: the backend enforces the same rules, and a
+ * form that only *looked* validated would let a disabled shop's visitor watch
+ * a request fail with no explanation.
+ */
+declare function validateContactSubmission(values: ContactFormValues, context: ContactSubmissionContext): string | null;
+declare function submitContactTicket(values: ContactFormValues, context: ContactSubmissionContext): Promise<void>;
+interface SupportChannel {
+    label: string;
+    href: string;
+    /** Mail links open the visitor's client rather than a new tab. */
+    isMail: boolean;
+}
+/**
+ * The channels a buyer can reach the shop on before they buy.
+ *
+ * Derived from the shop's own social profiles, not from theme content: those
+ * handles belong to the merchant and are edited once in the dashboard. The
+ * three networks and their order are the platform's
+ * (`withShopContactFallbacks` in the document renderer), so the two lanes list
+ * the same links in the same order.
+ */
+declare function resolveSupportChannels(links: readonly SocialLink[]): SupportChannel[];
+
+/**
+ * The merchant's navigation menus, and where they sit against theme content.
+ *
+ * A shop configures menus once in the dashboard and expects every theme to use
+ * them. The Easy lane resolves a slot in this order
+ * (`build-storefront-navigation.ts` + `resolveDocumentNavigationLinks`):
+ *
+ *   1. a link list the merchant authored IN THE THEME wins — including an
+ *      empty one, which means "no links here", not "fall back";
+ *   2. otherwise the merchant's menu for that slot;
+ *   3. otherwise the theme's own static links.
+ *
+ * Mirrored exactly. `hasAuthoredLinks` is what separates (1) from (3): the
+ * template's shipped `nav.links` are step 3, not an override, so a shop with a
+ * header menu and no theme edit gets its menu — which is the whole gap this
+ * closes.
+ *
+ * The menus are fetched once per page load and shared by both slots. While the
+ * request is in flight the theme's own links render: that is the same list step
+ * 3 would settle on, so the header is never empty and never shows a spinner
+ * where its navigation belongs. A shop WITH a menu therefore swaps its links in
+ * once, on first resolve.
+ */
+
+type MenuSlot = 'header' | 'footer';
+/** One navigation link as a theme authors it: a label and where it goes. */
+type NavLink = {
+    label: string;
+    href: string;
+};
+type MenuNavLink = NavLink & {
+    target: string | null;
+};
+declare function resolveMenuLinksForSlot(menus: readonly SdkMenu[], slot: MenuSlot): MenuNavLink[];
+interface NavigationLinks {
+    links: readonly MenuNavLink[];
+    /**
+     * True when the rendered list is the THEME's content, which is what decides
+     * whether each entry carries a `data-sx-config` path — a merchant's menu item
+     * is edited in the dashboard's navigation screen, not in the design
+     * inspector, and pointing the inspector at it would offer an edit that goes
+     * nowhere.
+     */
+    fromTheme: boolean;
+}
+/**
+ * The links one slot should render, with the precedence above already applied.
+ *
+ * `themeLinks` is the template's own list. It is returned unchanged when the
+ * merchant authored it (step 1) and while the menus are still loading; a
+ * non-empty menu replaces it once resolved (step 2); an empty menu leaves it in
+ * place (step 3).
+ */
+declare function useNavigationLinks(slot: MenuSlot, themeLinks: readonly NavLink[], 
+/** True when the merchant edited this slot's links in the theme content. */
+authored: boolean): NavigationLinks;
+
+/**
+ * Strict parsing helpers shared by the content contract (`src/config`) and the
+ * storefront data contract (`src/commerce`).
+ *
+ * The rule both contracts follow: an ABSENT value may fall back to a documented
+ * default, a PRESENT but malformed one throws. Silently repairing bad input
+ * would hide a broken content draft or a changed wire contract behind a
+ * storefront that merely looks slightly wrong.
+ */
+declare function isRecord(value: unknown): value is Record<string, unknown>;
+declare function requireUnknownRecord(value: unknown, context: string): Record<string, unknown>;
+declare function requireRecord(record: Record<string, unknown>, key: string): Record<string, unknown>;
+declare function requireArray(record: Record<string, unknown>, key: string): unknown[];
+declare function requireString(record: Record<string, unknown>, key: string, context: string): string;
+declare function requireStringFromKeys(record: Record<string, unknown>, keys: string[], context: string): string;
+declare function requireNumber(record: Record<string, unknown>, key: string, context: string): number;
+/** A non-empty trimmed string, or null for absent/blank/non-string input. */
+declare function optionalString(value: unknown): string | null;
+/** The first usable string among several candidate keys. */
+declare function firstOptionalString(record: Record<string, unknown>, keys: string[]): string | null;
+/**
+ * A visible string that may be absent from an older content draft. Absent or
+ * blank renders the shipped wording; a present non-string is still an error.
+ */
+declare function optionalStringWithDefault(value: unknown, fallback: string, context: string): string;
+/**
+ * A boolean the serializer ALWAYS emits, so its absence is a broken payload.
+ *
+ * Defaulting one of these is worse than throwing: a merchant switch that never
+ * arrives silently reads as whatever the theme guessed, and the storefront then
+ * offers something the backend refuses. `0`/`1` are accepted because the wire
+ * carries some flags that way; anything else is an error.
+ */
+declare function requireBoolean(value: unknown, context: string): boolean;
+declare function optionalBoolean(value: unknown, fallback: boolean, context: string): boolean;
+declare function parseFiniteNumber(value: unknown, context: string): number;
+/**
+ * One of a fixed option set. Absent falls back to the theme default; anything
+ * else throws, because a typo in an enum is a broken content draft, not a
+ * missing field — and the wrong branch of a layout switch is worse than a
+ * visible error.
+ */
+declare function parseEnum<T extends string>(value: unknown, allowed: readonly T[], fallback: T, context: string): T;
+
+/**
+ * Product-page view models: the step between one parsed product and the
+ * gallery, buy box, details tabs and related strip.
+ *
+ * Same division of labour as `catalog.ts` — every decision a product page makes
+ * about WHAT to show is made here, so the components stay markup. The two files
+ * deliberately differ on stock wording: a catalog card shouts a short chip
+ * ("999 IN STOCK"), the buy box states the option's availability in a sentence
+ * ("999 in stock", "Only 3 left"). Same source, two audiences.
+ */
+
+/** The five star slots under the product title; `true` is a filled star. */
+type RatingStars = readonly [boolean, boolean, boolean, boolean, boolean];
+interface BuyBoxVariantModel {
+    variant: StorefrontPriceVariant;
+    /** Unit price with the product discount applied — what one unit costs today. */
+    price: number;
+    /** Undiscounted unit price, shown struck through. null when nothing is off. */
+    compareAtPrice: number | null;
+    stockTone: StockTone;
+    stockLabel: string;
+    soldOut: boolean;
+}
+interface ProductRatingModel {
+    stars: RatingStars;
+    /** Reviews the tally counted — the label pluralises off this. */
+    count: number;
+    /** 1-5, rounded to one decimal. */
+    average: number;
+    /**
+     * How the tally splits. The bootstrap payload carries these three buckets and
+     * no review bodies, so this is the finest grain the code lane can honestly
+     * report.
+     */
+    positive: number;
+    neutral: number;
+    negative: number;
+}
+interface ProductDetailModel {
+    product: StorefrontProduct;
+    /** Gallery images, primary first. Empty when the product has no art at all. */
+    images: string[];
+    /** Rating derived from real feedback; null when the product has none. */
+    rating: ProductRatingModel | null;
+    variants: BuyBoxVariantModel[];
+    addons: ProductAddon[];
+    soldOut: boolean;
+    /** Cards for the "You might also like" strip, in the merchant's shelf order. */
+    related: ProductCardModel[];
+}
+declare function buildProductDetail(product: StorefrontProduct, settings: StorefrontSettings, cards: CatalogCardModel[]): ProductDetailModel;
+interface LinePricing {
+    /** What the cart will charge for the whole line. */
+    total: number;
+    /** The same line before any discount. Equal to `total` when none applies. */
+    originalSubtotal: number;
+    /** Per-unit price after discounts, for the "… each" line. */
+    effectiveUnitPrice: number;
+    discountAmount: number;
+    hasDiscount: boolean;
+}
+/**
+ * What the buy box headline shows.
+ *
+ * The unit price folds the selected variant AND the selected addons before the
+ * discount stages run, exactly as the platform's product-form controller does —
+ * a storefront that discounted the variant and then added the extras would
+ * advertise a total the checkout does not honour.
+ */
+declare function calculateLinePricing(product: StorefrontProduct, variant: StorefrontPriceVariant | null, addons: ProductAddon[], quantity: number, 
+/**
+ * The buyer's pay-what-you-want amount: PER UNIT, and for the product alone.
+ * The extras are added on top of it here exactly once, which is the same
+ * split `pay_what_you_want_price` + `price_data.unit_price` the cart sends
+ * and the backend charges.
+ */
+payWhatYouWantPrice?: number): LinePricing;
+/**
+ * The floor a pay-what-you-want buyer may name: PER UNIT, extras excluded.
+ *
+ * It is the selected option's UNDISCOUNTED price — the same number the backend
+ * validates the buyer's amount against (`resolvePayWhatYouWantUnitPrice`) and
+ * the same one the document lane offers as the default. Reading a discounted
+ * price here would pre-fill an amount the checkout then refuses as too low.
+ */
+declare function resolvePayWhatYouWantMinimum(product: StorefrontProduct, variant: StorefrontPriceVariant | null): number;
+/**
+ * The backend's ceiling for a named price (`MAX_PAY_WHAT_YOU_WANT_PRICE`).
+ * An amount above it fails when the invoice is built, so the buy box refuses it
+ * first instead of handing the buyer to a checkout that cannot be created.
+ */
+declare const MAX_PAY_WHAT_YOU_WANT_PRICE = 1000000000;
+/** Clamps a buyer-entered quantity into the bounds the line actually allows. */
+declare function clampQuantity(product: StorefrontProduct, variant: StorefrontPriceVariant | null, quantity: number): number;
+
+/**
+ * Shop feedback for the `/reviews` page.
+ *
+ * Shoppex feedback is SHOP-level, not per product, and it is not part of the
+ * injected catalog payload — the bootstrap object carries only per-product
+ * tallies. The bodies come from a runtime call, so this is the one surface in
+ * the theme that renders a list it has to wait for.
+ *
+ * Nothing here invents a review. A shop with no feedback resolves to an empty
+ * list and the page says so; a failed request resolves to an error state and
+ * the page says that instead. Neither is padded with sample data.
+ */
+
+interface ShopReview {
+    id: string;
+    /** Filled-star count, the rating clamped to 0-5 and rounded. */
+    starCount: number;
+    rating: number;
+    comment: string;
+    author: string;
+    /** Localized short date, e.g. "Jan 12, 2026". Blank when the API sent none. */
+    dateLabel: string;
+    /** Sort key; 0 when the entry carries no usable timestamp. */
+    timestamp: number;
+    /**
+     * The reviewed product's CURRENT title, or null when the review names none.
+     * The public feed withholds product ids, so the title is the only link to a
+     * product there is; see `reviewsForProduct`.
+     */
+    productTitle: string | null;
+    /** True when the review is tied to a real completed purchase. */
+    verified: boolean;
+}
+type ShopReviewsState = {
+    status: 'loading';
+} | {
+    status: 'error';
+} | {
+    status: 'ready';
+    reviews: ShopReview[];
+    average: number | null;
+};
+/**
+ * How many cards the page shows. The reference storefront pages its list at
+ * twelve; a shop with hundreds of reviews should not ship all of them into one
+ * screenshot-tall grid.
+ */
+declare const SHOP_REVIEW_PAGE_SIZE = 12;
+interface ShopReviewLabels {
+    anonymousAuthor: string;
+    emptyComment: string;
+}
+declare function toStarCount(rating: number): number;
+/**
+ * Newest first, and only entries that carry a real rating: a zero-star row is
+ * an unrated record, not a one-star verdict, and averaging it in would drag
+ * every shop's score down.
+ */
+declare function toShopReviews(rows: readonly SdkShopReview[], labels: ShopReviewLabels): ShopReview[];
+/**
+ * The written reviews that name this product, newest first.
+ *
+ * Matched on the product's title because the public feed carries no product
+ * ids. That makes it a sample, not a count: the feed leaves out appealed and
+ * filtered feedback, and a renamed product loses its older reviews. Surfaces
+ * show these as "latest reviews" beside the payload's own tally and never
+ * derive a number from them.
+ */
+declare function reviewsForProduct(reviews: readonly ShopReview[], productTitle: string): ShopReview[];
+declare function averageRating(reviews: readonly ShopReview[]): number | null;
+declare function useShopReviews(labels: ShopReviewLabels): ShopReviewsState;
+
+/**
+ * Merchant-authored HTML, made safe to inject.
+ *
+ * The storefront payload carries product descriptions and content tabs exactly
+ * as the merchant stored them; nothing sanitizes them on the way out. The Easy
+ * lane sanitizes at RENDER time (`sanitizeStorefrontRichTextHtml`), so a code
+ * storefront that skipped this step would make the same shop's content safe on
+ * one lane and executable on the other.
+ *
+ * "The merchant wrote it, on their own storefront" is not a safety argument:
+ * imported shops carry HTML nobody at the shop authored, and dashboard access is
+ * not always the owner's. The allowlist mirrors the Easy lane's — anything
+ * outside it is DROPPED rather than escaped, so a stray `onerror` disappears
+ * instead of showing up as text.
+ */
+declare function sanitizeMerchantHtml(value: unknown): string;
+/**
+ * Merchant HTML reduced to plain text, safely.
+ *
+ * Product descriptions arrive as rich text and several surfaces render them as
+ * TEXT — a catalog card's two-line summary, the search haystack. Passing the
+ * raw string there printed the merchant's own `<p>` tags at the buyer, and
+ * passing `textContent` of the parsed markup ran the block boundaries together.
+ *
+ * So the value is sanitized first (same allowlist as everything else — the
+ * string is never parsed as live markup before DOMPurify has seen it) and then
+ * flattened with block boundaries counting as whitespace. The result is
+ * collapsed to single spaces because CSS line-clamping cannot do it for text.
+ */
+declare function flattenMerchantHtmlToText(value: unknown): string;
+/**
+ * True when the sanitized markup carries no renderable content.
+ *
+ * A description of `<p></p>` is not a description: the Easy lane's
+ * `hasDescription` gate tests the SOURCE text, so a merchant who cleared their
+ * editor without clearing its wrapper tags gets the empty state rather than a
+ * blank panel.
+ */
+/**
+ * Drops every picture from merchant HTML.
+ *
+ * The merchant's "show images in descriptions" switch, applied at the same
+ * place the document lane applies it (`stripDescriptionImages`): the shop asked
+ * for text, so the description and every content tab arrive without their
+ * `<img>` elements. Run BEFORE the sanitizer's output is injected, on the
+ * sanitized string, so a tag the allowlist would have dropped anyway cannot
+ * survive by looking like an image to this pass.
+ */
+declare function stripMerchantHtmlImages(html: string): string;
+declare function isBlankMerchantHtml(html: string): boolean;
+
+/**
+ * Merchant CMS pages (dashboard → Pages), fetched by slug for `/page/:slug`.
+ *
+ * These are NOT in the injected catalog: the edge injects the storefront
+ * payload, and the merchant's pages come from a separate service the SDK reads
+ * (`getPage` / `getPages`). So the route loads them, and every state it can be
+ * in is explicit — a slug that does not resolve renders the theme's not-found
+ * copy rather than an empty article.
+ *
+ * The rendering rules are the Easy lane's, from `enrichCmsPageBlockSettings`
+ * plus `blocks/page-tool-page.ts` → `renderCmsPage`:
+ *
+ *   1. `template_type === 'faq'` and `settings.faq_items` non-empty → the
+ *      accordion. A row needs BOTH a question and an answer to count, exactly
+ *      as `normalizeCmsFaqItems` requires.
+ *   2. otherwise the body, rendered from MARKDOWN (gfm + breaks, the same
+ *      `marked` configuration `renderCmsPageMarkdownHtml` uses).
+ *   3. otherwise the empty state.
+ *
+ * What this module does NOT do is sanitize. The markdown pass emits merchant
+ * HTML — markdown may contain raw tags — and it is merchant HTML of exactly the
+ * same status as `shop.termsHtml` or a product description, so it is sanitized
+ * where it is injected, by the component that injects it. That is the rule the
+ * whole template follows and the one its HTML-sink guard checks.
+ */
+type ShopPageFaqItem = {
+    question: string;
+    answer: string;
+};
+/** One resolved CMS page, reduced to what the route renders. */
+interface ShopPageModel {
+    title: string;
+    /**
+     * The markdown body as HTML — merchant markup, NOT yet sanitized. The route
+     * sanitizes it at the sink; see the module docblock.
+     */
+    bodyMarkdownHtml: string;
+    /** Non-empty only for a `faq` page with usable rows. */
+    faqItems: ShopPageFaqItem[];
+}
+type ShopPageState = {
+    status: 'loading';
+} | {
+    status: 'ready';
+    page: ShopPageModel;
+}
+/** The slug resolved to nothing, or the request failed. Same screen either way. */
+ | {
+    status: 'missing';
+};
+/**
+ * Loads one CMS page by slug.
+ *
+ * A slug the API does not know, a page without a name, and a failed request all
+ * end in `missing`: there is no page to show, and inventing a title from the
+ * slug would publish a heading the merchant never wrote.
+ */
+declare function loadShopPage(slug: string): Promise<ShopPageState>;
+
+/**
+ * The sentence that names the CAUSE rather than the symptom.
+ *
+ * A missing bootstrap global and a missing `__SHOPPEX_INITIAL__` payload are
+ * the same fault seen from two sides: the page is not being served by the
+ * worker that injects both. `App.tsx`'s configuration screen shows this to the
+ * merchant, so it lives here once instead of being written twice.
+ */
+declare const SERVING_CONTEXT_HINT = "This storefront must be served by the Shoppex storefront (or preview) worker.";
+declare function getShoppex(): ShoppexSdk;
+/**
+ * The currency the prices on this page are in.
+ *
+ * The edge injected it alongside the catalog, from the same payload the prices
+ * came from, so it is right whether the buyer asked for a currency, whether
+ * their country selected one, or neither.
+ *
+ * Pass it to every quote and checkout. Left out, the SDK falls back to reading
+ * `?currency=` off `window.location` — which survives the first page load and
+ * nothing after it, because client-side navigation drops the query. The cart
+ * then quoted in the shop's geo-resolved currency while the page went on
+ * showing the one the buyer asked for.
+ */
+declare function getBuyerCurrency(): string;
+
+interface StorefrontData {
+    settings: StorefrontSettings;
+    shop: StorefrontShop;
+    catalog: StorefrontCatalog;
+}
+declare function readStorefrontData(): StorefrontData;
+declare function StorefrontProvider({ data, children }: {
+    data: StorefrontData;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useStorefront(): StorefrontData;
+/**
+ * Live visitor count for the header pill.
+ *
+ * Starts at null — "not answered yet" — and the pill renders nothing until a
+ * real number arrives. A placeholder zero would flash "0 online" on every page
+ * load, and a placeholder guess would be a fabricated claim. A failed request
+ * leaves it null and the pill simply stays away.
+ */
+declare function useOnlineUserCount(): number | null;
+
+/**
+ * The merchant's product video, turned into an embeddable `src` — and gated.
+ *
+ * `products.video_link` is a raw string the merchant typed: a YouTube watch URL,
+ * a bare video id, a Streamable short link, a Vimeo page. The Easy lane resolves
+ * it through `resolveVideoEmbedSrc`
+ * (`packages/builder-runtime/src/video-embed.ts`, called by the storefront
+ * render context) and then renders the iframe ONLY when the resolved host is on
+ * the gallery block's allowlist (`blocks/gallery.ts`, ADR-0045).
+ *
+ * Both halves are ported here, in that order, because they answer different
+ * questions. The parser decides which provider a merchant meant; the allowlist
+ * decides whether the storefront is willing to frame it at all. A host that is
+ * not on the list renders NOTHING — never the raw string in an iframe, which is
+ * what turns a merchant-editable text column into an arbitrary embed.
+ *
+ * Ported rather than imported: the theme builds standalone from
+ * `templates/code-storefronts/`, with no workspace dependency on the renderer.
+ * Keep the allowlist and the provider rules in step with the two files above.
+ */
+/**
+ * The iframe `src` for a merchant's `video_link`, or null when there is nothing
+ * this storefront is willing to frame.
+ *
+ * Privacy-enhanced YouTube (`youtube-nocookie.com`) because that is what the
+ * render context asks for (`resolveVideoEmbedSrc(..., { privacyEnhanced: true })`)
+ * — a code storefront must not set more cookies on a buyer than the Easy lane
+ * for the same merchant's video.
+ */
+declare function resolveProductVideoEmbedSrc(value: unknown): string | null;
+
+export { ACCOUNT_ARTIFACT_CAPABILITIES, ACCOUNT_PATH, ACCOUNT_PATH_ALIAS, ACCOUNT_ROUTE_MESSAGE_KEYS, ACCOUNT_STOREFRONT_ROUTES, ACCOUNT_TABS, type AccountRouteMessageKey, type AccountRouteParts, type AccountTab, type AccountView, type BuyBoxVariantModel, CATALOG_PAGE_SIZE, CATALOG_SORTS, CATALOG_SORT_LABELS, type CartBoundsHeal, CartProvider, type CartQuoteLineBounds, type CartTotals, type CartView, type CartViewLine, type CatalogCardModel, type CatalogPage, type CatalogSort, type CheckoutFieldGroup, type CheckoutFieldValues, type CheckoutFields, type ContactFormValues, type ContactSubmissionContext, DEFAULT_ACCOUNT_TAB, DEFAULT_LOW_STOCK_THRESHOLD, DELIVERY_TIME_UNITS, type DeliveryPromise, type DeliveryTimeUnit, type GroupCardModel, IMPLEMENTED_ACCOUNT_TABS, type ImplementedAccountTab, type LicenseStatement, type LicenseTerm, type LinePricing, MAX_PAY_WHAT_YOU_WANT_PRICE, type MenuNavLink, type MenuSlot, type NavLink, type NavigationLinks, PRODUCT_BADGE_ICON_NAMES, type ProductAddon, type ProductAutomaticDeal, type ProductBadge, type ProductBadgeIconName, type ProductBundle, type ProductBundleItem, type ProductCardModel, type ProductCategoryRef, type ProductContentTab, type ProductCustomField, type ProductDetailModel, type ProductFaq, type ProductRatingModel, type ProductSubscription, type ProductType, QUOTE_UNAVAILABLE_CHECKOUT_ERROR, type RatingStars, type ResellerProgramSummary, type RewardProgramItem, type RewardProgramSummary, SERVING_CONTEXT_HINT, SHOP_REVIEW_PAGE_SIZE, STOREFRONT_SORT_KEYS, type SdkCartAddOptions, type SdkCartAddon, type SdkCartAppliedDiscount, type SdkCartCodeSource, type SdkCartItem, type SdkCartQuote, type SdkCartQuoteLine, type SdkCheckoutResult, type SdkCustomerAffiliateLink, type SdkCustomerAffiliateSummary, type SdkCustomerDashboard, type SdkCustomerDashboardOrder, type SdkCustomerDeliverable, type SdkCustomerDeliveryStatus, type SdkCustomerDeliverySummary, type SdkCustomerLicense, type SdkCustomerLoyalty, type SdkCustomerLoyaltyRedeem, type SdkCustomerLoyaltyTransactionType, type SdkCustomerOrderDetail, type SdkCustomerOrderPage, type SdkCustomerOrderSummary, type SdkCustomerRewardActivity, type SdkCustomerRewards, type SdkCustomerSubscription, type SdkCustomerTicketSummary, type SdkCustomerWarranty, type SdkCustomerWarrantyClaim, type SdkCustomerWarrantyClaimStatus, type SdkCustomerWarrantyList, type SdkCustomerWarrantyStatus, type SdkEligibleCartDeal, type SdkInitOptions, type SdkMenu, type SdkMenuItem, type SdkPage, type SdkRecentSaleEntry, type SdkResponse, type SdkShopReview, type ShopPageFaqItem, type ShopPageModel, type ShopPageState, type ShopReview, type ShopReviewLabels, type ShopReviewsState, type ShoppexSdk, type SocialLink, type SocialNetwork, type StockChip, type StockTone, type StorefrontAddon, type StorefrontCatalog, type StorefrontCategory, type StorefrontData, type StorefrontGroup, type StorefrontListingItem, type StorefrontPriceVariant, type StorefrontProduct, StorefrontProvider, type StorefrontSettings, type StorefrontShop, type StorefrontShopStats, type StorefrontSortKey, type SubscriptionIntervalUnit, type SupportChannel, type VolumeDiscountRule, accountOrderHref, accountRouteMessage, accountTabHref, accountTabLabelKey, averageRating, badgesForCard, badgesForProductPage, buildCartTotals, buildCartView, buildCustomFieldPayload, buildInitialCheckoutFieldValues, buildProductDetail, buildStorefrontCatalog, calculateDisplayLineTotal, calculateLinePricing, canonicalAccountPath, checkoutFieldKey, checkoutFieldWriteRepriced, checkoutNeedsDetails, clampQuantity, clearRecoveredQuoteCheckoutError, filterCatalogCards, findStorefrontProduct, firstOptionalString, flattenMerchantHtmlToText, formatCompactCount, formatDeliveryTime, formatLicenseTerm, formatMoney, formatSubscriptionCadence, formatSubscriptionTrial, getAuthoredContent, getBuyerCurrency, getProductGroups, getProducts, getShoppex, getStorefrontAddons, getStorefrontCategories, getStorefrontListing, getStorefrontSettings, getStorefrontShop, hasInjectedStorefrontData, isAccountTab, isBlankMerchantHtml, isCheckboxValueChecked, isImplementedAccountTab, isProductSoldOut, isRecord, isSelectionSoldOut, loadShopPage, missingRequiredCheckoutValues, optionalBoolean, optionalString, optionalStringWithDefault, paginateCatalogCards, parseAccountPath, parseCartQuoteLines, parseEnum, parseFiniteNumber, parseProductBadges, parseStorefrontSortKey, readCheckoutNeedsDetails, readStorefrontData, requireArray, requireBoolean, requireNumber, requireRecord, requireString, requireStringFromKeys, requireUnknownRecord, resolveAccountView, resolveBadgeForeground, resolveCartBoundsHeals, resolveCategorySelection, resolveCheckoutFields, resolveDeliveryPromise, resolveDisplayStock, resolveHideStockCounter, resolveLicenseTerm, resolveMenuLinksForSlot, resolvePayWhatYouWantMinimum, resolveProductVideoEmbedSrc, resolveQuantityBounds, resolveSupportChannels, resolveUnsellableLineIds, resolveVariantStock, reviewsForProduct, roundCurrency, sanitizeMerchantHtml, sortCatalogCards, startCartMutation, stripMerchantHtmlImages, submitContactTicket, toShopReviews, toStarCount, useCart, useNavigationLinks, useOnlineUserCount, useShopReviews, useStorefront, validateCheckoutFieldValue, validateCheckoutFields, validateContactSubmission };