@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

package/dist/development/core/cart/cart.d.mts

@@ -1,28 +1,32 @@
 import { CartData, CartState } from "./state.mjs";
 
 //#region src/core/cart/cart.d.ts
-/** Timeout (in milliseconds) for cart loads and mutations. */
+/** The timeout in milliseconds for cart loads and mutations. */
 declare const STANDARD_ACTION_TIMEOUT_IN_MS = 30000;
 /**
- * Error thrown when the cart endpoint responds with a non-2xx status.
+ * The error that a cart load or cart change throws when your cart endpoint responds with a non-2xx status. Read `status` to handle specific failures.
  *
- * Carries the HTTP {@link CartNetworkError.status | status} code so callers
- * can distinguish transient failures from permanent ones.
+ * Without a cart endpoint from `configureCartEndpoint`, cart requests fail with other error types.
+ *
+ * @publicDocs
  */
 declare class CartNetworkError extends Error {
+  /** The HTTP status code that the cart endpoint returned. */
   readonly status: number;
+  /** Always `CartNetworkError`. */
+  name: string;
+  /** Always `"Something went wrong updating your cart. Please try again."`, including for a failed cart load. */
+  message: string;
+  /** The stack trace, when the JavaScript runtime records one. */
+  stack?: string;
   constructor(status: number);
 }
 /**
- * A reactive, framework-agnostic cart state machine.
+ * Holds the customer's cart and runs cart changes in any framework. In React, `CartProvider` creates the store for you.
  *
- * The store manages optimistic mutations and server reconciliation — the client's
- * *intent*. Cart-level costs and totals are always server-authoritative, but
- * line-level data (quantity, estimated cost) and discount applicability are
- * projected optimistically until the server response arrives.
+ * The store shows line and discount code changes before the server responds, then updates the cart from each server response. Cart costs change only when the server responds.
  *
- * Mutations are dispatched via {@link CartStore.handleFormSubmit} (from HTML
- * forms) or through Shopify Standard Action `shopify:cart:*` events.
+ * Cart changes start from cart form submissions or from Standard Actions `shopify:cart:*` events. Cart changes need the Standard Actions script, which `ShopifyScripts` adds to the page. Cart loads and changes time out after 30 seconds.
  *
  * @example
  * ```ts
@@ -41,67 +45,71 @@ declare class CartNetworkError extends Error {
  */
 type CartStore = {
   /**
-   * Activates the store — starts listening for Shopify standard action events
-   * and triggers the initial cart load if no `initialData` was provided.
-   * Idempotent; no-op without `document` (SSR-safe).
+   * Starts handling cart events, and loads the cart when you created the store without initial data. Repeated calls have no effect. During server rendering, the method does nothing.
    */
-  connect(): void; /** Tears down the store — cancels in-flight requests, removes event listeners, releases resources. */
-  destroy(): void; /** Replaces the settled cart data with a fresh server response. */
-  hydrate(data: CartData): void; /** Returns the current {@link CartState}, with optimistic projections applied on top of settled data. */
+  connect(): void; /** Stops the store. Cancels in-flight cart requests and stops handling cart events. */
+  destroy(): void; /** Replaces the store's cart with a different cart that the server loaded. The method ignores data for the cart that the store already holds, and ignores data while cart changes are in flight. */
+  hydrate(data: CartData): void; /** Returns the current cart state, including changes that the server hasn't confirmed yet. */
   getState(): CartState;
   /**
-   * Registers a listener invoked on every state change. Returns an unsubscribe function.
-   * Compatible with React's `useSyncExternalStore`.
+   * Calls the listener on every state change and returns a function that removes the listener. The method works with React's `useSyncExternalStore`.
    *
-   * @param listener - Callback receiving the new {@link CartState} snapshot
+   * @param listener - The function that receives each new state.
+   */
+  subscribe(listener: (state: CartState) => void): () => void;
+  /**
+   * Loads the full cart from the server.
+   *
+   * The promise rejects when the load fails, with a `CartNetworkError` when your cart endpoint returns a non-2xx status.
    */
-  subscribe(listener: (state: CartState) => void): () => void; /** Triggers a full cart load from the server endpoint. */
   fetch(): Promise<void>;
   /**
-   * Reconciles the cart after an out-of-band mutation: revalidates the current
-   * cart, or loads one when none is present yet (e.g. just created server-side).
+   * Reloads the cart after a cart change that skipped the store, such as a server action. When the store has no cart yet, the method picks up the cart that the server created.
+   *
+   * A failed reload adds an entry to the network errors in the cart state.
    */
-  refresh(): void; /** Resets the store — aborts in-flight requests, clears data and errors, and re-fetches when connected. */
+  refresh(): void; /** Clears the cart data and errors and cancels in-flight cart requests. After you connect the store, the method also loads the cart again when the store held a cart. */
   reset(): void;
   /**
-   * Intercepts a native `SubmitEvent` from a cart form, parses the intent and
-   * field values, and dispatches the matching transaction.
+   * Runs the cart change that a cart form submission describes. Pass the form's submit event, and call `event.preventDefault()` to stop the browser's own form submission. The method connects the store when you haven't connected it.
    *
-   * The submitter's `value` attribute determines the action — `"add"`,
-   * `"increase"`, `"decrease"`, `"remove"`, `"set"`, `"discount-apply"`,
-   * `"discount-remove"`, `"note-update"`, or `"attributes-update"`. An empty
-   * value with a `merchandiseId` field is treated as `"add"`.
+   * The submit button's value sets the change: `add`, `increase`,
+   * `decrease`, `remove`, `set`, `discount-apply`, `discount-remove`,
+   * `note-update`, or `attributes-update`. A button without a value adds
+   * the line when the form has a `merchandiseId` field. A `set` with an empty or
+   * zero quantity removes the line. When your cart fragment selects the variant's
+   * available quantity, the store caps a `set` quantity at that number.
    *
-   * The returned promise rejects with a `TypeError` if `event.target` is not
-   * a form or `event.submitter` is missing, and with an `Error` if the
-   * submitter's value is not a recognized intent.
+   * The promise rejects with a type error when the event target isn't a form or
+   * the event has no submitter. The promise rejects with an error when the button's
+   * value isn't a recognized change, or when the form lacks a required field
+   * such as the line ID.
    */
   handleFormSubmit(event: SubmitEvent, eventDetail?: Record<string, unknown>): Promise<void>;
 };
