docs: Add mention of Picture and new srcset-related attributes

src/content/docs/en/guides/images.mdx

@@ -84,10 +84,6 @@ import myImage from "../assets/my_image.png"; // Image is 1600x900
 />
 ```
 
-Currently, the built-in assets feature does not include a `<Picture />` component.
-
-Instead, you can [generate images or custom components using `getImage()`](#generating-images-with-getimage) that use the HTML image attributes `srcset` and `sizes` or the `<picture>` tag [for art direction or to create responsive images](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#art_direction).
-
 #### Properties
 
 ##### src (required)
@@ -145,6 +141,18 @@ When using local images in their original aspect ratio, the `width` and `height`
 
 However, both of these properties are required for remote images and images stored in your `public/` folder as Astro is unable to analyze these files.
 
+##### densities
+
+A list of pixel densities to generate for the image. By default, no other densities are generated.
+
+This value will be used to generate a `srcset` attribute on the `<img>` tag.
+
+##### widths
+
+A list of widths to generate for the image. By default, no other widths are generated.
+
+This value will be used to generate a `srcset` attribute on the `<img>` tag. When using `widths`, a `sizes` property is also required for `srcset` to take effect.
+
 ##### format
 
 You can optionally state the [image file type](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types#common_image_file_types) output to be used.
@@ -209,6 +217,52 @@ const {src, ...attrs} = Astro.props;
 </style>
 ```
 
+### `<Picture />`
+
+Use the built-in `<Picture />` Astro component to display a responsive image with multiple formats and/or sizes.
+
+```astro title="src/pages/index.astro"
+---
+import { Picture } from 'astro:assets';
+import myImage from "../assets/my_image.png";
+---
+
+<!-- `alt` is also mandatory on the Picture component -->
+<Picture src={myImage} formats={['avif', 'webp']} alt="A description of my image." />
+```
+
+```html
+<!-- Output -->
+<picture>
+  <source srcset="/_astro/my_image.hash.avif" type="image/avif" />
+  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
+  <img
+    src="/_astro/my_image.hash.jpg"
+    width="1600"
+    height="900"
+    decoding="async"
+    loading="lazy"
+    alt="A description of my image."
+  />
+</picture>
+```
+
+#### Properties
+
+`<Picture />` accepts all the properties of the `<Image />` component, plus the following:
+
+##### `formats`
+
+An array of image formats to use for the `<source>` tags. Every entry will be added as `<source>` elements in the order they were inputted. As such, your most modern format should go first. By default, this is set to `['webp']`.
+
+##### `fallbackFormat`
+
+Format to use as a fallback value for the `<img>` tag. Defaults to `.png`, unless the image is animated or a SVG, in which case it'll fallback to `.gif` and `.svg` respectively.
+
+##### `pictureAttributes`
+
+An object of attributes to be added to the `<picture>` tag. Every other attributes, apart from the ones used for the image transformation, will be applied to the inner `<img>` element. This is notably useful for applying style and classes to your image.
+
 ### `<img>`
 
 The [Astro template syntax](/en/core-concepts/astro-syntax/) also supports writing an `<img>` tag directly, with full control over its final output. These images will not be processed and optimized.
@@ -484,8 +538,13 @@ It returns an object with the following properties:
 
 ```js
 {
-  options: {...} // Original parameters passed
-  src: "https//..." // Path to the generated image
+  rawOptions: {...}, // Original parameters passed
+  options: {...}, // Validated parameters passed
+  src: "...", // Path to the generated image
+  srcSet: {
+    values: [...], // Generated values for srcset, every entry has a url and a size descriptor
+    attribute: "", // Generated srcset attribute from the values
+  }
   attributes: {...} // Additional HTML attributes needed to render the image (width, height, style, etc..)
 }
 ```
@@ -731,7 +790,7 @@ The new `image` helper for content collections lets you validate the image metad
 
 ### Navigating Image Imports in Astro v3.0
 
-In Astro v3.0, if you have to preserve the old import behavior for images and require a string representation of the image's URL, append `?url` to the end of your image path when importing it. For example: 
+In Astro v3.0, if you have to preserve the old import behavior for images and require a string representation of the image's URL, append `?url` to the end of your image path when importing it. For example:
 
 ```astro title="src/pages/blog/MyImages.astro"
 ---
@@ -744,8 +803,8 @@ import Sprite from '../assets/logo.svg?url';
 
 ```
 
-This approach ensures you obtain the URL string. Keep in mind that during development, Astro uses a `src/` path, but upon building, it generates hashed paths like `/_astro/cat.a6737dd3.png`. 
+This approach ensures you obtain the URL string. Keep in mind that during development, Astro uses a `src/` path, but upon building, it generates hashed paths like `/_astro/cat.a6737dd3.png`.
 
-If you prefer to work directly with the image object itself, you can access the `.src` property. This approach is best for tasks like managing image dimensions for Core Web Vitals metrics and preventing CLS. 
+If you prefer to work directly with the image object itself, you can access the `.src` property. This approach is best for tasks like managing image dimensions for Core Web Vitals metrics and preventing CLS.
 
 If you are transitioning into the new import behavior, combining `?url` and `.src` methods might be the right method for seamless image handling.

src/content/docs/en/reference/image-service-reference.mdx

@@ -173,6 +173,8 @@ export type ImageTransform = {
     src: ImageMetadata | string;
     width?: number;
     height?: number;
+    widths?: number[] | undefined;
+	  densities?: (number | `${number}x`)[] | undefined;
     quality?: ImageQuality;
     format?: OutputFormat;
     alt?: string;
@@ -207,6 +209,25 @@ You must return a `format` to ensure that the proper MIME type is served to user
 
 This hook returns all additional attributes used to render the image as HTML, based on the parameters passed by the user (`options`).
 
+
+### `getSrcSet()`
+
+**Optional for both local and external services**
+
+`getSrcSet?: (options: ImageTransform, imageConfig: AstroConfig['image']): SrcSetValue[] | Promise<SrcSetValue[]>;`
+
+This hook allows the generation of multiple variants of the same image. While it is most notably and intended to be used for `srcset`, it can also be used to generate multiple variants of the same image for different use cases.
+
+Every item in the array returned by this hook is an object with the following properties:
+
+```ts
+export type SrcSetValue = {
+	transform: ImageTransform;
+	descriptor?: string;
+	attributes?: Record<string, any>;
+};
+```
+
 ### `validateOptions()`
 
 **Optional for both local and external services**