Clarify behavior of Clipboard.read()

Description

Per the docs, Clipboard.read() returns a Clipboard.ReadContent, which can hold text, file, or HTML data. The docs do not explain which data types will be returned depending on the state of the general pasteboard, and the current behavior is not what I would naively expect. A few examples below.

It seems like the html field is only used to render links, whether those are to files or web URLs. It is not used to return HTML data stored on the pasteboard. Is that correct? Clarification would be super helpful.

1. Copying text from a website

This only returns text:

{
  "text": "The original target for this event is the Element that was the intended target of the paste action."
}

Even though there's HTML in the general pasteboard with the standard type public.html:

% pasteboard types
com.apple.webarchive
public.rtf
public.html
public.utf8-plain-text
com.apple.WebKit.custom-pasteboard-data
public.utf16-external-plain-text

% pasteboard get -thtml | head -c80; echo
<meta charset="UTF-8"><span style="caret-color: rgb(27, 27, 27); color: rgb(27,

2. Copying a file in Finder

This returns all three data types:

{
  "html": "<a href=\"file:///Users/mkscrg/Downloads/Raycast.dmg\">Raycast.dmg</a>",
  "text": "Raycast.dmg",
  "file": "file:///Users/mkscrg/Downloads/Raycast.dmg"
}

3. Copying a link from Safari

This returns text and html:

{
  "text": "https://www.raycast.com/",
  "html": "<a href=\"https://www.raycast.com/\">https://www.raycast.com/</a>"
}

Start by reviewing the Clipboard.read documentation and its Clipboard.ReadContent examples. Compare the documented behavior with the three pasteboard cases described here, then clarify which data types and fields are returned in each case. Done means the docs explain text, file, and HTML behavior without relying on assumptions.