-/** Actions for reconciling cart state after updates outside Standard Actions. */
+/** The store action that reloads the cart after a cart change outside the store. */
 type CartActions = Pick<CartStore, "refresh">;
+/** The cart that the server loaded for the first render. */
 type CartInitialData<TData extends CartData = CartData> = {
-  cart: TData | null;
+  /** The loaded cart, or `null` when the server found no cart. */cart: TData | null; /** Load errors from the server. The store ignores the errors. */
   errors?: Array<{
     message: string;
   }>;
 };
-/** Options for {@link createCartStore}. */
+/** Options for creating a cart store. */
 type CreateCartStoreOptions<TData extends CartData = CartData> = {
   /**
-   * Server-loaded cart data to hydrate the store with on creation.
+   * The cart that the server loaded, or a promise of the cart for streamed data.
    *
-   * Accepts a synchronous value or a `PromiseLike` for streamed/deferred data.
-   * When omitted, the store starts empty and loads the cart on {@link CartStore.connect}.
+   * Pass the `data` property of the cart GET handler's result. A `null` cart
+   * tells the store that no cart exists yet. Without initial data, the store starts empty and loads the cart when you call `connect()`.
    */
   initialData?: CartInitialData<TData> | PromiseLike<CartInitialData<TData>>;
 };
 /**
- * Creates a new {@link CartStore} for the given initial data.
+ * Creates a cart store that holds the cart and applies cart changes before the server responds.
  *
- * The store is inert until {@link CartStore.connect} is called — no network
- * requests are made and no event listeners are attached at creation time.
- * Framework adapters call `connect()` on mount and `destroy()` on unmount.
+ * Call `connect()` to start the store and `destroy()` to stop it. The React and Vue cart providers call both for you.
  *
  * @example
  * ```ts
@@ -118,18 +126,23 @@ type CreateCartStoreOptions<TData extends CartData = CartData> = {
  * // Empty — loads the cart on connect()
  * const store = createCartStore();
  * ```
+ * @param options The cart that the server loaded for the first render.
+ * @returns The cart store. Read the cart with `getState()` and listen for changes with `subscribe()`.
+ * @publicDocs
  */
 declare function createCartStore<TData extends CartData = CartData>(options?: CreateCartStoreOptions<TData>): CartStore;
 /**
- * Routes cart loads and mutations to a custom endpoint instead of the
- * Standard Actions default handler.
+ * Sends every cart load and cart change on the page to your cart endpoint. Without an endpoint, Standard Actions handles cart requests with its default handler.
  *
- * Logs a warning if called again with a different endpoint.
+ * Call the function before you connect a cart store. The first cart load then goes to your endpoint. A later call with a different endpoint replaces the first endpoint and logs a warning. In React, `CartProvider` sets the endpoint to `/api/cart` when the provider mounts.
  *
+ * @param endpoint The URL path of your cart route.
+ * @returns Nothing. Later cart loads and changes on the page go to the endpoint.
  * @example
  * ```ts
  * configureCartEndpoint("/storefront/cart");
  * ```
+ * @publicDocs
  */
 declare function configureCartEndpoint(endpoint: string): void;
 //#endregion

