Add image loading hints

.changeset/gold-maps-promise.md

@@ -0,0 +1,5 @@
+---
+"emdash": patch
+---
+
+Add `fetchpriority="high"` to priority EmDash images so above-the-fold images can be requested eagerly and prioritized by the browser.

docs/src/content/docs/guides/media-library.mdx

@@ -230,38 +230,27 @@ const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
 
 ### Responsive Images
 
-For responsive images, use Astro's Image component with external URLs:
+For EmDash media fields, use the `Image` component from `emdash/ui`:
 
 ```astro
 ---
-import { Image } from "astro:assets";
+import { Image } from "emdash/ui";
 import { getEmDashEntry } from "emdash";
 
 const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
 ---
 
 {post?.data.featured_image && (
   <Image
-    src={post.data.featured_image}
-    alt={post.data.featured_image_alt ?? ""}
+    image={post.data.featured_image}
     width={800}
     height={450}
+    priority
   />
 )}
 ```
 
-<Aside type="tip">
-Configure allowed image domains in `astro.config.mjs` to use the Image component with external URLs:
-
-```js title="astro.config.mjs"
-export default defineConfig({
-	image: {
-		domains: ["media.example.com"],
-	},
-});
-```
-
-</Aside>
+`priority` is for the primary above-the-fold image. It sets `loading="eager"` and `fetchpriority="high"`: `loading` controls whether loading is deferred, and `fetchpriority` gives the browser a priority hint for the request.
 
 ## Deleting Media
 

docs/src/content/docs/themes/creating-themes.mdx

@@ -294,6 +294,7 @@ const { post } = Astro.props;
       alt={post.data.featured_image.alt || post.data.title}
       width={800}
       height={450}
+      priority
     />
   )}
   <h2><a href={`/posts/${post.slug}`}>{post.data.title}</a></h2>
@@ -306,6 +307,8 @@ const { post } = Astro.props;
 	with `src` and `alt` -- writing `<img src={post.data.featured_image} />` renders `[object Object]`.
 </Aside>
 
+Use `priority` only for the likely above-the-fold image on a page, such as a hero or first card image. It renders the image with `loading="eager"` and `fetchpriority="high"`. `loading` controls whether the browser may defer loading, while `fetchpriority` hints how important the request is once the browser discovers it.
+
 ## Using Menus
 
 Query admin-defined menus in your layouts. Never hard-code navigation links:

packages/core/src/components/EmDashImage.astro

@@ -170,6 +170,7 @@ const imgProps: Record<string, unknown> = {
 	height: finalHeight,
 	alt: finalAlt,
 	loading: priority ? "eager" : "lazy",
+	fetchpriority: priority ? "high" : undefined,
 	decoding: "async",
 	style: placeholderStyle ? `${baseStyle} ${placeholderStyle}` : baseStyle,
 	...attrs,