@shopify/hydrogen 2026.10.1 → 2026.10.2

package/dist/graphql/type-resolver.d.mts

@@ -245,6 +245,32 @@ type InferResult<T extends string> = InferResultForSchema<T, StorefrontSchema>;
 type InferVariables<T extends string> = InferVariablesForSchema<T, StorefrontSchema>;
 /** The operation kind of a query string, such as `query`. Resolves to `unknown` unless the query text has exactly one operation. */
 type InferOperationKind<T extends string> = parseDocument<T> extends infer Doc ? [Doc] extends [never] ? "unknown" : OperationKindType<Doc> : "unknown";
+type DeclaredNameOfType<Definition, Types> = Definition extends {
+  variable: {
+    name: {
+      value: infer Name extends keyof Types;
+    };
+  };
+  type: infer Type;
+} ? (Type extends {
+  kind: "NonNullType";
+  type: infer Inner;
+} ? Inner : Type) extends {
+  kind: "NamedType";
+  name: {
+    value: Types[Name];
+  };
+} ? Name : never : never;
+/**
+ * Names of the first operation's variables that are declared with the named
+ * type `Types` maps them to, nullable or non-null. List types never match.
+ */
+type InferVariableNamesDeclaredAs<T extends string, Types extends Record<string, string>> = parseDocument<T> extends infer Doc ? Doc extends {
+  kind: "Document";
+  definitions: infer Defs extends readonly unknown[];
+} ? FirstOperation<Defs> extends {
+  variableDefinitions: infer Vars extends readonly unknown[];
+} ? DeclaredNameOfType<Vars[number], Types> : never : never : never;
 //#endregion
-export { GraphQLSchemaFor, InferOperationKind, InferResult, InferResultForSchema, InferVariables, InferVariablesForSchema };
+export { GraphQLSchemaFor, InferOperationKind, InferResult, InferResultForSchema, InferVariableNamesDeclaredAs, InferVariables, InferVariablesForSchema };
 //# sourceMappingURL=type-resolver.d.mts.map

package/dist/react/cart.mjs

@@ -50,9 +50,7 @@ function createCartComponents() {
 		return useOptionalCart((state) => selector(state), isEqual);
 	}
 	function useSuspenseCart(selector, isEqual) {
-		const readyPromise = useCart((state) => state.readyPromise);
-		if (readyPromise) throw readyPromise;
-		return useCart(selector, isEqual);
+		return useSuspenseCartSelector(selector, isEqual);
 	}
 	return {
 		CartProvider: TypedCartProvider,
@@ -64,11 +62,14 @@ function createCartComponents() {
 	};
 }
 function useCartStore(hookName = "useCart") {
-	const store = useContext(CartContext);
-	if (!store) throw new Error(`${hookName} must be used inside <CartProvider>.`);
-	return store;
+	return useCartContext(hookName).store;
 }