package/dist/development/core/cart/cart.mjs

@@ -23,15 +23,17 @@ const EMPTY_QUANTITY = 0;
 const FNV1A_OFFSET_BASIS = 2166136261;
 const FNV1A_PRIME = 16777619;
 const CART_REVALIDATION_ERROR_MESSAGE = "Something went wrong refreshing your cart. Please try again.";
-/** Timeout (in milliseconds) for cart loads and mutations. */
+/** The timeout in milliseconds for cart loads and mutations. */
 const STANDARD_ACTION_TIMEOUT_IN_MS = 3e4;
 /**
-* Error thrown when the cart endpoint responds with a non-2xx status.
+* The error that a cart load or cart change throws when your cart endpoint responds with a non-2xx status. Read `status` to handle specific failures.
 *
-* Carries the HTTP {@link CartNetworkError.status | status} code so callers
-* can distinguish transient failures from permanent ones.
+* Without a cart endpoint from `configureCartEndpoint`, cart requests fail with other error types.
+*
+* @publicDocs
 */
 var CartNetworkError = class extends Error {
+	/** The HTTP status code that the cart endpoint returned. */
 	status;
 	constructor(status) {
 		super("Something went wrong updating your cart. Please try again.");
@@ -554,10 +556,11 @@ function getAddErrorKeys(payload, lineIds, failure) {
 }
 function mergeServerLine(previous, next) {
 	if (!previous) return next;
-	const merchandise = next.merchandise ? {
+	const swapped = previous.merchandise?.id !== void 0 && next.merchandise?.id !== void 0 && previous.merchandise.id !== next.merchandise.id;
+	const merchandise = next.merchandise && !swapped ? {
 		...previous.merchandise,
 		...next.merchandise
-	} : previous.merchandise;
+	} : next.merchandise ?? previous.merchandise;
 	return {
 		...previous,
 		...next,
@@ -677,17 +680,21 @@ const CART_TRANSACTION_TYPES = defineTransactionTypes({
 				data: reconcileCartLines(state.data, lines)
 			};
 		},
-		projectPromise: (state, result, payload, addError) => {
+		projectPromise: (state, result, payload, addError, options) => {
 			if (hasProjectedErrors(result)) addError((current, timestampMs) => projectLineErrors(current, result, [payload.lineId], timestampMs));
 			if (!result.cart) return state;
-			const serverLines = getLines(cartResponseFromStandardEvent(result.cart));
-			const matching = serverLines.find((line) => line.id === payload.lineId);
+			const cart = cartResponseFromStandardEvent(result.cart);
+			const matching = getLines(cart).find((line) => line.id === payload.lineId);
+			if (!matching && payload.quantity > 0 && options.mergeServerCart) return {
+				...state,
+				data: adoptServerLines(state.data, cart)
+			};
 			const previous = getLines(state.data);
-			let lines = previous.filter((line) => line.id !== payload.lineId);
+			let lines = previous;
 			if (matching) {
 				const prior = previous.find((line) => line.id === payload.lineId);
 				lines = previous.map((line) => line.id === payload.lineId ? mergeServerLine(prior, matching) : line);
-			} else if (payload.quantity > 0 && previous.length === 1 && serverLines.length === 1) lines = [mergeServerLine(previous[0], serverLines[0])];
+			} else if (payload.quantity === 0) lines = previous.filter((line) => line.id !== payload.lineId);
 			return {
 				...state,
 				data: reconcileCartLines(state.data, lines)
@@ -718,14 +725,11 @@ const CART_TRANSACTION_TYPES = defineTransactionTypes({
 			if (hasProjectedErrors(result)) addError((current, timestampMs) => projectDiscountErrors(current, result, payload.discountCodes, timestampMs, resolvedCodes));
 			if (!result.cart) return state;
 			const cart = cartResponseFromStandardEvent(result.cart);
-			if (options.mergeServerCart) return {
-				...state,
-				data: mergeAuthoritativeCartData(state.data, cart)
-			};
+			const data = options.mergeServerCart ? adoptServerLines(state.data, cart) : state.data;
 			return {
 				...state,
 				data: {
-					...state.data,
+					...data,
 					discountCodes: cart.discountCodes
 				}
 			};
@@ -872,16 +876,14 @@ function trimPendingTransaction(store, type, definition, payload, promise, ident
 }
 function addSnapshotFields(state, result) {
 	if (!result.cart) return state;
-	const cart = cartResponseFromStandardEvent(result.cart);
+	const { lines: _lines, checkoutUrl, updatedAt, ...fields } = cartResponseFromStandardEvent(result.cart);
 	return {
 		...state,
 		data: {
 			...state.data,
-			id: cart.id,
-			checkoutUrl: cart.checkoutUrl ?? state.data.checkoutUrl,
-			updatedAt: cart.updatedAt ?? state.data.updatedAt,
-			totalQuantity: cart.totalQuantity,
-			cost: cart.cost
+			...fields,
+			checkoutUrl: checkoutUrl ?? state.data.checkoutUrl,
+			updatedAt: updatedAt ?? state.data.updatedAt
 		}
 	};
 }
@@ -1377,11 +1379,9 @@ function loadCartInStore(store, cartPromise) {
 	return promise;
 }
 /**
-* Creates a new {@link CartStore} for the given initial data.
+* Creates a cart store that holds the cart and applies cart changes before the server responds.
 *
-* The store is inert until {@link CartStore.connect} is called — no network
-* requests are made and no event listeners are attached at creation time.
-* Framework adapters call `connect()` on mount and `destroy()` on unmount.
+* Call `connect()` to start the store and `destroy()` to stop it. The React and Vue cart providers call both for you.
 *
 * @example
 * ```ts
@@ -1398,6 +1398,9 @@ function loadCartInStore(store, cartPromise) {
 * // Empty — loads the cart on connect()
 * const store = createCartStore();
 * ```
+* @param options The cart that the server loaded for the first render.
+* @returns The cart store. Read the cart with `getState()` and listen for changes with `subscribe()`.
+* @publicDocs
 */
 function createCartStore(options = {}) {
 	const initialData = options.initialData;
@@ -1552,15 +1555,17 @@ async function handleFormSubmitInStore(store, handlers, event, eventDetail) {
 	throw new Error(`Unknown cart form intent: "${intent}"`);
 }
 /**
-* Routes cart loads and mutations to a custom endpoint instead of the
-* Standard Actions default handler.
+* Sends every cart load and cart change on the page to your cart endpoint. Without an endpoint, Standard Actions handles cart requests with its default handler.
 *
-* Logs a warning if called again with a different endpoint.
+* Call the function before you connect a cart store. The first cart load then goes to your endpoint. A later call with a different endpoint replaces the first endpoint and logs a warning. In React, `CartProvider` sets the endpoint to `/api/cart` when the provider mounts.
 *
+* @param endpoint The URL path of your cart route.
+* @returns Nothing. Later cart loads and changes on the page go to the endpoint.
 * @example
 * ```ts
 * configureCartEndpoint("/storefront/cart");
 * ```
+* @publicDocs
 */
 function configureCartEndpoint(endpoint) {
 	if (configuredCartEndpoint === endpoint) return;
@@ -1642,6 +1647,18 @@ function fetchCartData(cartId, signal) {
 		attributes: cart.attributes ?? []
 	} : null);
 }
+function adoptServerLines(previous, authoritative) {
+	const previousLines = new Map(getLines(previous).map((line) => [line.id, line]));
+	const nodes = getLines(authoritative).map((line) => mergeServerLine(previousLines.get(line.id), line));
+	return {
+		...previous,
+		lines: {
+			...previous.lines,
+			...authoritative.lines,
+			nodes
+		}
+	};
+}
 function mergeAuthoritativeCartData(previous, authoritative) {
 	const previousLines = new Map(getLines(previous).map((line) => [line.id, line]));
 	const lines = getLines(authoritative).map((line) => mergeServerLine(previousLines.get(line.id), line));