Exporting definitions linked to by 3+ specs

dontcallmedom commented 1 year ago

In an effort to help specifications use auto-links to the HTML spec (which relies on relevant definitions from the HTML spec being marked as exported), I've looked at non-exported definitions that 3 specs or more link to (sorted by number of specs with such a link):

[ ] active document linked from background-fetch, clear-site-data, content-index, credential-management-1, csp-embedded-enforcement, largest-contentful-paint, mediacapture-region, page-lifecycle, portals, reporting-1, sms-one-time-codes, web-animations-1, webdriver2, webdriver-bidi
[ ] create and initialize a Document object linked from CSP3, csp-next, document-policy, page-lifecycle, performance-measure-memory, prefetch, scroll-to-text-fragment, scroll-to-text-fragment, scroll-to-text-fragment, speculation-rules, web-bluetooth
[ ] event loop processing model linked from element-timing, event-timing, intersection-observer, layout-instability, longtasks-1, page-lifecycle, requestidlecallback, scheduling-apis, video-rvfc, web-animations-1, webgpu
[ ] being rendered linked from css-nav-1, cssom-1, css-transitions-2, page-lifecycle, paint-timing, resize-observer-1, scroll-to-text-fragment, web-animations-1
[ ] create a new browsing context and document linked from document-policy, fenced-frame, performance-measure-memory, presentation-api, service-workers, webdriver-bidi, web-share-target
[ ] task queues linked from generic-sensor, IndexedDB-3, is-input-pending, scheduling-apis, service-workers, webaudio, websockets
[ ] reflect linked from attribution-reporting-api, portals, SVG2, trusted-types, virtual-keyboard, wai-aria-1
[ ] media elements linked from mediasession, openscreenprotocol, page-lifecycle, remote-playback, web-animations-1, webvtt1
[ ] create navigation params by fetching linked from CSP3, fenced-frame, prefetch, prerendering-revamped, storage-access
[ ] run the animation frame callbacks linked from css-animation-worklet-1, video-rvfc, web-animations-1, webdriver2, webdriver-bidi
[ ] Content-Type metadata linked from css-cascade-3, css-cascade-4, css-cascade-5, css-cascade-6, cssom-1
[ ] focusable area linked from clipboard-apis, css-nav-1, selectors-4, webdriver2
[ ] Read-only mode linked from clipboard-apis, entries-api, file-system-access, input-events-2
[ ] attempt to populate the history entry's document linked from CSP3, fenced-frame, prefetch, prerendering-revamped
[ ] response linked from fenced-frame, prefetch, prerendering-revamped, webpackage
[ ] browsing context group linked from fenced-frame, performance-measure-memory, portals, webdriver2
[ ] parent linked from fenced-frame, prefetch, prerendering-revamped, webdriver-bidi
[ ] gain focus linked from generic-sensor, mediacapture-streams, mediacapture-viewport, screen-capture
[ ] origin-clean linked from mediacapture-fromelement, shape-detection-api, webdriver2, webgpu
[ ] current playback position linked from media-source-2, prerendering-revamped, webcodecs, webvtt1
[ ] unload linked from navigation-timing-2, page-lifecycle, portals, presentation-api
[ ] request linked from portals, prefetch, prerendering-revamped, scroll-to-text-fragment
[ ] Content attributes linked from attribution-reporting-api, csp-embedded-enforcement, fenced-frame
[ ] media resource linked from autoplay-detection, openscreenprotocol, remote-playback
[ ] Refresh state linked from change-password-url, navigation-timing-2, webdriver2
[ ] set up a worker environment settings object linked from client-hints-infrastructure, service-workers, webdriver-bidi
[ ] Read/write mode linked from clipboard-apis, entries-api, file-system-access
[ ] focused linked from compute-pressure, edit-context, SVG2
[ ] prepare the script element linked from CSP3, speculation-rules, trusted-types
[ ] mutable linked from css-scroll-anchoring-1, css-ui-4, webdriver2
[ ] The drag data item kind linked from entries-api, file-system-access, input-events-2
[ ] document state linked from fenced-frame, prefetch, prerendering-revamped
[ ] activation notification linked from fenced-frame, file-system-access, mediasession
[ ] parse a URL linked from fenced-frame, portals, presentation-api
[ ] checkedness linked from html-aam-1, html-aria, webdriver2
[ ] presentational hints linked from mathml-core, referrer-policy, webvtt1
[ ] history handling behavior linked from navigation-timing-2, prerendering-revamped, webdriver-bidi
[ ] current document readiness linked from navigation-timing-2, page-lifecycle, webdriver2
[ ] media element event task source linked from picture-in-picture, remote-playback, webaudio
[ ] active window linked from portals, remote-playback, webdriver-bidi
[ ] navigation ID linked from prefetch, prerendering-revamped, webdriver-bidi
[ ] session history entry linked from prefetch, prerendering-revamped, web-animations-1
[ ] set up a window environment settings object linked from service-workers, storage-access, webdriver-bidi
[ ] enumerated attributes linked from virtual-keyboard, wai-aria-1, webdriver2
[ ] check the usability of the image argument linked from webcodecs, webgpu, webxrlayers-1

