@shopify/hydrogen 2026.4.1 → 2026.4.3

package/dist/production/index.d.cts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode, ComponentType, ScriptHTMLAttributes, FC, ForwardRefExoticComponent, RefAttributes, ComponentProps } from 'react';
-import { BuyerInput, CountryCode as CountryCode$1, LanguageCode as LanguageCode$1, VisitorConsent as VisitorConsent$1, CartInput, CartLineInput, CartLineUpdateInput, CartBuyerIdentityInput, CartSelectedDeliveryOptionInput, AttributeInput, Scalars, CartSelectableAddressInput, CartSelectableAddressUpdateInput, Cart, CartMetafieldsSetInput, CartUserError, MetafieldsSetUserError, MetafieldDeleteUserError, CartWarning, Product, ProductVariant, CartLine, ComponentizableCartLine, CurrencyCode, PageInfo, Maybe, ProductOptionValue, ProductOption, ProductVariantConnection, SelectedOptionInput } from '@shopify/hydrogen-react/storefront-api-types';
+import { BuyerInput, Cart, CountryCode as CountryCode$1, LanguageCode as LanguageCode$1, VisitorConsent as VisitorConsent$1, CartInput, CartLineInput, CartLineUpdateInput, CartBuyerIdentityInput, CartSelectedDeliveryOptionInput, AttributeInput, Scalars, CartSelectableAddressInput, CartSelectableAddressUpdateInput, CartMetafieldsSetInput, CartUserError, MetafieldsSetUserError, MetafieldDeleteUserError, CartWarning, Product, ProductVariant, CartLine, ComponentizableCartLine, CurrencyCode, PageInfo, Maybe, ProductOptionValue, ProductOption, ProductVariantConnection, SelectedOptionInput } from '@shopify/hydrogen-react/storefront-api-types';
 import { createStorefrontClient as createStorefrontClient$1, StorefrontClientProps, RichText as RichText$1, ShopPayButton as ShopPayButton$1 } from '@shopify/hydrogen-react';
 export { AnalyticsEventName, AnalyticsPageType, ClientBrowserParameters, ExternalVideo, IMAGE_FRAGMENT, Image, MappedProductOptions, MediaFile, ModelViewer, Money, ParsedMetafields, ShopifyAnalytics as SendShopifyAnalyticsEvent, ShopifyAddToCart, ShopifyAddToCartPayload, ShopifyAnalyticsPayload, ShopifyAnalyticsProduct, ShopifyCookies, ShopifyPageView, ShopifyPageViewPayload, ShopifySalesChannel, StorefrontApiResponse, StorefrontApiResponseError, StorefrontApiResponseOk, StorefrontApiResponseOkPartial, StorefrontApiResponsePartial, Video, customerAccountApiCustomScalars, decodeEncodedVariant, flattenConnection, getAdjacentAndFirstAvailableVariants, getClientBrowserParameters, getProductOptions, getShopifyCookies, getTrackingValues, isOptionValueCombinationInEncodedVariant, mapSelectedProductOptionToObject, parseGid, parseMetafield, sendShopifyAnalytics, storefrontApiCustomScalars, useLoadScript, useMoney, useSelectedOptionInUrlParam, useShopifyCookies } from '@shopify/hydrogen-react';
 import { LanguageCode, CountryCode } from '@shopify/hydrogen-react/customer-account-api-types';
@@ -1077,7 +1077,7 @@ type CustomerAccountOptions = {
     useCustomAuthDomain?: boolean;
 };
 