-function useOptionalCartStore() {
+function useCartContext(hookName = "useCart") {
+	const context = useContext(CartContext);
+	if (!context) throw new Error(`${hookName} must be used inside <CartProvider>.`);
+	return context;
+}
+function useOptionalCartContext() {
 	return useContext(CartContext);
 }
 /**
@@ -88,7 +89,14 @@ function useOptionalCartStore() {
 * @publicDocs
 */
 function CartProvider({ initialData, children }) {
-	const store = useMemo(() => createCartStore({ initialData }), []);
+	const context = useMemo(() => {
+		const store = createCartStore({ initialData });
+		return {
+			store,
+			hydrationSnapshot: store.getState()
+		};
+	}, []);
+	const { store } = context;
 	useEffect(() => {
 		configureCartEndpoint(cartEndpoint);
 		store.connect();
@@ -97,7 +105,7 @@ function CartProvider({ initialData, children }) {
 		};
 	}, [store]);
 	return /* @__PURE__ */ jsx(CartContext.Provider, {
-		value: store,
+		value: context,
 		children
 	});
 }
@@ -127,7 +135,8 @@ function CartProvider({ initialData, children }) {
 * @publicDocs
 */
 function useCart(selector, isEqual) {
-	return useCartSelector(useCartStore(), selector, isEqual);
+	const { store, hydrationSnapshot } = useCartContext();
+	return useCartSelector(store, hydrationSnapshot, selector, isEqual);
 }
 /**
 * Returns the cart action that reloads the cart after a cart change outside cart forms.
@@ -194,32 +203,77 @@ function useCartAnalytics() {
 * @publicDocs
 */
 function useOptionalCart(selector, isEqual) {
-	const store = useOptionalCartStore();
-	if (!store) return void 0;
-	return useCartSelector(store, selector, isEqual);
+	const context = useOptionalCartContext();
+	if (!context) return void 0;
+	return useCartSelector(context.store, context.hydrationSnapshot, selector, isEqual);
 }
-function useCartSelector(store, selector, isEqual) {
-	const cachedRef = useRef(null);
+function useCartSelector(store, hydrationSnapshot, selector, isEqual) {
+	const liveCacheRef = useRef(null);
+	const hydrationCacheRef = useRef(null);
+	const getSnapshot = () => selectCartSnapshot(store.getState(), selector, isEqual, liveCacheRef);
+	const getServerSnapshot = () => selectCartSnapshot(hydrationSnapshot, selector, isEqual, hydrationCacheRef);
+	return useSyncExternalStore(store.subscribe, getSnapshot, getServerSnapshot);
+}
+function selectCartSnapshot(state, selector, isEqual, cacheRef) {
+	if (cacheRef.current?.state === state && cacheRef.current.selector === selector) return cacheRef.current.value;
+	const next = selector(state);
+	if (cacheRef.current && isEqual?.(cacheRef.current.value, next)) {
+		cacheRef.current = {
+			state,
+			selector,
+			value: cacheRef.current.value
+		};
+		return cacheRef.current.value;
+	}
+	cacheRef.current = {
+		state,
+		selector,
+		value: next
+	};
+	return next;
+}
+function useSuspenseCartSelector(selector, isEqual) {
+	const { store } = useCartContext();
+	const cacheRef = useRef(null);
 	const getSnapshot = () => {
 		const state = store.getState();
-		if (cachedRef.current && cachedRef.current.state === state && cachedRef.current.selector === selector) return cachedRef.current.value;
-		const next = selector(state);
-		if (cachedRef.current && isEqual?.(cachedRef.current.value, next)) {
-			cachedRef.current = {
+		if (cacheRef.current?.state === state && cacheRef.current.selector === selector) return cacheRef.current.snapshot;
+		if (state.readyPromise) {
+			const snapshot = {
+				status: "pending",
+				promise: state.readyPromise
+			};
+			cacheRef.current = {
 				state,
 				selector,
-				value: cachedRef.current.value
+				snapshot
 			};
-			return cachedRef.current.value;
+			return snapshot;
 		}
-		cachedRef.current = {
+		const value = selector(state);
+		const previous = cacheRef.current?.snapshot;
+		if (previous?.status === "ready" && isEqual?.(previous.value, value)) {
+			cacheRef.current = {
+				state,
+				selector,
+				snapshot: previous
+			};
+			return previous;
+		}
+		const snapshot = {
+			status: "ready",
+			value
+		};
+		cacheRef.current = {
 			state,
 			selector,
-			value: next
+			snapshot
 		};
-		return next;
+		return snapshot;
 	};
-	return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
+	const snapshot = useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
+	if (snapshot.status === "pending") throw snapshot.promise;
+	return snapshot.value;
 }
 /**
 * Returns form props and a field register function for building cart forms.

package/dist/react/cart.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cart.mjs","names":[],"sources":["../../src/react/cart.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  createContext,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useSyncExternalStore,\n  type FormHTMLAttributes,\n  type ReactNode,\n  type RefCallback,\n  type SubmitEvent,\n} from \"react\";\n\nimport { trackCartAnalytics } from \"../core/analytics/cart-tracker\";\nimport { attachQuantityInput } from \"../core/cart/attach-quantity-input\";\nimport {\n  configureCartEndpoint as configureCoreCartEndpoint,\n  createCartStore,\n  type CreateCartStoreOptions,\n  type CartActions,\n  type CartStore,\n} from \"../core/cart/cart\";\nimport { createCartFormRegister, type CartFormRegister } from \"../core/cart/form\";\nimport type { CartDataFromHandlers } from \"../core/cart/server-handlers\";\nimport { type CartData, type CartState } from \"../core/cart/state\";\n\nconst DEFAULT_CART_ENDPOINT = \"/api/cart\";\n\nlet cartEndpoint = DEFAULT_CART_ENDPOINT;\n\nconst CartContext = createContext<CartStore | null>(null);\n\nexport function configureCartEndpoint(endpoint: string): void {\n  cartEndpoint = endpoint;\n  configureCoreCartEndpoint(endpoint);\n}\n\nexport function getCartEndpoint(): string {\n  return cartEndpoint;\n}\n\n/**\n * Props for the cart provider that `createCartComponents` returns.\n */\ntype TypedCartProviderProps<TData extends CartData> = {\n  /**\n   * The `data` property of the cart GET handler's result, or a promise of that data. Without initial data, the store loads the cart from `/api/cart` after the provider mounts, and the server-rendered page shows an empty cart. The provider creates its store from the first value and ignores later changes.\n   */\n  initialData?: CartInitialData<TData>;\n  /** Content that can read the cart through the cart hooks. */\n  children?: ReactNode;\n};\n\ntype CartInitialData<TData extends CartData = CartData> =\n  CreateCartStoreOptions<TData>[\"initialData\"];\n\nexport type { CartActions };\n\n/** A hook that returns the slice of cart state that your selector picks. */\ntype CartStateHook<TData extends CartData> =\n  /**\n   * @param selector - Picks the value to return from the cart state.\n   * @param isEqual - Compares the previous and next selected values. Return `true` to skip the re-render. Without the function, the hook compares the values by reference.\n   * @returns The selected value.\n   */\n  <S>(selector: (state: CartState<TData>) => S, isEqual?: (a: S, b: S) => boolean) => S;\n\n/** A hook that returns the slice of cart state that your selector picks, or `undefined` outside the cart provider. */\ntype OptionalCartStateHook<TData extends CartData> =\n  /**\n   * @param selector - Picks the value to return from the cart state.\n   * @param isEqual - Compares the previous and next selected values. Return `true` to skip the re-render. Without the function, the hook compares the values by reference.\n   * @returns The selected value, or `undefined` outside the cart provider.\n   */\n  <S>(selector: (state: CartState<TData>) => S, isEqual?: (a: S, b: S) => boolean) => S | undefined;\n\n/** Callbacks that run around a cart form submission. */\ninterface CartFormPropsOptions {\n  /** Runs before the cart store handles the submission. Call `event.preventDefault()` to skip the cart submission. */\n  beforeSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;\n  /** Runs as soon as the cart change starts, before the server responds. */\n  afterSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;\n}\n\n/** The form props function and the register function for a cart form. */\ninterface CartFormBindings {\n  /** Returns the `method`, `action`, and `onSubmit` props to spread on the form. The form posts to the cart endpoint, and the cart store handles each submission. */\n  formProps: (opts?: CartFormPropsOptions) => FormHTMLAttributes<HTMLFormElement>;\n  /** Returns the attributes for a cart field or action button. Register the quantity field with `interactive: true` to submit the form when the quantity changes. The interactive input takes the quantity as a default value and stays uncontrolled. */\n  register: CartFormRegister;\n}\n\n/**\n * The cart provider and hooks that `createCartComponents` returns, typed with the custom cart fields from your cart server handlers.\n */\ntype TypedCartComponents<TData extends CartData> = {\n  /** Creates the cart store and shares the store with the cart hooks inside the provider. The provider connects the store on mount and destroys the store on unmount. */\n  CartProvider: (props: TypedCartProviderProps<TData>) => ReactNode;\n  /**\n   * Returns the slice of cart state that the selector picks. The component re-renders when the selected value changes by reference, or when your `isEqual` function reports a change. A selector that returns the full state re-renders on every cart update.\n   */\n  useCart: CartStateHook<TData>;\n  /** Suspends while the full cart loads, then returns the slice of cart state that the selector picks. Wrap the component in a `Suspense` boundary. */\n  useSuspenseCart: CartStateHook<TData>;\n  /**\n   * Returns the slice of cart state that the selector picks, or `undefined` outside the provider. Use the hook in a component that also renders above the provider, such as a cart badge on an error page.\n   */\n  useOptionalCart: OptionalCartStateHook<TData>;\n  /** Returns the `refresh()` action. Call `refresh()` after a server-side cart change that skips cart forms. */\n  useCartActions: typeof useCartActions;\n  /** Returns form props and a register function for cart forms. */\n  useCartForm: typeof useCartForm;\n};\n\n/**\n * Returns a cart provider and cart hooks typed to the cart fragment in your cart server handlers.\n * Pass `typeof cartServerHandlers` as the `THandlers` type argument. Every hook's cart state then includes your custom cart fields.\n *\n * On mount, the provider sends cart requests to `/api/cart` and connects the store. Every hook except `useOptionalCart` throws when you call it outside the provider.\n *\n * @returns The cart provider, the cart state hooks, and the cart actions and form hooks.\n *\n * @example\n * ```tsx\n * import type { cartServerHandlers } from \"./server/cart.server\";\n *\n * const {\n *   CartProvider,\n *   useCart,\n *   useSuspenseCart,\n *   useOptionalCart,\n *   useCartActions,\n *   useCartForm,\n * } = createCartComponents<typeof cartServerHandlers>();\n * ```\n * @publicDocs\n */\nexport function createCartComponents<THandlers>(): TypedCartComponents<\n  CartDataFromHandlers<THandlers>\n> {\n  type TData = CartDataFromHandlers<THandlers>;\n\n  function TypedCartProvider({ initialData, children }: TypedCartProviderProps<TData>) {\n    return (\n      <CartProvider initialData={initialData as CartInitialData | undefined}>\n        {children}\n      </CartProvider>\n    );\n  }\n\n  function useTypedCart<S>(\n    selector: (state: CartState<TData>) => S,\n    isEqual?: (a: S, b: S) => boolean,\n  ): S {\n    return useCart<CartData, S>((state) => selector(state as CartState<TData>), isEqual);\n  }\n\n  function useTypedOptionalCart<S>(\n    selector: (state: CartState<TData>) => S,\n    isEqual?: (a: S, b: S) => boolean,\n  ): S | undefined {\n    return useOptionalCart<CartData, S>((state) => selector(state as CartState<TData>), isEqual);\n  }\n\n  function useSuspenseCart<S>(\n    selector: (state: CartState<TData>) => S,\n    isEqual?: (a: S, b: S) => boolean,\n  ): S {\n    const readyPromise = useCart((state) => state.readyPromise);\n    if (readyPromise) throw readyPromise;\n    return useCart(selector, isEqual);\n  }\n\n  return {\n    CartProvider: TypedCartProvider,\n    useCart: useTypedCart,\n    useSuspenseCart,\n    useOptionalCart: useTypedOptionalCart,\n    useCartActions,\n    useCartForm,\n  } as const;\n}\n\nexport function useCartStore(hookName = \"useCart\"): CartStore {\n  const store = useContext(CartContext);\n  if (!store) throw new Error(`${hookName} must be used inside <CartProvider>.`);\n  return store;\n}\n\nfunction useOptionalCartStore(): CartStore | null {\n  return useContext(CartContext);\n}\n\n/**\n * Creates a cart store and shares the store with the cart hooks inside the provider.\n *\n * Render every cart hook inside the provider. On mount, the provider sends cart requests to `/api/cart` and connects the store. On unmount, the provider destroys the store. The provider creates its store from the first initial data and ignores later changes.\n *\n * @example\n * ```tsx\n * // In your root layout\n * <CartProvider initialData={{ cart: loaderData.cart }}>\n *   <App />\n * </CartProvider>\n * ```\n * @param props - The initial cart data and the content that uses the cart hooks.\n * @returns A context provider that shares the cart store with its children.\n * @publicDocs\n */\nexport function CartProvider({\n  initialData,\n  children,\n}: {\n  initialData?: CartInitialData;\n  children?: ReactNode;\n}) {\n  // oxlint-disable-next-line react-hooks/exhaustive-deps -- store is created once with the initial server data\n  const store = useMemo(() => createCartStore({ initialData }), []);\n\n  useEffect(() => {\n    configureCoreCartEndpoint(cartEndpoint);\n    store.connect();\n    return () => {\n      store.destroy();\n    };\n  }, [store]);\n\n  return <CartContext.Provider value={store}>{children}</CartContext.Provider>;\n}\n\n/**\n * Returns the slice of cart state that the selector picks.\n *\n * The component re-renders when the selected value changes by reference, or when your `isEqual` function reports a change. A selector that returns the full state re-renders on every cart update.\n *\n * @param selector The function that picks a value from the cart state.\n * @param isEqual The function that compares the previous and next selected values. Return `true` to skip the re-render.\n * @returns The selected value.\n *\n * @example\n * ```tsx\n * // Select cart lines\n * const lines = useCart((state) => state.data.lines.nodes);\n *\n * // Select pending state for a specific line\n * const isPending = useCart((state) => state.pending.lines.has(lineId));\n *\n * // Custom equality to avoid re-renders on unchanged totals\n * const total = useCart(\n *   (state) => state.data.cost.totalAmount,\n *   (a, b) => a.amount === b.amount,\n * );\n * ```\n * @publicDocs\n */\nexport function useCart<TData extends CartData = CartData, S = unknown>(\n  selector: (state: CartState<TData>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S {\n  const store = useCartStore();\n  return useCartSelector(store, selector, isEqual) as S;\n}\n\n/**\n * Returns the cart action that reloads the cart after a cart change outside cart forms.\n *\n * Call `refresh()` after a server-side cart change that skips cart forms, such as a server action that creates the cart.\n *\n * @returns The `refresh()` action.\n *\n * @example\n * ```tsx\n * const { refresh } = useCartActions();\n *\n * async function handleServerAction() {\n *   await createCartOnServer();\n *   refresh(); // re-fetch the cart\n * }\n * ```\n * @publicDocs\n */\nexport function useCartActions(): CartActions {\n  const store = useCartStore(\"useCartActions\");\n\n  return useMemo(() => ({ refresh: store.refresh }), [store]);\n}\n\n/**\n * Publishes cart analytics events when the customer's cart changes.\n *\n * Call the hook once near the root of your app, inside `CartProvider`. The hook starts tracking on mount and stops on unmount. The hook publishes `cart_updated`, `product_added_to_cart`, and `product_removed_from_cart` events.\n *\n * The hook throws outside `CartProvider`, and when the Shopify analytics bus isn't available. Render `ShopifyScripts` before the hook runs.\n *\n * @returns Nothing. The hook tracks cart analytics for the lifetime of the calling component.\n *\n * @example\n * ```tsx\n * function App() {\n *   useCartAnalytics();\n *   return <Layout />;\n * }\n * ```\n * @publicDocs\n */\nexport function useCartAnalytics(): void {\n  const store = useCartStore(\"useCartAnalytics\");\n\n  useEffect(() => trackCartAnalytics(store), [store]);\n}\n\n/**\n * Returns a selected slice of cart state, or `undefined` when the component renders outside the cart provider.\n *\n * Use the hook in a component that also renders above the provider, such as a header cart badge on an error page.\n * Wherever the provider always exists, use `useCart`, which throws when the provider is missing.\n *\n * @param selector The function that picks a value from the cart state.\n * @param isEqual The function that compares the previous and next selected values. Return `true` to skip the re-render.\n * @returns The selected value, or `undefined` outside the provider.\n *\n * @example\n * ```tsx\n * function CartBadge() {\n *   const count = useOptionalCart((state) => state.data.totalQuantity);\n *   if (count === undefined) return null;\n *   return <span>Cart ({count})</span>;\n * }\n * ```\n * @publicDocs\n */\nexport function useOptionalCart<TData extends CartData = CartData, S = unknown>(\n  selector: (state: CartState<TData>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S | undefined {\n  const store = useOptionalCartStore();\n  if (!store) return undefined;\n  return useCartSelector(store, selector, isEqual);\n}\n\nfunction useCartSelector<TData extends CartData = CartData, S = unknown>(\n  store: CartStore,\n  selector: (state: CartState<TData>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S {\n  const cachedRef = useRef<{ state: unknown; selector: typeof selector; value: S } | null>(null);\n\n  const getSnapshot = () => {\n    const state = store.getState() as CartState<TData>;\n\n    if (\n      cachedRef.current &&\n      cachedRef.current.state === state &&\n      cachedRef.current.selector === selector\n    ) {\n      return cachedRef.current.value;\n    }\n\n    const next = selector(state);\n\n    if (cachedRef.current && isEqual?.(cachedRef.current.value, next)) {\n      cachedRef.current = { state, selector, value: cachedRef.current.value };\n      return cachedRef.current.value;\n    }\n\n    cachedRef.current = { state, selector, value: next };\n    return next;\n  };\n\n  return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);\n}\n\n/**\n * Returns form props and a field register function for building cart forms.\n *\n * Spread `formProps()` on the form. The form posts to the cart endpoint. On submit, the form props stop the browser's navigation and send the form through the cart store.\n * The submit handler ignores a failed cart change. Read failures from the cart state's `errors`.\n * To skip the cart submission, call `event.preventDefault()` in a `beforeSubmit` callback. The `afterSubmit` callback runs as soon as the cart change starts, before the server responds.\n * The register function returns the HTML attributes for each cart field and action.\n *\n * Register the quantity field with `interactive: true` to submit the form when the quantity changes. The interactive input takes the quantity as a default value and stays uncontrolled.\n *\n * @returns The form props function and the register function.\n *\n * @example\n * ```tsx\n * function LineItem({ line }) {\n *   const { formProps, register } = useCartForm();\n *\n *   return (\n *     <form {...formProps()}>\n *       <input {...register(\"lineId\", { value: line.id })} />\n *       <input {...register(\"quantity\", { value: line.quantity, interactive: true })} />\n *       <button {...register(\"set\")} />\n *       <button {...register(\"increase\")}>+</button>\n *       <button {...register(\"decrease\")}>−</button>\n *       <button {...register(\"remove\")}>Remove</button>\n *     </form>\n *   );\n * }\n * ```\n * @publicDocs\n */\nexport function useCartForm(): CartFormBindings {\n  const store = useCartStore(\"useCartForm\");\n  const coreRegister = useMemo(() => createCartFormRegister(), []);\n\n  const register = useMemo(() => {\n    type Register = typeof coreRegister;\n    const wrapped = ((...args: Parameters<Register>) => {\n      const result = (coreRegister as Function)(...args);\n      const [field, opts] = args as [string, { interactive?: boolean }?];\n\n      if (field === \"quantity\" && opts?.interactive) {\n        let cleanup: (() => void) | null = null;\n        const ref: RefCallback<HTMLInputElement> = (el) => {\n          cleanup?.();\n          cleanup = null;\n          if (el) {\n            const form = el.closest(\"form\");\n            if (form) cleanup = attachQuantityInput(el, form);\n          }\n        };\n        const { value: _, ...rest } = result;\n        return { ...rest, defaultValue: result.value, ref };\n      }\n\n      return result;\n    }) as Register;\n    return wrapped;\n  }, [coreRegister]);\n\n  const formProps = (opts?: CartFormPropsOptions): FormHTMLAttributes<HTMLFormElement> => ({\n    onSubmit: (e: SubmitEvent<HTMLFormElement>) => {\n      opts?.beforeSubmit?.(e);\n      if (e.defaultPrevented) return;\n      e.preventDefault();\n      store.handleFormSubmit(e.nativeEvent).catch(() => {});\n      opts?.afterSubmit?.(e);\n    },\n    method: \"post\",\n    action: cartEndpoint,\n  });\n\n  return { formProps, register };\n}\n"],"mappings":"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"}
+{"version":3,"file":"cart.mjs","names":[],"sources":["../../src/react/cart.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  createContext,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useSyncExternalStore,\n  type FormHTMLAttributes,\n  type ReactNode,\n  type RefCallback,\n  type SubmitEvent,\n} from \"react\";\n\nimport { trackCartAnalytics } from \"../core/analytics/cart-tracker\";\nimport { attachQuantityInput } from \"../core/cart/attach-quantity-input\";\nimport {\n  configureCartEndpoint as configureCoreCartEndpoint,\n  createCartStore,\n  type CreateCartStoreOptions,\n  type CartActions,\n  type CartStore,\n} from \"../core/cart/cart\";\nimport { createCartFormRegister, type CartFormRegister } from \"../core/cart/form\";\nimport type { CartDataFromHandlers } from \"../core/cart/server-handlers\";\nimport { type CartData, type CartState } from \"../core/cart/state\";\n\nconst DEFAULT_CART_ENDPOINT = \"/api/cart\";\n\nlet cartEndpoint = DEFAULT_CART_ENDPOINT;\n\ninterface CartContextValue {\n  store: CartStore;\n  hydrationSnapshot: CartState;\n}\n\nconst CartContext = createContext<CartContextValue | null>(null);\n\nexport function configureCartEndpoint(endpoint: string): void {\n  cartEndpoint = endpoint;\n  configureCoreCartEndpoint(endpoint);\n}\n\nexport function getCartEndpoint(): string {\n  return cartEndpoint;\n}\n\n/**\n * Props for the cart provider that `createCartComponents` returns.\n */\ntype TypedCartProviderProps<TData extends CartData> = {\n  /**\n   * The `data` property of the cart GET handler's result, or a promise of that data. Without initial data, the store loads the cart from `/api/cart` after the provider mounts, and the server-rendered page shows an empty cart. The provider creates its store from the first value and ignores later changes.\n   */\n  initialData?: CartInitialData<TData>;\n  /** Content that can read the cart through the cart hooks. */\n  children?: ReactNode;\n};\n\ntype CartInitialData<TData extends CartData = CartData> =\n  CreateCartStoreOptions<TData>[\"initialData\"];\n\nexport type { CartActions };\n\n/** A hook that returns the slice of cart state that your selector picks. */\ntype CartStateHook<TData extends CartData> =\n  /**\n   * @param selector - Picks the value to return from the cart state.\n   * @param isEqual - Compares the previous and next selected values. Return `true` to skip the re-render. Without the function, the hook compares the values by reference.\n   * @returns The selected value.\n   */\n  <S>(selector: (state: CartState<TData>) => S, isEqual?: (a: S, b: S) => boolean) => S;\n\n/** A hook that returns the slice of cart state that your selector picks, or `undefined` outside the cart provider. */\ntype OptionalCartStateHook<TData extends CartData> =\n  /**\n   * @param selector - Picks the value to return from the cart state.\n   * @param isEqual - Compares the previous and next selected values. Return `true` to skip the re-render. Without the function, the hook compares the values by reference.\n   * @returns The selected value, or `undefined` outside the cart provider.\n   */\n  <S>(selector: (state: CartState<TData>) => S, isEqual?: (a: S, b: S) => boolean) => S | undefined;\n\n/** Callbacks that run around a cart form submission. */\ninterface CartFormPropsOptions {\n  /** Runs before the cart store handles the submission. Call `event.preventDefault()` to skip the cart submission. */\n  beforeSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;\n  /** Runs as soon as the cart change starts, before the server responds. */\n  afterSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;\n}\n\n/** The form props function and the register function for a cart form. */\ninterface CartFormBindings {\n  /** Returns the `method`, `action`, and `onSubmit` props to spread on the form. The form posts to the cart endpoint, and the cart store handles each submission. */\n  formProps: (opts?: CartFormPropsOptions) => FormHTMLAttributes<HTMLFormElement>;\n  /** Returns the attributes for a cart field or action button. Register the quantity field with `interactive: true` to submit the form when the quantity changes. The interactive input takes the quantity as a default value and stays uncontrolled. */\n  register: CartFormRegister;\n}\n\n/**\n * The cart provider and hooks that `createCartComponents` returns, typed with the custom cart fields from your cart server handlers.\n */\ntype TypedCartComponents<TData extends CartData> = {\n  /** Creates the cart store and shares the store with the cart hooks inside the provider. The provider connects the store on mount and destroys the store on unmount. */\n  CartProvider: (props: TypedCartProviderProps<TData>) => ReactNode;\n  /**\n   * Returns the slice of cart state that the selector picks. The component re-renders when the selected value changes by reference, or when your `isEqual` function reports a change. A selector that returns the full state re-renders on every cart update.\n   */\n  useCart: CartStateHook<TData>;\n  /** Suspends while the full cart loads, then returns the slice of cart state that the selector picks. Wrap the component in a `Suspense` boundary. */\n  useSuspenseCart: CartStateHook<TData>;\n  /**\n   * Returns the slice of cart state that the selector picks, or `undefined` outside the provider. Use the hook in a component that also renders above the provider, such as a cart badge on an error page.\n   */\n  useOptionalCart: OptionalCartStateHook<TData>;\n  /** Returns the `refresh()` action. Call `refresh()` after a server-side cart change that skips cart forms. */\n  useCartActions: typeof useCartActions;\n  /** Returns form props and a register function for cart forms. */\n  useCartForm: typeof useCartForm;\n};\n\n/**\n * Returns a cart provider and cart hooks typed to the cart fragment in your cart server handlers.\n * Pass `typeof cartServerHandlers` as the `THandlers` type argument. Every hook's cart state then includes your custom cart fields.\n *\n * On mount, the provider sends cart requests to `/api/cart` and connects the store. Every hook except `useOptionalCart` throws when you call it outside the provider.\n *\n * @returns The cart provider, the cart state hooks, and the cart actions and form hooks.\n *\n * @example\n * ```tsx\n * import type { cartServerHandlers } from \"./server/cart.server\";\n *\n * const {\n *   CartProvider,\n *   useCart,\n *   useSuspenseCart,\n *   useOptionalCart,\n *   useCartActions,\n *   useCartForm,\n * } = createCartComponents<typeof cartServerHandlers>();\n * ```\n * @publicDocs\n */\nexport function createCartComponents<THandlers>(): TypedCartComponents<\n  CartDataFromHandlers<THandlers>\n> {\n  type TData = CartDataFromHandlers<THandlers>;\n\n  function TypedCartProvider({ initialData, children }: TypedCartProviderProps<TData>) {\n    return (\n      <CartProvider initialData={initialData as CartInitialData | undefined}>\n        {children}\n      </CartProvider>\n    );\n  }\n\n  function useTypedCart<S>(\n    selector: (state: CartState<TData>) => S,\n    isEqual?: (a: S, b: S) => boolean,\n  ): S {\n    return useCart<CartData, S>((state) => selector(state as CartState<TData>), isEqual);\n  }\n\n  function useTypedOptionalCart<S>(\n    selector: (state: CartState<TData>) => S,\n    isEqual?: (a: S, b: S) => boolean,\n  ): S | undefined {\n    return useOptionalCart<CartData, S>((state) => selector(state as CartState<TData>), isEqual);\n  }\n\n  function useSuspenseCart<S>(\n    selector: (state: CartState<TData>) => S,\n    isEqual?: (a: S, b: S) => boolean,\n  ): S {\n    return useSuspenseCartSelector(selector, isEqual);\n  }\n\n  return {\n    CartProvider: TypedCartProvider,\n    useCart: useTypedCart,\n    useSuspenseCart,\n    useOptionalCart: useTypedOptionalCart,\n    useCartActions,\n    useCartForm,\n  } as const;\n}\n\nexport function useCartStore(hookName = \"useCart\"): CartStore {\n  return useCartContext(hookName).store;\n}\n\nfunction useCartContext(hookName = \"useCart\"): CartContextValue {\n  const context = useContext(CartContext);\n  if (!context) throw new Error(`${hookName} must be used inside <CartProvider>.`);\n  return context;\n}\n\nfunction useOptionalCartContext(): CartContextValue | null {\n  return useContext(CartContext);\n}\n\n/**\n * Creates a cart store and shares the store with the cart hooks inside the provider.\n *\n * Render every cart hook inside the provider. On mount, the provider sends cart requests to `/api/cart` and connects the store. On unmount, the provider destroys the store. The provider creates its store from the first initial data and ignores later changes.\n *\n * @example\n * ```tsx\n * // In your root layout\n * <CartProvider initialData={{ cart: loaderData.cart }}>\n *   <App />\n * </CartProvider>\n * ```\n * @param props - The initial cart data and the content that uses the cart hooks.\n * @returns A context provider that shares the cart store with its children.\n * @publicDocs\n */\nexport function CartProvider({\n  initialData,\n  children,\n}: {\n  initialData?: CartInitialData;\n  children?: ReactNode;\n}) {\n  const context = useMemo(() => {\n    const store = createCartStore({ initialData });\n    // Plain consumers must hydrate from the state used for SSR, even if the live store settles first.\n    return { store, hydrationSnapshot: store.getState() };\n    // oxlint-disable-next-line react-hooks/exhaustive-deps -- provider initialData seeds one store for its lifetime\n  }, []);\n  const { store } = context;\n\n  useEffect(() => {\n    configureCoreCartEndpoint(cartEndpoint);\n    store.connect();\n    return () => {\n      store.destroy();\n    };\n  }, [store]);\n\n  return <CartContext.Provider value={context}>{children}</CartContext.Provider>;\n}\n\n/**\n * Returns the slice of cart state that the selector picks.\n *\n * The component re-renders when the selected value changes by reference, or when your `isEqual` function reports a change. A selector that returns the full state re-renders on every cart update.\n *\n * @param selector The function that picks a value from the cart state.\n * @param isEqual The function that compares the previous and next selected values. Return `true` to skip the re-render.\n * @returns The selected value.\n *\n * @example\n * ```tsx\n * // Select cart lines\n * const lines = useCart((state) => state.data.lines.nodes);\n *\n * // Select pending state for a specific line\n * const isPending = useCart((state) => state.pending.lines.has(lineId));\n *\n * // Custom equality to avoid re-renders on unchanged totals\n * const total = useCart(\n *   (state) => state.data.cost.totalAmount,\n *   (a, b) => a.amount === b.amount,\n * );\n * ```\n * @publicDocs\n */\nexport function useCart<TData extends CartData = CartData, S = unknown>(\n  selector: (state: CartState<TData>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S {\n  const { store, hydrationSnapshot } = useCartContext();\n  return useCartSelector(store, hydrationSnapshot, selector, isEqual) as S;\n}\n\n/**\n * Returns the cart action that reloads the cart after a cart change outside cart forms.\n *\n * Call `refresh()` after a server-side cart change that skips cart forms, such as a server action that creates the cart.\n *\n * @returns The `refresh()` action.\n *\n * @example\n * ```tsx\n * const { refresh } = useCartActions();\n *\n * async function handleServerAction() {\n *   await createCartOnServer();\n *   refresh(); // re-fetch the cart\n * }\n * ```\n * @publicDocs\n */\nexport function useCartActions(): CartActions {\n  const store = useCartStore(\"useCartActions\");\n\n  return useMemo(() => ({ refresh: store.refresh }), [store]);\n}\n\n/**\n * Publishes cart analytics events when the customer's cart changes.\n *\n * Call the hook once near the root of your app, inside `CartProvider`. The hook starts tracking on mount and stops on unmount. The hook publishes `cart_updated`, `product_added_to_cart`, and `product_removed_from_cart` events.\n *\n * The hook throws outside `CartProvider`, and when the Shopify analytics bus isn't available. Render `ShopifyScripts` before the hook runs.\n *\n * @returns Nothing. The hook tracks cart analytics for the lifetime of the calling component.\n *\n * @example\n * ```tsx\n * function App() {\n *   useCartAnalytics();\n *   return <Layout />;\n * }\n * ```\n * @publicDocs\n */\nexport function useCartAnalytics(): void {\n  const store = useCartStore(\"useCartAnalytics\");\n\n  useEffect(() => trackCartAnalytics(store), [store]);\n}\n\n/**\n * Returns a selected slice of cart state, or `undefined` when the component renders outside the cart provider.\n *\n * Use the hook in a component that also renders above the provider, such as a header cart badge on an error page.\n * Wherever the provider always exists, use `useCart`, which throws when the provider is missing.\n *\n * @param selector The function that picks a value from the cart state.\n * @param isEqual The function that compares the previous and next selected values. Return `true` to skip the re-render.\n * @returns The selected value, or `undefined` outside the provider.\n *\n * @example\n * ```tsx\n * function CartBadge() {\n *   const count = useOptionalCart((state) => state.data.totalQuantity);\n *   if (count === undefined) return null;\n *   return <span>Cart ({count})</span>;\n * }\n * ```\n * @publicDocs\n */\nexport function useOptionalCart<TData extends CartData = CartData, S = unknown>(\n  selector: (state: CartState<TData>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S | undefined {\n  const context = useOptionalCartContext();\n  if (!context) return undefined;\n  return useCartSelector(context.store, context.hydrationSnapshot, selector, isEqual);\n}\n\nfunction useCartSelector<TData extends CartData = CartData, S = unknown>(\n  store: CartStore,\n  hydrationSnapshot: CartState,\n  selector: (state: CartState<TData>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S {\n  const liveCacheRef = useRef<SelectorCache<S> | null>(null);\n  const hydrationCacheRef = useRef<SelectorCache<S> | null>(null);\n\n  const getSnapshot = () =>\n    selectCartSnapshot(store.getState() as CartState<TData>, selector, isEqual, liveCacheRef);\n  const getServerSnapshot = () =>\n    selectCartSnapshot(hydrationSnapshot as CartState<TData>, selector, isEqual, hydrationCacheRef);\n\n  return useSyncExternalStore(store.subscribe, getSnapshot, getServerSnapshot);\n}\n\ninterface SelectorCache<S> {\n  state: unknown;\n  selector: unknown;\n  value: S;\n}\n\nfunction selectCartSnapshot<TData extends CartData, S>(\n  state: CartState<TData>,\n  selector: (state: CartState<TData>) => S,\n  isEqual: ((a: S, b: S) => boolean) | undefined,\n  cacheRef: { current: SelectorCache<S> | null },\n): S {\n  if (cacheRef.current?.state === state && cacheRef.current.selector === selector) {\n    return cacheRef.current.value;\n  }\n\n  const next = selector(state);\n\n  if (cacheRef.current && isEqual?.(cacheRef.current.value, next)) {\n    cacheRef.current = { state, selector, value: cacheRef.current.value };\n    return cacheRef.current.value;\n  }\n\n  cacheRef.current = { state, selector, value: next };\n  return next;\n}\n\ntype SuspenseSnapshot<S> =\n  | { status: \"pending\"; promise: PromiseLike<void> }\n  | { status: \"ready\"; value: S };\n\ninterface SuspenseSelectorCache<S> {\n  state: unknown;\n  selector: unknown;\n  snapshot: SuspenseSnapshot<S>;\n}\n\nfunction useSuspenseCartSelector<TData extends CartData, S>(\n  selector: (state: CartState<TData>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S {\n  const { store } = useCartContext();\n  const cacheRef = useRef<SuspenseSelectorCache<S> | null>(null);\n\n  // Suspense retries must read live readiness and data; the hydration snapshot would freeze the fallback.\n  const getSnapshot = () => {\n    const state = store.getState() as CartState<TData>;\n\n    if (cacheRef.current?.state === state && cacheRef.current.selector === selector) {\n      return cacheRef.current.snapshot;\n    }\n\n    if (state.readyPromise) {\n      const snapshot: SuspenseSnapshot<S> = { status: \"pending\", promise: state.readyPromise };\n      cacheRef.current = { state, selector, snapshot };\n      return snapshot;\n    }\n\n    const value = selector(state);\n    const previous = cacheRef.current?.snapshot;\n\n    if (previous?.status === \"ready\" && isEqual?.(previous.value, value)) {\n      cacheRef.current = { state, selector, snapshot: previous };\n      return previous;\n    }\n\n    const snapshot: SuspenseSnapshot<S> = { status: \"ready\", value };\n    cacheRef.current = { state, selector, snapshot };\n    return snapshot;\n  };\n\n  const snapshot = useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);\n  if (snapshot.status === \"pending\") throw snapshot.promise;\n  return snapshot.value;\n}\n\n/**\n * Returns form props and a field register function for building cart forms.\n *\n * Spread `formProps()` on the form. The form posts to the cart endpoint. On submit, the form props stop the browser's navigation and send the form through the cart store.\n * The submit handler ignores a failed cart change. Read failures from the cart state's `errors`.\n * To skip the cart submission, call `event.preventDefault()` in a `beforeSubmit` callback. The `afterSubmit` callback runs as soon as the cart change starts, before the server responds.\n * The register function returns the HTML attributes for each cart field and action.\n *\n * Register the quantity field with `interactive: true` to submit the form when the quantity changes. The interactive input takes the quantity as a default value and stays uncontrolled.\n *\n * @returns The form props function and the register function.\n *\n * @example\n * ```tsx\n * function LineItem({ line }) {\n *   const { formProps, register } = useCartForm();\n *\n *   return (\n *     <form {...formProps()}>\n *       <input {...register(\"lineId\", { value: line.id })} />\n *       <input {...register(\"quantity\", { value: line.quantity, interactive: true })} />\n *       <button {...register(\"set\")} />\n *       <button {...register(\"increase\")}>+</button>\n *       <button {...register(\"decrease\")}>−</button>\n *       <button {...register(\"remove\")}>Remove</button>\n *     </form>\n *   );\n * }\n * ```\n * @publicDocs\n */\nexport function useCartForm(): CartFormBindings {\n  const store = useCartStore(\"useCartForm\");\n  const coreRegister = useMemo(() => createCartFormRegister(), []);\n\n  const register = useMemo(() => {\n    type Register = typeof coreRegister;\n    const wrapped = ((...args: Parameters<Register>) => {\n      const result = (coreRegister as Function)(...args);\n      const [field, opts] = args as [string, { interactive?: boolean }?];\n\n      if (field === \"quantity\" && opts?.interactive) {\n        let cleanup: (() => void) | null = null;\n        const ref: RefCallback<HTMLInputElement> = (el) => {\n          cleanup?.();\n          cleanup = null;\n          if (el) {\n            const form = el.closest(\"form\");\n            if (form) cleanup = attachQuantityInput(el, form);\n          }\n        };\n        const { value: _, ...rest } = result;\n        return { ...rest, defaultValue: result.value, ref };\n      }\n\n      return result;\n    }) as Register;\n    return wrapped;\n  }, [coreRegister]);\n\n  const formProps = (opts?: CartFormPropsOptions): FormHTMLAttributes<HTMLFormElement> => ({\n    onSubmit: (e: SubmitEvent<HTMLFormElement>) => {\n      opts?.beforeSubmit?.(e);\n      if (e.defaultPrevented) return;\n      e.preventDefault();\n      store.handleFormSubmit(e.nativeEvent).catch(() => {});\n      opts?.afterSubmit?.(e);\n    },\n    method: \"post\",\n    action: cartEndpoint,\n  });\n\n  return { formProps, register };\n}\n"],"mappings":"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"}

package/dist/vite/index.d.mts

@@ -1,2 +1,12 @@
 import { LOCAL_HTTPS_DEFAULTS, LocalHttpsDevServerConfig, LocalHttpsOptions, LocalHttpsPlugin, ProvisionLocalHttpsOptions, localHttps, provisionLocalHttps } from "./local-https.mjs";
-export { LOCAL_HTTPS_DEFAULTS, LocalHttpsDevServerConfig, LocalHttpsOptions, LocalHttpsPlugin, ProvisionLocalHttpsOptions, localHttps, provisionLocalHttps };
+
+//#region src/vite/index.d.ts
+/**
+ * Projects built on 2026.4 import this name from their `vite.config`. Without it, a project whose `^2026.4.0` range resolved to 2026.10 fails at ESM link time with "does not provide an export named 'hydrogen'" before any Hydrogen code can explain the collision. This export turns that failure into a message with the fix.
+ *
+ * @deprecated Removed in `@shopify/hydrogen` 2026.10. Pin `@shopify/hydrogen` to `~2026.4.0` to keep using the `hydrogen()` Vite plugin.
+ */
+declare function hydrogen(): never;
+//#endregion
+export { LOCAL_HTTPS_DEFAULTS, LocalHttpsDevServerConfig, LocalHttpsOptions, LocalHttpsPlugin, ProvisionLocalHttpsOptions, hydrogen, localHttps, provisionLocalHttps };
+//# sourceMappingURL=index.d.mts.map

package/dist/vite/index.mjs

@@ -1,3 +1,23 @@
 import { LOCAL_HTTPS_DEFAULTS, localHttps, provisionLocalHttps } from "./local-https.mjs";
 
-export { LOCAL_HTTPS_DEFAULTS, localHttps, provisionLocalHttps };
+//#region src/vite/index.ts
+const HYDROGEN_MIGRATION_GUIDE_URL = "https://shopify.dev/docs/storefronts/hydrogen/migrate";
+/**
+* Projects built on 2026.4 import this name from their `vite.config`. Without it, a project whose `^2026.4.0` range resolved to 2026.10 fails at ESM link time with "does not provide an export named 'hydrogen'" before any Hydrogen code can explain the collision. This export turns that failure into a message with the fix.
+*
+* @deprecated Removed in `@shopify/hydrogen` 2026.10. Pin `@shopify/hydrogen` to `~2026.4.0` to keep using the `hydrogen()` Vite plugin.
+*/
+function hydrogen() {
+	throw new Error([
+		`This project is not compatible with @shopify/hydrogen 2026.10.2.`,
+		"Its vite.config imports `hydrogen()` from `@shopify/hydrogen/vite`, which 2026.10 and later no longer provide. A caret range such as `^2026.4.0` resolves to 2026.10.",
+		"",
+		"To stay on 2026.4, pin \"@shopify/hydrogen\" to \"~2026.4.0\" in package.json and reinstall.",
+		"",
+		`To move to 2026.10, follow the migration guide: ${HYDROGEN_MIGRATION_GUIDE_URL}`
+	].join("\n"));
+}
+
+//#endregion
+export { LOCAL_HTTPS_DEFAULTS, hydrogen, localHttps, provisionLocalHttps };
+//# sourceMappingURL=index.mjs.map

package/dist/vite/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/vite/index.ts"],"sourcesContent":["export * from \"./local-https\";\n\nconst HYDROGEN_MIGRATION_GUIDE_URL = \"https://shopify.dev/docs/storefronts/hydrogen/migrate\";\n\n/**\n * Projects built on 2026.4 import this name from their `vite.config`. Without it, a project whose `^2026.4.0` range resolved to 2026.10 fails at ESM link time with \"does not provide an export named 'hydrogen'\" before any Hydrogen code can explain the collision. This export turns that failure into a message with the fix.\n *\n * @deprecated Removed in `@shopify/hydrogen` 2026.10. Pin `@shopify/hydrogen` to `~2026.4.0` to keep using the `hydrogen()` Vite plugin.\n */\nexport function hydrogen(): never {\n  throw new Error(\n    [\n      `This project is not compatible with @shopify/hydrogen ${__HYDROGEN_VERSION__}.`,\n      \"Its vite.config imports `hydrogen()` from `@shopify/hydrogen/vite`, which 2026.10 and later no longer provide. A caret range such as `^2026.4.0` resolves to 2026.10.\",\n      \"\",\n      'To stay on 2026.4, pin \"@shopify/hydrogen\" to \"~2026.4.0\" in package.json and reinstall.',\n      \"\",\n      `To move to 2026.10, follow the migration guide: ${HYDROGEN_MIGRATION_GUIDE_URL}`,\n    ].join(\"\\n\"),\n  );\n}\n"],"mappings":";;;AAEA,MAAM,+BAA+B;;;;;;AAOrC,SAAgB,WAAkB;AAChC,OAAM,IAAI,MACR;EACE;EACA;EACA;EACA;EACA;EACA,mDAAmD;EACpD,CAAC,KAAK,KAAK,CACb"}

package/dist/vue/shopify-scripts.d.mts

@@ -146,7 +146,6 @@ declare const ShopifyScripts: _$vue.DefineComponent<_$vue.ExtractPropTypes<{
     required: true;
   };
 }>> & Readonly<{}>, {
-  nonce: string;
   account: boolean | undefined;
   analytics: ShopifyScriptsAnalyticsConfig | undefined;
   consent: ConsentConfig | undefined;
@@ -155,6 +154,7 @@ declare const ShopifyScripts: _$vue.DefineComponent<_$vue.ExtractPropTypes<{
   } | undefined;
   i18n: ShopifyScriptsI18n;
   inbox: boolean | undefined;
+  nonce: string;
   shopifyAnalytics: boolean;
   navigate: any;
   routes: any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopify/hydrogen",
-  "version": "2026.10.1",
+  "version": "2026.10.2",
   "description": "Framework-agnostic Shopify storefront SDK and agent skills.",
   "license": "MIT",
   "author": "Shopify",

package/skills/hydrogen-cart-ui/SKILL.md

@@ -44,11 +44,11 @@ On mutation:
 3. When the promise resolves, the store folds that transaction into settled state and reapplies remaining projections. Overlapping mutations discard ambiguous response snapshots, then coalesce one authoritative cart refresh after the burst settles.
 4. On failure, the store removes only the failed projection, preserves unrelated work, and clears the matching pending entry.
 
-When overlapping mutations make response snapshots ambiguous, the store sets `state.revalidating` to `true`. It starts one authoritative refresh after those mutations settle and clears the flag when the refresh completes or fails. Until then, server-derived values such as costs remain at their last trustworthy value. A refresh failure preserves the locally reconciled cart and appears in `errors.network`.
+When overlapping mutations make response snapshots ambiguous, the store sets `state.revalidating` to `true`. It starts one authoritative refresh after those mutations settle and clears the flag when the refresh completes or fails. Until then, server-derived values such as costs remain at their last trustworthy value. A refresh failure preserves the locally reconciled cart and appears in `errors.network`. A change made while a cart load is in flight is handled the same way: `loading` ends and the refresh brings in the rest of the cart.
 
 App-owned cart mutations outside Standard Actions do not emit the events the store normally observes. After such a mutation succeeds, call `CartStore.refresh()` directly or use the framework binding's `useCartActions().refresh()`. The refresh waits for active optimistic work, reconciles custom fragment fields from the configured cart endpoint, and loads the cart when none exists yet (e.g. one just created server-side). Do not call it after ordinary Hydrogen cart forms; their Standard Actions events already synchronize the store. For cart metafields specifically, see the `hydrogen-cart-metafields` skill.
 
-The store supersedes keyed mutations for the same line, discount batch, note, or complete attribute list. Relative additions remain independent so every submitted quantity reaches the server; their projections are reconciled together without disabling controls.
+The store supersedes keyed mutations for the same line, discount batch, note, or complete attribute list. Relative additions remain independent so every submitted quantity reaches the server; their projections are reconciled together without disabling controls. A `Shopify.actions.updateCart` call that updates or removes several lines is keyed per line: each line is projected, pending and rolled back on its own, and a newer change to one of those lines supersedes only that line.
 
 The cart store combines its lifecycle, timeout, and caller signals with `AbortSignal.any`, which Safari added in 17.4. The store already requires Safari 16 for `toSorted`, so Safari 16.0 through 17.3 is the gap. To keep add to cart working there, load an `AbortSignal.any` polyfill in the browser bundle before the store is created.
 

package/skills/hydrogen-request-handlers/SKILL.md

@@ -44,7 +44,6 @@ Serve the storefront over HTTPS and wire `handleShopifyRoutes` before framework
 const shopifyRoute = handleShopifyRoutes({
   request,
   requestContext,
-  sessionManager,
   storefrontClient,
   routeTemplates,
   handlers: [cartHandlers],
@@ -73,7 +72,8 @@ const redirect = await handleShopifyRedirects({
 - Route handlers, cart server handlers, and `handleShopifyRedirects` accept any provided Storefront client.
 - When creating a private client, resolve trusted `buyerIp` first and pass it to `createShopifyRequestContext`. Use the `hydrogen-storefront-client` buyer-IP guidance for the app's deployment.
 - Create `requestContext` with `createShopifyRequestContext({ request, i18n, buyerIp })` where buyer context exists and the framework exposes a real `Request`; use `request: { headers }` only when no `Request` exists.
-- Pass the same request-scoped `requestContext`, `storefrontClient`, and `sessionManager` into `handleShopifyRoutes` and registered handler groups.
+- Pass the same request-scoped `requestContext` and `storefrontClient` into `handleShopifyRoutes` and registered handler groups, plus the same request-scoped `sessionManager` when a handler needs one.
+- `handleShopifyRoutes` requires `sessionManager` only when a registered handler reads the session: Customer Account handlers, cart handlers created with `customerSession`, or custom handlers whose context includes it. Apps whose handlers never read the session, such as cart and predictive search only, can omit it. The requirement comes from the handler types, so a handler list that conditionally includes Customer Account handlers still needs a session manager on every request; when the account handlers are not registered, an in-memory session manager is enough, as in the starter templates. Annotate custom `createShopifyRouteHandler` contexts as `Omit<ShopifyRouteHandlerContext, "sessionManager">` when they do not use the session; a context that declares `sessionManager`, even as optional, requires one.
 - Call `handleShopifyRoutes` without awaiting it immediately. It returns `null` synchronously when no route matches; only return or await the promise after checking that it is truthy.
 - If the app has a request-level `try/catch` that converts errors into a `Response`, use `return await shopifyRoute` inside that boundary so rejected route promises reach the same error handling as synchronous setup failures. If the framework owns request error handling, return `shopifyRoute` directly. Do not add an inline `.catch()` unless the matched route intentionally needs different error handling.
 - Pass `request` and `storefrontClient` into `handleShopifyRedirects`; it does not receive a session manager.

package/skills/hydrogen-request-handlers/references/frameworks.md

@@ -32,7 +32,7 @@ Prefer this over adding `.catch()` only to the returned promise: the request-lev
 
 The scaffold defaults to a public client; `PUBLIC_STOREFRONT_API_TOKEN` may be unset, which means tokenless access (all mock.shop supports). Once the app has a private token and trusted buyer context, switch to `type: "private"` and resolve `buyerIp` per the `hydrogen-storefront-client` buyer-IP guidance.
 
-This shape assumes app-owned `getBuyerIp`, `createSessionManager`, and `routeTemplates` values.
+This shape assumes app-owned `getBuyerIp` and `routeTemplates` values. Cart and predictive search handlers do not read the session, so no `sessionManager` is passed; add a request-scoped one when registering Customer Account handlers or cart handlers created with `customerSession`.
 
 ```ts
 import {
@@ -52,7 +52,6 @@ export async function handleRequest(request: Request, next: () => Promise<Respon
     request,
     i18n: { country: "US", language: "EN" },
   });
-  const sessionManager = await createSessionManager(request);
   const storefrontClient = createStorefrontClient({
     type: "public",
     requestContext,
@@ -65,7 +64,6 @@ export async function handleRequest(request: Request, next: () => Promise<Respon
   const shopifyRoute = handleShopifyRoutes({
     request,
     requestContext,
-    sessionManager,
     storefrontClient,
     routeTemplates,
     handlers: [cartHandlers, predictiveSearchHandlers],
@@ -111,7 +109,6 @@ export const middleware: Route.MiddlewareFunction[] = [
       request,
       i18n: { country: "US", language: "EN" },
     });
-    const sessionManager = await createSessionManager(request);
     const storefrontClient = createStorefrontClient({
       type: "public",
       requestContext,
@@ -124,7 +121,6 @@ export const middleware: Route.MiddlewareFunction[] = [
     const shopifyRoute = handleShopifyRoutes({
       request,
       requestContext,
-      sessionManager,
       storefrontClient,
       routeTemplates,
       handlers: [cartHandlers, predictiveSearchHandlers],
@@ -148,13 +144,12 @@ export const middleware: Route.MiddlewareFunction[] = [
 
 SolidStart middleware can short-circuit before routing, but cannot reliably observe the final 404 after SSR streaming starts. Put `handleShopifyRoutes` in middleware and `handleShopifyRedirects` in a last-priority catch-all route.
 
-In middleware, create an app-owned request-scoped `sessionManager` before calling `handleShopifyRoutes`:
+In middleware, call `handleShopifyRoutes`. Create an app-owned request-scoped `sessionManager` first only if a registered handler reads the session:
 
 ```ts
 const shopifyRoute = handleShopifyRoutes({
   request: event.request,
   requestContext,
-  sessionManager,
   storefrontClient,
   routeTemplates,
   handlers: [cartHandlers, predictiveSearchHandlers],

package/skills/hydrogen-request-handlers/references/nuxt.md

@@ -21,7 +21,7 @@ Create `server/middleware/shopify.ts`:
 
 The scaffold defaults to a public client; `PUBLIC_STOREFRONT_API_TOKEN` may be unset, which means tokenless access (all mock.shop supports). Once the app has a private token and trusted buyer context, switch to `type: "private"` and resolve `buyerIp` from the app's trusted deployment headers per the buyer-IP guidance from `hydrogen-storefront-client`.
 
-Create app-owned `sessionManager` and `routeTemplates` values before `handleShopifyRoutes`; the session manager must be request-scoped.
+Create an app-owned `routeTemplates` value before `handleShopifyRoutes`. Cart handlers do not read the session, so this example passes no `sessionManager`; add a request-scoped one when registering Customer Account handlers or cart handlers created with `customerSession`.
 
 ```ts
 import {
@@ -40,13 +40,11 @@ export default defineEventHandler(async (event) => {
     request,
     i18n: { country: "US", language: "EN" },
   });
-  const sessionManager = await createSessionManager(request);
   const storefrontClient = createPublicStorefrontClient(requestContext);
 
   const shopifyRoute = handleShopifyRoutes({
     request,
     requestContext,
-    sessionManager,
     storefrontClient,
     routeTemplates,
     handlers: [cartHandlers],

package/skills/hydrogen-storefront-client/SKILL.md

@@ -232,7 +232,7 @@ export type ProductCardData =
 
 ### Variables and i18n auto-injection
 
-`$country` and `$language` variables are auto-injected from `requestContext.i18n` when declared in the query. Static clients still create a request context, usually with empty headers plus the resolved locale. You only pass the variables you own:
+`$country` and `$language` are auto-injected from `requestContext.i18n` when the query declares them as `$country: CountryCode` and `$language: LanguageCode` (nullable or `!`). Static clients still create a request context, usually with empty headers plus the resolved locale. You only pass the variables you own:
 
 ```ts
 const PRODUCTS = gql(`
@@ -247,7 +247,9 @@ const { data } = await client.graphql(PRODUCTS, {
 });
 ```
 
-User-provided values take precedence over auto-injected ones.
+For those declarations the request context wins: the variables type rejects `country` and `language`, and the client overwrites any value passed anyway. To query another market, create the client with a request context for that `i18n`.
+
+A same-named variable of any other type stays yours and keeps its nullability, for example `$country: String!` as a metafield key, `$country: [CountryCode!]!`, or `$language: ProductSortKeys`. Only the first operation's declarations count.
 
 ### Request state storage