Incorrect snippet and outdated imports in `astro:assets` docs

📚 Subject area/topic

astro/assets module

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/reference/modules/astro-assets/

📋 Description of content that is out-of-date or incorrect

I spotted two documentation issues related to assets, but I don't know yet if we should fix docs or the codebase.

1. Background prop on <Image /> https://docs.astro.build/en/reference/modules/astro-assets/#background

https://github.com/withastro/astro/pull/15153 introduced a background property to control the background color used when images (e.g. png) are flattened. Using our docs code snippet we get a TypeScript error:

Type '{ src: ImageMetadata; alt: string; format: "jpeg"; background: string; }' is not assignable to type 'IntrinsicAttributes & Props'.
  Property 'background' does not exist on type 'IntrinsicAttributes & Props'.ts(2322)

Despite that, this works because <Image /> uses getImage() under the hood. But is this the intended usage? I mean, looking at the implementation PR, <Image /> were never mentioned before we update the changeset. And, currently background is only set on ImageTransform.

So, should we add background as valid prop for <Image /> (in the core repo) or should we fix the docs?

Either way, we'll need to update the docs to add ImageTransform.background in https://docs.astro.build/en/reference/modules/astro-assets/#imagetransform

2. Images utilities https://docs.astro.build/en/reference/modules/astro-assets/#imports-from-astroassetsutils

• matchHostname, matchPathname, matchPort, and matchProtocol were removed in https://github.com/withastro/astro/pull/16197

• emitImageMetadata, propsToFilename, and hashTransform were removed in https://github.com/withastro/astro/pull/14306/changes#diff-d48e632552d390dcbbb96a1bd4d7989897c469b75379973c0d721815fd00c7d8
  Then, propsToFilename and hashTransform were added to astro/assets in https://github.com/withastro/astro/pull/15435

This is a v6 breaking change and the upgrade guide doesn't mention it! Actually, this is even worse: we recommend using emitImageMetadata instead of emitEsmImage but this helper is no longer available, see https://docs.astro.build/en/guides/upgrade-to/v6/#removed-emitesmimage.

Is the breaking change intentional? Those were documented in the Image Service API before moving to that page (see https://github.com/withastro/docs/pull/11158 and https://github.com/withastro/docs/pull/11194).

If this is intentional, we should we remove them from the docs and update the v6 upgrade guide to mention the removal. Otherwise, we'll have to add them back in the core repo.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

For the background issue:

https://stackblitz.com/edit/astro-image-background-prop?file=src%2Fcomponents%2FMyComponent.astro&on=stackblitz

Run astro check or download the repro locally to see the TypeScript error in your editor.

Start with the astro:assets reference page and the linked StackBlitz reproduction, then compare the current Image props and ImageTransform types with PRs 15153, 16197, 14306, and 15435. Check the v6 upgrade guide alongside the documented utility exports. Done means the docs accurately reflect supported APIs, removed utilities, and any required breaking-change guidance.