-type CartGetProps = {
+type CartGetProps<TExtraVariables = {}> = {
     /**
      * The cart ID.
      * @default cart.getCartId();
@@ -1112,8 +1112,8 @@ type CartGetProps = {
      * When provided, consent is encoded into the cart's checkoutUrl via the _cs parameter.
      */
     visitorConsent?: VisitorConsent$1;
-};
-type CartGetFunction = (cartInput?: CartGetProps) => Promise<CartReturn | null>;
+} & TExtraVariables;
+type CartGetFunction<TCart = Cart, TExtraVariables = {}> = (cartInput?: CartGetProps<TExtraVariables>) => Promise<CartReturn<TCart> | null>;
 type CartGetOptions = CartQueryOptions & {
     /**
      * The customer account client instance created by [`createCustomerAccountClient`](docs/api/hydrogen/latest/utilities/createcustomeraccountclient).
@@ -1121,43 +1121,43 @@ type CartGetOptions = CartQueryOptions & {
     customerAccount?: CustomerAccount;
 };
 /** @publicDocs */
-declare function cartGetDefault({ storefront, customerAccount, getCartId, cartFragment, }: CartGetOptions): CartGetFunction;
+declare function cartGetDefault<TCart = Cart, TExtraVariables = {}>({ storefront, customerAccount, getCartId, cartFragment, }: CartGetOptions): CartGetFunction<TCart, TExtraVariables>;
 
-type CartCreateFunction = (input: CartInput, optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn>;
+type CartCreateFunction<TCart = CartQueryDataReturn['cart']> = (input: CartInput, optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn<TCart>>;
 /** @publicDocs */
-declare function cartCreateDefault(options: CartQueryOptions): CartCreateFunction;
+declare function cartCreateDefault<TCart = CartQueryDataReturn['cart']>(options: CartQueryOptions): CartCreateFunction<TCart>;
 
-type CartLinesAddFunction = (lines: Array<CartLineInput>, optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn>;
+type CartLinesAddFunction<TCart = CartQueryDataReturn['cart']> = (lines: Array<CartLineInput>, optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn<TCart>>;
 /** @publicDocs */
-declare function cartLinesAddDefault(options: CartQueryOptions): CartLinesAddFunction;
+declare function cartLinesAddDefault<TCart = CartQueryDataReturn['cart']>(options: CartQueryOptions): CartLinesAddFunction<TCart>;
 
-type CartLinesUpdateFunction = (lines: CartLineUpdateInput[], optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn>;
+type CartLinesUpdateFunction<TCart = CartQueryDataReturn['cart']> = (lines: CartLineUpdateInput[], optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn<TCart>>;
 /** @publicDocs */
-declare function cartLinesUpdateDefault(options: CartQueryOptions): CartLinesUpdateFunction;
+declare function cartLinesUpdateDefault<TCart = CartQueryDataReturn['cart']>(options: CartQueryOptions): CartLinesUpdateFunction<TCart>;
 
-type CartLinesRemoveFunction = (lineIds: string[], optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn>;
+type CartLinesRemoveFunction<TCart = CartQueryDataReturn['cart']> = (lineIds: string[], optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn<TCart>>;
 /** @publicDocs */
-declare function cartLinesRemoveDefault(options: CartQueryOptions): CartLinesRemoveFunction;
+declare function cartLinesRemoveDefault<TCart = CartQueryDataReturn['cart']>(options: CartQueryOptions): CartLinesRemoveFunction<TCart>;
 
-type CartDiscountCodesUpdateFunction = (discountCodes: string[], optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn>;
+type CartDiscountCodesUpdateFunction<TCart = CartQueryDataReturn['cart']> = (discountCodes: string[], optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn<TCart>>;
 /** @publicDocs */
-declare function cartDiscountCodesUpdateDefault(options: CartQueryOptions): CartDiscountCodesUpdateFunction;
+declare function cartDiscountCodesUpdateDefault<TCart = CartQueryDataReturn['cart']>(options: CartQueryOptions): CartDiscountCodesUpdateFunction<TCart>;
 
-type CartBuyerIdentityUpdateFunction = (buyerIdentity: CartBuyerIdentityInput, optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn>;
+type CartBuyerIdentityUpdateFunction<TCart = CartQueryDataReturn['cart']> = (buyerIdentity: CartBuyerIdentityInput, optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn<TCart>>;
 /** @publicDocs */
-declare function cartBuyerIdentityUpdateDefault(options: CartQueryOptions): CartBuyerIdentityUpdateFunction;
+declare function cartBuyerIdentityUpdateDefault<TCart = CartQueryDataReturn['cart']>(options: CartQueryOptions): CartBuyerIdentityUpdateFunction<TCart>;
 
-type CartNoteUpdateFunction = (note: string, optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn>;
+type CartNoteUpdateFunction<TCart = CartQueryDataReturn['cart']> = (note: string, optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn<TCart>>;
 /** @publicDocs */
-declare function cartNoteUpdateDefault(options: CartQueryOptions): CartNoteUpdateFunction;
+declare function cartNoteUpdateDefault<TCart = CartQueryDataReturn['cart']>(options: CartQueryOptions): CartNoteUpdateFunction<TCart>;
 
-type CartSelectedDeliveryOptionsUpdateFunction = (selectedDeliveryOptions: CartSelectedDeliveryOptionInput[], optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn>;
+type CartSelectedDeliveryOptionsUpdateFunction<TCart = CartQueryDataReturn['cart']> = (selectedDeliveryOptions: CartSelectedDeliveryOptionInput[], optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn<TCart>>;
 /** @publicDocs */
-declare function cartSelectedDeliveryOptionsUpdateDefault(options: CartQueryOptions): CartSelectedDeliveryOptionsUpdateFunction;
+declare function cartSelectedDeliveryOptionsUpdateDefault<TCart = CartQueryDataReturn['cart']>(options: CartQueryOptions): CartSelectedDeliveryOptionsUpdateFunction<TCart>;
 
-type CartAttributesUpdateFunction = (attributes: AttributeInput[], optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn>;
+type CartAttributesUpdateFunction<TCart = CartQueryDataReturn['cart']> = (attributes: AttributeInput[], optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn<TCart>>;
 /** @publicDocs */
-declare function cartAttributesUpdateDefault(options: CartQueryOptions): CartAttributesUpdateFunction;
+declare function cartAttributesUpdateDefault<TCart = CartQueryDataReturn['cart']>(options: CartQueryOptions): CartAttributesUpdateFunction<TCart>;
 
 type CartMetafieldsSetFunction = (metafields: MetafieldWithoutOwnerId[], optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn>;
 /** @publicDocs */
@@ -1167,7 +1167,7 @@ type CartMetafieldDeleteFunction = (key: Scalars['String']['input'], optionalPar
 /** @publicDocs */
 declare function cartMetafieldDeleteDefault(options: CartQueryOptions): CartMetafieldDeleteFunction;
 
-type CartGiftCardCodesUpdateFunction = (giftCardCodes: string[], optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn>;
+type CartGiftCardCodesUpdateFunction<TCart = CartQueryDataReturn['cart']> = (giftCardCodes: string[], optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn<TCart>>;
 /**
  * Updates (replaces) gift card codes in the cart.
  *
@@ -1181,9 +1181,9 @@ type CartGiftCardCodesUpdateFunction = (giftCardCodes: string[], optionalParams?
  * await updateGiftCardCodes(['SUMMER2025', 'WELCOME10']);
  * @publicDocs
  */
-declare function cartGiftCardCodesUpdateDefault(options: CartQueryOptions): CartGiftCardCodesUpdateFunction;
+declare function cartGiftCardCodesUpdateDefault<TCart = CartQueryDataReturn['cart']>(options: CartQueryOptions): CartGiftCardCodesUpdateFunction<TCart>;
 
-type CartGiftCardCodesAddFunction = (giftCardCodes: string[], optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn>;
+type CartGiftCardCodesAddFunction<TCart = CartQueryDataReturn['cart']> = (giftCardCodes: string[], optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn<TCart>>;
 /**
  * Adds gift card codes to the cart without replacing existing ones.
  *
@@ -1198,127 +1198,19 @@ type CartGiftCardCodesAddFunction = (giftCardCodes: string[], optionalParams?: C
  * await addGiftCardCodes(['SUMMER2025', 'WELCOME10']);
  * @publicDocs
  */
-declare function cartGiftCardCodesAddDefault(options: CartQueryOptions): CartGiftCardCodesAddFunction;
+declare function cartGiftCardCodesAddDefault<TCart = CartQueryDataReturn['cart']>(options: CartQueryOptions): CartGiftCardCodesAddFunction<TCart>;
 
-type CartGiftCardCodesRemoveFunction = (appliedGiftCardIds: string[], optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn>;
+type CartGiftCardCodesRemoveFunction<TCart = CartQueryDataReturn['cart']> = (appliedGiftCardIds: string[], optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn<TCart>>;
 /** @publicDocs */
-declare function cartGiftCardCodesRemoveDefault(options: CartQueryOptions): CartGiftCardCodesRemoveFunction;
+declare function cartGiftCardCodesRemoveDefault<TCart = CartQueryDataReturn['cart']>(options: CartQueryOptions): CartGiftCardCodesRemoveFunction<TCart>;
 
-type CartDeliveryAddressesAddFunction = (addresses: Array<CartSelectableAddressInput>, optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn>;
-/**
- * Adds delivery addresses to the cart.
- *
- * This function sends a mutation to the storefront API to add one or more delivery addresses to the cart.
- * It returns the result of the mutation, including any errors that occurred.
- *
- * @param {CartQueryOptions} options - The options for the cart query, including the storefront API client and cart fragment.
- * @returns {CartDeliveryAddressAddFunction} - A function that takes an array of addresses and optional parameters, and returns the result of the API call.
- *
- * @example
- * const addDeliveryAddresses = cartDeliveryAddressesAddDefault({ storefront, getCartId });
- * const result = await addDeliveryAddresses([
- *    {
- *      address1: '123 Main St',
- *      city: 'Anytown',
- *      countryCode: 'US'
- *      // other address fields...
- *    }
- *  ], { someOptionalParam: 'value' }
- * );
- * @publicDocs
- */
-declare function cartDeliveryAddressesAddDefault(options: CartQueryOptions): CartDeliveryAddressesAddFunction;
+type CartDeliveryAddressesAddFunction<TCart = CartQueryDataReturn['cart']> = (addresses: Array<CartSelectableAddressInput>, optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn<TCart>>;
 
-type CartDeliveryAddressesRemoveFunction = (addressIds: Array<Scalars['ID']['input']> | Array<string>, optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn>;
-/**
- * Removes delivery addresses from the cart.
- *
- * This function sends a mutation to the storefront API to remove one or more delivery addresses from the cart.
- * It returns the result of the mutation, including any errors that occurred.
- *
- * @param {CartQueryOptions} options - The options for the cart query, including the storefront API client and cart fragment.
- * @returns {CartDeliveryAddressRemoveFunction} - A function that takes an array of address IDs and optional parameters, and returns the result of the API call.
- *
- * @example
- * const removeDeliveryAddresses = cartDeliveryAddressesRemoveDefault({ storefront, getCartId });
- * const result = await removeDeliveryAddresses([
- *   "gid://shopify/<objectName>/10079785100"
- * ],
- * { someOptionalParam: 'value' });
- * @publicDocs
- */
-declare function cartDeliveryAddressesRemoveDefault(options: CartQueryOptions): CartDeliveryAddressesRemoveFunction;
+type CartDeliveryAddressesRemoveFunction<TCart = CartQueryDataReturn['cart']> = (addressIds: Array<Scalars['ID']['input']> | Array<string>, optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn<TCart>>;
 
-type CartDeliveryAddressesUpdateFunction = (addresses: Array<CartSelectableAddressUpdateInput>, optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn>;
-/**
- * Updates delivery addresses in the cart.
- *
- * Pass an empty array to clear all delivery addresses from the cart.
- *
- * @param {CartQueryOptions} options - The options for the cart query, including the storefront API client and cart fragment.
- * @returns {CartDeliveryAddressUpdateFunction} - A function that takes an array of addresses and optional parameters, and returns the result of the API call.
- *
- * @example Clear all delivery addresses
- * const updateAddresses = cartDeliveryAddressesUpdateDefault(cartQueryOptions);
- * await updateAddresses([]);
- *
- * @example Update specific delivery addresses
- * const updateAddresses = cartDeliveryAddressesUpdateDefault(cartQueryOptions);
- * await updateAddresses([
-    {
-      "address": {
-        "copyFromCustomerAddressId": "gid://shopify/<objectName>/10079785100",
-        "deliveryAddress": {
-          "address1": "<your-address1>",
-          "address2": "<your-address2>",
-          "city": "<your-city>",
-          "company": "<your-company>",
-          "countryCode": "AC",
-          "firstName": "<your-firstName>",
-          "lastName": "<your-lastName>",
-          "phone": "<your-phone>",
-          "provinceCode": "<your-provinceCode>",
-          "zip": "<your-zip>"
-        }
-      },
-      "id": "gid://shopify/<objectName>/10079785100",
-      "oneTimeUse": true,
-      "selected": true,
-      "validationStrategy": "COUNTRY_CODE_ONLY"
-    }
-  ],{ someOptionalParam: 'value' });
- * @publicDocs
- */
-declare function cartDeliveryAddressesUpdateDefault(options: CartQueryOptions): CartDeliveryAddressesUpdateFunction;
+type CartDeliveryAddressesUpdateFunction<TCart = CartQueryDataReturn['cart']> = (addresses: Array<CartSelectableAddressUpdateInput>, optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn<TCart>>;
 
-type CartDeliveryAddressesReplaceFunction = (addresses: Array<CartSelectableAddressInput>, optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn>;
-/**
- * Replaces all delivery addresses on the cart.
- *
- * This function sends a mutation to the storefront API to replace all delivery addresses on the cart
- * with the provided addresses. It returns the result of the mutation, including any errors that occurred.
- *
- * @param {CartQueryOptions} options - The options for the cart query, including the storefront API client and cart fragment.
- * @returns {CartDeliveryAddressesReplaceFunction} - A function that takes an array of addresses and optional parameters, and returns the result of the API call.
- *
- * @example
- * const replaceDeliveryAddresses = cartDeliveryAddressesReplaceDefault({ storefront, getCartId });
- * const result = await replaceDeliveryAddresses([
- *    {
- *      address: {
- *        deliveryAddress: {
- *          address1: '123 Main St',
- *          city: 'Anytown',
- *          countryCode: 'US'
- *        }
- *      },
- *      selected: true
- *    }
- *  ], { someOptionalParam: 'value' }
- * );
- * @publicDocs
- */
-declare function cartDeliveryAddressesReplaceDefault(options: CartQueryOptions): CartDeliveryAddressesReplaceFunction;
+type CartDeliveryAddressesReplaceFunction<TCart = CartQueryDataReturn['cart']> = (addresses: Array<CartSelectableAddressInput>, optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn<TCart>>;
 
 type CartHandlerOptions = {
     storefront: Storefront;
@@ -1330,26 +1222,26 @@ type CartHandlerOptions = {
     buyerIdentity?: CartBuyerIdentityInput;
 };
 type CustomMethodsBase = Record<string, Function>;
-type CartHandlerOptionsWithCustom<TCustomMethods extends CustomMethodsBase> = CartHandlerOptions & {
-    customMethods?: TCustomMethods;
+type CartHandlerOptionsWithRequiredCustom<TCustomMethods extends CustomMethodsBase> = CartHandlerOptions & {
+    customMethods: TCustomMethods;
 };
-type HydrogenCart = {
-    get: ReturnType<typeof cartGetDefault>;
+type HydrogenCart<TCart = HydrogenCustomCartFragment & Cart, TGetExtraVariables = {}> = {
+    get: CartGetFunction<TCart, TGetExtraVariables>;
     getCartId: () => string | undefined;
     setCartId: (cartId: string) => Headers;
-    create: ReturnType<typeof cartCreateDefault>;
-    addLines: ReturnType<typeof cartLinesAddDefault>;
-    updateLines: ReturnType<typeof cartLinesUpdateDefault>;
-    removeLines: ReturnType<typeof cartLinesRemoveDefault>;
-    updateDiscountCodes: ReturnType<typeof cartDiscountCodesUpdateDefault>;
-    updateGiftCardCodes: ReturnType<typeof cartGiftCardCodesUpdateDefault>;
-    addGiftCardCodes: ReturnType<typeof cartGiftCardCodesAddDefault>;
-    removeGiftCardCodes: ReturnType<typeof cartGiftCardCodesRemoveDefault>;
-    updateBuyerIdentity: ReturnType<typeof cartBuyerIdentityUpdateDefault>;
-    updateNote: ReturnType<typeof cartNoteUpdateDefault>;
-    updateSelectedDeliveryOption: ReturnType<typeof cartSelectedDeliveryOptionsUpdateDefault>;
-    updateAttributes: ReturnType<typeof cartAttributesUpdateDefault>;
-    setMetafields: ReturnType<typeof cartMetafieldsSetDefault>;
+    create: CartCreateFunction<TCart>;
+    addLines: CartLinesAddFunction<TCart>;
+    updateLines: CartLinesUpdateFunction<TCart>;
+    removeLines: CartLinesRemoveFunction<TCart>;
+    updateDiscountCodes: CartDiscountCodesUpdateFunction<TCart>;
+    updateGiftCardCodes: CartGiftCardCodesUpdateFunction<TCart>;
+    addGiftCardCodes: CartGiftCardCodesAddFunction<TCart>;
+    removeGiftCardCodes: CartGiftCardCodesRemoveFunction<TCart>;
+    updateBuyerIdentity: CartBuyerIdentityUpdateFunction<TCart>;
+    updateNote: CartNoteUpdateFunction<TCart>;
+    updateSelectedDeliveryOption: CartSelectedDeliveryOptionsUpdateFunction<TCart>;
+    updateAttributes: CartAttributesUpdateFunction<TCart>;
+    setMetafields: (metafields: MetafieldWithoutOwnerId[], optionalParams?: CartOptionalInput) => Promise<CartQueryDataReturn | CartQueryDataReturn<TCart>>;
     deleteMetafield: ReturnType<typeof cartMetafieldDeleteDefault>;
     /**
      * Adds delivery addresses to the cart.
@@ -1372,7 +1264,7 @@ type HydrogenCart = {
      *   { someOptionalParam: 'value' }
      * );
      */
-    addDeliveryAddresses: ReturnType<typeof cartDeliveryAddressesAddDefault>;
+    addDeliveryAddresses: CartDeliveryAddressesAddFunction<TCart>;
     /**
      * Removes delivery addresses from the cart.
      *
@@ -1388,7 +1280,7 @@ type HydrogenCart = {
      * ],
      * { someOptionalParam: 'value' });
      */
-    removeDeliveryAddresses: ReturnType<typeof cartDeliveryAddressesRemoveDefault>;
+    removeDeliveryAddresses: CartDeliveryAddressesRemoveFunction<TCart>;
     /**
     * Updates delivery addresses in the cart.
     *
@@ -1422,7 +1314,7 @@ type HydrogenCart = {
         }
       ],{ someOptionalParam: 'value' });
     */
-    updateDeliveryAddresses: ReturnType<typeof cartDeliveryAddressesUpdateDefault>;
+    updateDeliveryAddresses: CartDeliveryAddressesUpdateFunction<TCart>;
     /**
      * Replaces all delivery addresses on the cart.
      *
@@ -1446,12 +1338,13 @@ type HydrogenCart = {
      *   }
      * ], { someOptionalParam: 'value' });
      */
-    replaceDeliveryAddresses: ReturnType<typeof cartDeliveryAddressesReplaceDefault>;
+    replaceDeliveryAddresses: CartDeliveryAddressesReplaceFunction<TCart>;
 };
-type HydrogenCartCustom<TCustomMethods extends Partial<HydrogenCart> & CustomMethodsBase> = Omit<HydrogenCart, keyof TCustomMethods> & TCustomMethods;
+type HydrogenCartCustom<TCustomMethods extends CustomMethodsBase, TCart = HydrogenCustomCartFragment & Cart, TGetExtraVariables = {}> = Omit<HydrogenCart<TCart, TGetExtraVariables>, keyof TCustomMethods> & TCustomMethods;
 /** @publicDocs */
-declare function createCartHandler(options: CartHandlerOptions): HydrogenCart;
-declare function createCartHandler<TCustomMethods extends CustomMethodsBase>(options: CartHandlerOptionsWithCustom<TCustomMethods>): HydrogenCartCustom<TCustomMethods>;
+declare function createCartHandler<TCustomMethods extends CustomMethodsBase>(options: CartHandlerOptionsWithRequiredCustom<TCustomMethods>): HydrogenCartCustom<TCustomMethods>;
+declare function createCartHandler<TCart = HydrogenCustomCartFragment & Cart, TGetExtraVariables = {}>(options: CartHandlerOptions): HydrogenCart<TCart, TGetExtraVariables>;
+declare function createCartHandler<TCart, TGetExtraVariables, TCustomMethods extends CustomMethodsBase>(options: CartHandlerOptionsWithRequiredCustom<TCustomMethods>): HydrogenCartCustom<TCustomMethods, TCart, TGetExtraVariables>;
 
 type RequestEventPayload = {
     url: string;
@@ -1848,6 +1741,29 @@ type StorefrontMutationOptionsForDocs = {
     displayName?: string;
 };
 
+declare global {
+    /**
+     * Extensible interface for typing cart results with a custom cart fragment.
+     * Augment this interface with your codegen'd fragment type to get full type
+     * safety on every cart operation — whether accessed via `context.cart`,
+     * `createCartHandler`, or `createHydrogenContext`.
+     *
+     * When empty (the default), `HydrogenCustomCartFragment & Cart` collapses
+     * to `Cart`, so existing behaviour is unchanged.
+     *
+     * @example
+     * ```ts
+     * // In app/lib/context.ts
+     * import type {CartApiQueryFragment} from 'storefrontapi.generated';
+     *
+     * declare global {
+     *   interface HydrogenCustomCartFragment extends CartApiQueryFragment {}
+     * }
+     * ```
+     */
+    interface HydrogenCustomCartFragment {
+    }
+}
 type CartOptionalInput = {
     /**
      * The cart id.
@@ -1899,18 +1815,18 @@ type CartQueryOptions = {
      */
     customerAccount?: CustomerAccount;
 };
-type CartReturn = Cart & {
+type CartReturn<TCart = Cart> = TCart & {
     errors?: StorefrontApiErrors;
 };
-type CartQueryData = {
-    cart: Cart;
+type CartQueryData<TCart = Cart> = {
+    cart: TCart;
     userErrors?: CartUserError[] | MetafieldsSetUserError[] | MetafieldDeleteUserError[];
     warnings?: CartWarning[];
 };
-type CartQueryDataReturn = CartQueryData & {
+type CartQueryDataReturn<TCart = Cart> = CartQueryData<TCart> & {
     errors?: StorefrontApiErrors;
 };
-type CartQueryReturn<T> = (requiredParams: T, optionalParams?: CartOptionalInput) => Promise<CartQueryData>;
+type CartQueryReturn<T, TCart = Cart> = (requiredParams: T, optionalParams?: CartOptionalInput) => Promise<CartQueryData<TCart>>;
 
 declare const AnalyticsEvent: {
     PAGE_VIEWED: "page_viewed";
@@ -2927,12 +2843,12 @@ type GetSelectedProductOptions = (request: Request) => SelectedOptionInput[];
 declare const getSelectedProductOptions: GetSelectedProductOptions;
 
 /**
- * Official Hydrogen Preset for React Router 7.12.x
+ * Official Hydrogen Preset for React Router 7.16.x
  *
  * Provides optimal React Router configuration for Hydrogen applications on Oxygen.
  * Enables validated performance optimizations while ensuring CLI compatibility.
  *
- * React Router 7.12.x Feature Support Matrix for Hydrogen 2025.7.0
+ * React Router 7.16.x Feature Support Matrix for Hydrogen 2025.7.0
  *
  * +----------------------------------+----------+----------------------------------+
  * | Feature                          | Status   | Notes                            |
@@ -2960,7 +2876,7 @@ declare const getSelectedProductOptions: GetSelectedProductOptions;
  * | prerender: ['/routes']           | Blocked  | Plugin incompatibility           |
  * | serverBundles: () => {}          | Blocked  | Manifest incompatibility         |
  * | buildEnd: () => {}               | Blocked  | CLI bypasses hook execution      |
- * | unstable_subResourceIntegrity    | Blocked  | CSP nonce/hash conflict          |
+ * | subResourceIntegrity             | Blocked  | CSP nonce/hash conflict          |
  * | v8_viteEnvironmentApi            | Blocked  | CLI fallback detection used      |
  * +----------------------------------+----------+----------------------------------+
  *