I'd be happy to provide a PR that mark the relevant definitions as exported - could someone take a look and check in the list above the ones that are reasonable targets?

cc @tidoust

domenic commented 1 year ago

Most of these should not be linked, as they are either misused or used by monkeypatch specs (which we don't want to encourage, and indeed want people to understand they are doing something unusual). Randomly selecting a few:

"active document" refers to the deprecated concept of a browsing context's active document, when specs should be updated to use navigables.
"parse a URL" is used by two specs that define new HTML elements (i.e., monkeypatch specs) and is being misused by presentation API (which should use https://url.spec.whatwg.org/#concept-url-parser instead).
"unload" seems to be mostly used for monkeypatches
"content attributes", "enumerated attributes", "presentational hints", and "parent" would be fine to export
Anything inside navigation params, e.g. "response", are very core bits of navigation that other specs must not depend on. (Unless they're monkeypatch specs, in which case it's unavoidable.)
"Content-Type metadata" is deprecated and should be replaced by appropriate algorithmic calls to https://fetch.spec.whatwg.org/#concept-header-extract-mime-type
"gain focus" is very suspicious; I haven't checked all call sites but I suspect most of the uses should be replaced with modifications to HTML to call out to algorithms in other specs as part of the focusing steps.
"task queues" are internal implementation details of the event loop, so it is suspicious other specifications are referencing them.

A good first step, I think, would be to remove consideration of portals, fenced-frame, prefetch, prerendering-revamped, and speculation-rules and see what's left. But I think mostly this issue is highlighting a lot of specs that are reaching into internal implementation details of HTML, that could change any time, and thus these specs are in trouble. (Or are monkeypatch specs.)

dontcallmedom commented 1 year ago

Updated list without portals, fenced-frame, prefetch, prerendering-revamped, and speculation-rules, and removing the 4 definitions I'm suggesting marking as exported in #9163

[ ] active document linked from background-fetch, clear-site-data, content-index, credential-management-1, csp-embedded-enforcement, largest-contentful-paint, mediacapture-region, page-lifecycle, reporting-1, sms-one-time-codes, web-animations-1, webdriver2, webdriver-bidi
[ ] event loop processing model linked from element-timing, event-timing, intersection-observer, layout-instability, longtasks-1, page-lifecycle, requestidlecallback, scheduling-apis, video-rvfc, web-animations-1, webgpu
[ ] create and initialize a Document object linked from CSP3, csp-next, document-policy, page-lifecycle, performance-measure-memory, scroll-to-text-fragment, scroll-to-text-fragment, scroll-to-text-fragment, web-bluetooth
[ ] being rendered linked from css-nav-1, cssom-1, css-transitions-2, page-lifecycle, paint-timing, resize-observer-1, scroll-to-text-fragment, web-animations-1
[ ] task queues linked from generic-sensor, IndexedDB-3, is-input-pending, scheduling-apis, service-workers, webaudio, websockets
[ ] create a new browsing context and document linked from document-policy, performance-measure-memory, presentation-api, service-workers, webdriver-bidi, web-share-target
[ ] media elements linked from mediasession, openscreenprotocol, page-lifecycle, remote-playback, web-animations-1, webvtt1
[ ] reflect linked from attribution-reporting-api, SVG2, trusted-types, virtual-keyboard, wai-aria-1
[ ] run the animation frame callbacks linked from css-animation-worklet-1, video-rvfc, web-animations-1, webdriver2, webdriver-bidi
[ ] Content-Type metadata linked from css-cascade-3, css-cascade-4, css-cascade-5, css-cascade-6, cssom-1
[ ] focusable area linked from clipboard-apis, css-nav-1, selectors-4, webdriver2
[ ] Read-only mode linked from clipboard-apis, entries-api, file-system-access, input-events-2
[ ] gain focus linked from generic-sensor, mediacapture-streams, mediacapture-viewport, screen-capture
[ ] origin-clean linked from mediacapture-fromelement, shape-detection-api, webdriver2, webgpu
[ ] media resource linked from autoplay-detection, openscreenprotocol, remote-playback
[ ] Refresh state linked from change-password-url, navigation-timing-2, webdriver2
[ ] set up a worker environment settings object linked from client-hints-infrastructure, service-workers, webdriver-bidi
[ ] Read/write mode linked from clipboard-apis, entries-api, file-system-access
[ ] focused linked from compute-pressure, edit-context, SVG2
[ ] mutable linked from css-scroll-anchoring-1, css-ui-4, webdriver2
[ ] The drag data item kind linked from entries-api, file-system-access, input-events-2
[ ] checkedness linked from html-aam-1, html-aria, webdriver2
[ ] current playback position linked from media-source-2, webcodecs, webvtt1
[ ] unload linked from navigation-timing-2, page-lifecycle, presentation-api
[ ] current document readiness linked from navigation-timing-2, page-lifecycle, webdriver2
[ ] media element event task source linked from picture-in-picture, remote-playback, webaudio
[ ] set up a window environment settings object linked from service-workers, storage-access, webdriver-bidi
[ ] check the usability of the image argument linked from webcodecs, webgpu, webxrlayers-1

whatwg / html

Exporting definitions linked to by 3+ specs #9159